Syntax and directives
This page covers how an L4 file is written: layout, comments, names, literals, annotations, directives and the special forms that make rules read like legal text. For how to write rules that read well, see Writing in the L4 style.
Layout
L4 is layout-sensitive: indentation, not braces or semicolons, shows what belongs to what. The lines of a block are indented further than the line that opens it, and the items of a block (fields, inputs, branches) start in the same column. Spaces only; a tab is not a substitute.
Example:
-- Example: Layout rules (indentation-based grouping)
-- Demonstrates how indentation defines code blocks
DECLARE Person
HAS name IS A STRING -- Indented: part of declaration
age IS A NUMBER -- Same level: another field
john MEANS Person WITH
name IS "John Doe"
age IS 30
#EVAL john's name
In a long expression, indentation also groups the operators; see AND, OR, NOT, IMPLIES: Several lines.
Comments
--or//starts a comment that runs to the end of the line.{- … -}and/* … */enclose a comment that can span several lines.
Example:
-- Comments
-- A line comment starts with two dashes
// or with two slashes
`the age limit` MEANS 18 -- and can follow code on a line
{- A block comment
can span several lines -}
/* So can this
one */
#EVAL `the age limit`
Identifiers
- A plain identifier starts with a letter and continues with letters, digits and underscores:
age,income_band. - A quoted identifier is written in backquotes and can contain spaces and punctuation:
`the applicant`,`Section 2(a)`. Prefer these: they let a rule read like the legal text. - Keywords (
DECIDE,GIVEN,IF, …) are written in capitals. Identifiers are case-sensitive:`the rate`and`The rate`are different names.
Example:
-- Identifiers: plain and quoted
-- A plain identifier: letters, digits and underscores, starting with a letter
ASSUME age IS A NUMBER
ASSUME income_band IS A STRING
-- A quoted identifier, in backquotes, can contain spaces and punctuation
ASSUME `total tax` IS A NUMBER
ASSUME `Section 2(a)` IS A STRING
-- Identifiers are case-sensitive: these are two different names
`the rate` MEANS 1
`The rate` MEANS 2
#EVAL `the rate`
#EVAL `The rate`
Literals
| Kind | Examples |
|---|---|
| Number | 42, -17, 3.14, 5% (= 0.05), 100_000 |
| Text | "hello", with \", \\ and \n as escapes |
| Boolean | TRUE, FALSE |
| List | LIST 1, 2, 3, EMPTY, 1 FOLLOWED BY 2 FOLLOWED BY EMPTY |
Underscores between the digits of a number are ignored. A number must start with a digit and must not end with an underscore. There is no date literal; see Types.
IMPORT
IMPORT name at the top of a file, before the first § section, makes the definitions of a library or another L4 file available. An IMPORT below a section heading is ignored. See Standard libraries: IMPORT.
Annotations
Annotations attach information to the definition that follows them, or to the line they end.
@desc
@desc text describes a rule, a type or an input. It goes on the line above a definition, or at the end of an input's line. Deployed functions show it to their callers.
@desc The applicant's age in years
ASSUME `the applicant's age` IS A NUMBER
@nlg
@nlg gives a definition its wording in natural language, with %name% slots for its inputs.
GIVEN x IS A NUMBER, y IS A NUMBER
GIVETH A NUMBER
@nlg the greater of %x% and %y%
`the greater of` x y MEANS IF x >= y THEN x ELSE y
See @nlg.
@ref
@ref cites a legal source: the provision a rule, a type or an input comes from.
- Line form:
@refand the citation, on a line of its own. - Inline form: the citation between
<<and>>, which can sit in the middle of a line.
What a @ref cites
A @ref cites what comes after it, so write it on the line above the thing it cites:
@ref Section 4(1)(a) of the Act
GIVEN age IS A NUMBER
resident IS A BOOLEAN
GIVETH A BOOLEAN
`is eligible` MEANS
age >= 18
AND <<Section 4(1)(b)>> resident
The @ref cites the rule is eligible; the <<…>> cites resident, the expression that follows it.
A @ref is held by the first construct that starts after it: a rule, a type, a section heading, an input, or an expression inside a rule.
Blank lines and comments between a @ref and that construct make no difference.
A citation before the first operand of a chain of AND, OR or arithmetic is held by the whole chain, because the chain is the outermost expression that starts after it; to cite one operand, put the citation just before that operand inside the chain, as with resident above.
Several citations. Write them one above the other, each on a line of its own. The construct below keeps all of them, in the order written.
@ref Dog Act 058 of 1976 (WA)
@ref url https://www.legislation.wa.gov.au/legislation/statutes.nsf/law_a230.html
§ `Dogs Act - 33D.1`
Where only one citation per construct is wanted, the nearest is used: the one written last, just above the construct. In the editor, hovering over a citation shows it as a link.
@ref-map name url maps a citation to a link: a @ref whose text is name links to url.
Two warnings
Both are warnings, so l4 check still succeeds, and the VS Code extension marks the @ref itself.
The browser-based editor does not show them.
A @ref that follows code on its line.
A @ref written at the end of a line, after the code it means to cite, cannot cite that code, because it cites what comes after it.
It does not cite the next construct either: it is attached to nothing, so the next construct's citation, in the IDE and in every export, is not this one.
The warning names the code it trails:
This @ref (
1981/61 sec. 2) follows code on its line, but a @ref refers to what follows it, so this one is attached to nothing. Put it on the line aboveGIVETH A BOOLEAN.
The fix is to move it to the line above that code.
An inline <<…>> is warned about only when it ends the line, because in the middle of a line it cites the word after it, which is what it is for.
A @ref with nothing after it.
A @ref after the last construct of the file has nothing to attach to:
This @ref (
Section 4(1)(a) of the Act) is at the end of the file, so there is nothing after it to attach to.
Writing a literal >>
The inline form ends at >>, so a citation that contains those two characters would otherwise stop halfway.
Put a backslash before the angle bracket:
| you write | you get |
|---|---|
<<see s.5 \>> onward>> |
see s.5 >> onward |
<<\\>> |
\ |
A single > needs nothing.
<<s.5 > s.3>> is one citation: only the doubled >> closes it, so a lone > is ordinary text.
To end a citation with a backslash, write \\.
A backslash immediately before >> is an escape, so \> is a literal > and the citation goes on.
Any other character after a backslash is left alone, so \q is a backslash followed by a q.
This is the same idea as the \% and \] escapes in @nlg, but the set of characters is deliberately different.
% and ] are ordinary text in a citation, and > is ordinary text in an @nlg annotation.
Each annotation escapes only what would otherwise be read as punctuation in that annotation.
@export
@export marks a function to be published as an endpoint when the file is deployed. The rest of the line is the function's description. Functions without @export stay internal.
@export Check whether a person is old enough to apply
GIVEN age IS A NUMBER @desc The person's age in years
GIVETH A BOOLEAN
DECIDE `is old enough` IF age >= 18
@export default marks the file's main entry point among its exports.
A function written as several clauses needs a GIVEN to be exported, and a function-typed input cannot be exported (ASSUME).
How to deploy: Deploy your rules.
Example:
-- Annotations: @desc, @nlg, @ref, @export
@desc The applicant's age in years
ASSUME `the applicant's age` IS A NUMBER
-- @nlg at the end of a definition's line gives its wording, with %name% slots
GIVEN x IS A NUMBER, y IS A NUMBER
GIVETH A NUMBER
`the greater of` x y @nlg the greater of %x% and %y%
MEANS IF x >= y THEN x ELSE y
-- A @ref cites what comes after it
@ref Section 4(1)(a) of the Act
@export Check whether a person is old enough to apply
GIVEN age IS A NUMBER @desc The person's age in years
GIVETH A BOOLEAN
DECIDE `is old enough` IF age >= 18
#EVAL `the greater of` 3 7
#EVAL `is old enough` 20
-- A literal percent sign or close bracket in an `@nlg` annotation is written
-- with a backslash in front of it. Here the rate range `10%and%20` would
-- otherwise read `and` as a parameter name, silently.
GIVEN amount IS A NUMBER
GIVETH A NUMBER
`the levy on` amount [a rate between 10\%and\%20 applied to %amount%]
MEANS amount TIMES 0.15
#EVAL `the levy on` 100
-- A citation containing a literal `>>` needs a backslash before the angle
-- bracket, or the inline `@ref` form would end halfway through it.
GIVEN claimant IS A BOOLEAN
GIVETH A BOOLEAN
`is eligible` claimant MEANS
<<Section 4(1)(a) \>> as amended>>
claimant
#EVAL `is eligible` TRUE
-- An `@nlg` may carry a language subtag, and one rule may carry a
-- rendering per language. `l4 nlg --lang he` and `l4 render --lang he` select
-- the Hebrew one; with no flag, or for a rule that has none in that language,
-- the default rendering is used.
GIVEN amount IS A NUMBER
GIVETH A BOOLEAN
DECIDE `is a large amount` @nlg:en the amount %amount% is large
@nlg:he %amount% עולה על הסף
IF amount GREATER THAN 100
#EVAL `is a large amount` 150
Directives
Directives are instructions to the tools, written at the top level of a file. l4 run and the editor carry them out; l4 check only type-checks them.
| Directive | What it does |
|---|---|
#EVAL |
evaluates an expression and shows the result |
#EVALTRACE |
evaluates an expression and also shows the steps that led to the result (l4 trace draws them) |
#CHECK |
type-checks an expression and shows its type, without evaluating it |
#ASSERT |
evaluates an expression and reports whether it is TRUE (what it reports) |
#ASSERT REFUSED |
evaluates an expression and reports whether it refuses to answer, with the reason after BECAUSE if there is one (REFUSE) |
#TRACE |
runs a regulative rule against a list of events (see Regulative rules) |
#EVAL expression
#EVALTRACE expression
#CHECK expression
#ASSERT expression
#ASSERT REFUSED expression BECAUSE "reason"
#TRACE rule AT start-time WITH
PARTY party DOES action AT time
A directive's expression ends with its line. To continue it, start the next line with # and a space, followed by an operator:
GIVEN age IS A NUMBER
GIVETH A BOOLEAN
DECIDE `is an adult` IF age >= 18
#EVAL `is an adult` 21
# AND `is an adult` 30
#CHECK `is an adult`
#ASSERT NOT `is an adult` 12
Example:
-- Directives: #EVAL, #EVALTRACE, #CHECK, #ASSERT, #TRACE
GIVEN age IS A NUMBER
GIVETH A BOOLEAN
DECIDE `is an adult` IF age >= 18
-- #EVAL evaluates an expression and shows the result
#EVAL `is an adult` 21
-- A directive continues on the next line when that line starts with "# "
-- and the expression goes on with an operator
#EVAL `is an adult` 21
# AND `is an adult` 30
-- #EVALTRACE also shows how the result was reached
#EVALTRACE `is an adult` 15
-- #CHECK type-checks an expression and shows its type, without evaluating it
#CHECK `is an adult`
-- #ASSERT checks that an expression is TRUE
#ASSERT `is an adult` 40
#ASSERT NOT `is an adult` 12
-- #TRACE runs a regulative rule against events
DECLARE Person IS ONE OF Seller
DECLARE Action IS ONE OF delivery
GIVETH A DEONTIC Person Action
`delivery duty` MEANS
PARTY Seller
MUST delivery
WITHIN 3
#TRACE `delivery duty` AT 0 WITH
PARTY Seller DOES delivery AT 2
What #ASSERT reports
An #ASSERT has one of four outcomes:
| When the expression… | It prints | The editor shows | l4 run exit code |
In l4 run --json |
|---|---|---|---|---|
| is TRUE | assertion satisfied |
information | not affected | "value": true |
| is FALSE | assertion failed |
an error | not affected | "value": false |
cannot be evaluated: a division by zero, a CONSIDER with no matching branch, a term that is only ASSUMEd |
assertion could not be evaluated: and the reason |
an error, with the reason | non-zero | "value": null, with the reason under "error" |
reaches a REFUSE: the rules decline to answer |
assertion refused: and the reason |
a warning, with the reason | not affected | "value": null, with the reason under "refused" |
In --json the result's "kind" is "assertion" in all four.
An assertion that cannot be evaluated is not a verdict, so #ASSERT P and #ASSERT NOT P then report the same thing. Asserting an ASSUMEd BOOLEAN directly, as in #ASSERT b, is one such case: b has no value to check.
Testing your rules shows an example.
A refused assertion is not a verdict either, and l4 run still exits 0, so a CI job that looks for failures looks for assertion refused as well as assertion failed.
To assert that an expression refuses, use #ASSERT REFUSED; Testing a refusal lists what it reports.
Sections
§ starts a section, like a part or section of a statute; §§ starts a subsection, §§§ a sub-subsection, and so on. The heading is the name after the marks.
§ `Part VII`
§§ `Subsection 2`
`age of majority` MEANS 18
§§ `Subsection 3`
`age of majority` MEANS 21
GIVEN age IS A NUMBER
GIVETH A BOOLEAN
DECIDE `is an adult under subsection 2` IF
age >= `Part VII`'s `Subsection 2`'s `age of majority`
Definitions in different sections can share a name. Where the name alone would be ambiguous, qualify it with the section's name and 's, as above.
A section can have a shorter alias: § `Definitions for Part VII` AKA defs, then defs's `taxable income` (or defs.`taxable income`).
Example:
-- Sections (§) group definitions, like the parts of a statute
§ `Eligibility Rules`
`the minimum age` MEANS 18
§§ `Age Requirements`
GIVEN age IS A NUMBER
GIVETH A BOOLEAN
`is old enough` age MEANS age >= `the minimum age`
§§ `Citizenship Requirements`
GIVEN `is a citizen` IS A BOOLEAN
GIVETH A BOOLEAN
`meets citizenship requirement` `is a citizen` MEANS `is a citizen`
#EVAL `is old enough` 21
#EVAL `meets citizenship requirement` TRUE
Genitive
's reads a field of a record, as in English: `the applicant`'s age. It can be chained: `the applicant`'s address's city.
age OF `the applicant` means the same.
Example:
-- Genitive: 's reads a field of a record, as in English
DECLARE Address
HAS city IS A STRING
DECLARE Person
HAS `full name` IS A STRING
age IS A NUMBER
address IS AN Address
DECIDE `the applicant` IS Person WITH
`full name` IS "Kim Tan"
age IS 30
address IS Address WITH city IS "Singapore"
-- A field is also a function of its record, so these two mean the same
#EVAL `the applicant`'s age
#EVAL age OF `the applicant`
-- 's can be chained
#EVAL `the applicant`'s address's city
OF
OF introduces arguments separated by commas: add OF 3, 4 means the same as add 3 4.
It also appears in types (LIST OF NUMBER, Box OF NUMBER), in enumerations (IS ONE OF), when making a record (Person OF "Kim", 30) and in patterns (WHEN JUST OF x).
Ditto
^ repeats the word in the same position on the line above, one ^ per word. It keeps repetitive lines short.
Example:
-- Example: Ditto (^) syntax
-- Copy tokens from previous line (one ^ per token)
eligible MEANS TRUE
john MEANS eligible
mary ^ ^ -- Copies "MEANS eligible"
alice ^ ^ -- Also copies "MEANS eligible"
#EVAL john
#EVAL mary
#EVAL alice
Asyndetic AND and OR
... means AND and .. means OR, as in lists of conditions in legal text. See Operators: Asyndetic AND and OR.