1. Purpose

Canon supports configuration through environment variables, allowing you to override default settings without modifying code. This is essential for CI/CD pipelines, containerized environments, and different deployment scenarios.

Critical: Environment variables work uniformly across all interfaces - CLI, Ruby API, and RSpec.

2. Priority chain

Configuration values are resolved using the following priority (highest to lowest):

  1. Environment Variables (highest priority)

  2. Programmatic Configuration (via Canon::Config)

  3. Default Values (lowest priority)

Environment variables always override programmatic settings, which in turn override defaults.

3. Naming convention

Environment variables follow a consistent naming pattern:

CANON_{FORMAT}_{CONFIG_TYPE}_{ATTRIBUTE}

Where:

  • FORMAT: XML, HTML, JSON, YAML, or STRING

  • CONFIG_TYPE: DIFF or MATCH

  • ATTRIBUTE: The configuration attribute name (e.g., ALGORITHM, MODE, PROFILE)

3.1. Global variables

You can also use global environment variables that apply to all formats by omitting the format prefix:

CANON_{ATTRIBUTE}

Global variables are overridden by format-specific variables.

4. Core environment variables

4.1. Diff algorithm

Canon supports two diff algorithms:

  • dom: DOM-based tree diff (default, stable)

  • semantic: Semantic tree diff (experimental, more sophisticated)

# Set algorithm for XML diff
export CANON_XML_DIFF_ALGORITHM=semantic

# Set algorithm for HTML diff
export CANON_HTML_DIFF_ALGORITHM=dom

# Set globally for all formats
export CANON_ALGORITHM=semantic

Valid values: dom, semantic

4.2. Diff mode 

# Set diff mode for JSON
export CANON_JSON_DIFF_MODE=by_object

# Set diff mode for YAML
export CANON_YAML_DIFF_MODE=by_line

Valid values: by_line, by_object

4.3. Color output 

# Disable color output for XML
export CANON_XML_DIFF_USE_COLOR=false

# Enable color output for HTML
export CANON_HTML_DIFF_USE_COLOR=true

Valid values: true, false, 1, 0, yes, no

4.4. Diff display theme

Choose a color theme for diff output. Themes control foreground/background colors, text effects, and visual markers.

# Set theme for dark terminal
export CANON_DIFF_THEME=dark

# Set theme for light terminal
export CANON_DIFF_THEME=light

# Amber CRT retro look
export CANON_DIFF_THEME=retro

# Claude Code style (red/green backgrounds)
export CANON_DIFF_THEME=claude

Valid values: light, dark, retro, claude

See Diff display themes for complete theme documentation.

4.5. Context and grouping 

# Set context lines for XML diff
export CANON_XML_DIFF_CONTEXT_LINES=5

# Set grouping lines for XML diff
export CANON_XML_DIFF_GROUPING_LINES=20

Valid values: Any positive integer

4.6. Show diffs filter 

# Show only informative diffs
export CANON_XML_DIFF_SHOW_DIFFS=informative

# Show all diffs
export CANON_XML_DIFF_SHOW_DIFFS=all

Valid values: all, informative, normative

4.7. Verbose output 

# Enable verbose diff output
export CANON_XML_DIFF_VERBOSE_DIFF=true

Valid values: true, false, 1, 0, yes, no

5. Size limits

Canon provides configurable size limits to prevent hangs or excessive resource usage when processing very large files.

See Size Limits for detailed configuration.

Key variables:

  • CANON_MAX_FILE_SIZE - Maximum file size in bytes (default: 5,242,880 = 5MB)

  • CANON_MAX_NODE_COUNT - Maximum tree node count (default: 10,000)

  • CANON_MAX_DIFF_LINES - Maximum diff output lines (default: 10,000)

6. Override system

See Override System for how environment variables interact with programmatic configuration.

7. Usage across interfaces

7.1. CLI

Environment variables automatically affect CLI commands:

# Set algorithm via ENV
export CANON_ALGORITHM=semantic

# CLI uses the ENV setting
canon diff file1.xml file2.xml --verbose

7.2. Ruby API

Environment variables are applied when creating Canon::Config:

# Environment variable is set
ENV['CANON_XML_DIFF_ALGORITHM'] = 'semantic'

# Config respects ENV variable
config = Canon::Config.new
puts config.xml.diff.algorithm  # => :semantic

# Programmatic setting is ignored when ENV is set
config.xml.diff.algorithm = :dom
puts config.xml.diff.algorithm  # => :semantic (ENV wins)

7.3. RSpec

Environment variables work with RSpec matchers:

# In spec_helper.rb, set defaults
Canon::RSpecMatchers.configure do |config|
  config.xml.diff.algorithm = :dom
end

# In shell, override for specific test run
# CANON_ALGORITHM=semantic bundle exec rspec

8. Type conversion

Environment variable values are automatically converted to the appropriate Ruby types:

8.1. Boolean values

Accepted values for boolean attributes:

  • True: true, 1, yes

  • False: false, 0, no

Case-insensitive.

8.2. Integer values

Any valid integer string is converted to an integer:

export CANON_CONTEXT_LINES=15  # Converted to Integer 15

8.3. Symbol values

String values are converted to symbols:

export CANON_ALGORITHM=semantic  # Converted to Symbol :semantic

9. Common scenarios

9.1. CI/CD environment 

# .github/workflows/test.yml or similar
export CANON_USE_COLOR=false
export CANON_ALGORITHM=semantic
export CANON_SHOW_COMPARE=true

bundle exec rspec

9.2. Docker container 

# Dockerfile
ENV CANON_XML_DIFF_ALGORITHM=semantic
ENV CANON_USE_COLOR=false
ENV CANON_CONTEXT_LINES=5

9.3. Different environments 

# Development
export CANON_VERBOSE_DIFF=true
export CANON_USE_COLOR=true

# Production
export CANON_VERBOSE_DIFF=false
export CANON_USE_COLOR=false
export CANON_XML_MATCH_PROFILE=strict

9.4. Format-specific configuration 

# XML uses semantic diff
export CANON_XML_DIFF_ALGORITHM=semantic

# HTML uses DOM diff
export CANON_HTML_DIFF_ALGORITHM=dom

# All formats disable color
export CANON_USE_COLOR=false

10. Complete variable reference

See Environment Variables Reference for a complete table of all environment variables.

11. Troubleshooting

11.1. ENV variable not taking effect

Check the priority chain. If a programmatic value seems to override ENV, verify:

  1. The ENV variable is set before creating the Config instance

  2. The variable name follows the correct naming convention

  3. The value is valid for the attribute type

11.2. Type conversion errors

If you encounter type conversion errors:

  1. Check that boolean values use accepted strings (true, false, 1, 0, yes, no)

  2. Ensure integer values are valid integers

  3. Verify symbol values don’t contain special characters

11.3. Debugging

You can inspect the resolver to see which values are from ENV:

config = Canon::Config.new
resolver = config.xml.diff.instance_variable_get(:@resolver)

puts "ENV values: #{resolver.env.inspect}"
puts "Programmatic values: #{resolver.programmatic.inspect}"
puts "Defaults: #{resolver.defaults.inspect}"
puts "Source of algorithm: #{resolver.source_for(:algorithm)}"

12. See also