Overview

• What does this change accomplish and why?

  • Adds support for underscores as visual separators in numeric literals, a common readability feature in modern languages (Rust, Python, Java, Kotlin, Swift). Closes Underscores in numeric literals #2228.
  • How does it change the user experience?
    • Users can now write 1_000_000 instead of 1000000, 0xFF_FF instead of 0xFFFF, etc.
  • What was the old behavior/API and what is the new behavior/API?
    • Before: 1_000 produced a confusing parse error.
    • After: 1_000 is accepted and evaluates to 1000.

• Before and after examples:

  Input	Before	After
  1_000_000	parse error	1000000
  0xFF_FF	parse error	65535
  0b1010_0101	parse error	165
  1_000.5e1_0	parse error	1000.5e10
  1_	1 (silent)	parse error
  1__2	1 (silent)	parse error
  1_x	1, _x (two tokens)	parse error

• Closes Underscores in numeric literals #2228

Implementation approach and notes

This is a parser-only change — underscores are stripped at lex time, so no downstream changes to the parser, typechecker, pretty-printer, or runtime are needed.

Two helpers are added to the numeric parser in Unison.Syntax.Lexer.Unison:

• digitsWithUnderscores — parses digit groups separated by single underscores, committing after each _ so that malformed literals (trailing _, consecutive __, _ before non-digit) produce errors instead of silently accepting partial input.
• digitsToInteger — converts a digit string to Integer for a given base, replacing megaparsec's LP.decimal/LP.hexadecimal/LP.octal/LP.binary.

The three prefixed-base parsers (octal, hex, binary) are factored into a shared baseWithPrefix helper. Decimal is intentionally excluded from this because it has no prefix, which changes the backtracking semantics.

Interesting/controversial decisions

• 1_x is now an error, not two tokens (1, _x). Once the lexer sees <digit>_, it commits to the underscore-in-number interpretation. This seems like the right call — 1_x looks like a malformed numeric literal, and users can write 1 _x if they mean two tokens.
• Underscores are not allowed after base prefixes (0x_FF is rejected) or adjacent to ./e/exponent signs. This matches Java's rules. Rust and Python are more permissive here.
• Underscores are never emitted on output. The pretty-printer always renders 1000000, not 1_000_000. This is consistent with how Unison handles string literals (single-line vs multi-line formatting is regenerated by the pretty-printer, not preserved from source). A configurable pretty-printer could be a future enhancement.
• Bytes literals (0xs...) don't support underscores. This is a separate piece of work since the bytes parser has different structure.

Test coverage

• Lexer unit tests: 38 new test cases covering all numeric forms with underscores (decimal, float, scientific, hex, octal, binary) plus error cases (trailing _, consecutive __, _ adjacent to prefix/period/exponent, digit_nondigit sequences, leading zeros).
• Transcript integration test: numeric-underscore-literals.md exercises valid literals end-to-end (parse → evaluate → display) and verifies error messages for invalid literals.
• Test coverage is adequate for this change.

Loose ends

• Bytes literals (0xs...) could also support underscores — separate issue.
• The pretty-printer could optionally insert underscores in large numeric literals for readability — separate feature.

Final checklist

• PR title is descriptive of the change.
• Transcripts included demonstrating the changed behavior.
• No .cabal file changes.