Pre-release Harn is pre-1.0 — the language, standard library, and CLI may change between releases. See the release notes

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:

KeywordToken
pipeline.pipeline
extends.extends
override.overrideKw
let.letKw
const.constKw
var.varKw (reserved for the removed-keyword migration diagnostic)
if.ifKw
else.elseKw
for.forKw
in.inKw
match.matchKw
retry.retry
parallel.parallel
defer.defer
return.returnKw
import.importKw
true.trueKw
false.falseKw
nil.nilKw
try.tryKw
catch.catchKw
throw.throwKw
throws.throwsKw
finally.finally
fn.fnKw
emit.emit
spawn.spawnKw
while.whileKw
type.typeKw
enum.enum
eval_pack.evalPack
struct.struct
interface.interface
pub.pub
from.from
to.to
tool.tool
skill.skill
exclusive.exclusive
guard.guard
require.require
deadline.deadline
yield.yield
mutex.mutex
break.break
continue.continue
select.select
impl.impl

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).

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')
SuffixUnitEquivalent
msmilliseconds--
sseconds1000 ms
mminutes60 s
hhours60 m
ddays24 h
wweeks7 d

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' | '\\' | '"' | '

Pre-release Harn is pre-1.0 — the language, standard library, and CLI may change between releases. See the release notes

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:

KeywordToken
pipeline.pipeline
extends.extends
override.overrideKw
let.letKw
const.constKw
var.varKw (reserved for the removed-keyword migration diagnostic)
if.ifKw
else.elseKw
for.forKw
in.inKw
match.matchKw
retry.retry
parallel.parallel
defer.defer
return.returnKw
import.importKw
true.trueKw
false.falseKw
nil.nilKw
try.tryKw
catch.catchKw
throw.throwKw
throws.throwsKw
finally.finally
fn.fnKw
emit.emit
spawn.spawnKw
while.whileKw
type.typeKw
enum.enum
eval_pack.evalPack
struct.struct
interface.interface
pub.pub
from.from
to.to
tool.tool
skill.skill
exclusive.exclusive
guard.guard
require.require
deadline.deadline
yield.yield
mutex.mutex
break.break
continue.continue
select.select
impl.impl

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).

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')
SuffixUnitEquivalent
msmilliseconds--
sseconds1000 ms
mminutes60 s
hhours60 m
ddays24 h
wweeks7 d

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' | '\\' | '"' | '
(dollar sign). Any other character\nafter `\\` produces a literal backslash followed by that character.\n\n#### Raw string literals\n\n```javascript\nraw_string_literal ::= 'r\"' char* '\"'\n | 'r' '#'+ '\"' char* '\"' '#'+\n```\n\nRaw strings use the `r\"...\"` prefix. No escape processing or interpolation is\nperformed inside a raw string -- backslashes, dollar signs, and other characters\nare taken literally. Raw strings cannot span multiple lines.\n\nRaw strings are useful for regex patterns and file paths where backslashes are\ncommon:\n\n```harn\nconst pattern = r\"\\d+\\.\\d+\"\nconst path = r\"C:\\Users\\alice\\docs\"\n```\n\nTo embed a literal double quote, use the *hashed* form `r#\"...\"#`. The literal\nends at the first `\"` followed by the same number of `#` as the opening\ndelimiter, so the body may contain any `\"` that is not followed by that many\n`#`. Add more `#` (`r##\"...\"##`, etc.) when the body itself contains a `\"#`\nsequence. This mirrors Rust's raw string syntax and keeps quote-heavy patterns\nescape-free:\n\n```harn\n// A regex matching a double-quoted string body, with no backslash soup:\nconst caps = regex_captures(r#\"\"([^\"\\\\]*)\"\"#, \"name=\\\"value\\\"\")\nharness.obs.log(\"first body: ${caps[0].groups[0]}\")\n```\n\n#### Multi-line strings\n\n```javascript\nmulti_line_string ::= '\"\"\"' newline? content '\"\"\"'\n```\n\nTriple-quoted strings can span multiple lines. The optional newline immediately after the\nopening `\"\"\"` is consumed. Common leading whitespace is stripped from all non-empty lines.\nA trailing newline before the closing `\"\"\"` is removed.\n\nMulti-line strings support `${expression}` interpolation with automatic indent\nstripping. If at least one `${...}` interpolation is present, the result is an\n`interpolatedString` token; otherwise it is a plain `stringLiteral` token.\nUse `\\${` for a literal `${` sequence inside a multi-line string.\n\n```harn\nconst name = \"world\"\nconst doc = \"\"\"\n Hello, ${name}!\n Today is ${harness.clock.timestamp()}.\n\"\"\"\n```\n\n### Operators\n\n#### Two-character operators (checked first)\n\n| Operator | Token | Description |\n|---|---|---|\n| `==` | `.eq` | Equality |\n| `!=` | `.neq` | Inequality |\n| `&&` | `.and` | Logical AND |\n| `\\|\\|` | `.or` | Logical OR |\n| `\\|>` | `.pipe` | Pipe |\n| `??` | `.nilCoal` | Nil coalescing |\n| `**` | `.pow` | Exponentiation |\n| `?.` | `.questionDot` | Optional property/method chaining |\n| `->` | `.arrow` | Arrow |\n| `\u003c=` | `.lte` | Less than or equal |\n| `>=` | `.gte` | Greater than or equal |\n| `+=` | `.plusAssign` | Compound assignment |\n| `-=` | `.minusAssign` | Compound assignment |\n| `*=` | `.starAssign` | Compound assignment |\n| `/=` | `.slashAssign` | Compound assignment |\n| `%=` | `.percentAssign` | Compound assignment |\n\n#### Single-character operators\n\n| Operator | Token | Description |\n|---|---|---|\n| `=` | `.assign` | Assignment |\n| `!` | `.not` | Logical NOT |\n| `.` | `.dot` | Member access |\n| `+` | `.plus` | Addition / concatenation |\n| `-` | `.minus` | Subtraction / negation |\n| `*` | `.star` | Multiplication / string repetition |\n| `/` | `.slash` | Division |\n| `\u003c` | `.lt` | Less than |\n| `>` | `.gt` | Greater than |\n| `%` | `.percent` | Modulo |\n| `?` | `.question` | Ternary / Result propagation |\n| `\\|` | `.bar` | Union types |\n| `&` | `.amp` | Intersection types |\n\n#### Keyword operators\n\n| Operator | Description |\n|---|---|\n| `in` | Membership test (lists, dicts, strings, sets) |\n| `not in` | Negated membership test |\n\n### Delimiters\n\n| Delimiter | Token |\n|---|---|\n| `{` | `.lBrace` |\n| `}` | `.rBrace` |\n| `(` | `.lParen` |\n| `)` | `.rParen` |\n| `[` | `.lBracket` |\n| `]` | `.rBracket` |\n| `,` | `.comma` |\n| `:` | `.colon` |\n| `;` | `.semicolon` |\n| `@` | `.at` (attribute prefix) |\n\n### Special tokens\n\n| Token | Description |\n|---|---|\n| `.newline` | Line break character |\n| `.eof` | End of input |\n"} ) interpolation ::= '${' expression '}'

