341 lines
9.2 KiB
Markdown
341 lines
9.2 KiB
Markdown
# Language Reference
|
|
|
|
## Grammar
|
|
|
|
```
|
|
Root : many(TopLevelDecl) "EOF"
|
|
|
|
TopLevelDecl : FnDef | ExternBlock | RootExportDecl | Import | ContainerDecl | VariableDeclaration | ErrorValueDecl
|
|
|
|
ErrorValueDecl : option(FnVisibleMod) "error" "Symbol"
|
|
|
|
VariableDeclaration : option(FnVisibleMod) ("var" | "const") "Symbol" ("=" Expression | ":" PrefixOpExpression option("=" Expression))
|
|
|
|
ContainerDecl : many(Directive) option(FnVisibleMod) ("struct" | "enum") "Symbol" "{" many(StructMember) "}"
|
|
|
|
StructMember: StructField | FnDecl
|
|
|
|
StructField : "Symbol" option(":" Expression) ",")
|
|
|
|
Import : many(Directive) "import" "String" ";"
|
|
|
|
RootExportDecl : many(Directive) "export" "Symbol" "String" ";"
|
|
|
|
ExternBlock : many(Directive) "extern" "{" many(FnDecl) "}"
|
|
|
|
FnProto : many(Directive) option(FnVisibleMod) "fn" "Symbol" ParamDeclList option(PrefixOpExpression)
|
|
|
|
Directive : "#" "Symbol" "(" "String" ")"
|
|
|
|
FnVisibleMod : "pub" | "export"
|
|
|
|
FnDecl : FnProto ";"
|
|
|
|
FnDef : FnProto "=>" Block
|
|
|
|
ParamDeclList : "(" list(ParamDecl, ",") ")"
|
|
|
|
ParamDecl : option("noalias") "Symbol" ":" PrefixOpExpression | "..."
|
|
|
|
Block : "{" list(option(Statement), ";") "}"
|
|
|
|
Statement : Label | VariableDeclaration ";" | NonBlockExpression ";" | BlockExpression
|
|
|
|
Label: "Symbol" ":"
|
|
|
|
Expression : BlockExpression | NonBlockExpression
|
|
|
|
NonBlockExpression : ReturnExpression | AssignmentExpression
|
|
|
|
AsmExpression : "asm" option("volatile") "(" "String" option(AsmOutput) ")"
|
|
|
|
AsmOutput : ":" list(AsmOutputItem, ",") option(AsmInput)
|
|
|
|
AsmInput : ":" list(AsmInputItem, ",") option(AsmClobbers)
|
|
|
|
AsmOutputItem : "[" "Symbol" "]" "String" "(" ("Symbol" | "->" PrefixOpExpression) ")"
|
|
|
|
AsmInputItem : "[" "Symbol" "]" "String" "(" Expression ")"
|
|
|
|
AsmClobbers: ":" list("String", ",")
|
|
|
|
UnwrapMaybeExpression : BoolOrExpression "??" BoolOrExpression | BoolOrExpression
|
|
|
|
AssignmentExpression : UnwrapMaybeExpression AssignmentOperator UnwrapMaybeExpression | UnwrapMaybeExpression
|
|
|
|
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" "(" "Symbol" "," Expression option("," "Symbol") ")" Expression
|
|
|
|
BoolOrExpression : BoolAndExpression "||" BoolOrExpression | BoolAndExpression
|
|
|
|
ReturnExpression : option("%" | "?") "return" option(Expression)
|
|
|
|
IfExpression : IfVarExpression | IfBoolExpression
|
|
|
|
IfBoolExpression : "if" "(" Expression ")" Expression option(Else)
|
|
|
|
IfVarExpression : "if" "(" ("const" | "var") "Symbol" option(":" PrefixOpExpression) "?=" 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 : PrefixOpExpression 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 | AsmExpression | ("error" "." "Symbol")
|
|
|
|
ArrayType : "[" option(Expression) "]" option("const") PrefixOpExpression
|
|
|
|
GotoExpression: "goto" "Symbol"
|
|
|
|
GroupedExpression : "(" Expression ")"
|
|
|
|
KeywordLiteral : "true" | "false" | "null" | "break" | "continue" | "undefined" | "error"
|
|
```
|
|
|
|
## Operator Precedence
|
|
|
|
```
|
|
x() x[] x.y
|
|
!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
|
|
f128 long double 128-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
|
|
```
|
|
|
|
### 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
|
|
|
|
### Error 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
|
|
TODO
|
|
|
|
### Sizeof
|
|
TODO
|
|
|
|
### Overflow Arithmetic
|
|
Overflow arithmetic functions have defined behavior on overflow or underflow. TODO what is that behaviour?
|
|
|
|
The functions take an integer (TODO float?) 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
|
|
bool add_with_overflow(type, a: type, b: type, x: &type) *x = a + b
|
|
bool sub_with_overflow(type, a: type, b: type, x: &type) *x = a - b
|
|
bool mul_with_overflow(type, a: type, b: type, x: &type) *x = a * b
|
|
```
|
|
|
|
### Memory Operations
|
|
TODO memset and memcpy
|
|
|
|
### Value Count
|
|
TODO
|
|
|
|
### Max and Min Value
|
|
TODO
|