@nlg
@nlg gives a definition its wording in natural language.
l4 render, l4 nlg and the editor read that wording in place of the name.
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
#EVAL `the greater of` 3 7 reads "the greater of 3 and 7".
- To fix wording in a document: Fix wording with @nlg
- To write rules that read well: Make rules read like law
- Example:
-- An `@nlg` sentence on a mixfix function, and what reads it.
-- See the `@nlg` section of the syntax reference.
GIVEN a IS A NUMBER, b IS A NUMBER
GIVETH A NUMBER
`the lower of` a `and` b @nlg the smaller of %a% and %b%
MEANS IF a AT MOST b THEN a ELSE b
GIVEN price IS A NUMBER
GIVETH A NUMBER
`the price we charge` price MEANS `the lower of` price `and` 100
#EVAL `the lower of` 840 `and` 160
Text in square brackets after a name is a short form: DECIDE `the limit` [the statutory limit] IS 5.
Slots
%name% is filled with the call's argument.
- An input with spaces in its name keeps its backticks:
%`the amount`%. - A slot has no spaces inside.
% amount %is plain text, and L4 warns. - An input with no slot is not dropped. It follows the sentence: "the threshold is passed with 5".
To write % or ] as itself, put a backslash before it:
| You write | You get |
|---|---|
10\%and\%20 |
10%and%20 |
[rate \] per unit] |
rate ] per unit |
[see note \[3\] here] |
see note [3] here |
\\ |
\ |
You need this only where a % touches a word: a 5% levy on %amount% works as written.
Take care with %word%: if word names an input, L4 fills it in and nothing warns.
Where to put it
| Where | Whose wording it is |
|---|---|
On its own line, between the GIVEN or GIVETH and the rule |
The rule's sentence |
After the rule's name: DECIDE `is large` @nlg … |
The rule's sentence |
After an input named in the head: `is large` amount @nlg … |
The rule's sentence |
On an AKA name |
The rule's sentence |
After an input in the GIVEN, or indented under it |
That input's |
| After a field, or under it | That field's |
On its own line above a GIVEN |
Not the rule's |
- Trailing a line, it describes that line. On its own line, it describes what follows. Fields and inputs are the exception: an annotation under one describes that one.
- Under the last input, field or
ASSUME, the column decides. Indented past theGIVEN,DECLAREorASSUMEkeyword, it describes that item. At the keyword's column or left of it, it describes what comes next. One extra space turns a rule's sentence into an input's wording, and nothing warns. - After an enum whose last value has no fields, a line at the margin belongs to that value. Put the next rule's sentence after its name instead.
- Empty or duplicated: an empty
@nlgis ignored with a warning. Two wordings in one language on one thing warn, and neither is used. - In the head and above it: the one above is the rule's sentence, and the one on the input is that input's wording.
- A head that repeats an input takes the input from the head, so a wording in the
GIVENlabels nothing.
How it reads
| You annotate | It reads |
|---|---|
| A rule | The sentence heads the rule and the body follows. Every call reads as the sentence. |
| A rule that calls itself, or an imported one | The sentence stands in for the body. |
| An input | Its label in a WITH call: … where the amount is x. |
| A field | After its owner: @nlg date of birth reads "the employee's date of birth". |
A BOOLEAN field |
On its own, with no owner, so write a whole statement. |
- In a rule's own sentence, an input of a built-in type reads as a blank,
[x]. An input of your own type reads as the rule's body calls it, such as "the application kind". - A
WITHcall reads the sentence, then each argument by name: "the smaller of a and b where a is price and b is 100". - A call reads the sentence of the definition it resolved to, not of another definition with the same name.
- A unit of time after a slot agrees with the number: "%n% months" reads "1 month" for 1.
l4 nlgwrites literal dates as dates:Date 16 7 2025reads16 July 2025. A date that does not exist, such asDate 31 2 2025, stays a call.
When a slot gets brackets
A sentence's own words can read as part of what fills its slot. So a slot gets brackets when two things hold: the sentence goes on after the slot, and what fills it has no word to close it.
The sentence goes on after a slot when its words or another of its slots come after it.
With @nlg %a%, %b% on comma, `comma` (NOT (`fb` p)) q reads "(it is not the case that fb for p), [q]".
A slot at the end of a sentence has nothing after it, so it gets no brackets.
With @nlg %a% is told %b% on told, and @nlg %p% is shown on shown, `told` p (NOT (`shown` q)) reads "[p] is told it is not the case that [q] is shown".
These have no closing word. Each example is in l4 render, where shown and told have the sentences above and fb has none.
| What fills the slot | You write | It reads |
|---|---|---|
An OR or an AND |
`shown` (p OR q) |
"(p or q) is shown" |
| A denial | `shown` (NOT (`fb` p)) |
"(it is not the case that fb for p) is shown" |
An IMPLIES |
`shown` (p IMPLIES q) |
"(p implies q) is shown" |
| A call with no sentence that ends with one of these | `shown` (`fb` (p AND q)) |
"(fb for p and q) is shown" |
| A call with a sentence whose last slot holds one | `shown` (`told` p (NOT (`fb` q))) |
"([p] is told it is not the case that fb for q) is shown" |
l4 nlg brackets the same slots, with names in backticks: `shown` (TRUE OR FALSE) reads "(TRUE or FALSE) is shown".
It also brackets an IF: `shown` (IF TRUE THEN FALSE ELSE TRUE) reads "(if TRUE then FALSE else TRUE) is shown".
l4 render moves a call into the branches of an IF instead.
Wording can still read two ways in these cases:
- A denial of one condition in
l4 renderreads "p is false" and gets no brackets, so`shown` (NOT p)reads "p is false is shown". - The slot at the end of a sentence can run on into what follows the sentence:
((`told` p (NOT (`fb` q))) OR r) IMPLIES rreads "[p] is told it is not the case that fb for q or r implies r". - A sentence that ends with its slot, in
l4 nlg: with@nlg it is shown that %x%onshown that,(`shown that` TRUE) AND FALSEand`shown that` (TRUE AND FALSE)both read "it is shown thatTRUEandFALSE". - A condition given to a call with no sentence gets no brackets:
NOT (p OR (`fb` (q AND r)))reads "neither p nor fb for q and r".
If a rule reads two ways because of one of these, give the condition a rule of its own, with a sentence, and call that.
Limits
- An
ASSUMEd function has no named inputs, so it has no slots, and a call reads as its name and arguments. Use aBOOLEANfield or a rule instead. - A function passed on, or named without being called, reads as its name. In
filter even xs,evenreadseven. - A sentence inside another call is spliced in without brackets, so nested calls can read alike: with
@nlg %a% doubledondbl,`f2` 2 (`dbl` 3)and`dbl` (`f2` 2 3)both read "f2with 2 and 3 doubled". Set slots off with words that cannot be part of an argument, and read the output of nested calls. A sentence that ends with a condition is the exception: see When a slot gets brackets. Arithmetic is bracketed, and so is anything beside it that does not say where it ends: "10 minus (5 minus 2)", "(5 doubled) minus 2", "twice (5 minus 2)", "(f2 for 2 and x) − 3". - A function with no sentence reads as its pattern:
`_ LESS _` with 100 and 20.
Several languages
Tag each wording with its language, and ask for one with --lang:
GIVEN amount IS A NUMBER
GIVETH A BOOLEAN
DECIDE `is large` @nlg:en the amount %amount% is large
@nlg:he %amount% עולה על הסף
IF amount GREATER THAN 100
$ l4 nlg --lang he mymodule.l4
$ l4 render --format html --lang he mymodule.l4 -o mymodule.he.html
The Render tab in VS Code has a language menu when a file has wordings in more than one language.
- L4 does not translate. It picks among the wordings you wrote.
- Regions match.
--lang hereads ahe-ILwording, and--lang he-ILreads aheone. An exact match comes first. - A missing wording falls back to the rule's default: the one in the module's language, otherwise the first in the file.
- The square-bracket form cannot be tagged.
- A word glued to the colon is a tag.
@nlg:the employee payshas the tagthe. L4 warns when nothing backs a tag as a language. Leave a space after the colon to keep it as text.
@lang he on a line of its own means every untagged @nlg in the module is Hebrew. It applies to the whole file.
- A module that declares nothing is
en, so@lang enis not needed, and L4 hints that it can go. - Declare the language of a module that is not English: it sets
<html lang=…>, right-to-leftdirand the Akoma Ntoso language. - If two
@langlines disagree, the last one is used, and L4 warns.
L4's own words, such as "is equal to", "if" and "with", follow --lang where L4 has a table for the language. Hebrew is the only one. It is small and keeps English word order, so have a Hebrew speaker read the output. A word with no entry stays English, and l4 nlg names it on stderr.