A string cannot span multiple lines. An unescaped newline inside a string is a lexer error.

If the string contains at least one ${...} interpolation, it produces an interpolatedString token containing a list of segments (literal text and expression source strings). Otherwise it produces a plain stringLiteral token.

Escape sequences: \n (newline), \r (carriage return), \t (tab), \0 (NUL), \\ (backslash), \" (double quote), \$ (dollar sign). Any other character after \ produces a literal backslash followed by that character.

Raw string literals#

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

Raw strings use the r"..." prefix. No escape processing or interpolation is performed inside a raw string -- backslashes, dollar signs, and other characters are taken literally. Raw strings cannot span multiple lines.

Raw strings are useful for regex patterns and file paths where backslashes are common:

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

To embed a literal double quote, use the hashed form r#"..."#. The literal ends at the first " followed by the same number of # as the opening delimiter, so the body may contain any " that is not followed by that many #. Add more # (r##"..."##, etc.) when the body itself contains a "# sequence. This mirrors Rust's raw string syntax and keeps quote-heavy patterns escape-free:

// 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 strings#

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

Triple-quoted strings can span multiple lines. The optional newline immediately after the opening """ is consumed. Common leading whitespace is stripped from all non-empty lines. A trailing newline before the closing """ is removed.

Multi-line strings support ${expression} interpolation with automatic indent stripping. If at least one ${...} interpolation is present, the result is an interpolatedString token; otherwise it is a plain stringLiteral token. Use \${ for a literal ${ sequence inside a multi-line string.

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

Operators#

Two-character operators (checked first)#

OperatorTokenDescription
==.eqEquality
!=.neqInequality
&&.andLogical AND
||.orLogical OR
|>.pipePipe
??.nilCoalNil coalescing
**.powExponentiation
?..questionDotOptional property/method chaining
->.arrowArrow
<=.lteLess than or equal
>=.gteGreater than or equal
+=.plusAssignCompound assignment
-=.minusAssignCompound assignment
*=.starAssignCompound assignment
/=.slashAssignCompound assignment
%=.percentAssignCompound assignment

Single-character operators#

OperatorTokenDescription
=.assignAssignment
!.notLogical NOT
..dotMember access
+.plusAddition / concatenation
-.minusSubtraction / negation
*.starMultiplication / string repetition
/.slashDivision
<.ltLess than
>.gtGreater than
%.percentModulo
?.questionTernary / Result propagation
|.barUnion types
&.ampIntersection types

Keyword operators#

OperatorDescription
inMembership test (lists, dicts, strings, sets)
not inNegated membership test

Delimiters#

DelimiterToken
{.lBrace
}.rBrace
(.lParen
).rParen
[.lBracket
].rBracket
,.comma
:.colon
;.semicolon
@.at (attribute prefix)

Special tokens#

TokenDescription
.newlineLine break character
.eofEnd of input
Edit this page on GitHub