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.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
0b
binary-number ¶
-
macro (
try
try-expressionexcept
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 (
$.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-variable-expression – The name of the variable to be changed,
a
-
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-table-expression (table) – An expression that evaluates to the
table to be searched for
-
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.
- 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 (
__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
orfalse
is interpreted as logical false and causesspecial-else-expression
to be evaluated. Otherwise, logical true is assumed andspecial-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-condition-expression – An expression whose value selects the
subsequent expression to be evaluated. A value of
-
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
orfalse
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-condition-expression – An expression to be evaluated at the
beginning of each loop. A value of
-
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.
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, includingnull
.
-
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 )¶