Lexical rules#

Whitespace#

Spaces (' '), tabs ('\t'), and carriage returns ('\r') are insignificant and skipped between tokens. Newlines ('\n') are significant tokens used as statement separators. The parser skips newlines between statements but they are preserved in the token stream. Semicolons (';') are also accepted as optional statement separators in statement-list contexts (top-level items, block statements, tool bodies, and skill fields), but they are non-canonical input syntax. harn fmt normalizes them back to newline-separated form.

Backslash line continuation#

A backslash (\) immediately before a newline joins the current line with the next. Both the backslash and the newline are removed from the token stream, so the two physical lines are treated as a single logical line by the lexer.

const total = 1 + 2 \
  + 3 + 4
// equivalent to: const total = 1 + 2 + 3 + 4

This is useful for breaking long expressions that do not involve a binary operator eligible for multiline continuation (see "Multiline expressions").

Comments#

// Line comment: everything until the next newline is ignored.

/* Block comment: can span multiple lines.
   /* Nesting is supported. */
   Still inside the outer comment. */

Block comments track nesting depth, so /* /* */ */ is valid. An unterminated block comment produces a lexer error.

Keywords#

The following identifiers are reserved:

Contextual keywords#

These words introduce syntax only in one position and are ordinary identifiers everywhere else, so let tool = ..., let select = ..., and config.from work:

to and exclusive are not keywords. They spelled ranges before Harn 0.11; ranges are now a..b and a..=b, and a to b reports HARN-PAR-007.

Identifiers#

An identifier starts with a letter or underscore, followed by zero or more letters, digits, or underscores:

identifier ::= [a-zA-Z_][a-zA-Z0-9_]*

Number literals#

int_literal   ::= digit+
float_literal ::= digit+ '.' digit+

A number followed by . where the next character is not a digit is lexed as an integer followed by the . operator (enabling 42.method). 1..3 therefore lexes as an integer, the .. range operator, and an integer.

Range operators#

.. and ..= are single tokens. A run of three dots stays three . tokens, which the parser reads as a spread or rest marker ([...xs]).

Duration literals#

A duration literal is an integer followed immediately (no whitespace) by a time-unit suffix:

duration_literal ::= digit+ ('ms' | 's' | 'm' | 'h' | 'd' | 'w')

Duration literals evaluate to an integer number of milliseconds. They can be used anywhere an expression is expected:

harness.clock.sleep_ms(500ms)
deadline 30s { /* ... */ }
const one_day = 1d       // 86400000
const two_weeks = 2w     // 1209600000

String literals#

Single-line strings#

string_literal ::= '"' (char | escape | interpolation)* '"'
escape         ::= '\' ('n' | 'r' | 't' | '0' | '\\' | '"' | '

const total = 1 + 2 \
  + 3 + 4
// equivalent to: const total = 1 + 2 + 3 + 4

// Line comment: everything until the next newline is ignored.

/* Block comment: can span multiple lines.
   /* Nesting is supported. */
   Still inside the outer comment. */

identifier ::= [a-zA-Z_][a-zA-Z0-9_]*

int_literal   ::= digit+
float_literal ::= digit+ '.' digit+

duration_literal ::= digit+ ('ms' | 's' | 'm' | 'h' | 'd' | 'w')

harness.clock.sleep_ms(500ms)
deadline 30s { /* ... */ }
const one_day = 1d       // 86400000
const two_weeks = 2w     // 1209600000

string_literal ::= '"' (char | escape | interpolation)* '"'
escape         ::= '\' ('n' | 'r' | 't' | '0' | '\\' | '"' | '

raw_string_literal ::= 'r"' char* '"'
                     | 'r' '#'+ '"' char* '"' '#'+

const pattern = r"\d+\.\d+"
const path = r"C:\Users\alice\docs"

// A regex matching a double-quoted string body, with no backslash soup:
const caps = regex_captures(r#""([^"\\]*)""#, "name=\"value\"")
harness.obs.log("first body: ${caps[0].groups[0]}")

multi_line_string ::= '"""' newline? content '"""'

const name = "world"
const doc = """
  Hello, ${name}!
  Today is ${harness.clock.timestamp()}.
"""