381 lines
9.6 KiB
Markdown
381 lines
9.6 KiB
Markdown
# Language Reference
|
|
|
|
## Grammar
|
|
|
|
```
|
|
Root = many(TopLevelDecl) "EOF"
|
|
|
|
TopLevelDecl = many(Directive) option(VisibleMod) (FnDef | ExternDecl | RootExportDecl | Import | ContainerDecl | GlobalVarDecl | ErrorValueDecl | CImportDecl | TypeDecl)
|
|
|
|
CImportDecl = "c_import" Block
|
|
|
|
TypeDecl = "type" "Symbol" "=" TypeExpr ";"
|
|
|
|
ErrorValueDecl = "error" "Symbol" ";"
|
|
|
|
GlobalVarDecl = VariableDeclaration ";"
|
|
|
|
VariableDeclaration = ("var" | "const") "Symbol" option(":" TypeExpr) "=" Expression
|
|
|
|
ContainerDecl = ("struct" | "enum") "Symbol" "{" many(StructMember) "}"
|
|
|
|
StructMember = many(Directive) option(VisibleMod) (StructField | FnDef)
|
|
|
|
StructField = "Symbol" option(":" Expression) ",")
|
|
|
|
Import = "import" "String" ";"
|
|
|
|
RootExportDecl = "export" "Symbol" "String" ";"
|
|
|
|
ExternDecl = "extern" (FnProto | VariableDeclaration) ";"
|
|
|
|
FnProto = "fn" option("Symbol") ParamDeclList option("->" TypeExpr)
|
|
|
|
Directive = "#" "Symbol" "(" Expression ")"
|
|
|
|
VisibleMod = "pub" | "export"
|
|
|
|
FnDef = option("inline") FnProto Block
|
|
|
|
ParamDeclList = "(" list(ParamDecl, ",") ")"
|
|
|
|
ParamDecl = option("noalias") option("Symbol" ":") TypeExpr | "..."
|
|
|
|
Block = "{" list(option(Statement), ";") "}"
|
|
|
|
Statement = Label | VariableDeclaration ";" | Defer ";" | NonBlockExpression ";" | BlockExpression
|
|
|
|
Label = "Symbol" ":"
|
|
|
|
Expression = BlockExpression | NonBlockExpression
|
|
|
|
TypeExpr = PrefixOpExpression
|
|
|
|
NonBlockExpression = ReturnExpression | AssignmentExpression
|
|
|
|
AsmExpression = "asm" option("volatile") "(" "String" option(AsmOutput) ")"
|
|
|
|
AsmOutput = ":" list(AsmOutputItem, ",") option(AsmInput)
|
|
|
|
AsmInput = ":" list(AsmInputItem, ",") option(AsmClobbers)
|
|
|
|
AsmOutputItem = "[" "Symbol" "]" "String" "(" ("Symbol" | "->" TypeExpr) ")"
|
|
|
|
AsmInputItem = "[" "Symbol" "]" "String" "(" Expression ")"
|
|
|
|
AsmClobbers= ":" list("String", ",")
|
|
|
|
UnwrapExpression = BoolOrExpression (UnwrapMaybe | UnwrapError) | BoolOrExpression
|
|
|
|
UnwrapMaybe = "??" Expression
|
|
|
|
UnwrapError = "%%" option("|" "Symbol" "|") Expression
|
|
|
|
AssignmentExpression = UnwrapExpression AssignmentOperator UnwrapExpression | UnwrapExpression
|
|
|
|
AssignmentOperator = "=" | "*=" | "/=" | "%=" | "+=" | "-=" | "<<=" | ">>=" | "&=" | "^=" | "|=" | "&&=" | "||="
|
|
|
|
BlockExpression = IfExpression | Block | WhileExpression | ForExpression | SwitchExpression
|
|
|
|
SwitchExpression = "switch" "(" Expression ")" "{" many(SwitchProng) "}"
|
|
|
|
SwitchProng = (list(SwitchItem, ",") | "else") "=>" option("|" "Symbol" "|") Expression ","
|
|
|
|
SwitchItem = Expression | (Expression "..." Expression)
|
|
|
|
WhileExpression = "while" "(" Expression ")" Expression
|
|
|
|
ForExpression = "for" "(" Expression ")" option("|" "Symbol" option("," "Symbol") "|") Expression
|
|
|
|
BoolOrExpression = BoolAndExpression "||" BoolOrExpression | BoolAndExpression
|
|
|
|
ReturnExpression = option("%" | "?") "return" option(Expression)
|
|
|
|
Defer = option("%" | "?") "defer" option(Expression)
|
|
|
|
IfExpression = IfVarExpression | IfBoolExpression
|
|
|
|
IfBoolExpression = "if" "(" Expression ")" Expression option(Else)
|
|
|
|
IfVarExpression = "if" "(" ("const" | "var") "Symbol" option(":" TypeExpr) "?=" Expression ")" Expression Option(Else)
|
|
|
|
Else = "else" Expression
|
|
|
|
BoolAndExpression = ComparisonExpression "&&" BoolAndExpression | ComparisonExpression
|
|
|
|
ComparisonExpression = BinaryOrExpression ComparisonOperator BinaryOrExpression | BinaryOrExpression
|
|
|
|
ComparisonOperator = "==" | "!=" | "<" | ">" | "<=" | ">="
|
|
|
|
BinaryOrExpression = BinaryXorExpression "|" BinaryOrExpression | BinaryXorExpression
|
|
|
|
BinaryXorExpression = BinaryAndExpression "^" BinaryXorExpression | BinaryAndExpression
|
|
|
|
BinaryAndExpression = BitShiftExpression "&" BinaryAndExpression | BitShiftExpression
|
|
|
|
BitShiftExpression = AdditionExpression BitShiftOperator BitShiftExpression | AdditionExpression
|
|
|
|
BitShiftOperator = "<<" | ">>"
|
|
|
|
AdditionExpression = MultiplyExpression AdditionOperator AdditionExpression | MultiplyExpression
|
|
|
|
AdditionOperator = "+" | "-" | "++"
|
|
|
|
MultiplyExpression = CurlySuffixExpression MultiplyOperator MultiplyExpression | CurlySuffixExpression
|
|
|
|
CurlySuffixExpression = TypeExpr option(ContainerInitExpression)
|
|
|
|
MultiplyOperator = "*" | "/" | "%"
|
|
|
|
PrefixOpExpression = PrefixOp PrefixOpExpression | SuffixOpExpression
|
|
|
|
SuffixOpExpression = PrimaryExpression option(FnCallExpression | ArrayAccessExpression | FieldAccessExpression | SliceExpression)
|
|
|
|
FieldAccessExpression = "." "Symbol"
|
|
|
|
FnCallExpression = "(" list(Expression, ",") ")"
|
|
|
|
ArrayAccessExpression = "[" Expression "]"
|
|
|
|
SliceExpression = "[" Expression "..." option(Expression) "]" option("const")
|
|
|
|
ContainerInitExpression = "{" ContainerInitBody "}"
|
|
|
|
ContainerInitBody = list(StructLiteralField, ",") | list(Expression, ",")
|
|
|
|
StructLiteralField = "." "Symbol" "=" Expression
|
|
|
|
PrefixOp = "!" | "-" | "~" | "*" | ("&" option("const")) | "?" | "%" | "%%" | "??"
|
|
|
|
PrimaryExpression = "Number" | "String" | "CharLiteral" | KeywordLiteral | GroupedExpression | GotoExpression | BlockExpression | "Symbol" | ("@" "Symbol" FnCallExpression) | ArrayType | (option("extern") FnProto) | AsmExpression | ("error" "." "Symbol")
|
|
|
|
ArrayType = "[" option(Expression) "]" option("const") TypeExpr
|
|
|
|
GotoExpression = "goto" "Symbol"
|
|
|
|
GroupedExpression = "(" Expression ")"
|
|
|
|
KeywordLiteral = "true" | "false" | "null" | "break" | "continue" | "undefined" | "error" | "type"
|
|
```
|
|
|
|
## Operator Precedence
|
|
|
|
```
|
|
x() x[] x.y
|
|
!x -x ~x *x &x ?x %x %%x
|
|
x{}
|
|
* / %
|
|
+ - ++
|
|
<< >>
|
|
&
|
|
^
|
|
|
|
|
== != < > <= >=
|
|
&&
|
|
||
|
|
?? %%
|
|
= *= /= %= += -= <<= >>= &= ^= |= &&= ||=
|
|
```
|
|
|
|
## Types
|
|
|
|
### Numeric Types
|
|
|
|
```
|
|
Type name C equivalent Description
|
|
|
|
i8 int8_t signed 8-bit integer
|
|
u8 uint8_t unsigned 8-bit integer
|
|
i16 int16_t signed 16-bit integer
|
|
u16 uint16_t unsigned 16-bit integer
|
|
i32 int32_t signed 32-bit integer
|
|
u32 uint32_t unsigned 32-bit integer
|
|
i64 int64_t signed 64-bit integer
|
|
u64 uint64_t unsigned 64-bit integer
|
|
|
|
f32 float 32-bit IEE754 floating point
|
|
f64 double 64-bit IEE754 floating point
|
|
|
|
isize intptr_t signed pointer sized integer
|
|
usize uintptr_t unsigned pointer sized integer
|
|
|
|
c_short short for ABI compatibility with C
|
|
c_ushort unsigned short for ABI compatibility with C
|
|
c_int int for ABI compatibility with C
|
|
c_uint unsigned int for ABI compatibility with C
|
|
c_long long for ABI compatibility with C
|
|
c_ulong unsigned long for ABI compatibility with C
|
|
c_longlong long long for ABI compatibility with C
|
|
c_ulonglong unsigned long long for ABI compatibility with C
|
|
c_long_double long double for ABI compatibility with C
|
|
```
|
|
|
|
### Boolean Type
|
|
|
|
The boolean type has the name `bool` and represents either true or false.
|
|
|
|
### Function Type
|
|
|
|
TODO
|
|
|
|
### Fixed-Size Array Type
|
|
|
|
Example: The string `"aoeu"` has type `[4]u8`.
|
|
|
|
The size is known at compile time and is part of the type.
|
|
|
|
### Slice Type
|
|
|
|
A slice can be obtained with the slicing syntax: `array[start...end]`
|
|
|
|
Example: `"aoeu"[0...2]` has type `[]u8`.
|
|
|
|
### Struct Type
|
|
|
|
TODO
|
|
|
|
### Enum Type
|
|
|
|
TODO
|
|
|
|
### Maybe Type
|
|
|
|
TODO
|
|
|
|
### Pure Error Type
|
|
|
|
TODO
|
|
|
|
### Error Union Type
|
|
|
|
TODO
|
|
|
|
### Pointer Type
|
|
|
|
TODO
|
|
|
|
### Unreachable Type
|
|
|
|
The unreachable type has the name `unreachable`. TODO explanation
|
|
|
|
### Void Type
|
|
|
|
The void type has the name `void`. void types are zero bits and are omitted
|
|
from codegen.
|
|
|
|
|
|
## Expressions
|
|
|
|
### Literals
|
|
|
|
#### Character and String Literals
|
|
```
|
|
Literal Example Characters Escapes Null Term Type
|
|
|
|
Byte 'H' All ASCII Byte No u8
|
|
UTF-8 Bytes "hello" All Unicode Byte & Unicode No [5]u8
|
|
UTF-8 C string c"hello" All Unicode Byte & Unicode Yes &const u8
|
|
```
|
|
|
|
```
|
|
Escape Name
|
|
|
|
\xNN hexadecimal 8-bit character code (exactly 2 digits)
|
|
\n Newline
|
|
\r Carriage return
|
|
\t Tab
|
|
\\ Backslash
|
|
\0 Null
|
|
\' Single quote
|
|
\" Double quote
|
|
```
|
|
|
|
### Unicode Escapes
|
|
|
|
Escape | Name
|
|
------------|-----------------------------------------------
|
|
\u{NNNNNN} | hexadecimal 24-bit Unicode character code (up to 6 digits)
|
|
|
|
#### Numeric Literals
|
|
|
|
```
|
|
Number literals Example Exponentiation
|
|
|
|
Decimal integer 98222 N/A
|
|
Hex integer 0xff N/A
|
|
Octal integer 0o77 N/A
|
|
Binary integer 0b11110000 N/A
|
|
Floating-point 123.0E+77 Optional
|
|
Hex floating point TODO TODO
|
|
```
|
|
|
|
### Identifiers
|
|
|
|
TODO
|
|
|
|
### Declarations
|
|
|
|
Declarations have type `void`.
|
|
|
|
#### Function Declarations
|
|
|
|
TODO
|
|
|
|
#### Variable Declarations
|
|
|
|
TODO
|
|
|
|
#### Struct Declarations
|
|
|
|
TODO
|
|
|
|
#### Enum Declarations
|
|
|
|
TODO
|
|
|
|
|
|
## Built-in Functions
|
|
|
|
Built-in functions are prefixed with `@`.
|
|
|
|
### @typeof
|
|
|
|
`@typeof(expression)`
|
|
|
|
### @sizeof
|
|
|
|
`@sizeof(type)`
|
|
|
|
### Overflow Arithmetic
|
|
|
|
Overflow arithmetic functions have defined behavior on overflow or underflow.
|
|
|
|
The functions take an integer type, two variables of the specified type, and a
|
|
pointer to a variable of the specified type where the result is stored. The
|
|
functions return a boolean value: true of overflow/underflow occurred, false
|
|
otherwise.
|
|
|
|
```
|
|
Function Operation
|
|
@add_with_overflow(T: type, a: T, b: T, x: &T) -> bool *x = a + b
|
|
@sub_with_overflow(T: type, a: T, b: T, x: &T) -> bool *x = a - b
|
|
@mul_with_overflow(T: type, a: T, b: T, x: &T) -> bool *x = a * b
|
|
```
|
|
|
|
### @memset
|
|
|
|
`@memset(dest, char, len)`
|
|
|
|
### @memcpy
|
|
|
|
`@memcpy(dest, source, len)`
|
|
|
|
### @member_count
|
|
|
|
`@member_count(enum_type)`
|
|
|
|
### Max and Min Value
|
|
|
|
`@max_value(type)`
|
|
`@min_value(type)`
|