authorgravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2015-12-09 15:20:31-07:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2015-12-09 15:20:31-07:00
log3e8a98fa619516d0617a827a79601264a554d88b
treeb4b1b6cb2a04b7485a533482986ec879593207e1
parent28debf1fc3b1b3049dd9959fb7ecbd874a5f8084

add language reference documentation

2 files changed, 189 insertions(+), 149 deletions(-)

README.md-149
......@@ -90,152 +90,3 @@ cmake ..
9090make
9191./run_tests
9292```
93
94## Primitive Numeric Types:
95
96zig | C equivalent | Description
97-------------|------------------------|-------------------------------
98 bool | bool | unsigned 1-bit integer
99 i8 | signed char, int8_t | signed 8-bit integer
100 u8 | unsigned char, uint8_t | unsigned 8-bit integer
101 i16 | int16_t | signed 16-bit integer
102 u16 | uint16_t | unsigned 16-bit integer
103 i32 | int32_t | signed 32-bit integer
104 u32 | uint32_t | unsigned 32-bit integer
105 i64 | int64_t | signed 64-bit integer
106 u64 | uint64_t | unsigned 64-bit integer
107 f32 | float | 32-bit IEE754 floating point
108 f64 | double | 64-bit IEE754 floating point
109 f128 | long double | 128-bit IEE754 floating point
110 isize | intptr_t | signed pointer sized integer
111 usize | uintptr_t | unsigned pointer sized integer
112 c_short | short | for API compatibility with C
113 c_ushort | unsigned short | for API compatibility with C
114 c_int | int | for API compatibility with C
115 c_uint | unsigned int | for API compatibility with C
116 c_long | long | for API compatibility with C
117 c_ulong | unsigned long | for API compatibility with C
118 c_longlong | long long | for API compatibility with C
119 c_ulonglong | unsigned long long | for API compatibility with C
120
121## Grammar
122
123```
124Root : many(TopLevelDecl) token(EOF)
125
126TopLevelDecl : FnDef | ExternBlock | RootExportDecl | Use
127
128Use : many(Directive) token(Use) token(String) token(Semicolon)
129
130RootExportDecl : many(Directive) token(Export) token(Symbol) token(String) token(Semicolon)
131
132ExternBlock : many(Directive) token(Extern) token(LBrace) many(FnDecl) token(RBrace)
133
134FnProto : many(Directive) option(FnVisibleMod) token(Fn) token(Symbol) ParamDeclList option(token(Arrow) Type)
135
136Directive : token(NumberSign) token(Symbol) token(LParen) token(String) token(RParen)
137
138FnVisibleMod : token(Pub) | token(Export)
139
140FnDecl : FnProto token(Semicolon)
141
142FnDef : FnProto Block
143
144ParamDeclList : token(LParen) list(ParamDecl, token(Comma)) token(RParen)
145
146ParamDecl : token(Symbol) token(Colon) Type | token(Ellipsis)
147
148Type : token(Symbol) | token(Unreachable) | token(Void) | PointerType | ArrayType
149
150PointerType : token(Star) (token(Const) | token(Mut)) Type
151
152ArrayType : token(LBracket) Type token(Semicolon) Expression token(RBracket)
153
154Block : token(LBrace) list(option(Statement), token(Semicolon)) token(RBrace)
155
156Statement : Label | VariableDeclaration token(Semicolon) | NonBlockExpression token(Semicolon) | BlockExpression
157
158Label: token(Symbol) token(Colon)
159
160VariableDeclaration : token(Let) option(token(Mut)) token(Symbol) (token(Eq) Expression | token(Colon) Type option(token(Eq) Expression))
161
162Expression : BlockExpression | NonBlockExpression
163
164NonBlockExpression : ReturnExpression | AssignmentExpression
165
166AssignmentExpression : BoolOrExpression token(Equal) BoolOrExpression | BoolOrExpression
167
168BlockExpression : IfExpression | Block
169
170BoolOrExpression : BoolAndExpression token(BoolOr) BoolAndExpression | BoolAndExpression
171
172ReturnExpression : token(Return) option(Expression)
173
174IfExpression : token(If) Expression Block option(Else | ElseIf)
175
176ElseIf : token(Else) IfExpression
177
178Else : token(Else) Block
179
180BoolAndExpression : ComparisonExpression token(BoolAnd) ComparisonExpression | ComparisonExpression
181
182ComparisonExpression : BinaryOrExpression ComparisonOperator BinaryOrExpression | BinaryOrExpression
183
184ComparisonOperator : token(BoolEq) | token(BoolNotEq) | token(BoolLessThan) | token(BoolGreaterThan) | token(BoolLessEqual) | token(BoolGreaterEqual)
185
186BinaryOrExpression : BinaryXorExpression token(BinOr) BinaryXorExpression | BinaryXorExpression
187
188BinaryXorExpression : BinaryAndExpression token(BinXor) BinaryAndExpression | BinaryAndExpression
189
190BinaryAndExpression : BitShiftExpression token(BinAnd) BitShiftExpression | BitShiftExpression
191
192BitShiftExpression : AdditionExpression BitShiftOperator AdditionExpression | AdditionExpression
193
194BitShiftOperator : token(BitShiftLeft | token(BitShiftRight)
195
196AdditionExpression : MultiplyExpression AdditionOperator MultiplyExpression | MultiplyExpression
197
198AdditionOperator : token(Plus) | token(Minus)
199
200MultiplyExpression : CastExpression MultiplyOperator CastExpression | CastExpression
201
202MultiplyOperator : token(Star) | token(Slash) | token(Percent)
203
204CastExpression : PrefixOpExpression token(as) Type | PrefixOpExpression
205
206PrefixOpExpression : PrefixOp SuffixOpExpression | SuffixOpExpression
207
208SuffixOpExpression : PrimaryExpression option(FnCallExpression | ArrayAccessExpression)
209
210FnCallExpression : token(LParen) list(Expression, token(Comma)) token(RParen)
211
212ArrayAccessExpression : token(LBracket) Expression token(RBracket)
213
214PrefixOp : token(Not) | token(Dash) | token(Tilde)
215
216PrimaryExpression : token(Number) | token(String) | KeywordLiteral | GroupedExpression | token(Symbol) | Goto
217
218Goto: token(Goto) token(Symbol)
219
220GroupedExpression : token(LParen) Expression token(RParen)
221
222KeywordLiteral : token(Unreachable) | token(Void) | token(True) | token(False)
223```
224
225## Operator Precedence
226
227```
228x() x[]
229!x -x ~x
230as
231* / %
232+ -
233<< >>
234&
235^
236|
237== != < > <= >=
238&&
239||
240=
241```
doc/langref.md created+189
......@@ -0,0 +1,189 @@
1# Language Reference
2
3## Primitive Numeric Types:
4
5zig | C equivalent | Description
6-------------|------------------------|-------------------------------
7 bool | bool | unsigned 1-bit integer
8 i8 | int8_t | signed 8-bit integer
9 u8 | uint8_t | unsigned 8-bit integer
10 i16 | int16_t | signed 16-bit integer
11 u16 | uint16_t | unsigned 16-bit integer
12 i32 | int32_t | signed 32-bit integer
13 u32 | uint32_t | unsigned 32-bit integer
14 i64 | int64_t | signed 64-bit integer
15 u64 | uint64_t | unsigned 64-bit integer
16 f32 | float | 32-bit IEE754 floating point
17 f64 | double | 64-bit IEE754 floating point
18 f128 | long double | 128-bit IEE754 floating point
19 isize | intptr_t | signed pointer sized integer
20 usize | uintptr_t | unsigned pointer sized integer
21 c_short | short | for API compatibility with C
22 c_ushort | unsigned short | for API compatibility with C
23 c_int | int | for API compatibility with C
24 c_uint | unsigned int | for API compatibility with C
25 c_long | long | for API compatibility with C
26 c_ulong | unsigned long | for API compatibility with C
27 c_longlong | long long | for API compatibility with C
28 c_ulonglong | unsigned long long | for API compatibility with C
29
30## Grammar
31
32```
33Root : many(TopLevelDecl) token(EOF)
34
35TopLevelDecl : FnDef | ExternBlock | RootExportDecl | Use
36
37Use : many(Directive) token(Use) token(String) token(Semicolon)
38
39RootExportDecl : many(Directive) token(Export) token(Symbol) token(String) token(Semicolon)
40
41ExternBlock : many(Directive) token(Extern) token(LBrace) many(FnDecl) token(RBrace)
42
43FnProto : many(Directive) option(FnVisibleMod) token(Fn) token(Symbol) ParamDeclList option(token(Arrow) Type)
44
45Directive : token(NumberSign) token(Symbol) token(LParen) token(String) token(RParen)
46
47FnVisibleMod : token(Pub) | token(Export)
48
49FnDecl : FnProto token(Semicolon)
50
51FnDef : FnProto Block
52
53ParamDeclList : token(LParen) list(ParamDecl, token(Comma)) token(RParen)
54
55ParamDecl : token(Symbol) token(Colon) Type | token(Ellipsis)
56
57Type : token(Symbol) | token(Unreachable) | token(Void) | PointerType | ArrayType
58
59PointerType : token(Star) (token(Const) | token(Mut)) Type
60
61ArrayType : token(LBracket) Type token(Semicolon) Expression token(RBracket)
62
63Block : token(LBrace) list(option(Statement), token(Semicolon)) token(RBrace)
64
65Statement : Label | VariableDeclaration token(Semicolon) | NonBlockExpression token(Semicolon) | BlockExpression
66
67Label: token(Symbol) token(Colon)
68
69VariableDeclaration : token(Let) option(token(Mut)) token(Symbol) (token(Eq) Expression | token(Colon) Type option(token(Eq) Expression))
70
71Expression : BlockExpression | NonBlockExpression
72
73NonBlockExpression : ReturnExpression | AssignmentExpression
74
75AssignmentExpression : BoolOrExpression token(Equal) BoolOrExpression | BoolOrExpression
76
77BlockExpression : IfExpression | Block
78
79BoolOrExpression : BoolAndExpression token(BoolOr) BoolAndExpression | BoolAndExpression
80
81ReturnExpression : token(Return) option(Expression)
82
83IfExpression : token(If) Expression Block option(Else | ElseIf)
84
85ElseIf : token(Else) IfExpression
86
87Else : token(Else) Block
88
89BoolAndExpression : ComparisonExpression token(BoolAnd) ComparisonExpression | ComparisonExpression
90
91ComparisonExpression : BinaryOrExpression ComparisonOperator BinaryOrExpression | BinaryOrExpression
92
93ComparisonOperator : token(BoolEq) | token(BoolNotEq) | token(BoolLessThan) | token(BoolGreaterThan) | token(BoolLessEqual) | token(BoolGreaterEqual)
94
95BinaryOrExpression : BinaryXorExpression token(BinOr) BinaryXorExpression | BinaryXorExpression
96
97BinaryXorExpression : BinaryAndExpression token(BinXor) BinaryAndExpression | BinaryAndExpression
98
99BinaryAndExpression : BitShiftExpression token(BinAnd) BitShiftExpression | BitShiftExpression
100
101BitShiftExpression : AdditionExpression BitShiftOperator AdditionExpression | AdditionExpression
102
103BitShiftOperator : token(BitShiftLeft | token(BitShiftRight)
104
105AdditionExpression : MultiplyExpression AdditionOperator MultiplyExpression | MultiplyExpression
106
107AdditionOperator : token(Plus) | token(Minus)
108
109MultiplyExpression : CastExpression MultiplyOperator CastExpression | CastExpression
110
111MultiplyOperator : token(Star) | token(Slash) | token(Percent)
112
113CastExpression : PrefixOpExpression token(as) Type | PrefixOpExpression
114
115PrefixOpExpression : PrefixOp SuffixOpExpression | SuffixOpExpression
116
117SuffixOpExpression : PrimaryExpression option(FnCallExpression | ArrayAccessExpression)
118
119FnCallExpression : token(LParen) list(Expression, token(Comma)) token(RParen)
120
121ArrayAccessExpression : token(LBracket) Expression token(RBracket)
122
123PrefixOp : token(Not) | token(Dash) | token(Tilde)
124
125PrimaryExpression : token(Number) | token(String) | KeywordLiteral | GroupedExpression | token(Symbol) | Goto
126
127Goto: token(Goto) token(Symbol)
128
129GroupedExpression : token(LParen) Expression token(RParen)
130
131KeywordLiteral : token(Unreachable) | token(Void) | token(True) | token(False)
132```
133
134## Operator Precedence
135
136```
137x() x[]
138!x -x ~x
139as
140* / %
141+ -
142<< >>
143&
144^
145|
146== != < > <= >=
147&&
148||
149= += -=
150```
151
152## Literals
153
154### Characters and Strings
155
156 | Example | Characters | Escapes | Null Terminated
157-------------------------------------------------------------------------------
158 Byte | 'H' | All ASCII | Byte | No
159 UTF-8 Bytes | "hello" | All Unicode | Byte & Unicode | No
160 UTF-8 C string | c"hello" | All Unicode | Byte & Unicode | Yes
161
162### Byte Escapes
163
164 | Name
165-----------------------------------------------
166 \x7F | 8-bit character code (exactly 2 digits)
167 \n | Newline
168 \r | Carriage return
169 \t | Tab
170 \\ | Backslash
171 \0 | Null
172 \' | Single quote
173 \" | Double quote
174
175### Unicode Escapes
176
177 | Name
178----------------------------------------------------------
179 \u{7FFF} | 24-bit Unicode character code (up to 6 digits)
180
181### Numbers
182
183 Number literals | Example | Exponentiation
184-------------------------------------------
185 Decimal integer | 98222 | N/A
186 Hex integer | 0xff | N/A
187 Octal integer | 0o77 | N/A
188 Binary integer | 0b11110000 | N/A
189 Floating-point | 123.0E+77 | Optional