The epher language reference

This page is the formal, normative definition of the epher language: its lexical rules, grammar, types, operators, statements, built-in constants and functions, units, display rules, errors, and limits. Every name and every signature here is extracted from the evaluating engine itself (the epher-core crate), not from prose.

The user guide teaches the language by example; this reference defines it exactly. Where the two appear to disagree, this page wins, and the disagreement is a bug worth filing.

1. Notation

• code spells a token, expression, or statement exactly as written.
• italic names in the grammar name non-terminals.
• "number" without qualification means a real value; "complex" includes reals as the special case with zero imaginary part.
• Signatures write built-in calls the way you type them: hypot(a, b).
• Every example in a code block is engine-verified: the epher block evaluates, the text block is what the engine answers.

2. Program structure

An epher program (a script file, a pasted block, a piped stdin, or a REPL line) is a sequence of statements separated by ; or by a newline. Both separators are equivalent; ; never terminates a statement, it separates statements, so an empty statement is not an error and leading, trailing, and doubled separators are allowed.

The value of a program is the value of its last statement that produced one. A statement that produces no value (for example an if without an else whose condition is false, or break) is skipped when the program's value is collected; a program whose statements all produce no value answers nothing.

Comments come in three kinds:

# a line comment, from # to end of line
2 + 2      // another line comment, from // to end of line
/* an inline comment */ 4 * 4
/* a block comment may span
   several lines */

4
16

#, //, and /* ... */ may appear between any two tokens. Newlines inside a block comment do not separate statements; the comment's closing */ is required, and its absence is a parse error.

A statement is one of: an assignment, a constant definition, a function definition, a destructuring, if, while, for, solve, return, break, continue, or an expression. The full grammar is given in The complete grammar.

3. Lexical grammar

3.1 Numbers

• Decimal: digits with an optional fractional part (3, 3.5, .5) and an optional decimal-exponent suffix (2e3, 1.5E-3, 2e+2). The exponent needs at least one digit, so 2e and 2eggs tokenize as the number 2 followed by a name.
• Based integers: 0b binary, 0o octal, 0x hexadecimal, 0b101, 0o17, 0xFF. Digits after the prefix must suit the base. A base prefix changes the spelling, never the value: 0xFF is 255.
• Imaginary suffix: a number directly followed by i, with no letter or _ after the i, is one imaginary literal: 4i, 2.5i, 0xFFi. 3 + 4i is a sum of two literals. 4it is not imaginary; it is the number 4 followed by the name it, which the grammar then rejects.
• All numbers are 64-bit binary floats. Integers are exact up to 2^53; beyond that, spelling a literal keeps at most the 53 most significant bits.

3.2 Strings

A string literal is double quotes around any run of characters. Five escapes exist: \n newline, \t tab, \r carriage return, \\ backslash, \" quote. Any other escape is a parse error that names the mistake, and a string cannot end on a lone backslash.

"line one\nline two"
"quote: \" backslash: \\"

line one
line two
quote: " backslash: \

3.3 Names

A name starts with a letter or _ and continues with letters, digits, or _. Letters are Unicode; atan2, log10, and x2 are names. Names are case-sensitive: G and g are different constants.

4. Names and keywords

The following words are keywords. They cannot be written where a value is expected, and they are recognized by exact spelling:

break   const   continue   def   do   else   end   for   if
in      not     or         and   return   share   solve   step
then    to      while      xor

true and false are not literals: booleans are produced only by comparisons and predicates (1 < 2, isprime(7)), and a bare true is an unknown-name error.

One further name is reserved: i, the imaginary unit. It cannot be re-bound by assignment, by const, or by a destructuring pattern; see Names, scope, and the session store. i is not a keyword; it resolves as a built-in constant and can be shadowed by nothing.

5. Types and values

Notes:

• Lists hold numbers, or strings, not a mix. A complex element is rejected at construction.
• Matrices are reals only, stored row-major; matrix functions are in the function index.
• A quantity is an SI value plus its seven base dimensions and an optional display unit; see Units.
• ans is a normal variable the frontend rebinds after each computation; it holds the previous answer.

The answer panel spells values as Number display defines.

6. Expressions and operators

6.1 Precedence, tightest to loosest

-2 ^ 2 is -4 (unary minus binds looser than the power); 2 ^ -2 is 0.25 (the exponent may be unary); 3! ^ 2 is 36; d[2] ^ 2 indexes first; not x > 3 is not (x > 3); 5 & 3 == 1 is (5 & 3) == 1.

6.2 Arithmetic

+, -, *, / work over reals and complex; a complex operand computes in complex. / by zero is a division error. ^ is right-associative; 0 ^ 0 is 1.

