9. None Language Reference

9.1. Built-in Functions

These functions are loaded into the global namespace before core.n is executed.

function ( type object )
function ( generate-symbol )
function ( generate-anchor [ level ])
function ( expect-symbol symbol )
function ( expect-list list )
function ( expect-list-count list min-count [ max-count ])
function ( table-new ... )
function ( table-apply function table )
function ( table-call function [ argument ... ])
function ( table-get table key ... )
function ( table-setkey table key value )
function ( loop-pred step )

9.2. Built-in Symbols

var true
var false
var null
var globals

9.3. Core Macros

These macros are all defined in core.n and become available before the execution of any user script.

macro ( syntax-global macro-name function-expression )
macro ( __syntax-trace expression )
macro ( syntax-alias-global new-macro-name existing-macro-name )
macro ( syntax macro-name ... function-expression )
macro ( syntax-alias new-macro-name existing-macro-name )
macro ( do expression ... )
macro ( var variable-name [ init-expression ])
macro ( if conditional-expression then-expression [ else-expression ])
macro ( break )
macro ( locals )
macro ( quote expression )
macro ( do-splice expression ... )
macro ( del variable-name )
macro ( meta-eval expression ... )
macro ( meta-do expression ... )
macro ( loop variable-name ( start stop [ step ]) expression ... )
macro ( while conditional-expression loop-expression ... )
macro ( function ([ parameter-name | ( $ parameter-name ... ) ... ]) expression ... )
macro ( function-global ([ parameter-name ... ]) expression ... )
macro ( var-global variable-name init-expression )
macro ( __dot expression name )
macro ( __dotset expression name | ( name value ))
macro ( __member-call expression ( name [ argument ... ]))
macro ( __method-call expression ( name [ argument ... ]))
macro ( __hashset expression ( key value ))
macro ( syntax-rules ( pattern template ) ... )
macro ( syntax-table table-expression )
macro ( __and lhs-expression rhs-expression )
macro ( __or lhs-expression rhs-expression )
macro ( - [ lhs-expression ] rhs-expression )
macro ( / [ lhs-expression ] rhs-expression )
macro ( // lhs-expression rhs-expression )
macro ( __hashsetdefault expression ( key default-value ))
macro ( = variable-expression [ ... ] value-expression )
macro ( and lhs-expression rhs-expression [ ... ])
macro ( or lhs-expression rhs-expression [ ... ])
macro ( | lhs-expression rhs-expression [ ... ])
macro ( & lhs-expression rhs-expression [ ... ])
macro ( ^ lhs-expression rhs-expression [ ... ])
macro ( << lhs-expression rhs-expression [ ... ])
macro ( >> lhs-expression rhs-expression [ ... ])
macro ( + lhs-expression | table-expression [ rhs-expression ... ])
macro ( * lhs-expression rhs-expression [ ... ])
macro ( .. lhs-expression [ ... ] rhs-expression )
macro ( min lhs-expression | table-expression [ rhs-expression ... ])
macro ( max lhs-expression | table-expression [ rhs-expression ... ])
macro ( . expression name [ ... ])
macro ( -> expression ( name [ argument ... ])[ ... ])
macro ( --> expression ( name [ argument ... ])[ ... ])
macro ( .= expression name | ( name value )[ ... ])
macro ( #= expression ( key value )[ ... ])
macro ( =# expression ( key default-value )[ ... ])
macro ( syntax-infix-rules precedence associativity macro-name )
macro ( syntax-infix-alias-global macro-name rule )
macro ( syntax-infix-alias macro-name rule )
infix-macro ( variable-name = value-expression )
Precedence:50
Associativity:<
infix-macro ( variable-name := init-expression )
Precedence:50
Associativity:<
infix-macro ( lhs-expression or rhs-expression )
Precedence:100
Associativity:>
infix-macro ( lhs-expression and rhs-expression )
Precedence:200
Associativity:>
infix-macro ( lhs-expression | rhs-expression )
Precedence:240
Associativity:>
infix-macro ( lhs-expression ^ rhs-expression )
Precedence:250
Associativity:>
infix-macro ( lhs-expression & rhs-expression )
Precedence:260
Associativity:>
infix-macro ( lhs-expression < rhs-expression )
Precedence:300
Associativity:>
infix-macro ( lhs-expression > rhs-expression )
Precedence:300
Associativity:>
infix-macro ( lhs-expression <= rhs-expression )
Precedence:300
Associativity:>
infix-macro ( lhs-expression >= rhs-expression )
Precedence:300
Associativity:>
infix-macro ( lhs-expression != rhs-expression )
Precedence:300
Associativity:>
infix-macro ( lhs-expression == rhs-expression )
Precedence:300
Associativity:>
infix-macro ( lhs-expression is rhs-expression )
Precedence:300
Associativity:>
infix-macro ( lhs-expression .. rhs-expression )
Precedence:400
Associativity:<
infix-macro ( lhs-expression << rhs-expression )
Precedence:450
Associativity:>
infix-macro ( lhs-expression >> rhs-expression )
Precedence:450
Associativity:>
infix-macro ( lhs-expression - rhs-expression )
Precedence:500
Associativity:>
infix-macro ( lhs-expression + rhs-expression )
Precedence:500
Associativity:>
infix-macro ( lhs-expression % rhs-expression )
Precedence:600
Associativity:>
infix-macro ( lhs-expression / rhs-expression )
Precedence:600
Associativity:>
infix-macro ( lhs-expression * rhs-expression )
Precedence:600
Associativity:>
infix-macro ( lhs-expression ** rhs-expression )
Precedence:700
Associativity:<
infix-macro ( lhs-expression . rhs-expression )
Precedence:800
Associativity:>
infix-macro ( expression ->( name [ argument ... ]))
Precedence:800
Associativity:>
infix-macro ( expression -->( name [ argument ... ]))
Precedence:800
Associativity:>
infix-macro ( expression #( key value ))
Precedence:800
Associativity:>
infix-macro ( expression .= name | ( name value ))
Precedence:800
Associativity:>
infix-macro ( expression #=( key value ))
Precedence:800
Associativity:>
infix-macro ( expression =#( key default-value ))
Precedence:800
Associativity:>
macro ( backquote expression )
macro ( unquote expression )
macro ( unquote-splice list-expression )
macro ( assert expression [ string-expression ])
macro ( assert-error expression string-expression )
macro ( cond ( conditional-expression case-expression ... ) ... [( else else-expression )])
macro ( switch ( literal-expression case-expression ... ) ... [( else else-expression )])
macro ( do-if conditional-expression expression ... )
macro ( table-untupled ( function-expression [ argument-expression ... ]))
macro ( import-from table-expression | module-name symbol | index | ( name symbol ))
macro ( var-unpack table-expression variable-name ... )
macro ( foreach variable-name| ( variable-name ... ) iterator-expression loop-exression ... )
macro ( ast-list-each variable-name| ( variable-name ... ) iterator-expression loop-exression ... )
macro ( table-each variable-name| ( variable-name ... ) iterator-expression loop-exression ... )
macro ( table-loop variable-name ( start stop [ step ]) loop-expression ... )
macro ( table-do expression ... )
macro ( class name | name-expression [ : baseclass-expression ] expression ... )
macro ( class-global name | name-expression [ : baseclass-expression ] expression ... )
macro ( method [ name ]([ argument-expression ... ]) expression ... )
macro ( ++ variable-expression )
macro ( -- variable-expression )
macro ( += variable-expression value-expression )
macro ( -= variable-expression value-expression )
macro ( *= variable-expression value-expression )
macro ( /= variable-expression value-expression )
macro ( %= variable-expression value-expression )
macro ( &= variable-expression value-expression )
macro ( |= variable-expression value-expression )
macro ( ^= variable-expression value-expression )
macro ( <<= variable-expression value-expression )
macro ( >>= variable-expression value-expression )
macro ( ..= variable-expression value-expression )
infix-macro ( variable-expression += value-expression )
Precedence:50
Associativity:<
infix-macro ( variable-expression -= value-expression )
Precedence:50
Associativity:<
infix-macro ( variable-expression *= value-expression )
Precedence:50
Associativity:<
infix-macro ( variable-expression /= value-expression )
Precedence:50
Associativity:<
infix-macro ( variable-expression %= value-expression )
Precedence:50
Associativity:<
infix-macro ( variable-expression &= value-expression )
Precedence:50
Associativity:<
infix-macro ( variable-expression |= value-expression )
Precedence:50
Associativity:<
infix-macro ( variable-expression ^= value-expression )
Precedence:50
Associativity:<
infix-macro ( variable-expression <<= value-expression )
Precedence:50
Associativity:<
infix-macro ( variable-expression >>= value-expression )
Precedence:50
Associativity:<
infix-macro ( variable-expression ..= value-expression )
Precedence:50
Associativity:<
macro ( for ( init-expression predicate-expression increment-expression ) loop-expression ... )
macro ( postfix variable-expression operator )
symbol-prefix 0x hexadecimal-number
symbol-prefix 0bbinary-number
macro ( try try-expression except err catch-expression )
macro ( using module-name )
macro ( $ [ value | ( key := value ) | ( var key value ) ... ])
macro ( syntax-export table-expression )
macro ( syntax-import name-string )
macro ( syntax-import-replace name-string )
macro ( syntax-if conditional-expression then-expression [ else-expression ])
macro ( syntax-ifvar variable-name then-expression [ else-expression ])
macro ( main-module? )
macro ( syntax-quote syntax-expression )
macro ( syntax-expand syntax-expression )
macro ( syntax-join syntax-expression )
macro ( syntax-concat syntax-expression ... )
macro ( syntax-each variable-name ( value ... ) template )
macro ( syntax-string expression )
macro ( ast-list-unpack list-expression pattern )

9.4. Global Functions

These global functions are defined or imported in core.n and become available before any user script.

function ( print [ argument ... ])
function ( dprint [ argument ... ])
function ( syntax-globals )
function ( syntax-symbol-prefix-globals )
function ( __assert value error-message )
function ( ast-list [ object ... ])
function ( ast-tag anchor list )
function ( ast-string symbol )
function ( ast-repr object )
function ( ast-list? object )
function ( ast-symbol? object )
function ( ast-string? object )
function ( ast-number? object )
function ( ast-atom? object )
function ( ast-typeof object )
function ( ast-format list [ opts ])
function ( ast-pattern-keys context pattern )
function ( ast-syntax-match context pattern list )
function ( ast-apply-template context template )
function ( ast-expand-infix list infix-table )
function ( ast-wrap-compiler-call function list ... )
function ( __add a b )
function ( __sub a b )
function ( __mul a b )
function ( __div a b )
function ( __floordiv a b )
function ( __mod a b )
function ( __pow a b )
function ( __concat a b )
function ( __le a b )
function ( __lt a b )
function ( __ge a b )
function ( __gt a b )
function ( __eq a b )
function ( __ne a b )
function ( __is a b )
function ( __unm x )
function ( __not x )
function ( len x )
function ( __band a b )
function ( __bor a b )
function ( __bnot x )
function ( __bxor a b )
function ( __bswap a b )
function ( __shl a b )
function ( __shr a b )
function ( __rol a b )
function ( __ror a b )
function ( __min a b )
function ( __max a b )
function ( table [ object ... ])
function ( require module-name )
function ( __select n ... )
function ( tobit number )
function ( tohex number )
function ( xpcall function error-function )
function ( error message )
function ( tostring object )
function ( tonumber object )
function ( __pairs table )
function ( __ipairs table )
function ( __next table [ index ])
function ( rawset table key value )
function ( rawget table key )
function ( % a b )
function ( pow a b )
function ( not x )
function ( ~ x )
function ( == a b )
function ( != a b )
function ( < a b )
function ( <= a b )
function ( > a b )
function ( >= a b )
function ( is a b )
function ( ast-list-prepend list object ... )
function ( ast-list-append list object ... )
function ( ast-list-slice list start [ end ])
function ( ast-list-concat a b )
function ( ast-concat a b )
function ( trace ast-object )
function ( __call-method table name [ argument ... ])
function ( syntax-rules-factory list )
function ( binary-op-chainer-ltr op-name )
function ( binary-op-chainer-rtl op-name )
function ( unary-table-or-chainer-op chainer op-name )
function ( compound-assign-op op-name )
function ( tupled ... )
function ( table-tupled table )
function ( ipairs table start )
function ( pairs table )
function ( iter iterable )
function ( map iterable function )
function ( filter iterable predicate )
function ( zip iterable-a iterable-b )
function ( explode iterable )
function ( reduce iterable function init-value )
function ( null? object )
function ( cdata? object )
function ( table? object )
function ( function? object )
function ( userdata? object )
function ( number? object )
function ( string? object )
function ( boolean? object )
function ( empty? object )
function ( class? object )
function ( instance? object class )
function ( super? superclass class )
function ( ast-expand-symbol-prefix list syntax-table )
function ( set-syntax-symbol-prefix syntax-table prefix-name function )
function ( ast-parse-dot ast-object )
function ( hook-symbol-lookup scope-table table )
function ( $.insert table [ index ] value )
function ( $.remove table [ index ])
function ( $.len table )
function ( $.sort table compare-function )
function ( $.concat table [ sep [ i [ j ]]])
function ( $.copy table )
function ( $.extend table [ other-table ... ])
function ( $.update table other-table )
function ( $.keys table )
function ( $.values table )
function ( $.setmeta table metatable )
function ( $.sethiddenmeta table metatable )
function ( $.meta table )
function ( $.set table )
function ( __syntax-export package-name content init )
function ( __syntax-import package-name env replace )
function ( listrepr object )
function ( repr object )
function ( help object )

9.5. Global Objects

var ast
var Exception
var package
var MethodType
var math
var io
var os
var string
var ffi

9.6. Special Forms

None’s 16 special forms and 3 special macros are the barebone building blocks from which the rest of the language is bootstrapped. Only these objects and a handful of global functions are available before the core library is imported.

As such, they are only of interest to users seeking to completely replace the default namespace or override default behavior, and play no role in day to day usage of None.

By design, special forms do not use the macro system to expand their arguments; it is only later that they are overriden by expanding macros. A special form expects all nested expressions to be literals, symbols or special forms.

special ( __call special-function-expression [ special-argument-expression ... ])

Evaluates a function.

Parameters:
  • special-function-expression – An expression that evaluates to a callable object.
  • special-argument-expression – Zero or more expressions that evaluate to the arguments passed to the function to be evaluated.
Returns:

The return value of the evaluated function.

special ( __var variable-name special-init-expression )

Declares and initialize a new variable that becomes accessible to subsequent expressions in the active scope. Redeclaring a variable with the same name in the active scope is a syntax error.

Parameters:
  • variable-name (symbol) – The name of the variable to be defined.
  • special-init-expression – An expression that evaluates to the value to be assigned to the variable name.
Returns:

the value of special-init-expression.

special ( __set special-variable-expression special-value-expression )

Assigns a value to a variable or a table key.

Parameters:
  • special-variable-expression – The name of the variable to be changed, a __key expression, or a global name.
  • special-value-expression – An expression that evaluates to the value to be assigned.
Returns:

the value of special-value-expression.

special ( __key special-table-expression special-key-expression )

Retrieves a value stored in a table at a given key.

Parameters:
  • special-table-expression (table) – An expression that evaluates to the table to be searched for special-key-expression.
  • special-key-expression – An expression that evaluates to the key under which the value is stored. Must not be null.
Returns:

the value of the key or null if missing.

special ( __do special-expression ... )

Evaluates a list of expressions in a new scope. Variables declared using __var are only valid until __do returns.

Parameters:
  • special-expression – Zero or more expressions to be evaluated. Only the last expression’s value will be returned. Literals and symbols not last in the list will be ignored.
Returns:

the value of the last expression argument.

special ( __do-splice special-expression ... )

Evaluates a list of expressions in the existing scope. __do-splice is only safe to use within the scope created by __function or __do.

Parameters:
  • special-expression – Zero or more expressions to be evaluated. Only the last expression’s value will be returned. Literals and symbols not last in the list will be ignored.
Returns:

the value of the last expression argument.

special ( __function ([ parameter-name ... ]) special-expression )

Constructs an unnamed first-order function with the given parameters and a single expression to be evaluated. The function can be instantiated using __call. Variables declared using __var within the scope of the function are only valid until the function has been evaluated.

Parameters:
  • parameter-name – Zero or more parameter names that bind arguments passed by the caller to the function’s top level scope. The names are accessible as variables for the duration of special-expression.
  • special-expression – An expression that will be evaluated when the function is applied to a list of arguments using __call.
Returns:

a new function object.

special ( __if special-condition-expression special-then-expression special-else-expression )

Conditionally evaluates two expressions based on the value of a third.

Parameters:
  • special-condition-expression – An expression whose value selects the subsequent expression to be evaluated. A value of null or false is interpreted as logical false and causes special-else-expression to be evaluated. Otherwise, logical true is assumed and special-then-expression is evaluated.
  • special-then-expression – The expression to be evaluated if special-condition-expression evaluates to logical true.
  • special-else-expression – The expression to be evaluated if special-condition-expression evaluates to logical false.
Returns:

the value of the selected branch expression.

special ( __while special-condition-expression special-expression )

Repeatedly evaluate an expression until an exit condition is reached. The loop can also be exited using __break.

Parameters:
  • special-condition-expression – An expression to be evaluated at the beginning of each loop. A value of null or false is interpreted as logical false and causes the loop to abort. Otherwise, logical true is assumed, special-expression is evaluated and the loop repeats.
  • special-expression – An expression to be evaluated at the end of each loop. Calling __break anywhere within the loop’s scope aborts the loop prematurely.
Returns:

null

special ( __break )

Untimely abort a __while loop. Calling __break outside of __while is a syntax error.

special ( __scope )

Constructs a new table mapping each variable name in the active scope to its value.

Returns:the new scope table.
special ( __del variable-name )

Deletes a variable in the active scope previously declared by __var.

Returns:null
special ( __global variable-name [ table-name ])

Allows global variable look-ups for a specified name for the lifetime of the active scope.

Parameters:
  • table-name – If specified, the name of an alternative table to use for the lookup.
Returns:

null

special ( __quote special-expression )

Constructs an AST object from an expression instead of evaluating it.

Parameters:
  • special-expression – The expression to be quoted.
Returns:

an AST object representing the expression.

special ( __nop )

Contemplates the futility of existence.

Returns:null
special ( __pragma pragma-option [ special-expression ... ])

Influences compiler behavior to aid with language debugging. Internally used and subject to change.

special ( __unpack special-table-expression )

Splices elements of a table array into function arguments. Only valid when used as an argument to __call.

9.7. Special Macros

Special macros are defined before the runtime environment is bootstrapped. The runtime environment then provides its own implementation for completeness.

macro ( __meta-eval expression ... )

Evaluates a list of expressions within a new compiler context in a new top level scope that runs before the remainder of the source file has been translated. This can be used to patch the compiler’s environment with new macros and syntax handlers allowing the compiler to successfully translate the rest of the file.

The value returned by the last expression is spliced in place of the call to __meta-eval and is expected to be a valid AST object, including null.

macro ( __do expression ... )

This is the expanding form of __do, applying the built-in syntax expander on every argument and returning the final, escaped special form.

macro ( __escape expression )

When the syntax expander encounters this expression, the __escape part is removed and the remainder returned unaltered. This functionality can be used to terminate syntax expansion.

This is a pseudo-macro that has been hardcoded into the macro expansion routine and can not be overridden.

These macros are defined at the beginning of the runtime bootstrapping process and add macro expansion and optional parameters to the special forms. Each macro returns an expanded and escaped version of itself.

macro ( __if conditional-expression then-expression [ else-expression ])
macro ( __while conditional-expression loop-expression )
macro ( __break )
macro ( __set-scope table-expression )
macro ( __var variable-name [ init-expression ])
macro ( __key table-expression key-expression )
macro ( __set variable-expression value-expression )
macro ( __function ([ parameter-name ... ]) expression )
macro ( __unpack table-expression )
macro ( __call function-expression [ argument-expression ... ])
macro ( __do-splice expression ... )
macro ( __quote special-expression )