Invisible link to canonical for Microformats
 

ADR-012 Numeric Literals with Underscores

Status

Accepted

Context

As Slug programs grow in complexity, numeric literals representing large values (timeouts, byte sizes, monetary values, identifiers, etc.) become harder to read and reason about when written as long digit sequences.

Many modern programming languages allow underscores (_) within numeric literals as a visual separator (e.g. 1_000_000) without affecting the numeric value. This improves readability while preserving explicitness.

Slug currently parses numeric literals without visual separators. Introducing underscore support requires clear, unambiguous rules to avoid confusion, lexer complexity, or overlap with identifier syntax.

Decision

Slug will support underscores (_) in numeric literals as visual separators only, following a rule set closely aligned with Go’s numeric literal specification.

Allowed underscore placement

An underscore may appear:

  • Between two digits, or
  • Immediately after a numeric base prefix (0x) and before the first digit

Examples:

  • 1_000
  • 10_000_000
  • 3.141_592
  • 0xFF_EC_DE_5E

Disallowed underscore placement

An underscore is not permitted:

  • At the start or end of a numeric literal (_1, 1_)
  • Adjacent to a decimal point (1_.0, 1._0)
  • Repeated without digits between (1__000)
  • In any position not directly separating digits

These rules apply uniformly to all numeric literal forms supported by Slug.

Semantics

  • Underscores have no semantic meaning
  • All underscores are removed during lexing or numeric parsing
  • The AST and runtime representation never include underscores

Error handling

Malformed numeric literals containing invalid underscore placement will produce a syntax error at parse time with a clear diagnostic.

Consequences

Positive

  • Significantly improves numeric literal readability
  • Zero runtime cost
  • Minimal lexer and parser complexity
  • Aligns with expectations from modern languages
  • Preserves Slug’s goals of explicitness and simplicity

Negative

  • Slight increase in lexer validation logic
  • Requires explicit specification to avoid ambiguity

Neutral

  • No impact on the runtime, VM, or bytecode format
  • No impact on existing valid Slug programs