• List arithmetic is elementwise: two same-length lists combine element by element, and a list combined with a scalar maps over the list. Different lengths are a type error.
• String + concatenates two strings; a string with a non-string is a type error (spell the number first with str or fixed).
• Unit suffixes ride through + - * / with dimension checking; see Units.

6.3 Factorial and percent

n! is the factorial of a non-negative whole number. x% is exactly x / 100, a transparent suffix, so 200 + 10% is 200.1; the Casio add-on reading (220) is deliberately not a grammar rule.

6.4 Indexing

expr[k] indexes a list or string, 1-based; the index is any expression. A matrix indexed with one expression gives one whole row as a list: m[2] is the second row.

6.5 Comparisons

== and != compare any two values of the same kind; <, <=, >, >= order numbers and strings (strings in dictionary/code-point order). Complex values refuse ordering. Lists and matrices do not compare. Comparisons return booleans, and comparisons do not chain: 1 < 2 < 3 is a type error, not (1 < 2) < 3.

6.6 Booleans

and, or, not take booleans only and produce booleans. and and or short-circuit: the right side is not evaluated when the left decides. There is no truthiness: numbers are not booleans.

6.7 Bitwise operations

&, |, xor, ~, <<, >> take integers (whole floats, exact Big, integral rationals/decimals) and produce the exact result masked to the session's word size, a signed two's-complement word of 8, 16, 32, or 64 bits, set with bits(w) and defaulting to 64. Right shift is arithmetic; a negative shift amount reverses the direction.

7. Statements

7.1 Assignment: name = expr

Evaluates the expression and binds the name in the session. Rebinding is allowed; binding i is refused (see below).

7.2 Constant definition: const name = expr

Binds an immutable name. A definition prints nothing: a constant is a knob, machinery like a def, so the transcript stays silent while the binding takes effect (ADR-0080). Re-declaring with the same value succeeds, examples get pasted twice; a different value is a constant already defined error. Naming an existing variable is a cannot define constant x: the name is already a variable error — the session already bound that name, so reset the session or rename the binding.

7.3 Sharing a script's definitions: share name, name

A multi-statement submission is a script scope: the constants and functions it defines are its own, and they vanish when the script ends (variables and ans always stay — see §8). share is the one way definitions cross the boundary on purpose: the named definitions join the session, with their source lines, so save and the next startup replay persist them.

const tax = 0.2
total = 100 * (1 + tax)
share tax        # the session keeps tax; total stays script-local

share of a name the script never made is an unknown name error; sharing over a session definition of a different kind (a constant over a variable, say) is the same error defining that name directly would give. share is a top-level script statement; evaluated anywhere else it does nothing.

7.4 Destructuring: {a, b} = expr

The expression must be a list whose length equals the number of pattern names; each name binds to its position's element. _ skips a position: {x, _} = {1, 2} binds only x. Names in the pattern follow assignment rules (i refused, constants refused). The pattern is recognized only when the statement begins with {names} =; a {1, 2} at the start of a line stays the list expression it always was.

7.5 Function definition: def name(params) = expr and def name(params) do … end

Two body forms. = expr evaluates the expression in a child environment seeded with the arguments. do … end runs its statements one after another in that child environment; the last statement's value is the call's answer, and a body whose statements produce no value is a named error. Recursion works in both forms. A call carries its own 100,000-step budget. Parameters shadow session values only inside the call.

A name is one thing: a variable, a constant, or a function, never two (see §8). Re-defining a function the session already defined errors with function already defined: f unless the definition is the same; a def over a variable's or constant's name is refused, and so is const or an assignment over a function's name. reset starts the session over.

7.6 return, break, continue

return expr leaves the enclosing function now, with the value; return at top level (outside any function) is a named error. break leaves the innermost enclosing for or while; continue skips to its next pass. Outside a loop both are named errors. In a for loop, a pass ended by continue contributes no value to the collected list.

7.7 if as a statement: if cond then stmt / if cond then stmt else stmt

The condition must be a boolean. Without else, a false condition produces no value, which is how a for loop filters: a pass whose body produces no value adds nothing to the loop's list.

7.8 while cond do stmt

Evaluates the condition (which must be a boolean) and runs the one-statement body until it is false, break fires, or the step budget runs out. A while loop produces no value.

7.9 for name in iterable do stmt

Two iterable forms: a range start to end (optionally step s), or any expression evaluating to a list. The variable is bound per pass and removed afterwards: the loop never leaves its variable in the session, and a binding that existed before the loop is restored after it. The loop's value is the list of the body's per-pass values.

7.10 solve lhs == rhs

Numeric equation solving, no CAS. The equation must use ==. The unknown is x when x appears, otherwise the single other name; constants (built-in and user) are parameters, never unknowns. Real roots in a wide search window are reported, as a display string: solve x^2 == 9 answers x = -3, x = 3.

7.11 Expression statements

