Language Specification¶

This document defines the complete syntax of .nl files.

File Structure¶

An .nl file consists of:

Directives — Module metadata (@module, @version, @target, @imports)
ANLU Blocks — Function specifications ([name])
Type Definitions — Custom types (@type)
Test Blocks — Test specifications (@test)
Literal Blocks — Code escape hatches (@literal)
Comments — Lines starting with #

Directives¶

`@module`¶

Required. Declares the module name.

@module calculator

Pattern: ^[a-z][a-z0-9_]*$ (lowercase snake_case)

`@version`¶

Optional semantic version.

@version 1.0.0

`@target`¶

Required. Specifies the compilation target.

@target python

Supported: python (more coming)

`@imports`¶

Optional comma-separated import list.

@imports jwt, datetime, typing

ANLU Blocks¶

ANLU (Atomic Natural Language Unit) blocks define functions.

[function-name]
PURPOSE: Single sentence describing what this does
INPUTS:
  - param1: type
  - param2: type, optional
GUARDS:
  - condition -> ErrorType("message")
LOGIC:
  1. Description of step -> variable
  2. Another step
EDGE CASES:
  - condition -> behavior
RETURNS: expression
DEPENDS: [other-function], [another]

Identifier¶

ANLU names use kebab-case:

[calculate-tax]
[is-empty]
[validate-user-token]

Pattern: ^[a-z][a-z0-9-]*$

For methods, use dot notation:

[User.validate]
[Order.calculate-total]

PURPOSE¶

Required. Single sentence in imperative mood.

PURPOSE: Calculate the total price including tax

INPUTS¶

Typed parameter list with optional constraints.

INPUTS:
  - amount: number
  - rate: number, "Tax rate as decimal"
  - currency: string, optional

Bullets can be •, -, or *.

GUARDS¶

Preconditions with error mappings.

GUARDS:
  - amount must be non-negative -> ValueError("Amount cannot be negative")
  - rate must be between 0 and 1 -> ValidationError(INVALID_RATE, "Rate must be 0-1")

LOGIC¶

Numbered steps describing the algorithm.

LOGIC:
  1. Calculate base tax -> tax
  2. Add service fee if applicable -> fee
  3. Combine tax and fee -> total

Steps can include:

Output binding: -> variable
Conditionals: IF condition THEN action
State markers: [state] action

EDGE CASES¶

Explicit boundary condition handling.

EDGE CASES:
  - Zero amount -> return 0
  - Empty list -> return None

RETURNS¶

Required. Output expression or type.

RETURNS: base + tax
RETURNS: TaxResult with amount, effective_rate
RETURNS: list of Order

DEPENDS¶

Dependencies on other ANLUs.

DEPENDS: [validate-input], [calculate-base]

Type System¶

Primitives¶

Type	Description
`number`	Integer or float
`string`	Text
`boolean`	`true` / `false`
`void`	No return value
`any`	Dynamic typing escape hatch

Composites¶

List:

list of number
list of User

Optional:

string?
User?

Map:

map of string to number

Union:

string | number
Success | Error

Type Definitions¶

Define custom types with @type:

@type Point {
  x: number
  y: number
}

@type Order {
  id: string, required
  items: list of OrderItem
  total: number, "Order total in cents"
  status: string
}

Inheritance¶

@type OrderItem extends BaseItem {
  quantity: number
  price: number
}

Field Constraints¶

@type User {
  email: string, required
  age: number, optional
  role: string, "User role in system"
}

Test Blocks¶

Define test cases with @test:

@test [add] {
  add(1, 2) == 3
  add(0, 0) == 0
  add(-5, 5) == 0
}

@test [divide] {
  divide(10, 2) == 5.0
  divide(9, 3) == 3.0
}

Test blocks generate executable pytest code.

Literal Blocks¶

Escape hatch for exact code when needed:

[slugify]
PURPOSE: Convert text to URL-friendly slug format
INPUTS:
  - text: string

@literal python {
import re

def slugify(text: str) -> str:
    """Convert text to URL-friendly slug format."""
    text = text.lower().strip()
    text = re.sub(r'\s+', '-', text)
    text = re.sub(r'[^a-z0-9-]', '', text)
    return text.strip('-')
}

Literal blocks bypass the compiler and emit code exactly as written.

Comments¶

Lines starting with # are comments:

# Math Module
# This provides basic arithmetic operations

@module math
@target python

# Addition function
[add]
PURPOSE: Add two numbers
...

Formatting Notes¶

Bullets are flexible: •, -, or *
Arrows are flexible: → (Unicode) or -> (ASCII)
Section headers are case-insensitive
Indentation uses spaces for visual structure
Unicode is supported in text content

Grammar Reference¶

For the complete formal grammar, see nl-grammar.ebnf.