Any expression, typically a call. Its value, when there is one, becomes the statement's value.

8. Names, scope, and the session store

Name resolution tries, in order: session variables, then session constants, then built-in constants, then built-in functions (a call), then the error unknown name. A user function or constant shadows a built-in of the same name. A call resolves the function table first, so a name that is somehow a value and a function at once stays unambiguous — which cannot happen: a name is one thing, a variable, a constant, or a function, never two (ADR-0012).

• A multi-statement submission is a script scope. The constants and functions a script defines are its own and vanish at its end; its variables and ans stay. Definitions cross by share only (§7.3). A script that defines a name the session library already holds — a shared constant, a store replay — shadows it for the run instead of erroring, the way a for loop shadows its variable: re-running an example never depends on what ran before it. randseed and bits inside a script are the script's own too: the same script re-runs to the same draws. A single statement typed on its own is interactive, against the session itself.
• Session variables persist for the session and, in interactive frontends, across sessions and frontends of the same installation through the shared store (the .epher folder; the PWA keeps the same shape in browser storage).
• The imaginary unit is reserved. i = 5, const i = …, and a destructuring pattern naming i are all refused with cannot assign to i: that name is the imaginary unit, so no session, store, or frontend can shadow 3+4i. A stored i from an older release is dropped silently when the store loads.
• A for loop's variable exists only for the loop: it is removed afterwards, and a prior binding is restored (nothing a loop does reaches the store).
• A def's parameters and body live in a child environment: they shadow the session inside the call and cannot leak out. Assignments inside a function body are local to that call.
• save name asks the interactive frontend to persist a function or constant into the store; saving a script is a frontend command, not language (see Beyond the grammar).

9. Built-in constants

Values are SI throughout. A name's value is fixed by the engine; a user const of the same name shadows it by the resolution order.

9.1 Mathematics

9.2 Astronomy

9.3 Physics

9.4 Chemistry and thermodynamics

The imaginary unit's value is the complex number with real part 0 and imaginary part 1; its literal spellings i and 4i tokenize as literals.

10. Built-in functions

Every callable the engine knows, grouped by domain. Argument shapes are normative: x is a real number, z any number (complex allowed), n a whole number, s a string, L a list. A call with the wrong count or kinds is a type error that names the function, e.g. rad expects 1 number, got 1 argument(s).

10.1 Angles and logarithms

10.2 Powers, roots, rounding

10.3 Trigonometry (complex where the domain needs it)

10.4 Complex parts

10.5 Exact and display spellings

10.6 Number theory

Integers the float type reaches exactly (|n| < 2^53).

10.7 Statistics and probability

L is a list of reals; variance is population variance (divide by n).

10.8 Lists, strings, matrices

10.9 Calculus (numeric)

10.10 Randomness (seeded, reproducible)

10.11 Word size

10.12 Finance

Sign convention: money you pay out is negative. r is the rate per period.

10.13 Astronomy and time

Bodies are whole numbers: Mercury 1 … Neptune 8, Pluto 9, Sun 10, Moon 11. jd is a Julian Date. Observer functions take terrestrial latitude and longitude in degrees.

i the loop variable and i the imaginary unit coexist inside a for loop exactly because the loop scopes its variable; see Statements.

11. Units

A number directly followed by a unit name is a quantity: the number times the unit's SI factor, carrying its dimensions. 2 m stores 2 with length dimensions; 60 mile/hr stores 26.8224 m/s. Units may carry a whole-number power (2 m^2, powers to ±127) and a / may continue with another unit (5 m/s^2), that is unit syntax, not division, whenever a unit name follows. An SI prefix may start a unit: 30 cm, 5 kHz, 3 ns.

x in unit (or x -> unit) converts: 5 km in mile answers 3.10685596119 mile, and the display unit sticks. Arithmetic checks dimensions: adding 2 m to 30 cm gives 2.3 m; adding a metre to a second is a dimension error.

11.1 Prefixes

The 21 SI prefixes, as spellings before a unit: da (×10¹), h (×10²), k (×10³), M (×10⁶), G (×10⁹), T (×10¹²), P (×10¹⁵), E (×10¹⁸), Z (×10²¹), Y (×10²⁴), d (×10⁻¹), c (×10⁻²), m (×10⁻³), µ or u (×10⁻⁶), n (×10⁻⁹), p (×10⁻¹²), f (×10⁻¹⁵), a (×10⁻¹⁸), z (×10⁻²¹), y (×10⁻²⁴).

11.2 Base and derived units

A quantity displays in its display unit when it has one (typed or converted), otherwise in the SI spelling of its dimensions (m/s^2, or the exact derived name when the dimensions match one: N, W, Pa, …).

12. Number display

The answer panel's automatic spelling:

• A float prints with up to 12 significant digits, exact integers keeping every digit.
• Exact fractions: when a rational with denominator ≤ 1000 agrees with the value through all twelve displayed digits and is not a terminating decimal, the answer shows as a fraction, 1/3 stays 1/3, while 0.1 + 0.2 shows 0.3, not 3/10.
• Complex answers print in a+bi form. Booleans print true/false. Lists print {1, 2, 3}; matrices print row by row: [[1, 2], [3, 4]].
• The display verbs (scientific, engineering, grouped, fixed, bin, oct, hex) return text, ready to print or join.

13. Errors

An error stops evaluation of the statement in progress; in a script the whole run stops and the exit carries the message. Error classes, with the verbatim shape of each message:

14. Limits and determinism

• Step budget: every program run carries a 100,000-step budget; each function call gets its own fresh budget. Exhausting it stops the run.
• For iterations: a single for loop is capped at 100,000 passes.
• Floats: 64-bit binary; integers exact to 2^53.
• Reproducibility: the random generator is SplitMix64 with a Box–Muller step for randn; randseed(n) makes a sequence repeatable. Scripts evaluated by the checker pin a seed, so a script's transcript is byte-stable.
• Display: 12 significant digits, fractions only through denominator 1000.

15. The complete grammar (EBNF)

The grammar is written in EBNF, the Extended Backus–Naur Form. Each rule names a construct and says how it is built: , joins parts in sequence, | separates alternatives, [ … ] marks a part that may be absent, { … } a part that may repeat, and "quoted text" is a token written exactly so; rules refer to one another until every chain ends in a literal token, and any input that a chain of these rules accepts parses, and anything else does not.

program     = statement , { separator , statement } ;
separator   = ";" | newline ;

statement   = "break"
            | "continue"
            | "return" , expression
            | "if" , expression , "then" , statement , [ "else" , statement ]
            | "while" , expression , "do" , statement
            | "for" , name , "in" , expression , [ "to" , expression ,
                [ "step" , expression ] ] , "do" , statement
            | "solve" , expression
            | "const" , name , "=" , expression
            | "def" , name , "(" , [ params ] , ")" , defbody
            | pattern , "=" , expression
            | name , "=" , expression
            | expression ;
params      = name , { "," , name } ;
defbody     = "=" , expression
            | "do" , block , "end" ;
pattern     = "{" , name , { "," , name } , "}" ;
block       = statement , { separator , statement } ;

expression  = ifexpr ;
ifexpr      = "if" , expression , "then" , expression ,
              "else" , expression | orexpr ;
orexpr      = andexpr , { "or" , andexpr } ;
andexpr     = notexpr , { "and" , notexpr } ;
notexpr     = "not" , notexpr | comparison ;
comparison  = bitor , [ cmpop , bitor ] ;
cmpop       = ">" | "<" | ">=" | "<=" | "==" | "!=" ;
bitor       = bitand , { ( "|" | "xor" ) , bitand } ;
bitand      = shift , { "&" , shift } ;
shift       = additive , [ ( "<<" | ">>" ) , additive ] ;
additive    = term , { ( "+" | "-" ) , term } ;
term        = unary , { ( "*" | "/" ) , unary } ;
unary       = "-" , unary | "~" , unary | power ;
power       = postfix , [ "^" , unary ] ;
postfix     = primary , { "!" | "%" | index } ;
index       = "[" , expression , "]" ;
primary     = number | string | name | call
            | "(" , expression , ")"
            | list | matrix ;
call        = name , "(" , [ expression , { "," , expression } ] , ")" ;
list        = "{" , [ expression , { "," , expression } ] , "}" ;
matrix      = "[" , row , { "," , row } , "]" ;
row         = "[" , expression , { "," , expression } , "]" ;

Grammar notes the EBNF cannot say:

• The additive level also admits unit conversion after a term: expression "in" unitpath and expression "->" unitpath, looping so 3 m in ft in inch chains.
• Inside a multiplicative chain, a / directly followed by a unit name (and not a call) continues a unit path rather than dividing: 60 mile/hr, 5 m/s^2.
• A statement beginning { name , … } = is a destructuring; any other { begins a list expression (the parser rewinds).
• end closes a def's do block; there is no standalone do statement.
• in is a keyword both in for … in and in unit conversion; the position disambiguates.
• Number literals absorb an i suffix into an imaginary token; based literals (0b, 0o, 0x) too.

16. Beyond the grammar: interactive commands

The language is what this page defines. The frontends add commands around it, recognized before the parser sees the line; they are conveniences, not part of the language definition:

Everything else, expression entry, scripts, the store, behaves as this reference defines, identically on every frontend.

The function and constant tables are extracted from epher-core's dispatch and catalog; a core test keeps them from drifting: renaming or removing a builtin without updating this page fails the build.