Mercurial Hosting > luan
comparison website/src/manual.html.luan @ 562:7cc9d4a53d3b
remove SimplyHTML from documentation
author | Franklin Schmidt <fschmidt@gmail.com> |
---|---|
date | Wed, 24 Jun 2015 14:20:00 -0600 |
parents | d02f43598ba3 |
children | 22bfd8a2eaee |
comparison
equal
deleted
inserted
replaced
561:363d07e26549 | 562:7cc9d4a53d3b |
---|---|
1 local Luan = require "luan:Luan" | 1 local Luan = require "luan:Luan" |
2 local Io = require "luan:Io" | 2 local Io = require "luan:Io" |
3 local Html = require "luan:Html" | 3 local Html = require "luan:Html" |
4 local Http = require "luan:http/Http" | 4 local Http = require "luan:http/Http" |
5 local Shared = require "site:/Shared" | 5 local Shared = require "site:/Shared" |
6 local heading_options = Shared.heading_options | |
7 | 6 |
8 | 7 |
9 return function() | 8 return function() |
10 Io.stdout = Http.response.text_writer() | 9 Io.stdout = Http.response.text_writer() |
11 %> | 10 %> |
12 <html> | 11 <html> |
13 <head> | 12 <head> |
14 <% Html.simply_html_head() %> | |
15 <title>Luan Reference Manual</title> | 13 <title>Luan Reference Manual</title> |
14 <style> | |
15 @import "/site.css"; | |
16 </style> | |
16 </head> | 17 </head> |
17 <body> | 18 <body> |
18 | 19 |
19 <div container> | 20 <div container> |
20 <% Shared.header() %> | 21 <% Shared.header() %> |
21 | 22 |
22 <h1>Luan Reference Manual</h1> | 23 <h1>Luan Reference Manual</h1> |
23 | 24 |
24 <p> | 25 <p small> |
25 <small> | |
26 Original copyright © 2015 Lua.org, PUC-Rio. | 26 Original copyright © 2015 Lua.org, PUC-Rio. |
27 Freely available under the terms of the | 27 Freely available under the terms of the |
28 <a href="http://www.lua.org/license.html">Lua license</a>. | 28 <a href="http://www.lua.org/license.html">Lua license</a>. |
29 Modified for Luan. | 29 Modified for Luan. |
30 </small> | |
31 </p> | 30 </p> |
32 | 31 |
33 <hr/> | 32 <hr/> |
34 | 33 |
35 <h2>Contents</h2> | 34 <h2>Contents</h2> |
36 | 35 |
37 <div margin-bottom="1em"><a href="#intro">Introduction</a></div> | 36 <div contents><a href="#intro">Introduction</a></div> |
38 | 37 |
39 <div margin-bottom="1em"> | 38 <div contents> |
40 <a href="#basic">Basic Concepts</a> | 39 <a href="#basic">Basic Concepts</a> |
41 <ul> | 40 <ul> |
42 <li><a href="#types">Values and Types</a></li> | 41 <li><a href="#types">Values and Types</a></li> |
43 <li><a href="#env">Environments</a></li> | 42 <li><a href="#env">Environments</a></li> |
44 <li><a href="#error">Error Handling</a></li> | 43 <li><a href="#error">Error Handling</a></li> |
45 <li><a href="#meta">Metatables and Metamethods</a></li> | 44 <li><a href="#meta">Metatables and Metamethods</a></li> |
46 <li><a href="#gc">Garbage Collection</a></li> | 45 <li><a href="#gc">Garbage Collection</a></li> |
47 </ul> | 46 </ul> |
48 </div> | 47 </div> |
49 | 48 |
50 <div margin-bottom="1em"> | 49 <div contents> |
51 <a href="#lang">The Language</a> | 50 <a href="#lang">The Language</a> |
52 <ul> | 51 <ul> |
53 <li><a href="#lex">Lexical Conventions</a></li> | 52 <li><a href="#lex">Lexical Conventions</a></li> |
54 <li><a href="#vars">Variables</a></li> | 53 <li><a href="#vars">Variables</a></li> |
55 <li> | 54 <li> |
83 </li> | 82 </li> |
84 <li><a href="#visibility">Visibility Rules</a></li> | 83 <li><a href="#visibility">Visibility Rules</a></li> |
85 </ul> | 84 </ul> |
86 </div> | 85 </div> |
87 | 86 |
88 <div margin-bottom="1em"> | 87 <div contents> |
89 <a href="#libs">Standard Libraries</a> | 88 <a href="#libs">Standard Libraries</a> |
90 <ul> | 89 <ul> |
91 <li><a href="#default_lib">Default Environment</a></li> | 90 <li><a href="#default_lib">Default Environment</a></li> |
92 <li><a href="#luan_lib">Basic Functions</a></li> | 91 <li><a href="#luan_lib">Basic Functions</a></li> |
93 <li><a href="#package_lib">Modules</a></li> | 92 <li><a href="#package_lib">Modules</a></li> |
96 </div> | 95 </div> |
97 | 96 |
98 <hr/> | 97 <hr/> |
99 | 98 |
100 | 99 |
101 <h2 <%=heading_options%> ><a name="intro">Introduction</a></h2> | 100 <h2 heading><a name="intro">Introduction</a></h2> |
102 | 101 |
103 <p>Luan is a high level programming language based on <a href="http://www.lua.org">Lua</a>. A great strength of Lua is its simplicity and Luan takes this even further, being even simpler than Lua. The goal is to provide a simple programming language for the casual programmer with as few concepts as possible so that one can quickly learn the language and then easily understand any code written in Luan.</p> | 102 <p>Luan is a high level programming language based on <a href="http://www.lua.org">Lua</a>. A great strength of Lua is its simplicity and Luan takes this even further, being even simpler than Lua. The goal is to provide a simple programming language for the casual programmer with as few concepts as possible so that one can quickly learn the language and then easily understand any code written in Luan.</p> |
104 | 103 |
105 <p>Luan is implemented in Java and is tightly coupled with Java. So it makes a great scripting language for Java programmers.</p> | 104 <p>Luan is implemented in Java and is tightly coupled with Java. So it makes a great scripting language for Java programmers.</p> |
106 | 105 |
107 <p>Unlike Lua which is meant to be embedded, Luan is meant to be a full scripting language. This done not by adding feature to Luan, but rather by providing a complete set of libraries.</p> | 106 <p>Unlike Lua which is meant to be embedded, Luan is meant to be a full scripting language. This done not by adding feature to Luan, but rather by providing a complete set of libraries.</p> |
108 | 107 |
109 | 108 |
110 <h2 <%=heading_options%> ><a name="basic">Basic Concepts</a></h2> | 109 <h2 heading><a name="basic">Basic Concepts</a></h2> |
111 | 110 |
112 <p>This section describes the basic concepts of the language.</p> | 111 <p>This section describes the basic concepts of the language.</p> |
113 | 112 |
114 <h3 <%=heading_options%> ><a name="types">Values and Types</a></h3> | 113 <h3 heading><a name="types">Values and Types</a></h3> |
115 | 114 |
116 <p> | 115 <p> |
117 Luan is a <i>dynamically typed language</i>. | 116 Luan is a <em>dynamically typed language</em>. |
118 This means that | 117 This means that |
119 variables do not have types; only values do. | 118 variables do not have types; only values do. |
120 There are no type definitions in the language. | 119 There are no type definitions in the language. |
121 All values carry their own type. | 120 All values carry their own type. |
122 | 121 |
123 | 122 |
124 <p> | 123 <p> |
125 All values in Luan are <i>first-class values</i>. | 124 All values in Luan are <em>first-class values</em>. |
126 This means that all values can be stored in variables, | 125 This means that all values can be stored in variables, |
127 passed as arguments to other functions, and returned as results. | 126 passed as arguments to other functions, and returned as results. |
128 | 127 |
129 | 128 |
130 <p> | 129 <p> |
131 There are eight basic types in Luan: | 130 There are eight basic types in Luan: |
132 <i>nil</i>, <i>boolean</i>, <i>number</i>, | 131 <em>nil</em>, <em>boolean</em>, <em>number</em>, |
133 <i>string</i>, <i>binary</i>, <i>function</i>, <i>java</i>, | 132 <em>string</em>, <em>binary</em>, <em>function</em>, <em>java</em>, |
134 and <i>table</i>. | 133 and <em>table</em>. |
135 <i>Nil</i> is the type of the value <b>nil</b>, | 134 <em>Nil</em> is the type of the value <b>nil</b>, |
136 whose main property is to be different from any other value; | 135 whose main property is to be different from any other value; |
137 it usually represents the absence of a useful value. | 136 it usually represents the absence of a useful value. |
138 <i>Nil</i> is implemented as the Java value <i>null</i>. | 137 <em>Nil</em> is implemented as the Java value <em>null</em>. |
139 <i>Boolean</i> is the type of the values <b>false</b> and <b>true</b>. | 138 <em>Boolean</em> is the type of the values <b>false</b> and <b>true</b>. |
140 <i>Boolean</i> is implemented as the Java class <i>Boolean</i>. | 139 <em>Boolean</em> is implemented as the Java class <em>Boolean</em>. |
141 <i>Number</i> represents both | 140 <em>Number</em> represents both |
142 integer numbers and real (floating-point) numbers. | 141 integer numbers and real (floating-point) numbers. |
143 <i>Number</i> is implemented as the Java class <i>Number</i>. Any Java subclass of <i>Number</i> is allowed and this is invisible to the Luan user. Operations on numbers follow the same rules of | 142 <em>Number</em> is implemented as the Java class <em>Number</em>. Any Java subclass of <em>Number</em> is allowed and this is invisible to the Luan user. Operations on numbers follow the same rules of |
144 the underlying Java implementation. | 143 the underlying Java implementation. |
145 | 144 |
146 <i>String</i> is implemented as the Java class <i>String</i>. | 145 <em>String</em> is implemented as the Java class <em>String</em>. |
147 <i>Binary</i> is implemented as the Java type <i>byte[]</i>. | 146 <em>Binary</em> is implemented as the Java type <em>byte[]</em>. |
148 | 147 |
149 | 148 |
150 <p> | 149 <p> |
151 Luan can call (and manipulate) functions written in Luan and | 150 Luan can call (and manipulate) functions written in Luan and |
152 functions written in Java (see <a href="#fn_calls">Function Calls</a>). | 151 functions written in Java (see <a href="#fn_calls">Function Calls</a>). |
153 Both are represented by the type <i>function</i>. | 152 Both are represented by the type <em>function</em>. |
154 | 153 |
155 | 154 |
156 <p> | 155 <p> |
157 The type <i>java</i> is provided to allow arbitrary Java objects to | 156 The type <em>java</em> is provided to allow arbitrary Java objects to |
158 be stored in Luan variables. | 157 be stored in Luan variables. |
159 A <i>java</i> value is a Java object that isn't one of the standard Luan types. | 158 A <em>java</em> value is a Java object that isn't one of the standard Luan types. |
160 Java values have no predefined operations in Luan, | 159 Java values have no predefined operations in Luan, |
161 except assignment and identity test. | 160 except assignment and identity test. |
162 Java values are useful when Java access is enabled in Luan | 161 Java values are useful when Java access is enabled in Luan |
163 | 162 |
164 | 163 |
165 | 164 |
166 <p> | 165 <p> |
167 The type <i>table</i> implements associative arrays, | 166 The type <em>table</em> implements associative arrays, |
168 that is, arrays that can be indexed not only with numbers, | 167 that is, arrays that can be indexed not only with numbers, |
169 but with any Luan value except <b>nil</b>. | 168 but with any Luan value except <b>nil</b>. |
170 Tables can be <i>heterogeneous</i>; | 169 Tables can be <em>heterogeneous</em>; |
171 that is, they can contain values of all types (except <b>nil</b>). | 170 that is, they can contain values of all types (except <b>nil</b>). |
172 Any key with value <b>nil</b> is not considered part of the table. | 171 Any key with value <b>nil</b> is not considered part of the table. |
173 Conversely, any key that is not part of a table has | 172 Conversely, any key that is not part of a table has |
174 an associated value <b>nil</b>. | 173 an associated value <b>nil</b>. |
175 | 174 |
178 Tables are the sole data-structuring mechanism in Luan; | 177 Tables are the sole data-structuring mechanism in Luan; |
179 they can be used to represent ordinary arrays, sequences, | 178 they can be used to represent ordinary arrays, sequences, |
180 symbol tables, sets, records, graphs, trees, etc. | 179 symbol tables, sets, records, graphs, trees, etc. |
181 To represent records, Luan uses the field name as an index. | 180 To represent records, Luan uses the field name as an index. |
182 The language supports this representation by | 181 The language supports this representation by |
183 providing <tt>a.name</tt> as syntactic sugar for <tt>a["name"]</tt>. | 182 providing <code>a.name</code> as syntactic sugar for <code>a["name"]</code>. |
184 There are several convenient ways to create tables in Luan | 183 There are several convenient ways to create tables in Luan |
185 (see <a href="#constructors">Table Constructors</a>). | 184 (see <a href="#constructors">Table Constructors</a>). |
186 | 185 |
187 | 186 |
188 <p> | 187 <p> |
189 We use the term <i>sequence</i> to denote a table where | 188 We use the term <em>sequence</em> to denote a table where |
190 the set of all positive numeric keys is equal to {1..<i>n</i>} | 189 the set of all positive numeric keys is equal to {1..<em>n</em>} |
191 for some non-negative integer <i>n</i>, | 190 for some non-negative integer <em>n</em>, |
192 which is called the length of the sequence (see <a href="#length">The Length Operator</a>). | 191 which is called the length of the sequence (see <a href="#length">The Length Operator</a>). |
193 | 192 |
194 | 193 |
195 <p> | 194 <p> |
196 Like indices, | 195 Like indices, |
197 the values of table fields can be of any type. | 196 the values of table fields can be of any type. |
198 In particular, | 197 In particular, |
199 because functions are first-class values, | 198 because functions are first-class values, |
200 table fields can contain functions. | 199 table fields can contain functions. |
201 Thus tables can also carry <i>methods</i> (see <a href="#fn_def">Function Definitions</a>). | 200 Thus tables can also carry <em>methods</em> (see <a href="#fn_def">Function Definitions</a>). |
202 | 201 |
203 | 202 |
204 <p> | 203 <p> |
205 The indexing of tables follows | 204 The indexing of tables follows |
206 the definition of raw equality in the language. | 205 the definition of raw equality in the language. |
207 The expressions <tt>a[i]</tt> and <tt>a[j]</tt> | 206 The expressions <code>a[i]</code> and <code>a[j]</code> |
208 denote the same table element | 207 denote the same table element |
209 if and only if <tt>i</tt> and <tt>j</tt> are raw equal | 208 if and only if <code>i</code> and <code>j</code> are raw equal |
210 (that is, equal without metamethods). | 209 (that is, equal without metamethods). |
211 In particular, floats with integral values | 210 In particular, floats with integral values |
212 are equal to their respective integers | 211 are equal to their respective integers |
213 (e.g., <tt>1.0 == 1</tt>). | 212 (e.g., <code>1.0 == 1</code>). |
214 | 213 |
215 | 214 |
216 <p> | 215 <p> |
217 Luan values are <i>objects</i>: | 216 Luan values are <em>objects</em>: |
218 variables do not actually <i>contain</i> values, | 217 variables do not actually <em>contain</em> values, |
219 only <i>references</i> to them. | 218 only <em>references</em> to them. |
220 Assignment, parameter passing, and function returns | 219 Assignment, parameter passing, and function returns |
221 always manipulate references to values; | 220 always manipulate references to values; |
222 these operations do not imply any kind of copy. | 221 these operations do not imply any kind of copy. |
223 | 222 |
224 | 223 |
225 <p> | 224 <p> |
226 The library function <a href="#Luan.type"><tt>Luan.type</tt></a> returns a string describing the type | 225 The library function <a href="#Luan.type"><code>Luan.type</code></a> returns a string describing the type |
227 of a given value. | 226 of a given value. |
228 | 227 |
229 | 228 |
230 | 229 |
231 | 230 |
232 | 231 |
233 <h3 <%=heading_options%> ><a name="env">Environments</a></h3> | 232 <h3 heading><a name="env">Environments</a></h3> |
234 | 233 |
235 <p> | 234 <p> |
236 The environment of a chunk starts with only two local variables: <tt><a href="#require">require</a></tt> and <tt><a href="#java">java</a></tt>. These are functions are used to load and access libraries and other modules. All other variables must be added to the environment using <a href="http://localhost:8080/manual.html#local_stmt">local declarations</a>. | 235 The environment of a chunk starts with only two local variables: <code><a href="#require">require</a></code> and <code><a href="#java">java</a></code>. These are functions are used to load and access libraries and other modules. All other variables must be added to the environment using <a href="http://localhost:8080/manual.html#local_stmt">local declarations</a>. |
237 | 236 |
238 <p> | 237 <p> |
239 As will be discussed in <a href="#vars">Variables</a> and <a href=#assignment">Assignment</a>, | 238 As will be discussed in <a href="#vars">Variables</a> and <a href=#assignment">Assignment</a>, |
240 any reference to a free name | 239 any reference to a free name |
241 (that is, a name not bound to any declaration) <tt>var</tt> | 240 (that is, a name not bound to any declaration) <code>var</code> |
242 can be syntactically translated to <tt>_ENV.var</tt> if <tt>_ENV</tt> is defined. | 241 can be syntactically translated to <code>_ENV.var</code> if <code>_ENV</code> is defined. |
243 | 242 |
244 | 243 |
245 <h3 <%=heading_options%> ><a name="error">Error Handling</a></h3> | 244 <h3 heading><a name="error">Error Handling</a></h3> |
246 | 245 |
247 <p> | 246 <p> |
248 Luan code can explicitly generate an error by calling the | 247 Luan code can explicitly generate an error by calling the |
249 <a href="#Luan.error"><tt>error</tt></a> function. | 248 <a href="#Luan.error"><code>error</code></a> function. |
250 If you need to catch errors in Luan, | 249 If you need to catch errors in Luan, |
251 you can use <a href="#Luan.pcall"><tt>pcall</tt></a> or <a href="#Luan.try"><tt>try</tt></a> | 250 you can use <a href="#Luan.pcall"><code>pcall</code></a> or <a href="#Luan.try"><code>try</code></a> |
252 to call a given function in <i>protected mode</i>. | 251 to call a given function in <em>protected mode</em>. |
253 | 252 |
254 | 253 |
255 <p> | 254 <p> |
256 Whenever there is an error, | 255 Whenever there is an error, |
257 an <i>error table</i> | 256 an <em>error table</em> |
258 is propagated with information about the error. | 257 is propagated with information about the error. |
259 See <a href="#Luan.new_error"><tt>Luan.new_error</tt></a>. | 258 See <a href="#Luan.new_error"><code>Luan.new_error</code></a>. |
260 | 259 |
261 | 260 |
262 | 261 |
263 <h3 <%=heading_options%> ><a name="meta">Metatables and Metamethods</a></h3> | 262 <h3 heading><a name="meta">Metatables and Metamethods</a></h3> |
264 | 263 |
265 <p> | 264 <p> |
266 Every table in Luan can have a <i>metatable</i>. | 265 Every table in Luan can have a <em>metatable</em>. |
267 This <i>metatable</i> is an ordinary Luan table | 266 This <em>metatable</em> is an ordinary Luan table |
268 that defines the behavior of the original value | 267 that defines the behavior of the original value |
269 under certain special operations. | 268 under certain special operations. |
270 You can change several aspects of the behavior | 269 You can change several aspects of the behavior |
271 of operations over a value by setting specific fields in its metatable. | 270 of operations over a value by setting specific fields in its metatable. |
272 For instance, when a table is the operand of an addition, | 271 For instance, when a table is the operand of an addition, |
273 Luan checks for a function in the field "<tt>__add</tt>" of the table's metatable. | 272 Luan checks for a function in the field "<code>__add</code>" of the table's metatable. |
274 If it finds one, | 273 If it finds one, |
275 Luan calls this function to perform the addition. | 274 Luan calls this function to perform the addition. |
276 | 275 |
277 | 276 |
278 <p> | 277 <p> |
279 The keys in a metatable are derived from the <i>event</i> names; | 278 The keys in a metatable are derived from the <em>event</em> names; |
280 the corresponding values are called <ii>metamethods</i>. | 279 the corresponding values are called <ii>metamethods</em>. |
281 In the previous example, the event is <tt>"add"</tt> | 280 In the previous example, the event is <code>"add"</code> |
282 and the metamethod is the function that performs the addition. | 281 and the metamethod is the function that performs the addition. |
283 | 282 |
284 | 283 |
285 <p> | 284 <p> |
286 You can query the metatable of any table | 285 You can query the metatable of any table |
287 using the <a href="#Luan.get_metatable"><tt>get_metatable</tt></a> function. | 286 using the <a href="#Luan.get_metatable"><code>get_metatable</code></a> function. |
288 | 287 |
289 | 288 |
290 <p> | 289 <p> |
291 You can replace the metatable of tables | 290 You can replace the metatable of tables |
292 using the <a href="#Luan.set_metatable"><tt>set_metatable</tt></a> function. | 291 using the <a href="#Luan.set_metatable"><code>set_metatable</code></a> function. |
293 | 292 |
294 | 293 |
295 <p> | 294 <p> |
296 A metatable controls how a table behaves in | 295 A metatable controls how a table behaves in |
297 arithmetic operations, bitwise operations, | 296 arithmetic operations, bitwise operations, |
300 | 299 |
301 <p> | 300 <p> |
302 A detailed list of events controlled by metatables is given next. | 301 A detailed list of events controlled by metatables is given next. |
303 Each operation is identified by its corresponding event name. | 302 Each operation is identified by its corresponding event name. |
304 The key for each event is a string with its name prefixed by | 303 The key for each event is a string with its name prefixed by |
305 two underscores, '<tt>__</tt>'; | 304 two underscores, '<code>__</code>'; |
306 for instance, the key for operation "add" is the | 305 for instance, the key for operation "add" is the |
307 string "<tt>__add</tt>". | 306 string "<code>__add</code>". |
308 Note that queries for metamethods are always raw; | 307 Note that queries for metamethods are always raw; |
309 the access to a metamethod does not invoke other metamethods. | 308 the access to a metamethod does not invoke other metamethods. |
310 You can emulate how Luan queries a metamethod for an object <tt>obj</tt> | 309 You can emulate how Luan queries a metamethod for an object <code>obj</code> |
311 with the following code: | 310 with the following code: |
312 | 311 |
313 <p><tt><pre> | 312 <pre> |
314 raw_get(get_metatable(obj) or {}, "__" .. event_name) | 313 raw_get(get_metatable(obj) or {}, "__" .. event_name) |
315 </pre></tt></p> | 314 </pre> |
316 | 315 |
317 <p> | 316 <p> |
318 Here are the events: | 317 Here are the events: |
319 | 318 |
320 <ul> | 319 <ul> |
321 | 320 |
322 <li><p><b>"add": </b> | 321 <li><p><b>"add": </b> |
323 the <tt>+</tt> operation. | 322 the <code>+</code> operation. |
324 | 323 |
325 If any operand for an addition is a table, | 324 If any operand for an addition is a table, |
326 Luan will try to call a metamethod. | 325 Luan will try to call a metamethod. |
327 First, Luan will check the first operand (even if it is valid). | 326 First, Luan will check the first operand (even if it is valid). |
328 If that operand does not define a metamethod for the "<tt>__add</tt>" event, | 327 If that operand does not define a metamethod for the "<code>__add</code>" event, |
329 then Luan will check the second operand. | 328 then Luan will check the second operand. |
330 If Luan can find a metamethod, | 329 If Luan can find a metamethod, |
331 it calls the metamethod with the two operands as arguments, | 330 it calls the metamethod with the two operands as arguments, |
332 and the result of the call | 331 and the result of the call |
333 (adjusted to one value) | 332 (adjusted to one value) |
335 Otherwise, | 334 Otherwise, |
336 it raises an error. | 335 it raises an error. |
337 </li> | 336 </li> |
338 | 337 |
339 <li><p><b>"sub": </b> | 338 <li><p><b>"sub": </b> |
340 the <tt>-</tt> operation. | 339 the <code>-</code> operation. |
341 | 340 |
342 Behavior similar to the "add" operation. | 341 Behavior similar to the "add" operation. |
343 </li> | 342 </li> |
344 | 343 |
345 <li><p><b>"mul": </b> | 344 <li><p><b>"mul": </b> |
346 the <tt>*</tt> operation. | 345 the <code>*</code> operation. |
347 | 346 |
348 Behavior similar to the "add" operation. | 347 Behavior similar to the "add" operation. |
349 </li> | 348 </li> |
350 | 349 |
351 <li><p><b>"div": </b> | 350 <li><p><b>"div": </b> |
352 the <tt>/</tt> operation. | 351 the <code>/</code> operation. |
353 | 352 |
354 Behavior similar to the "add" operation. | 353 Behavior similar to the "add" operation. |
355 </li> | 354 </li> |
356 | 355 |
357 <li><p><b>"mod": </b> | 356 <li><p><b>"mod": </b> |
358 the <tt>%</tt> operation. | 357 the <code>%</code> operation. |
359 | 358 |
360 Behavior similar to the "add" operation. | 359 Behavior similar to the "add" operation. |
361 </li> | 360 </li> |
362 | 361 |
363 <li><p><b>"pow": </b> | 362 <li><p><b>"pow": </b> |
364 the <tt>^</tt> (exponentiation) operation. | 363 the <code>^</code> (exponentiation) operation. |
365 | 364 |
366 Behavior similar to the "add" operation. | 365 Behavior similar to the "add" operation. |
367 </li> | 366 </li> |
368 | 367 |
369 <li><p><b>"unm": </b> | 368 <li><p><b>"unm": </b> |
370 the <tt>-</tt> (unary minus) operation. | 369 the <code>-</code> (unary minus) operation. |
371 | 370 |
372 Behavior similar to the "add" operation. | 371 Behavior similar to the "add" operation. |
373 </li> | 372 </li> |
374 | 373 |
375 <li><p><b>"concat": </b> | 374 <li><p><b>"concat": </b> |
376 the <tt>..</tt> (concatenation) operation. | 375 the <code>..</code> (concatenation) operation. |
377 | 376 |
378 Behavior similar to the "add" operation. | 377 Behavior similar to the "add" operation. |
379 </li> | 378 </li> |
380 | 379 |
381 <li><p><b>"len": </b> | 380 <li><p><b>"len": </b> |
382 the <tt>#</tt> (length) operation. | 381 the <code>#</code> (length) operation. |
383 | 382 |
384 If there is a metamethod, | 383 If there is a metamethod, |
385 Luan calls it with the object as argument, | 384 Luan calls it with the object as argument, |
386 and the result of the call | 385 and the result of the call |
387 (always adjusted to one value) | 386 (always adjusted to one value) |
390 then Luan uses the table length operation (see <a href="#length">The Length Operator</a>). | 389 then Luan uses the table length operation (see <a href="#length">The Length Operator</a>). |
391 Otherwise, Luan raises an error. | 390 Otherwise, Luan raises an error. |
392 </li> | 391 </li> |
393 | 392 |
394 <li><p><b>"eq": </b> | 393 <li><p><b>"eq": </b> |
395 the <tt>==</tt> (equal) operation. | 394 the <code>==</code> (equal) operation. |
396 | 395 |
397 Behavior similar to the "add" operation, | 396 Behavior similar to the "add" operation, |
398 except that Luan will try a metamethod only when the values | 397 except that Luan will try a metamethod only when the values |
399 being compared are both tables | 398 being compared are both tables |
400 and they are not primitively equal. | 399 and they are not primitively equal. |
401 The result of the call is always converted to a boolean. | 400 The result of the call is always converted to a boolean. |
402 </li> | 401 </li> |
403 | 402 |
404 <li><p><b>"lt": </b> | 403 <li><p><b>"lt": </b> |
405 the <tt><</tt> (less than) operation. | 404 the <code><</code> (less than) operation. |
406 | 405 |
407 Behavior similar to the "add" operation. | 406 Behavior similar to the "add" operation. |
408 The result of the call is always converted to a boolean. | 407 The result of the call is always converted to a boolean. |
409 </li> | 408 </li> |
410 | 409 |
411 <li><p><b>"le": </b> | 410 <li><p><b>"le": </b> |
412 the <tt><=</tt> (less equal) operation. | 411 the <code><=</code> (less equal) operation. |
413 | 412 |
414 Unlike other operations, | 413 Unlike other operations, |
415 The less-equal operation can use two different events. | 414 The less-equal operation can use two different events. |
416 First, Luan looks for the "<tt>__le</tt>" metamethod in both operands, | 415 First, Luan looks for the "<code>__le</code>" metamethod in both operands, |
417 like in the "lt" operation. | 416 like in the "lt" operation. |
418 If it cannot find such a metamethod, | 417 If it cannot find such a metamethod, |
419 then it will try the "<tt>__lt</tt>" event, | 418 then it will try the "<code>__lt</code>" event, |
420 assuming that <tt>a <= b</tt> is equivalent to <tt>not (b < a)</tt>. | 419 assuming that <code>a <= b</code> is equivalent to <code>not (b < a)</code>. |
421 As with the other comparison operators, | 420 As with the other comparison operators, |
422 the result is always a boolean. | 421 the result is always a boolean. |
423 </li> | 422 </li> |
424 | 423 |
425 <li><p><b>"index": </b> | 424 <li><p><b>"index": </b> |
426 The indexing access <tt>table[key]</tt>. | 425 The indexing access <code>table[key]</code>. |
427 | 426 |
428 This event happens | 427 This event happens |
429 when <tt>key</tt> is not present in <tt>table</tt>. | 428 when <code>key</code> is not present in <code>table</code>. |
430 The metamethod is looked up in <tt>table</tt>. | 429 The metamethod is looked up in <code>table</code>. |
431 | 430 |
432 | 431 |
433 <p> | 432 <p> |
434 Despite the name, | 433 Despite the name, |
435 the metamethod for this event can be any type. | 434 the metamethod for this event can be any type. |
436 If it is a function, | 435 If it is a function, |
437 it is called with <tt>table</tt> and <tt>key</tt> as arguments. | 436 it is called with <code>table</code> and <code>key</code> as arguments. |
438 Otherwise | 437 Otherwise |
439 the final result is the result of indexing this metamethod object with <tt>key</tt>. | 438 the final result is the result of indexing this metamethod object with <code>key</code>. |
440 (This indexing is regular, not raw, | 439 (This indexing is regular, not raw, |
441 and therefore can trigger another metamethod if the metamethod object is a table.) | 440 and therefore can trigger another metamethod if the metamethod object is a table.) |
442 </li> | 441 </li> |
443 | 442 |
444 <li><p><b>"new_index": </b> | 443 <li><p><b>"new_index": </b> |
445 The indexing assignment <tt>table[key] = value</tt>. | 444 The indexing assignment <code>table[key] = value</code>. |
446 | 445 |
447 Like the index event, | 446 Like the index event, |
448 this event happens when | 447 this event happens when |
449 when <tt>key</tt> is not present in <tt>table</tt>. | 448 when <code>key</code> is not present in <code>table</code>. |
450 The metamethod is looked up in <tt>table</tt>. | 449 The metamethod is looked up in <code>table</code>. |
451 | 450 |
452 | 451 |
453 <p> | 452 <p> |
454 Like with indexing, | 453 Like with indexing, |
455 the metamethod for this event can be either a function or a table. | 454 the metamethod for this event can be either a function or a table. |
456 If it is a function, | 455 If it is a function, |
457 it is called with <tt>table</tt>, <tt>key</tt>, and <tt>value</tt> as arguments. | 456 it is called with <code>table</code>, <code>key</code>, and <code>value</code> as arguments. |
458 If it is a table, | 457 If it is a table, |
459 Luan does an indexing assignment to this table with the same key and value. | 458 Luan does an indexing assignment to this table with the same key and value. |
460 (This assignment is regular, not raw, | 459 (This assignment is regular, not raw, |
461 and therefore can trigger another metamethod.) | 460 and therefore can trigger another metamethod.) |
462 | 461 |
463 | 462 |
464 <p> | 463 <p> |
465 Whenever there is a "new_index" metamethod, | 464 Whenever there is a "new_index" metamethod, |
466 Luan does not perform the primitive assignment. | 465 Luan does not perform the primitive assignment. |
467 (If necessary, | 466 (If necessary, |
468 the metamethod itself can call <a href="#Luan.raw_set"><tt>raw_set</tt></a> | 467 the metamethod itself can call <a href="#Luan.raw_set"><code>raw_set</code></a> |
469 to do the assignment.) | 468 to do the assignment.) |
470 </li> | 469 </li> |
471 | 470 |
472 <li><p><b>"call": </b> | 471 <li><p><b>"call": </b> |
473 The call operation <tt>func(args)</tt>. | 472 The call operation <code>func(args)</code>. |
474 | 473 |
475 This event happens when Luan tries to call a table. | 474 This event happens when Luan tries to call a table. |
476 The metamethod is looked up in <tt>func</tt>. | 475 The metamethod is looked up in <code>func</code>. |
477 If present, | 476 If present, |
478 the metamethod is called with <tt>func</tt> as its first argument, | 477 the metamethod is called with <code>func</code> as its first argument, |
479 followed by the arguments of the original call (<tt>args</tt>). | 478 followed by the arguments of the original call (<code>args</code>). |
480 </li> | 479 </li> |
481 | 480 |
482 </ul> | 481 </ul> |
483 | 482 |
484 | 483 |
485 | 484 |
486 | 485 |
487 <h3 <%=heading_options%> ><a name="gc">Garbage Collection</a></h3> | 486 <h3 heading><a name="gc">Garbage Collection</a></h3> |
488 | 487 |
489 <p> | 488 <p> |
490 Luan uses Java's garbage collection. | 489 Luan uses Java's garbage collection. |
491 | 490 |
492 | 491 |
493 | 492 |
494 | 493 |
495 | 494 |
496 <h2 <%=heading_options%> ><a name="lang">The Language</a></h2> | 495 <h2 heading><a name="lang">The Language</a></h2> |
497 | 496 |
498 <p> | 497 <p> |
499 This section describes the lexis, the syntax, and the semantics of Luan. | 498 This section describes the lexis, the syntax, and the semantics of Luan. |
500 In other words, | 499 In other words, |
501 this section describes | 500 this section describes |
505 | 504 |
506 | 505 |
507 <p> | 506 <p> |
508 Language constructs will be explained using the usual extended BNF notation, | 507 Language constructs will be explained using the usual extended BNF notation, |
509 in which | 508 in which |
510 {<i>a</i>} means 0 or more <i>a</i>'s, and | 509 {<em>a</em>} means 0 or more <em>a</em>'s, and |
511 [<i>a</i>] means an optional <i>a</i>. | 510 [<em>a</em>] means an optional <em>a</em>. |
512 Non-terminals are shown like non-terminal, | 511 Non-terminals are shown like non-terminal, |
513 keywords are shown like <b>kword</b>, | 512 keywords are shown like <b>kword</b>, |
514 and other terminal symbols are shown like ‘<b>=</b>’. | 513 and other terminal symbols are shown like ‘<b>=</b>’. |
515 The complete syntax of Luan can be found in <a href="#9">§9</a> | 514 The complete syntax of Luan can be found in <a href="#9">§9</a> |
516 at the end of this manual. | 515 at the end of this manual. |
517 | 516 |
518 | 517 |
519 | 518 |
520 <h3 <%=heading_options%> ><a name="lex">Lexical Conventions</a></h3> | 519 <h3 heading><a name="lex">Lexical Conventions</a></h3> |
521 | 520 |
522 <p> | 521 <p> |
523 Luan ignores spaces and comments | 522 Luan ignores spaces and comments |
524 between lexical elements (tokens), | 523 between lexical elements (tokens), |
525 except as delimiters between names and keywords. | 524 except as delimiters between names and keywords. |
526 Luan generally considers the end of a line to be the end of a statement. This catches errors and encourages readability. The exception to this is in paranthesis ( <i>(...)</i>, <i>[...]</i>, and <i>{...}</i> ) where the end of line is treated as white space. | 525 Luan generally considers the end of a line to be the end of a statement. This catches errors and encourages readability. The exception to this is in paranthesis ( <em>(...)</em>, <em>[...]</em>, and <em>{...}</em> ) where the end of line is treated as white space. |
527 | 526 |
528 <p> | 527 <p> |
529 <i>Names</i> | 528 <em>Names</em> |
530 (also called <i>identifiers</i>) | 529 (also called <em>identifiers</em>) |
531 in Luan can be any string of letters, | 530 in Luan can be any string of letters, |
532 digits, and underscores, | 531 digits, and underscores, |
533 not beginning with a digit. | 532 not beginning with a digit. |
534 Identifiers are used to name variables, table fields, and labels. | 533 Identifiers are used to name variables, table fields, and labels. |
535 | 534 |
536 | 535 |
537 <p> | 536 <p> |
538 The following <i>keywords</i> are reserved | 537 The following <em>keywords</em> are reserved |
539 and cannot be used as names: | 538 and cannot be used as names: |
540 | 539 |
541 | 540 |
542 <p><tt><pre> | 541 <pre> |
543 and break do else elseif end | 542 and break do else elseif end |
544 false for function goto if in | 543 false for function goto if in |
545 local nil not or repeat return | 544 local nil not or repeat return |
546 then true until while | 545 then true until while |
547 </pre></tt></p> | 546 </pre> |
548 | 547 |
549 <p> | 548 <p> |
550 Luan is a case-sensitive language: | 549 Luan is a case-sensitive language: |
551 <tt>and</tt> is a reserved word, but <tt>And</tt> and <tt>AND</tt> | 550 <code>and</code> is a reserved word, but <code>And</code> and <code>AND</code> |
552 are two different, valid names. | 551 are two different, valid names. |
553 | 552 |
554 | 553 |
555 <p> | 554 <p> |
556 The following strings denote other tokens: | 555 The following strings denote other tokens: |
557 | 556 |
558 <p><tt><pre> | 557 <pre> |
559 + - * / % ^ # | 558 + - * / % ^ # |
560 & ~ | << >> // | 559 & ~ | << >> // |
561 == ~= <= >= < > = | 560 == ~= <= >= < > = |
562 ( ) { } [ ] :: | 561 ( ) { } [ ] :: |
563 ; : , . .. ... | 562 ; : , . .. ... |
564 </pre></tt></p> | 563 </pre> |
565 | 564 |
566 <p> | 565 <p> |
567 <i>Literal strings</i> | 566 <em>Literal strings</em> |
568 can be delimited by matching single or double quotes, | 567 can be delimited by matching single or double quotes, |
569 and can contain the following C-like escape sequences: | 568 and can contain the following C-like escape sequences: |
570 '<tt>\a</tt>' (bell), | 569 '<code>\a</code>' (bell), |
571 '<tt>\b</tt>' (backspace), | 570 '<code>\b</code>' (backspace), |
572 '<tt>\f</tt>' (form feed), | 571 '<code>\f</code>' (form feed), |
573 '<tt>\n</tt>' (newline), | 572 '<code>\n</code>' (newline), |
574 '<tt>\r</tt>' (carriage return), | 573 '<code>\r</code>' (carriage return), |
575 '<tt>\t</tt>' (horizontal tab), | 574 '<code>\t</code>' (horizontal tab), |
576 '<tt>\v</tt>' (vertical tab), | 575 '<code>\v</code>' (vertical tab), |
577 '<tt>\\</tt>' (backslash), | 576 '<code>\\</code>' (backslash), |
578 '<tt>\"</tt>' (quotation mark [double quote]), | 577 '<code>\"</code>' (quotation mark [double quote]), |
579 and '<tt>\'</tt>' (apostrophe [single quote]). | 578 and '<code>\'</code>' (apostrophe [single quote]). |
580 A backslash followed by a real newline | 579 A backslash followed by a real newline |
581 results in a newline in the string. | 580 results in a newline in the string. |
582 The escape sequence '<tt>\z</tt>' skips the following span | 581 The escape sequence '<code>\z</code>' skips the following span |
583 of white-space characters, | 582 of white-space characters, |
584 including line breaks; | 583 including line breaks; |
585 it is particularly useful to break and indent a long literal string | 584 it is particularly useful to break and indent a long literal string |
586 into multiple lines without adding the newlines and spaces | 585 into multiple lines without adding the newlines and spaces |
587 into the string contents. | 586 into the string contents. |
588 | 587 |
589 | 588 |
590 <p> | 589 <p> |
591 Luan can specify any character in a literal string by its numerical value. | 590 Luan can specify any character in a literal string by its numerical value. |
592 This can be done | 591 This can be done |
593 with the escape sequence <tt>\x<i>XX</i></tt>, | 592 with the escape sequence <code>\x<em>XX</em></code>, |
594 where <i>XX</i> is a sequence of exactly two hexadecimal digits, | 593 where <em>XX</em> is a sequence of exactly two hexadecimal digits, |
595 or with the escape sequence <tt>\<i>ddd</i></tt>, | 594 or with the escape sequence <code>\<em>ddd</em></code>, |
596 where <i>ddd</i> is a sequence of up to three decimal digits. | 595 where <em>ddd</em> is a sequence of up to three decimal digits. |
597 (Note that if a decimal escape sequence is to be followed by a digit, | 596 (Note that if a decimal escape sequence is to be followed by a digit, |
598 it must be expressed using exactly three digits.) | 597 it must be expressed using exactly three digits.) |
599 | 598 |
600 | 599 |
601 <p> | 600 <p> |
602 Literal strings can also be defined using a long format | 601 Literal strings can also be defined using a long format |
603 enclosed by <i>long brackets</i>. | 602 enclosed by <em>long brackets</em>. |
604 We define an <i>opening long bracket of level <i>n</i></i> as an opening | 603 We define an <em>opening long bracket of level <em>n</em></em> as an opening |
605 square bracket followed by <i>n</i> equal signs followed by another | 604 square bracket followed by <em>n</em> equal signs followed by another |
606 opening square bracket. | 605 opening square bracket. |
607 So, an opening long bracket of level 0 is written as <tt>[[</tt>, | 606 So, an opening long bracket of level 0 is written as <code>[[</code>, |
608 an opening long bracket of level 1 is written as <tt>[=[</tt>, | 607 an opening long bracket of level 1 is written as <code>[=[</code>, |
609 and so on. | 608 and so on. |
610 A <i>closing long bracket</i> is defined similarly; | 609 A <em>closing long bracket</em> is defined similarly; |
611 for instance, | 610 for instance, |
612 a closing long bracket of level 4 is written as <tt>]====]</tt>. | 611 a closing long bracket of level 4 is written as <code>]====]</code>. |
613 A <i>long literal</i> starts with an opening long bracket of any level and | 612 A <em>long literal</em> starts with an opening long bracket of any level and |
614 ends at the first closing long bracket of the same level. | 613 ends at the first closing long bracket of the same level. |
615 It can contain any text except a closing bracket of the same level. | 614 It can contain any text except a closing bracket of the same level. |
616 Literals in this bracketed form can run for several lines, | 615 Literals in this bracketed form can run for several lines, |
617 do not interpret any escape sequences, | 616 do not interpret any escape sequences, |
618 and ignore long brackets of any other level. | 617 and ignore long brackets of any other level. |
638 when the opening long bracket is immediately followed by a newline, | 637 when the opening long bracket is immediately followed by a newline, |
639 the newline is not included in the string. | 638 the newline is not included in the string. |
640 As an example | 639 As an example |
641 the five literal strings below denote the same string: | 640 the five literal strings below denote the same string: |
642 | 641 |
643 <p><tt><pre> | 642 <pre> |
644 a = 'alo\n123"' | 643 a = 'alo\n123"' |
645 a = "alo\n123\"" | 644 a = "alo\n123\"" |
646 a = '\97lo\10\04923"' | 645 a = '\97lo\10\04923"' |
647 a = [[alo | 646 a = [[alo |
648 123"]] | 647 123"]] |
649 a = [==[ | 648 a = [==[ |
650 alo | 649 alo |
651 123"]==] | 650 123"]==] |
652 </pre></tt></p> | 651 </pre> |
653 | 652 |
654 <p> | 653 <p> |
655 A <i>numerical constant</i> (or <i>numeral</i>) | 654 A <em>numerical constant</em> (or <em>numeral</em>) |
656 can be written with an optional fractional part | 655 can be written with an optional fractional part |
657 and an optional decimal exponent, | 656 and an optional decimal exponent, |
658 marked by a letter '<tt>e</tt>' or '<tt>E</tt>'. | 657 marked by a letter '<code>e</code>' or '<code>E</code>'. |
659 Luan also accepts hexadecimal constants, | 658 Luan also accepts hexadecimal constants, |
660 which start with <tt>0x</tt> or <tt>0X</tt>. | 659 which start with <code>0x</code> or <code>0X</code>. |
661 Hexadecimal constants also accept an optional fractional part | 660 Hexadecimal constants also accept an optional fractional part |
662 plus an optional binary exponent, | 661 plus an optional binary exponent, |
663 marked by a letter '<tt>p</tt>' or '<tt>P</tt>'. | 662 marked by a letter '<code>p</code>' or '<code>P</code>'. |
664 A numeric constant with a fractional dot or an exponent | 663 A numeric constant with a fractional dot or an exponent |
665 denotes a float; | 664 denotes a float; |
666 otherwise it denotes an integer. | 665 otherwise it denotes an integer. |
667 Examples of valid integer constants are | 666 Examples of valid integer constants are |
668 | 667 |
669 <p><tt><pre> | 668 <pre> |
670 3 345 0xff 0xBEBADA | 669 3 345 0xff 0xBEBADA |
671 </pre></tt></p> | 670 </pre> |
672 | 671 |
673 <p> | 672 <p> |
674 Examples of valid float constants are | 673 Examples of valid float constants are |
675 | 674 |
676 <p><tt><pre> | 675 <pre> |
677 3.0 3.1416 314.16e-2 0.31416E1 34e1 | 676 3.0 3.1416 314.16e-2 0.31416E1 34e1 |
678 0x0.1E 0xA23p-4 0X1.921FB54442D18P+1 | 677 0x0.1E 0xA23p-4 0X1.921FB54442D18P+1 |
679 </pre></tt></p> | 678 </pre> |
680 | 679 |
681 <p> | 680 <p> |
682 A <i>comment</i> starts with a double hyphen (<tt>--</tt>) | 681 A <em>comment</em> starts with a double hyphen (<code>--</code>) |
683 anywhere outside a string. | 682 anywhere outside a string. |
684 If the text immediately after <tt>--</tt> is not an opening long bracket, | 683 If the text immediately after <code>--</code> is not an opening long bracket, |
685 the comment is a <i>short comment</i>, | 684 the comment is a <em>short comment</em>, |
686 which runs until the end of the line. | 685 which runs until the end of the line. |
687 Otherwise, it is a <i>long comment</i>, | 686 Otherwise, it is a <em>long comment</em>, |
688 which runs until the corresponding closing long bracket. | 687 which runs until the corresponding closing long bracket. |
689 Long comments are frequently used to disable code temporarily. | 688 Long comments are frequently used to disable code temporarily. |
690 | 689 |
691 | 690 |
692 | 691 |
693 | 692 |
694 | 693 |
695 <h3 <%=heading_options%> ><a name="vars">Variables</a></h3> | 694 <h3 heading><a name="vars">Variables</a></h3> |
696 | 695 |
697 <p> | 696 <p> |
698 Variables are places that store values. | 697 Variables are places that store values. |
699 There are three kinds of variables in Luan: | 698 There are three kinds of variables in Luan: |
700 global variables, local variables, and table fields. | 699 global variables, local variables, and table fields. |
702 <p> | 701 <p> |
703 A single name can denote a global variable or a local variable | 702 A single name can denote a global variable or a local variable |
704 (or a function's formal parameter, | 703 (or a function's formal parameter, |
705 which is a particular kind of local variable): | 704 which is a particular kind of local variable): |
706 | 705 |
707 <p><tt><pre> | 706 <pre> |
708 var ::= Name | 707 var ::= Name |
709 </pre></tt></p> | 708 </pre> |
710 | 709 |
711 <p> | 710 <p> |
712 Name denotes identifiers, as defined in <a href="#lex">Lexical Conventions</a>. | 711 Name denotes identifiers, as defined in <a href="#lex">Lexical Conventions</a>. |
713 | 712 |
714 <p> | 713 <p> |
715 Local variables are <i>lexically scoped</i>: | 714 Local variables are <em>lexically scoped</em>: |
716 local variables can be freely accessed by functions | 715 local variables can be freely accessed by functions |
717 defined inside their scope (see <a href="#visibility">Visibility Rules</a>). | 716 defined inside their scope (see <a href="#visibility">Visibility Rules</a>). |
718 | 717 |
719 | 718 |
720 <p> | 719 <p> |
721 Before the first assignment to a variable, its value is <b>nil</b>. | 720 Before the first assignment to a variable, its value is <b>nil</b>. |
722 | 721 |
723 <p> | 722 <p> |
724 Square brackets are used to index a table: | 723 Square brackets are used to index a table: |
725 | 724 |
726 <p><tt><pre> | 725 <pre> |
727 var ::= prefixexp ‘<b>[</b>’ exp ‘<b>]</b>’ | 726 var ::= prefixexp ‘<b>[</b>’ exp ‘<b>]</b>’ |
728 </pre></tt></p> | 727 </pre> |
729 | 728 |
730 <p> | 729 <p> |
731 The meaning of accesses to table fields can be changed via metatables. | 730 The meaning of accesses to table fields can be changed via metatables. |
732 An access to an indexed variable <tt>t[i]</tt> is equivalent to | 731 An access to an indexed variable <code>t[i]</code> is equivalent to |
733 a call <tt>gettable_event(t,i)</tt>. | 732 a call <code>gettable_event(t,i)</code>. |
734 (See <a href="#meta">Metatables and Metamethods</a> for a complete description of the | 733 (See <a href="#meta">Metatables and Metamethods</a> for a complete description of the |
735 <tt>gettable_event</tt> function. | 734 <code>gettable_event</code> function. |
736 This function is not defined or callable in Luan. | 735 This function is not defined or callable in Luan. |
737 We use it here only for explanatory purposes.) | 736 We use it here only for explanatory purposes.) |
738 | 737 |
739 | 738 |
740 <p> | 739 <p> |
741 The syntax <tt>var.Name</tt> is just syntactic sugar for | 740 The syntax <code>var.Name</code> is just syntactic sugar for |
742 <tt>var["Name"]</tt>: | 741 <code>var["Name"]</code>: |
743 | 742 |
744 <p><tt><pre> | 743 <pre> |
745 var ::= prefixexp ‘<b>.</b>’ Name | 744 var ::= prefixexp ‘<b>.</b>’ Name |
746 </pre></tt></p> | 745 </pre> |
747 | 746 |
748 <p> | 747 <p> |
749 Global variables are not available by default. To enable global variable, you must define <tt>_ENV</tt> as a local variable whose value is a table. If <tt>_ENV</tt> is not defined, then an unrecognized variable name will produce a compile error. If <tt>_ENV</tt> is defined then an access to an unrecognized variable name will be consider a global variable. So then an acces to global variable <tt>x</tt> | 748 Global variables are not available by default. To enable global variable, you must define <code>_ENV</code> as a local variable whose value is a table. If <code>_ENV</code> is not defined, then an unrecognized variable name will produce a compile error. If <code>_ENV</code> is defined then an access to an unrecognized variable name will be consider a global variable. So then an acces to global variable <code>x</code> |
750 is equivalent to <tt>_ENV.x</tt>. | 749 is equivalent to <code>_ENV.x</code>. |
751 Due to the way that chunks are compiled, | 750 Due to the way that chunks are compiled, |
752 <tt>_ENV</tt> is never a global name (see <a href="#env">Environments</a>). | 751 <code>_ENV</code> is never a global name (see <a href="#env">Environments</a>). |
753 | 752 |
754 | 753 |
755 | 754 |
756 | 755 |
757 | 756 |
758 <h3 <%=heading_options%> ><a name="stmts">Statements</a></h3> | 757 <h3 heading><a name="stmts">Statements</a></h3> |
759 | 758 |
760 <p> | 759 <p> |
761 Luan supports an almost conventional set of statements, | 760 Luan supports an almost conventional set of statements, |
762 similar to those in Pascal or C. | 761 similar to those in Pascal or C. |
763 This set includes | 762 This set includes |
764 assignments, control structures, function calls, | 763 assignments, control structures, function calls, |
765 and variable declarations. | 764 and variable declarations. |
766 | 765 |
767 | 766 |
768 | 767 |
769 <h4 <%=heading_options%> ><a name="blocks">Blocks</a></h4> | 768 <h4 heading><a name="blocks">Blocks</a></h4> |
770 | 769 |
771 <p> | 770 <p> |
772 A block is a list of statements, | 771 A block is a list of statements, |
773 which are executed sequentially: | 772 which are executed sequentially: |
774 | 773 |
775 <p><tt><pre> | 774 <pre> |
776 block ::= {stat} | 775 block ::= {stat} |
777 </pre></tt></p> | 776 </pre> |
778 | 777 |
779 <p> | 778 <p> |
780 Luan has <i>empty statements</i> | 779 Luan has <em>empty statements</em> |
781 that allow you to separate statements with semicolons, | 780 that allow you to separate statements with semicolons, |
782 start a block with a semicolon | 781 start a block with a semicolon |
783 or write two semicolons in sequence: | 782 or write two semicolons in sequence: |
784 | 783 |
785 <p><tt><pre> | 784 <pre> |
786 stat ::= ‘<b>;</b>’ | 785 stat ::= ‘<b>;</b>’ |
787 </pre></tt></p> | 786 </pre> |
788 | 787 |
789 <p> | 788 <p> |
790 A block can be explicitly delimited to produce a single statement: | 789 A block can be explicitly delimited to produce a single statement: |
791 | 790 |
792 <p><tt><pre> | 791 <pre> |
793 stat ::= <b>do</b> block <b>end</b> | 792 stat ::= <b>do</b> block <b>end</b> |
794 </pre></tt></p> | 793 </pre> |
795 | 794 |
796 <p> | 795 <p> |
797 Explicit blocks are useful | 796 Explicit blocks are useful |
798 to control the scope of variable declarations. | 797 to control the scope of variable declarations. |
799 Explicit blocks are also sometimes used to | 798 Explicit blocks are also sometimes used to |
802 | 801 |
803 | 802 |
804 | 803 |
805 | 804 |
806 | 805 |
807 <h4 <%=heading_options%> ><a name="chunks">Chunks</a></h4> | 806 <h4 heading><a name="chunks">Chunks</a></h4> |
808 | 807 |
809 <p> | 808 <p> |
810 The unit of compilation of Luan is called a <i>chunk</i>. | 809 The unit of compilation of Luan is called a <em>chunk</em>. |
811 Syntactically, | 810 Syntactically, |
812 a chunk is simply a block: | 811 a chunk is simply a block: |
813 | 812 |
814 <p><tt><pre> | 813 <pre> |
815 chunk ::= block | 814 chunk ::= block |
816 </pre></tt></p> | 815 </pre> |
817 | 816 |
818 <p> | 817 <p> |
819 Luan handles a chunk as the body of an anonymous function | 818 Luan handles a chunk as the body of an anonymous function |
820 with a variable number of arguments | 819 with a variable number of arguments |
821 (see <a href="#fn_def">Function Definitions</a>). | 820 (see <a href="#fn_def">Function Definitions</a>). |
824 | 823 |
825 | 824 |
826 <p> | 825 <p> |
827 A chunk can be stored in a file or in a string inside the host program. | 826 A chunk can be stored in a file or in a string inside the host program. |
828 To execute a chunk, | 827 To execute a chunk, |
829 Luan first <i>loads</i> it, | 828 Luan first <em>loads</em> it, |
830 compiling the chunk's code, | 829 compiling the chunk's code, |
831 and then Luan executes the compiled code. | 830 and then Luan executes the compiled code. |
832 | 831 |
833 | 832 |
834 | 833 |
835 | 834 |
836 | 835 |
837 <h4 <%=heading_options%> ><a name="assignment">Assignment</a></h4> | 836 <h4 heading><a name="assignment">Assignment</a></h4> |
838 | 837 |
839 <p> | 838 <p> |
840 Luan allows multiple assignments. | 839 Luan allows multiple assignments. |
841 Therefore, the syntax for assignment | 840 Therefore, the syntax for assignment |
842 defines a list of variables on the left side | 841 defines a list of variables on the left side |
843 and a list of expressions on the right side. | 842 and a list of expressions on the right side. |
844 The elements in both lists are separated by commas: | 843 The elements in both lists are separated by commas: |
845 | 844 |
846 <p><tt><pre> | 845 <pre> |
847 stat ::= varlist ‘<b>=</b>’ explist | 846 stat ::= varlist ‘<b>=</b>’ explist |
848 varlist ::= var {‘<b>,</b>’ var} | 847 varlist ::= var {‘<b>,</b>’ var} |
849 explist ::= exp {‘<b>,</b>’ exp} | 848 explist ::= exp {‘<b>,</b>’ exp} |
850 </pre></tt></p> | 849 </pre> |
851 | 850 |
852 <p> | 851 <p> |
853 Expressions are discussed in <a href="#expressions">Expressions</a>. | 852 Expressions are discussed in <a href="#expressions">Expressions</a>. |
854 | 853 |
855 | 854 |
856 <p> | 855 <p> |
857 Before the assignment, | 856 Before the assignment, |
858 the list of values is <i>adjusted</i> to the length of | 857 the list of values is <em>adjusted</em> to the length of |
859 the list of variables. | 858 the list of variables. |
860 If there are more values than needed, | 859 If there are more values than needed, |
861 the excess values are thrown away. | 860 the excess values are thrown away. |
862 If there are fewer values than needed, | 861 If there are fewer values than needed, |
863 the list is extended with as many <b>nil</b>'s as needed. | 862 the list is extended with as many <b>nil</b>'s as needed. |
870 <p> | 869 <p> |
871 The assignment statement first evaluates all its expressions | 870 The assignment statement first evaluates all its expressions |
872 and only then the assignments are performed. | 871 and only then the assignments are performed. |
873 Thus the code | 872 Thus the code |
874 | 873 |
875 <p><tt><pre> | 874 <pre> |
876 i = 3 | 875 i = 3 |
877 i, a[i] = i+1, 20 | 876 i, a[i] = i+1, 20 |
878 </pre></tt></p> | 877 </pre> |
879 | 878 |
880 <p> | 879 <p> |
881 sets <tt>a[3]</tt> to 20, without affecting <tt>a[4]</tt> | 880 sets <code>a[3]</code> to 20, without affecting <code>a[4]</code> |
882 because the <tt>i</tt> in <tt>a[i]</tt> is evaluated (to 3) | 881 because the <code>i</code> in <code>a[i]</code> is evaluated (to 3) |
883 before it is assigned 4. | 882 before it is assigned 4. |
884 Similarly, the line | 883 Similarly, the line |
885 | 884 |
886 <p><tt><pre> | 885 <pre> |
887 x, y = y, x | 886 x, y = y, x |
888 </pre></tt></p> | 887 </pre> |
889 | 888 |
890 <p> | 889 <p> |
891 exchanges the values of <tt>x</tt> and <tt>y</tt>, | 890 exchanges the values of <code>x</code> and <code>y</code>, |
892 and | 891 and |
893 | 892 |
894 <p><tt><pre> | 893 <pre> |
895 x, y, z = y, z, x | 894 x, y, z = y, z, x |
896 </pre></tt></p> | 895 </pre> |
897 | 896 |
898 <p> | 897 <p> |
899 cyclically permutes the values of <tt>x</tt>, <tt>y</tt>, and <tt>z</tt>. | 898 cyclically permutes the values of <code>x</code>, <code>y</code>, and <code>z</code>. |
900 | 899 |
901 | 900 |
902 <p> | 901 <p> |
903 The meaning of assignments to global variables | 902 The meaning of assignments to global variables |
904 and table fields can be changed via metatables. | 903 and table fields can be changed via metatables. |
905 An assignment to an indexed variable <tt>t[i] = val</tt> is equivalent to | 904 An assignment to an indexed variable <code>t[i] = val</code> is equivalent to |
906 <tt>settable_event(t,i,val)</tt>. | 905 <code>settable_event(t,i,val)</code>. |
907 (See <a href="#meta">Metatables and Metamethods</a> for a complete description of the | 906 (See <a href="#meta">Metatables and Metamethods</a> for a complete description of the |
908 <tt>settable_event</tt> function. | 907 <code>settable_event</code> function. |
909 This function is not defined or callable in Luan. | 908 This function is not defined or callable in Luan. |
910 We use it here only for explanatory purposes.) | 909 We use it here only for explanatory purposes.) |
911 | 910 |
912 | 911 |
913 <p> | 912 <p> |
914 An assignment to a global name <tt>x = val</tt> | 913 An assignment to a global name <code>x = val</code> |
915 is equivalent to the assignment | 914 is equivalent to the assignment |
916 <tt>_ENV.x = val</tt> (see <a href="#env">Environments</a>). | 915 <code>_ENV.x = val</code> (see <a href="#env">Environments</a>). |
917 Global names are only available when <tt>_ENV</tt> is defined. | 916 Global names are only available when <code>_ENV</code> is defined. |
918 | 917 |
919 | 918 |
920 | 919 |
921 <h4 <%=heading_options%> ><a name="control">Control Structures</a></h4> | 920 <h4 heading><a name="control">Control Structures</a></h4> |
922 | 921 |
923 <p> | 922 <p> |
924 The control structures | 923 The control structures |
925 <b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and | 924 <b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and |
926 familiar syntax: | 925 familiar syntax: |
927 | 926 |
928 <p><tt><pre> | 927 <pre> |
929 stat ::= <b>while</b> exp <b>do</b> block <b>end</b> | 928 stat ::= <b>while</b> exp <b>do</b> block <b>end</b> |
930 stat ::= <b>repeat</b> block <b>until</b> exp | 929 stat ::= <b>repeat</b> block <b>until</b> exp |
931 stat ::= <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> | 930 stat ::= <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> |
932 </pre></tt></p> | 931 </pre> |
933 | 932 |
934 <p> | 933 <p> |
935 Luan also has a <b>for</b> statement (see <a href="#for">For Statement</a>). | 934 Luan also has a <b>for</b> statement (see <a href="#for">For Statement</a>). |
936 | 935 |
937 | 936 |
954 The <b>break</b> statement terminates the execution of a | 953 The <b>break</b> statement terminates the execution of a |
955 <b>while</b>, <b>repeat</b>, or <b>for</b> loop, | 954 <b>while</b>, <b>repeat</b>, or <b>for</b> loop, |
956 skipping to the next statement after the loop: | 955 skipping to the next statement after the loop: |
957 | 956 |
958 | 957 |
959 <p><tt><pre> | 958 <pre> |
960 stat ::= <b>break</b> | 959 stat ::= <b>break</b> |
961 </pre></tt></p> | 960 </pre> |
962 | 961 |
963 <p> | 962 <p> |
964 A <b>break</b> ends the innermost enclosing loop. | 963 A <b>break</b> ends the innermost enclosing loop. |
965 | 964 |
966 | 965 |
970 (which is an anonymous function). | 969 (which is an anonymous function). |
971 | 970 |
972 Functions can return more than one value, | 971 Functions can return more than one value, |
973 so the syntax for the <b>return</b> statement is | 972 so the syntax for the <b>return</b> statement is |
974 | 973 |
975 <p><tt><pre> | 974 <pre> |
976 stat ::= <b>return</b> [explist] [‘<b>;</b>’] | 975 stat ::= <b>return</b> [explist] [‘<b>;</b>’] |
977 </pre></tt></p> | 976 </pre> |
978 | 977 |
979 | 978 |
980 | 979 |
981 | 980 |
982 <h4 <%=heading_options%> ><a name="for">For Statement</a></h4> | 981 <h4 heading><a name="for">For Statement</a></h4> |
983 | 982 |
984 <p> | 983 <p> |
985 The <b>for</b> statement works over functions, | 984 The <b>for</b> statement works over functions, |
986 called <i>iterators</i>. | 985 called <em>iterators</em>. |
987 On each iteration, the iterator function is called to produce a new value, | 986 On each iteration, the iterator function is called to produce a new value, |
988 stopping when this new value is <b>nil</b>. | 987 stopping when this new value is <b>nil</b>. |
989 The <b>for</b> loop has the following syntax: | 988 The <b>for</b> loop has the following syntax: |
990 | 989 |
991 <p><tt><pre> | 990 <pre> |
992 stat ::= <b>for</b> namelist <b>in</b> exp <b>do</b> block <b>end</b> | 991 stat ::= <b>for</b> namelist <b>in</b> exp <b>do</b> block <b>end</b> |
993 namelist ::= Name {‘<b>,</b>’ Name} | 992 namelist ::= Name {‘<b>,</b>’ Name} |
994 </pre></tt></p> | 993 </pre> |
995 | 994 |
996 <p> | 995 <p> |
997 A <b>for</b> statement like | 996 A <b>for</b> statement like |
998 | 997 |
999 <p><tt><pre> | 998 <pre> |
1000 for <i>var_1</i>, ···, <i>var_n</i> in <i>exp</i> do <i>block</i> end | 999 for <em>var_1</em>, ···, <em>var_n</em> in <em>exp</em> do <em>block</em> end |
1001 </pre></tt></p> | 1000 </pre> |
1002 | 1001 |
1003 <p> | 1002 <p> |
1004 is equivalent to the code: | 1003 is equivalent to the code: |
1005 | 1004 |
1006 <p><tt><pre> | 1005 <pre> |
1007 do | 1006 do |
1008 local <i>f</i> = <i>exp</i> | 1007 local <em>f</em> = <em>exp</em> |
1009 while true do | 1008 while true do |
1010 local <i>var_1</i>, ···, <i>var_n</i> = <i>f</i>() | 1009 local <em>var_1</em>, ···, <em>var_n</em> = <em>f</em>() |
1011 if <i>var_1</i> == nil then break end | 1010 if <em>var_1</em> == nil then break end |
1012 <i>block</i> | 1011 <em>block</em> |
1013 end | 1012 end |
1014 end | 1013 end |
1015 </pre></tt></p> | 1014 </pre> |
1016 | 1015 |
1017 <p> | 1016 <p> |
1018 Note the following: | 1017 Note the following: |
1019 | 1018 |
1020 <ul> | 1019 <ul> |
1021 | 1020 |
1022 <li> | 1021 <li> |
1023 <tt><i>exp</i></tt> is evaluated only once. | 1022 <code><em>exp</em></code> is evaluated only once. |
1024 Its result is an <i>iterator</i> function. | 1023 Its result is an <em>iterator</em> function. |
1025 </li> | 1024 </li> |
1026 | 1025 |
1027 <li> | 1026 <li> |
1028 <tt><i>f</i></tt> is an invisible variable. | 1027 <code><em>f</em></code> is an invisible variable. |
1029 The name is here for explanatory purposes only. | 1028 The name is here for explanatory purposes only. |
1030 </li> | 1029 </li> |
1031 | 1030 |
1032 <li> | 1031 <li> |
1033 You can use <b>break</b> to exit a <b>for</b> loop. | 1032 You can use <b>break</b> to exit a <b>for</b> loop. |
1034 </li> | 1033 </li> |
1035 | 1034 |
1036 <li> | 1035 <li> |
1037 The loop variables <tt><i>var_i</i></tt> are local to the loop; | 1036 The loop variables <code><em>var_i</em></code> are local to the loop; |
1038 you cannot use their values after the <b>for</b> ends. | 1037 you cannot use their values after the <b>for</b> ends. |
1039 If you need these values, | 1038 If you need these values, |
1040 then assign them to other variables before breaking or exiting the loop. | 1039 then assign them to other variables before breaking or exiting the loop. |
1041 </li> | 1040 </li> |
1042 | 1041 |
1043 </ul> | 1042 </ul> |
1044 | 1043 |
1045 | 1044 |
1046 | 1045 |
1047 | 1046 |
1048 <h4 <%=heading_options%> ><a name="fn_stmt">Function Calls as Statements</a></h4> | 1047 <h4 heading><a name="fn_stmt">Function Calls as Statements</a></h4> |
1049 | 1048 |
1050 <p> | 1049 <p> |
1051 To allow possible side-effects, | 1050 To allow possible side-effects, |
1052 function calls can be executed as statements: | 1051 function calls can be executed as statements: |
1053 | 1052 |
1054 <p><tt><pre> | 1053 <pre> |
1055 stat ::= functioncall | 1054 stat ::= functioncall |
1056 </pre></tt></p> | 1055 </pre> |
1057 | 1056 |
1058 <p> | 1057 <p> |
1059 In this case, all returned values are thrown away. | 1058 In this case, all returned values are thrown away. |
1060 Function calls are explained in <a href="#fn_calls">Function Calls</a>. | 1059 Function calls are explained in <a href="#fn_calls">Function Calls</a>. |
1061 | 1060 |
1062 | 1061 |
1063 | 1062 |
1064 <h4 <%=heading_options%> ><a name="local_stmt">Local Declarations</a></h4> | 1063 <h4 heading><a name="local_stmt">Local Declarations</a></h4> |
1065 | 1064 |
1066 <p> | 1065 <p> |
1067 Local variables can be declared anywhere inside a block. | 1066 Local variables can be declared anywhere inside a block. |
1068 The declaration can include an initial assignment: | 1067 The declaration can include an initial assignment: |
1069 | 1068 |
1070 <p><tt><pre> | 1069 <pre> |
1071 stat ::= <b>local</b> namelist [‘<b>=</b>’ explist] | 1070 stat ::= <b>local</b> namelist [‘<b>=</b>’ explist] |
1072 </pre></tt></p> | 1071 </pre> |
1073 | 1072 |
1074 <p> | 1073 <p> |
1075 If present, an initial assignment has the same semantics | 1074 If present, an initial assignment has the same semantics |
1076 of a multiple assignment (see <a href="#assignment">Assignment</a>). | 1075 of a multiple assignment (see <a href="#assignment">Assignment</a>). |
1077 Otherwise, all variables are initialized with <b>nil</b>. | 1076 Otherwise, all variables are initialized with <b>nil</b>. |
1084 | 1083 |
1085 <p> | 1084 <p> |
1086 The visibility rules for local variables are explained in <a href="#visibility">Visibility Rules</a>. | 1085 The visibility rules for local variables are explained in <a href="#visibility">Visibility Rules</a>. |
1087 | 1086 |
1088 | 1087 |
1089 <h4 <%=heading_options%> ><a name="template_stmt">Template Statements</a></h4> | 1088 <h4 heading><a name="template_stmt">Template Statements</a></h4> |
1090 | 1089 |
1091 <p>Template statements are based on <a href="#template_expr">template exressions</a> and provide the full equivalent of <a href="http://en.wikipedia.org/wiki/JavaServer_Pages">JSP</a> but in a general way. Template statements write the equivalent template exression to standard output. For example:</p> | 1090 <p>Template statements are based on <a href="#template_expr">template exressions</a> and provide the full equivalent of <a href="http://en.wikipedia.org/wiki/JavaServer_Pages">JSP</a> but in a general way. Template statements write the equivalent template exression to standard output. For example:</p> |
1092 | 1091 |
1093 <p><tt><pre><%=Html.encode[[ | 1092 <pre><%=Html.encode[[ |
1094 local name = "Bob" | 1093 local name = "Bob" |
1095 %> | 1094 %> |
1096 Hello <%= name %>! | 1095 Hello <%= name %>! |
1097 Bye <%= name %>. | 1096 Bye <%= name %>. |
1098 <% | 1097 <% |
1099 ]]%></pre></tt></p> | 1098 ]]%></pre> |
1100 | 1099 |
1101 <p>is equivalent to the code:</p> | 1100 <p>is equivalent to the code:</p> |
1102 | 1101 |
1103 <p><tt><pre><%=Html.encode[[ | 1102 <pre><%=Html.encode[[ |
1104 local name = "Bob" | 1103 local name = "Bob" |
1105 require("luan:Io").stdout.write( %> | 1104 require("luan:Io").stdout.write( %> |
1106 Hello <%= name %>! | 1105 Hello <%= name %>! |
1107 Bye <%= name %>. | 1106 Bye <%= name %>. |
1108 <% ) | 1107 <% ) |
1109 ]]%></pre></tt></p> | 1108 ]]%></pre> |
1110 | 1109 |
1111 | 1110 |
1112 | 1111 |
1113 <h3 <%=heading_options%> ><a name="expressions">Expressions</a></h3> | 1112 <h3 heading><a name="expressions">Expressions</a></h3> |
1114 | 1113 |
1115 <p> | 1114 <p> |
1116 The basic expressions in Luan are the following: | 1115 The basic expressions in Luan are the following: |
1117 | 1116 |
1118 <p><tt><pre> | 1117 <pre> |
1119 exp ::= prefixexp | 1118 exp ::= prefixexp |
1120 exp ::= <b>nil</b> | <b>false</b> | <b>true</b> | 1119 exp ::= <b>nil</b> | <b>false</b> | <b>true</b> |
1121 exp ::= Numeral | 1120 exp ::= Numeral |
1122 exp ::= LiteralString | 1121 exp ::= LiteralString |
1123 exp ::= functiondef | 1122 exp ::= functiondef |
1124 exp ::= tableconstructor | 1123 exp ::= tableconstructor |
1125 exp ::= ‘<b>...</b>’ | 1124 exp ::= ‘<b>...</b>’ |
1126 exp ::= exp binop exp | 1125 exp ::= exp binop exp |
1127 exp ::= unop exp | 1126 exp ::= unop exp |
1128 prefixexp ::= var | functioncall | ‘<b>(</b>’ exp ‘<b>)</b>’ | 1127 prefixexp ::= var | functioncall | ‘<b>(</b>’ exp ‘<b>)</b>’ |
1129 </pre></tt></p> | 1128 </pre> |
1130 | 1129 |
1131 <p> | 1130 <p> |
1132 Numerals and literal strings are explained in <a href="#lex">Lexical Conventions</a>; | 1131 Numerals and literal strings are explained in <a href="#lex">Lexical Conventions</a>; |
1133 variables are explained in <a href="#vars">Variables</a>; | 1132 variables are explained in <a href="#vars">Variables</a>; |
1134 function definitions are explained in <a href="#fn_def">Function Definitions</a>; | 1133 function definitions are explained in <a href="#fn_def">Function Definitions</a>; |
1135 function calls are explained in <a href="#fn_calls">Function Calls</a>; | 1134 function calls are explained in <a href="#fn_calls">Function Calls</a>; |
1136 table constructors are explained in <a href="#constructors">Table Constructors</a>. | 1135 table constructors are explained in <a href="#constructors">Table Constructors</a>. |
1137 Vararg expressions, | 1136 Vararg expressions, |
1138 denoted by three dots ('<tt>...</tt>'), can only be used when | 1137 denoted by three dots ('<code>...</code>'), can only be used when |
1139 directly inside a vararg function; | 1138 directly inside a vararg function; |
1140 they are explained in <a href="#fn_def">Function Definitions</a>. | 1139 they are explained in <a href="#fn_def">Function Definitions</a>. |
1141 | 1140 |
1142 | 1141 |
1143 <p> | 1142 <p> |
1165 | 1164 |
1166 | 1165 |
1167 <p> | 1166 <p> |
1168 Here are some examples: | 1167 Here are some examples: |
1169 | 1168 |
1170 <p><tt><pre> | 1169 <pre> |
1171 f() -- adjusted to 0 results | 1170 f() -- adjusted to 0 results |
1172 g(f(), x) -- f() is adjusted to 1 result | 1171 g(f(), x) -- f() is adjusted to 1 result |
1173 g(x, f()) -- g gets x plus all results from f() | 1172 g(x, f()) -- g gets x plus all results from f() |
1174 a,b,c = f(), x -- f() is adjusted to 1 result (c gets nil) | 1173 a,b,c = f(), x -- f() is adjusted to 1 result (c gets nil) |
1175 a,b = ... -- a gets the first vararg parameter, b gets | 1174 a,b = ... -- a gets the first vararg parameter, b gets |
1182 return ... -- returns all received vararg parameters | 1181 return ... -- returns all received vararg parameters |
1183 return x,y,f() -- returns x, y, and all results from f() | 1182 return x,y,f() -- returns x, y, and all results from f() |
1184 {f()} -- creates a list with all results from f() | 1183 {f()} -- creates a list with all results from f() |
1185 {...} -- creates a list with all vararg parameters | 1184 {...} -- creates a list with all vararg parameters |
1186 {f(), nil} -- f() is adjusted to 1 result | 1185 {f(), nil} -- f() is adjusted to 1 result |
1187 </pre></tt></p> | 1186 </pre> |
1188 | 1187 |
1189 <p> | 1188 <p> |
1190 Any expression enclosed in parentheses always results in only one value. | 1189 Any expression enclosed in parentheses always results in only one value. |
1191 Thus, | 1190 Thus, |
1192 <tt>(f(x,y,z))</tt> is always a single value, | 1191 <code>(f(x,y,z))</code> is always a single value, |
1193 even if <tt>f</tt> returns several values. | 1192 even if <code>f</code> returns several values. |
1194 (The value of <tt>(f(x,y,z))</tt> is the first value returned by <tt>f</tt> | 1193 (The value of <code>(f(x,y,z))</code> is the first value returned by <code>f</code> |
1195 or <b>nil</b> if <tt>f</tt> does not return any values.) | 1194 or <b>nil</b> if <code>f</code> does not return any values.) |
1196 | 1195 |
1197 | 1196 |
1198 | 1197 |
1199 <h4 <%=heading_options%> ><a name="arithmetic">Arithmetic Operators</a></h4> | 1198 <h4 heading><a name="arithmetic">Arithmetic Operators</a></h4> |
1200 | 1199 |
1201 <p> | 1200 <p> |
1202 Luan supports the following arithmetic operators: | 1201 Luan supports the following arithmetic operators: |
1203 | 1202 |
1204 <ul> | 1203 <ul> |
1205 <li><b><tt>+</tt>: </b>addition</li> | 1204 <li><b><code>+</code>: </b>addition</li> |
1206 <li><b><tt>-</tt>: </b>subtraction</li> | 1205 <li><b><code>-</code>: </b>subtraction</li> |
1207 <li><b><tt>*</tt>: </b>multiplication</li> | 1206 <li><b><code>*</code>: </b>multiplication</li> |
1208 <li><b><tt>/</tt>: </b>division</li> | 1207 <li><b><code>/</code>: </b>division</li> |
1209 <li><b><tt>%</tt>: </b>modulo</li> | 1208 <li><b><code>%</code>: </b>modulo</li> |
1210 <li><b><tt>^</tt>: </b>exponentiation</li> | 1209 <li><b><code>^</code>: </b>exponentiation</li> |
1211 <li><b><tt>-</tt>: </b>unary minus</li> | 1210 <li><b><code>-</code>: </b>unary minus</li> |
1212 </ul> | 1211 </ul> |
1213 | 1212 |
1214 <p> | 1213 <p> |
1215 Addition, subtraction, multiplication, division, and unary minus are the same as these operators in Java. Exponentiation uses Java's <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Math.html#pow(double,%20double)">Math.pow</a> function. | 1214 Addition, subtraction, multiplication, division, and unary minus are the same as these operators in Java. Exponentiation uses Java's <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Math.html#pow(double,%20double)">Math.pow</a> function. |
1216 | 1215 |
1219 that rounds the quotient towards minus infinite (floor division). | 1218 that rounds the quotient towards minus infinite (floor division). |
1220 (The Java modulo operator is not used.) | 1219 (The Java modulo operator is not used.) |
1221 | 1220 |
1222 | 1221 |
1223 | 1222 |
1224 <h4 <%=heading_options%> ><a name="conversions">Coercions and Conversions</a></h4> | 1223 <h4 heading><a name="conversions">Coercions and Conversions</a></h4> |
1225 | 1224 |
1226 <p> | 1225 <p> |
1227 Luan generally avoids automatic conversions. | 1226 Luan generally avoids automatic conversions. |
1228 String concatenation automatically converts all of its arguments to strings. | 1227 String concatenation automatically converts all of its arguments to strings. |
1229 | 1228 |
1231 Luan provides library functions for explicit type conversions. | 1230 Luan provides library functions for explicit type conversions. |
1232 | 1231 |
1233 | 1232 |
1234 | 1233 |
1235 | 1234 |
1236 <h4 <%=heading_options%> ><a name="relational">Relational Operators</a></h4> | 1235 <h4 heading><a name="relational">Relational Operators</a></h4> |
1237 | 1236 |
1238 <p> | 1237 <p> |
1239 Luan supports the following relational operators: | 1238 Luan supports the following relational operators: |
1240 | 1239 |
1241 <ul> | 1240 <ul> |
1242 <li><b><tt>==</tt>: </b>equality</li> | 1241 <li><b><code>==</code>: </b>equality</li> |
1243 <li><b><tt>~=</tt>: </b>inequality</li> | 1242 <li><b><code>~=</code>: </b>inequality</li> |
1244 <li><b><tt><</tt>: </b>less than</li> | 1243 <li><b><code><</code>: </b>less than</li> |
1245 <li><b><tt>></tt>: </b>greater than</li> | 1244 <li><b><code>></code>: </b>greater than</li> |
1246 <li><b><tt><=</tt>: </b>less or equal</li> | 1245 <li><b><code><=</code>: </b>less or equal</li> |
1247 <li><b><tt>>=</tt>: </b>greater or equal</li> | 1246 <li><b><code>>=</code>: </b>greater or equal</li> |
1248 </ul><p> | 1247 </ul><p> |
1249 These operators always result in <b>false</b> or <b>true</b>. | 1248 These operators always result in <b>false</b> or <b>true</b>. |
1250 | 1249 |
1251 | 1250 |
1252 <p> | 1251 <p> |
1253 Equality (<tt>==</tt>) first compares the type of its operands. | 1252 Equality (<code>==</code>) first compares the type of its operands. |
1254 If the types are different, then the result is <b>false</b>. | 1253 If the types are different, then the result is <b>false</b>. |
1255 Otherwise, the values of the operands are compared. | 1254 Otherwise, the values of the operands are compared. |
1256 Strings, numbers, and binary values are compared in the obvious way (by value). | 1255 Strings, numbers, and binary values are compared in the obvious way (by value). |
1257 | 1256 |
1258 <p> | 1257 <p> |
1266 <p> | 1265 <p> |
1267 You can change the way that Luan compares tables | 1266 You can change the way that Luan compares tables |
1268 by using the "eq" metamethod (see <a href="#meta">Metatables and Metamethods</a>). | 1267 by using the "eq" metamethod (see <a href="#meta">Metatables and Metamethods</a>). |
1269 | 1268 |
1270 <p> | 1269 <p> |
1271 Java values are compared for equality with the Java <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Object.html#equals(java.lang.Object)"><tt>equals</tt></a> method. | 1270 Java values are compared for equality with the Java <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Object.html#equals(java.lang.Object)"><code>equals</code></a> method. |
1272 | 1271 |
1273 <p> | 1272 <p> |
1274 Equality comparisons do not convert strings to numbers | 1273 Equality comparisons do not convert strings to numbers |
1275 or vice versa. | 1274 or vice versa. |
1276 Thus, <tt>"0"==0</tt> evaluates to <b>false</b>, | 1275 Thus, <code>"0"==0</code> evaluates to <b>false</b>, |
1277 and <tt>t[0]</tt> and <tt>t["0"]</tt> denote different | 1276 and <code>t[0]</code> and <code>t["0"]</code> denote different |
1278 entries in a table. | 1277 entries in a table. |
1279 | 1278 |
1280 | 1279 |
1281 <p> | 1280 <p> |
1282 The operator <tt>~=</tt> is exactly the negation of equality (<tt>==</tt>). | 1281 The operator <code>~=</code> is exactly the negation of equality (<code>==</code>). |
1283 | 1282 |
1284 | 1283 |
1285 <p> | 1284 <p> |
1286 The order operators work as follows. | 1285 The order operators work as follows. |
1287 | 1286 |
1290 the usual rule for binary operations. | 1289 the usual rule for binary operations. |
1291 Otherwise, if both arguments are strings, | 1290 Otherwise, if both arguments are strings, |
1292 then their values are compared according to the current locale. | 1291 then their values are compared according to the current locale. |
1293 Otherwise, Luan tries to call the "lt" or the "le" | 1292 Otherwise, Luan tries to call the "lt" or the "le" |
1294 metamethod (see <a href="#meta">Metatables and Metamethods</a>). | 1293 metamethod (see <a href="#meta">Metatables and Metamethods</a>). |
1295 A comparison <tt>a > b</tt> is translated to <tt>b < a</tt> | 1294 A comparison <code>a > b</code> is translated to <code>b < a</code> |
1296 and <tt>a >= b</tt> is translated to <tt>b <= a</tt>. | 1295 and <code>a >= b</code> is translated to <code>b <= a</code>. |
1297 | 1296 |
1298 | 1297 |
1299 | 1298 |
1300 | 1299 |
1301 | 1300 |
1302 <h4 <%=heading_options%> ><a name="logical_ops">Logical Operators</a></h4> | 1301 <h4 heading><a name="logical_ops">Logical Operators</a></h4> |
1303 | 1302 |
1304 <p> | 1303 <p> |
1305 The logical operators in Luan are | 1304 The logical operators in Luan are |
1306 <b>and</b>, <b>or</b>, and <b>not</b>. | 1305 <b>and</b>, <b>or</b>, and <b>not</b>. |
1307 The <b>and</b> and <b>or</b> operators consider both <b>false</b> and <b>nil</b> as false | 1306 The <b>and</b> and <b>or</b> operators consider both <b>false</b> and <b>nil</b> as false |
1320 Both <b>and</b> and <b>or</b> use short-circuit evaluation; | 1319 Both <b>and</b> and <b>or</b> use short-circuit evaluation; |
1321 that is, | 1320 that is, |
1322 the second operand is evaluated only if necessary. | 1321 the second operand is evaluated only if necessary. |
1323 Here are some examples: | 1322 Here are some examples: |
1324 | 1323 |
1325 <p><tt><pre> | 1324 <pre> |
1326 10 or 20 --> 10 | 1325 10 or 20 --> 10 |
1327 10 or error() --> 10 | 1326 10 or error() --> 10 |
1328 nil or "a" --> "a" | 1327 nil or "a" --> "a" |
1329 nil and 10 --> nil | 1328 nil and 10 --> nil |
1330 false and error() --> false | 1329 false and error() --> false |
1331 false and nil --> false | 1330 false and nil --> false |
1332 false or nil --> nil | 1331 false or nil --> nil |
1333 10 and 20 --> 20 | 1332 10 and 20 --> 20 |
1334 </pre></tt></p> | 1333 </pre> |
1335 | 1334 |
1336 <p> | 1335 <p> |
1337 (In this manual, | 1336 (In this manual, |
1338 <tt>--></tt> indicates the result of the preceding expression.) | 1337 <code>--></code> indicates the result of the preceding expression.) |
1339 | 1338 |
1340 | 1339 |
1341 | 1340 |
1342 <h4 <%=heading_options%> ><a name="concatenation">Concatenation</a></h4> | 1341 <h4 heading><a name="concatenation">Concatenation</a></h4> |
1343 | 1342 |
1344 <p> | 1343 <p> |
1345 The string concatenation operator in Luan is | 1344 The string concatenation operator in Luan is |
1346 denoted by two dots ('<tt>..</tt>'). | 1345 denoted by two dots ('<code>..</code>'). |
1347 All operands are converted to strings. | 1346 All operands are converted to strings. |
1348 | 1347 |
1349 | 1348 |
1350 | 1349 |
1351 <h4 <%=heading_options%> ><a name="length">The Length Operator</a></h4> | 1350 <h4 heading><a name="length">The Length Operator</a></h4> |
1352 | 1351 |
1353 <p> | 1352 <p> |
1354 The length operator is denoted by the unary prefix operator <tt>#</tt>. | 1353 The length operator is denoted by the unary prefix operator <code>#</code>. |
1355 The length of a string is its number of characters. | 1354 The length of a string is its number of characters. |
1356 The length of a binary is its number of bytes. | 1355 The length of a binary is its number of bytes. |
1357 | 1356 |
1358 | 1357 |
1359 <p> | 1358 <p> |
1360 A program can modify the behavior of the length operator for | 1359 A program can modify the behavior of the length operator for |
1361 any table through the <tt>__len</tt> metamethod (see <a href="#meta">Metatables and Metamethods</a>). | 1360 any table through the <code>__len</code> metamethod (see <a href="#meta">Metatables and Metamethods</a>). |
1362 | 1361 |
1363 | 1362 |
1364 <p> | 1363 <p> |
1365 Unless a <tt>__len</tt> metamethod is given, | 1364 Unless a <code>__len</code> metamethod is given, |
1366 the length of a table <tt>t</tt> is defined | 1365 the length of a table <code>t</code> is defined |
1367 as the number of elements in <em>sequence</em>, | 1366 as the number of elements in <em>sequence</em>, |
1368 that is, | 1367 that is, |
1369 the size of the set of its positive numeric keys is equal to <em>{1..n}</em> | 1368 the size of the set of its positive numeric keys is equal to <em>{1..n}</em> |
1370 for some non-negative integer <em>n</em>. | 1369 for some non-negative integer <em>n</em>. |
1371 In that case, <em>n</em> is its length. | 1370 In that case, <em>n</em> is its length. |
1372 Note that a table like | 1371 Note that a table like |
1373 | 1372 |
1374 <p><tt><pre> | 1373 <pre> |
1375 {10, 20, nil, 40} | 1374 {10, 20, nil, 40} |
1376 </pre></tt></p> | 1375 </pre> |
1377 | 1376 |
1378 <p> | 1377 <p> |
1379 has a length of <tt>2</tt>, because that is the last key in sequence. | 1378 has a length of <code>2</code>, because that is the last key in sequence. |
1380 | 1379 |
1381 | 1380 |
1382 | 1381 |
1383 | 1382 |
1384 | 1383 |
1385 <h4 <%=heading_options%> ><a name="precedence">Precedence</a></h4> | 1384 <h4 heading><a name="precedence">Precedence</a></h4> |
1386 | 1385 |
1387 <p> | 1386 <p> |
1388 Operator precedence in Luan follows the table below, | 1387 Operator precedence in Luan follows the table below, |
1389 from lower to higher priority: | 1388 from lower to higher priority: |
1390 | 1389 |
1391 <p><tt><pre> | 1390 <pre> |
1392 or | 1391 or |
1393 and | 1392 and |
1394 < > <= >= ~= == | 1393 < > <= >= ~= == |
1395 .. | 1394 .. |
1396 + - | 1395 + - |
1397 * / % | 1396 * / % |
1398 unary operators (not # -) | 1397 unary operators (not # -) |
1399 ^ | 1398 ^ |
1400 </pre></tt></p> | 1399 </pre> |
1401 | 1400 |
1402 <p> | 1401 <p> |
1403 As usual, | 1402 As usual, |
1404 you can use parentheses to change the precedences of an expression. | 1403 you can use parentheses to change the precedences of an expression. |
1405 The concatenation ('<tt>..</tt>') and exponentiation ('<tt>^</tt>') | 1404 The concatenation ('<code>..</code>') and exponentiation ('<code>^</code>') |
1406 operators are right associative. | 1405 operators are right associative. |
1407 All other binary operators are left associative. | 1406 All other binary operators are left associative. |
1408 | 1407 |
1409 | 1408 |
1410 | 1409 |
1411 | 1410 |
1412 | 1411 |
1413 <h4 <%=heading_options%> ><a name="constructors">Table Constructors</a></h4> | 1412 <h4 heading><a name="constructors">Table Constructors</a></h4> |
1414 | 1413 |
1415 <p> | 1414 <p> |
1416 Table constructors are expressions that create tables. | 1415 Table constructors are expressions that create tables. |
1417 Every time a constructor is evaluated, a new table is created. | 1416 Every time a constructor is evaluated, a new table is created. |
1418 A constructor can be used to create an empty table | 1417 A constructor can be used to create an empty table |
1419 or to create a table and initialize some of its fields. | 1418 or to create a table and initialize some of its fields. |
1420 The general syntax for constructors is | 1419 The general syntax for constructors is |
1421 | 1420 |
1422 <p><tt><pre> | 1421 <pre> |
1423 tableconstructor ::= ‘<b>{</b>’ [fieldlist] ‘<b>}</b>’ | 1422 tableconstructor ::= ‘<b>{</b>’ [fieldlist] ‘<b>}</b>’ |
1424 fieldlist ::= field {fieldsep field} [fieldsep] | 1423 fieldlist ::= field {fieldsep field} [fieldsep] |
1425 field ::= ‘<b>[</b>’ exp ‘<b>]</b>’ ‘<b>=</b>’ exp | Name ‘<b>=</b>’ exp | exp | 1424 field ::= ‘<b>[</b>’ exp ‘<b>]</b>’ ‘<b>=</b>’ exp | Name ‘<b>=</b>’ exp | exp |
1426 fieldsep ::= ‘<b>,</b>’ | ‘<b>;</b>’ | 1425 fieldsep ::= ‘<b>,</b>’ | ‘<b>;</b>’ |
1427 </pre></tt></p> | 1426 </pre> |
1428 | 1427 |
1429 <p> | 1428 <p> |
1430 Each field of the form <tt>[exp1] = exp2</tt> adds to the new table an entry | 1429 Each field of the form <code>[exp1] = exp2</code> adds to the new table an entry |
1431 with key <tt>exp1</tt> and value <tt>exp2</tt>. | 1430 with key <code>exp1</code> and value <code>exp2</code>. |
1432 A field of the form <tt>name = exp</tt> is equivalent to | 1431 A field of the form <code>name = exp</code> is equivalent to |
1433 <tt>["name"] = exp</tt>. | 1432 <code>["name"] = exp</code>. |
1434 Finally, fields of the form <tt>exp</tt> are equivalent to | 1433 Finally, fields of the form <code>exp</code> are equivalent to |
1435 <tt>[i] = exp</tt>, where <tt>i</tt> are consecutive integers | 1434 <code>[i] = exp</code>, where <code>i</code> are consecutive integers |
1436 starting with 1. | 1435 starting with 1. |
1437 Fields in the other formats do not affect this counting. | 1436 Fields in the other formats do not affect this counting. |
1438 For example, | 1437 For example, |
1439 | 1438 |
1440 <p><tt><pre> | 1439 <pre> |
1441 a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 } | 1440 a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 } |
1442 </pre></tt></p> | 1441 </pre> |
1443 | 1442 |
1444 <p> | 1443 <p> |
1445 is equivalent to | 1444 is equivalent to |
1446 | 1445 |
1447 <p><tt><pre> | 1446 <pre> |
1448 do | 1447 do |
1449 local t = {} | 1448 local t = {} |
1450 t[f(1)] = g | 1449 t[f(1)] = g |
1451 t[1] = "x" -- 1st exp | 1450 t[1] = "x" -- 1st exp |
1452 t[2] = "y" -- 2nd exp | 1451 t[2] = "y" -- 2nd exp |
1454 t[3] = f(x) -- 3rd exp | 1453 t[3] = f(x) -- 3rd exp |
1455 t[30] = 23 | 1454 t[30] = 23 |
1456 t[4] = 45 -- 4th exp | 1455 t[4] = 45 -- 4th exp |
1457 a = t | 1456 a = t |
1458 end | 1457 end |
1459 </pre></tt></p> | 1458 </pre> |
1460 | 1459 |
1461 <p> | 1460 <p> |
1462 The order of the assignments in a constructor is undefined. | 1461 The order of the assignments in a constructor is undefined. |
1463 (This order would be relevant only when there are repeated keys.) | 1462 (This order would be relevant only when there are repeated keys.) |
1464 | 1463 |
1465 | 1464 |
1466 <p> | 1465 <p> |
1467 If the last field in the list has the form <tt>exp</tt> | 1466 If the last field in the list has the form <code>exp</code> |
1468 and the expression is a function call or a vararg expression, | 1467 and the expression is a function call or a vararg expression, |
1469 then all values returned by this expression enter the list consecutively | 1468 then all values returned by this expression enter the list consecutively |
1470 (see <a href="#fn_calls">Function Calls</a>). | 1469 (see <a href="#fn_calls">Function Calls</a>). |
1471 | 1470 |
1472 | 1471 |
1476 | 1475 |
1477 | 1476 |
1478 | 1477 |
1479 | 1478 |
1480 | 1479 |
1481 <h4 <%=heading_options%> ><a name="fn_calls">Function Calls</a></h4> | 1480 <h4 heading><a name="fn_calls">Function Calls</a></h4> |
1482 | 1481 |
1483 <p> | 1482 <p> |
1484 A function call in Luan has the following syntax: | 1483 A function call in Luan has the following syntax: |
1485 | 1484 |
1486 <p><tt><pre> | 1485 <pre> |
1487 functioncall ::= prefixexp args | 1486 functioncall ::= prefixexp args |
1488 </pre></tt></p> | 1487 </pre> |
1489 | 1488 |
1490 <p> | 1489 <p> |
1491 In a function call, | 1490 In a function call, |
1492 first prefixexp and args are evaluated. | 1491 first prefixexp and args are evaluated. |
1493 If the value of prefixexp has type <i>function</i>, | 1492 If the value of prefixexp has type <em>function</em>, |
1494 then this function is called | 1493 then this function is called |
1495 with the given arguments. | 1494 with the given arguments. |
1496 Otherwise, the prefixexp "call" metamethod is called, | 1495 Otherwise, the prefixexp "call" metamethod is called, |
1497 having as first parameter the value of prefixexp, | 1496 having as first parameter the value of prefixexp, |
1498 followed by the original call arguments | 1497 followed by the original call arguments |
1500 | 1499 |
1501 | 1500 |
1502 <p> | 1501 <p> |
1503 Arguments have the following syntax: | 1502 Arguments have the following syntax: |
1504 | 1503 |
1505 <p><tt><pre> | 1504 <pre> |
1506 args ::= ‘<b>(</b>’ [explist] ‘<b>)</b>’ | 1505 args ::= ‘<b>(</b>’ [explist] ‘<b>)</b>’ |
1507 args ::= tableconstructor | 1506 args ::= tableconstructor |
1508 args ::= LiteralString | 1507 args ::= LiteralString |
1509 </pre></tt></p> | 1508 </pre> |
1510 | 1509 |
1511 <p> | 1510 <p> |
1512 All argument expressions are evaluated before the call. | 1511 All argument expressions are evaluated before the call. |
1513 A call of the form <tt>f{<i>fields</i>}</tt> is | 1512 A call of the form <code>f{<em>fields</em>}</code> is |
1514 syntactic sugar for <tt>f({<i>fields</i>})</tt>; | 1513 syntactic sugar for <code>f({<em>fields</em>})</code>; |
1515 that is, the argument list is a single new table. | 1514 that is, the argument list is a single new table. |
1516 A call of the form <tt>f'<i>string</i>'</tt> | 1515 A call of the form <code>f'<em>string</em>'</code> |
1517 (or <tt>f"<i>string</i>"</tt> or <tt>f[[<i>string</i>]]</tt>) | 1516 (or <code>f"<em>string</em>"</code> or <code>f[[<em>string</em>]]</code>) |
1518 is syntactic sugar for <tt>f('<i>string</i>')</tt>; | 1517 is syntactic sugar for <code>f('<em>string</em>')</code>; |
1519 that is, the argument list is a single literal string. | 1518 that is, the argument list is a single literal string. |
1520 | 1519 |
1521 | 1520 |
1522 <p> | 1521 <p> |
1523 A call of the form <tt>return <i>functioncall</i></tt> is called | 1522 A call of the form <code>return <em>functioncall</em></code> is called |
1524 a <i>tail call</i>. | 1523 a <em>tail call</em>. |
1525 Luan implements <i>proper tail calls</i> | 1524 Luan implements <em>proper tail calls</em> |
1526 (or <i>proper tail recursion</i>): | 1525 (or <em>proper tail recursion</em>): |
1527 in a tail call, | 1526 in a tail call, |
1528 the called function reuses the stack entry of the calling function. | 1527 the called function reuses the stack entry of the calling function. |
1529 Therefore, there is no limit on the number of nested tail calls that | 1528 Therefore, there is no limit on the number of nested tail calls that |
1530 a program can execute. | 1529 a program can execute. |
1531 However, a tail call erases any debug information about the | 1530 However, a tail call erases any debug information about the |
1534 where the <b>return</b> has one single function call as argument; | 1533 where the <b>return</b> has one single function call as argument; |
1535 this syntax makes the calling function return exactly | 1534 this syntax makes the calling function return exactly |
1536 the returns of the called function. | 1535 the returns of the called function. |
1537 So, none of the following examples are tail calls: | 1536 So, none of the following examples are tail calls: |
1538 | 1537 |
1539 <p><tt><pre> | 1538 <pre> |
1540 return (f(x)) -- results adjusted to 1 | 1539 return (f(x)) -- results adjusted to 1 |
1541 return 2 * f(x) | 1540 return 2 * f(x) |
1542 return x, f(x) -- additional results | 1541 return x, f(x) -- additional results |
1543 f(x); return -- results discarded | 1542 f(x); return -- results discarded |
1544 return x or f(x) -- results adjusted to 1 | 1543 return x or f(x) -- results adjusted to 1 |
1545 </pre></tt></p> | 1544 </pre> |
1546 | 1545 |
1547 | 1546 |
1548 | 1547 |
1549 | 1548 |
1550 <h4 <%=heading_options%> ><a name="fn_def">Function Definitions</a></h4> | 1549 <h4 heading><a name="fn_def">Function Definitions</a></h4> |
1551 | 1550 |
1552 <p> | 1551 <p> |
1553 The syntax for function definition is | 1552 The syntax for function definition is |
1554 | 1553 |
1555 <p><tt><pre> | 1554 <pre> |
1556 functiondef ::= <b>function</b> funcbody | 1555 functiondef ::= <b>function</b> funcbody |
1557 funcbody ::= ‘<b>(</b>’ [parlist] ‘<b>)</b>’ block <b>end</b> | 1556 funcbody ::= ‘<b>(</b>’ [parlist] ‘<b>)</b>’ block <b>end</b> |
1558 </pre></tt></p> | 1557 </pre> |
1559 | 1558 |
1560 <p> | 1559 <p> |
1561 The following syntactic sugar simplifies function definitions: | 1560 The following syntactic sugar simplifies function definitions: |
1562 | 1561 |
1563 <p><tt><pre> | 1562 <pre> |
1564 stat ::= <b>function</b> funcname funcbody | 1563 stat ::= <b>function</b> funcname funcbody |
1565 stat ::= <b>local</b> <b>function</b> Name funcbody | 1564 stat ::= <b>local</b> <b>function</b> Name funcbody |
1566 funcname ::= Name {‘<b>.</b>’ Name} [‘<b>:</b>’ Name] | 1565 funcname ::= Name {‘<b>.</b>’ Name} [‘<b>:</b>’ Name] |
1567 </pre></tt></p> | 1566 </pre> |
1568 | 1567 |
1569 <p> | 1568 <p> |
1570 The statement | 1569 The statement |
1571 | 1570 |
1572 <p><tt><pre> | 1571 <pre> |
1573 function f () <i>body</i> end | 1572 function f () <em>body</em> end |
1574 </pre></tt></p> | 1573 </pre> |
1575 | 1574 |
1576 <p> | 1575 <p> |
1577 translates to | 1576 translates to |
1578 | 1577 |
1579 <p><tt><pre> | 1578 <pre> |
1580 f = function () <i>body</i> end | 1579 f = function () <em>body</em> end |
1581 </pre></tt></p> | 1580 </pre> |
1582 | 1581 |
1583 <p> | 1582 <p> |
1584 The statement | 1583 The statement |
1585 | 1584 |
1586 <p><tt><pre> | 1585 <pre> |
1587 function t.a.b.c.f () <i>body</i> end | 1586 function t.a.b.c.f () <em>body</em> end |
1588 </pre></tt></p> | 1587 </pre> |
1589 | 1588 |
1590 <p> | 1589 <p> |
1591 translates to | 1590 translates to |
1592 | 1591 |
1593 <p><tt><pre> | 1592 <pre> |
1594 t.a.b.c.f = function () <i>body</i> end | 1593 t.a.b.c.f = function () <em>body</em> end |
1595 </pre></tt></p> | 1594 </pre> |
1596 | 1595 |
1597 <p> | 1596 <p> |
1598 The statement | 1597 The statement |
1599 | 1598 |
1600 <p><tt><pre> | 1599 <pre> |
1601 local function f () <i>body</i> end | 1600 local function f () <em>body</em> end |
1602 </pre></tt></p> | 1601 </pre> |
1603 | 1602 |
1604 <p> | 1603 <p> |
1605 translates to | 1604 translates to |
1606 | 1605 |
1607 <p><tt><pre> | 1606 <pre> |
1608 local f; f = function () <em>body</em> end | 1607 local f; f = function () <em>body</em> end |
1609 </pre></tt></p> | 1608 </pre> |
1610 | 1609 |
1611 <p> | 1610 <p> |
1612 not to | 1611 not to |
1613 | 1612 |
1614 <p><tt><pre> | 1613 <pre> |
1615 local f = function () <em>body</em> end | 1614 local f = function () <em>body</em> end |
1616 </pre></tt></p> | 1615 </pre> |
1617 | 1616 |
1618 <p> | 1617 <p> |
1619 (This only makes a difference when the body of the function | 1618 (This only makes a difference when the body of the function |
1620 contains references to <tt>f</tt>.) | 1619 contains references to <code>f</code>.) |
1621 | 1620 |
1622 | 1621 |
1623 <p> | 1622 <p> |
1624 A function definition is an executable expression, | 1623 A function definition is an executable expression, |
1625 whose value has type <i>function</i>. | 1624 whose value has type <em>function</em>. |
1626 When Luan precompiles a chunk, | 1625 When Luan precompiles a chunk, |
1627 all its function bodies are precompiled too. | 1626 all its function bodies are precompiled too. |
1628 Then, whenever Luan executes the function definition, | 1627 Then, whenever Luan executes the function definition, |
1629 the function is <i>instantiated</i> (or <i>closed</i>). | 1628 the function is <em>instantiated</em> (or <em>closed</em>). |
1630 This function instance (or <i>closure</i>) | 1629 This function instance (or <em>closure</em>) |
1631 is the final value of the expression. | 1630 is the final value of the expression. |
1632 | 1631 |
1633 | 1632 |
1634 <p> | 1633 <p> |
1635 Parameters act as local variables that are | 1634 Parameters act as local variables that are |
1636 initialized with the argument values: | 1635 initialized with the argument values: |
1637 | 1636 |
1638 <p><tt><pre> | 1637 <pre> |
1639 parlist ::= namelist [‘<b>,</b>’ ‘<b>...</b>’] | ‘<b>...</b>’ | 1638 parlist ::= namelist [‘<b>,</b>’ ‘<b>...</b>’] | ‘<b>...</b>’ |
1640 </pre></tt></p> | 1639 </pre> |
1641 | 1640 |
1642 <p> | 1641 <p> |
1643 When a function is called, | 1642 When a function is called, |
1644 the list of arguments is adjusted to | 1643 the list of arguments is adjusted to |
1645 the length of the list of parameters, | 1644 the length of the list of parameters, |
1646 unless the function is a <i>vararg function</i>, | 1645 unless the function is a <em>vararg function</em>, |
1647 which is indicated by three dots ('<tt>...</tt>') | 1646 which is indicated by three dots ('<code>...</code>') |
1648 at the end of its parameter list. | 1647 at the end of its parameter list. |
1649 A vararg function does not adjust its argument list; | 1648 A vararg function does not adjust its argument list; |
1650 instead, it collects all extra arguments and supplies them | 1649 instead, it collects all extra arguments and supplies them |
1651 to the function through a <i>vararg expression</i>, | 1650 to the function through a <em>vararg expression</em>, |
1652 which is also written as three dots. | 1651 which is also written as three dots. |
1653 The value of this expression is a list of all actual extra arguments, | 1652 The value of this expression is a list of all actual extra arguments, |
1654 similar to a function with multiple results. | 1653 similar to a function with multiple results. |
1655 If a vararg expression is used inside another expression | 1654 If a vararg expression is used inside another expression |
1656 or in the middle of a list of expressions, | 1655 or in the middle of a list of expressions, |
1661 | 1660 |
1662 | 1661 |
1663 <p> | 1662 <p> |
1664 As an example, consider the following definitions: | 1663 As an example, consider the following definitions: |
1665 | 1664 |
1666 <p><tt><pre> | 1665 <pre> |
1667 function f(a, b) end | 1666 function f(a, b) end |
1668 function g(a, b, ...) end | 1667 function g(a, b, ...) end |
1669 function r() return 1,2,3 end | 1668 function r() return 1,2,3 end |
1670 </pre></tt></p> | 1669 </pre> |
1671 | 1670 |
1672 <p> | 1671 <p> |
1673 Then, we have the following mapping from arguments to parameters and | 1672 Then, we have the following mapping from arguments to parameters and |
1674 to the vararg expression: | 1673 to the vararg expression: |
1675 | 1674 |
1676 <p><tt><pre> | 1675 <pre> |
1677 CALL PARAMETERS | 1676 CALL PARAMETERS |
1678 | 1677 |
1679 f(3) a=3, b=nil | 1678 f(3) a=3, b=nil |
1680 f(3, 4) a=3, b=4 | 1679 f(3, 4) a=3, b=4 |
1681 f(3, 4, 5) a=3, b=4 | 1680 f(3, 4, 5) a=3, b=4 |
1684 | 1683 |
1685 g(3) a=3, b=nil, ... --> (nothing) | 1684 g(3) a=3, b=nil, ... --> (nothing) |
1686 g(3, 4) a=3, b=4, ... --> (nothing) | 1685 g(3, 4) a=3, b=4, ... --> (nothing) |
1687 g(3, 4, 5, 8) a=3, b=4, ... --> 5 8 | 1686 g(3, 4, 5, 8) a=3, b=4, ... --> 5 8 |
1688 g(5, r()) a=5, b=1, ... --> 2 3 | 1687 g(5, r()) a=5, b=1, ... --> 2 3 |
1689 </pre></tt></p> | 1688 </pre> |
1690 | 1689 |
1691 <p> | 1690 <p> |
1692 Results are returned using the <b>return</b> statement (see <a href="#control">Control Structures</a>). | 1691 Results are returned using the <b>return</b> statement (see <a href="#control">Control Structures</a>). |
1693 If control reaches the end of a function | 1692 If control reaches the end of a function |
1694 without encountering a <b>return</b> statement, | 1693 without encountering a <b>return</b> statement, |
1695 then the function returns with no results. | 1694 then the function returns with no results. |
1696 | 1695 |
1697 | 1696 |
1698 <h4 <%=heading_options%> ><a name="template_expr">Template Expressions</a></h4> | 1697 <h4 heading><a name="template_expr">Template Expressions</a></h4> |
1699 | 1698 |
1700 <p>Luan template expression are based on <a href="http://en.wikipedia.org/wiki/JavaServer_Pages">JSP</a>. Template expressions return multiple values. Here is an example:</p> | 1699 <p>Luan template expression are based on <a href="http://en.wikipedia.org/wiki/JavaServer_Pages">JSP</a>. Template expressions return multiple values. Here is an example:</p> |
1701 | 1700 |
1702 <p><tt><pre><%=Html.encode[[ | 1701 <pre><%=Html.encode[[ |
1703 local name = "Bob" | 1702 local name = "Bob" |
1704 write( %>Hello <%= name %>!<% ) | 1703 write( %>Hello <%= name %>!<% ) |
1705 ]]%></pre></tt></p> | 1704 ]]%></pre> |
1706 | 1705 |
1707 <p>This is equivalent to the code:</p> | 1706 <p>This is equivalent to the code:</p> |
1708 | 1707 |
1709 <p><tt><pre> | 1708 <pre> |
1710 local name = "Bob" | 1709 local name = "Bob" |
1711 write( "Hello ", name, "!" ) | 1710 write( "Hello ", name, "!" ) |
1712 </pre></tt></p> | 1711 </pre> |
1713 | 1712 |
1714 <p>The strings in template expressions may be multiple lines.</p> | 1713 <p>The strings in template expressions may be multiple lines.</p> |
1715 | 1714 |
1716 | 1715 |
1717 | 1716 |
1718 <h3 <%=heading_options%> ><a name="visibility">Visibility Rules</a></h3> | 1717 <h3 heading><a name="visibility">Visibility Rules</a></h3> |
1719 | 1718 |
1720 <p> | 1719 <p> |
1721 Luan is a lexically scoped language. | 1720 Luan is a lexically scoped language. |
1722 The scope of a local variable begins at the first statement after | 1721 The scope of a local variable begins at the first statement after |
1723 its declaration and lasts until the last non-void statement | 1722 its declaration and lasts until the last non-void statement |
1724 of the innermost block that includes the declaration. | 1723 of the innermost block that includes the declaration. |
1725 Consider the following example: | 1724 Consider the following example: |
1726 | 1725 |
1727 <p><tt><pre> | 1726 <pre> |
1728 x = 10 -- global variable | 1727 x = 10 -- global variable |
1729 do -- new block | 1728 do -- new block |
1730 local x = x -- new 'x', with value 10 | 1729 local x = x -- new 'x', with value 10 |
1731 print(x) --> 10 | 1730 print(x) --> 10 |
1732 x = x+1 | 1731 x = x+1 |
1735 print(x) --> 12 | 1734 print(x) --> 12 |
1736 end | 1735 end |
1737 print(x) --> 11 | 1736 print(x) --> 11 |
1738 end | 1737 end |
1739 print(x) --> 10 (the global one) | 1738 print(x) --> 10 (the global one) |
1740 </pre></tt></p> | 1739 </pre> |
1741 | 1740 |
1742 <p> | 1741 <p> |
1743 Notice that, in a declaration like <tt>local x = x</tt>, | 1742 Notice that, in a declaration like <code>local x = x</code>, |
1744 the new <tt>x</tt> being declared is not in scope yet, | 1743 the new <code>x</code> being declared is not in scope yet, |
1745 and so the second <tt>x</tt> refers to the outside variable. | 1744 and so the second <code>x</code> refers to the outside variable. |
1746 | 1745 |
1747 | 1746 |
1748 <p> | 1747 <p> |
1749 Because of the lexical scoping rules, | 1748 Because of the lexical scoping rules, |
1750 local variables can be freely accessed by functions | 1749 local variables can be freely accessed by functions |
1751 defined inside their scope. | 1750 defined inside their scope. |
1752 A local variable used by an inner function is called | 1751 A local variable used by an inner function is called |
1753 an <i>upvalue</i>, or <i>external local variable</i>, | 1752 an <em>upvalue</em>, or <em>external local variable</em>, |
1754 inside the inner function. | 1753 inside the inner function. |
1755 | 1754 |
1756 | 1755 |
1757 <p> | 1756 <p> |
1758 Notice that each execution of a <b>local</b> statement | 1757 Notice that each execution of a <b>local</b> statement |
1759 defines new local variables. | 1758 defines new local variables. |
1760 Consider the following example: | 1759 Consider the following example: |
1761 | 1760 |
1762 <p><tt><pre> | 1761 <pre> |
1763 a = {} | 1762 a = {} |
1764 local x = 20 | 1763 local x = 20 |
1765 for i=1,10 do | 1764 for i=1,10 do |
1766 local y = 0 | 1765 local y = 0 |
1767 a[i] = function () y=y+1; return x+y end | 1766 a[i] = function () y=y+1; return x+y end |
1768 end | 1767 end |
1769 </pre></tt></p> | 1768 </pre> |
1770 | 1769 |
1771 <p> | 1770 <p> |
1772 The loop creates ten closures | 1771 The loop creates ten closures |
1773 (that is, ten instances of the anonymous function). | 1772 (that is, ten instances of the anonymous function). |
1774 Each of these closures uses a different <tt>y</tt> variable, | 1773 Each of these closures uses a different <code>y</code> variable, |
1775 while all of them share the same <tt>x</tt>. | 1774 while all of them share the same <code>x</code>. |
1776 | 1775 |
1777 | 1776 |
1778 | 1777 |
1779 | 1778 |
1780 | 1779 |
1781 <h2 <%=heading_options%> ><a name="libs">Standard Libraries</a></h2> | 1780 <h2 heading><a name="libs">Standard Libraries</a></h2> |
1782 | 1781 |
1783 <p> | 1782 <p> |
1784 The standard Luan libraries provide useful functions | 1783 The standard Luan libraries provide useful functions |
1785 that are implemented both in Java and in Luan itself. | 1784 that are implemented both in Java and in Luan itself. |
1786 How each function is implemented shouldn't matter to the user. | 1785 How each function is implemented shouldn't matter to the user. |
1787 Some of these functions provide essential services to the language | 1786 Some of these functions provide essential services to the language |
1788 (e.g., <a href="#Luan.type"><tt>type</tt></a> and <a href="#Luan.get_metatable"><tt>get_metatable</tt></a>); | 1787 (e.g., <a href="#Luan.type"><code>type</code></a> and <a href="#Luan.get_metatable"><code>get_metatable</code></a>); |
1789 others provide access to "outside" services (e.g., I/O). | 1788 others provide access to "outside" services (e.g., I/O). |
1790 | 1789 |
1791 | 1790 |
1792 <h3 <%=heading_options%> ><a name="default_lib">Default Environment</a></h3> | 1791 <h3 heading><a name="default_lib">Default Environment</a></h3> |
1793 | 1792 |
1794 <p> | 1793 <p> |
1795 These are provided by default as local variables for any Luan code as described in <a href="#env">Environments</a>. | 1794 These are provided by default as local variables for any Luan code as described in <a href="#env">Environments</a>. |
1796 | 1795 |
1797 | 1796 |
1798 <h4 <%=heading_options%> ><a name="require"><tt>java ()</tt></a></h4> | 1797 <h4 heading><a name="require"><code>java ()</code></a></h4> |
1799 | 1798 |
1800 <p> | 1799 <p> |
1801 This function enables Java in the current chunk if that chunk has permission to use Java. If the chunk doesn't have permission to use Java, then an error is thrown. | 1800 This function enables Java in the current chunk if that chunk has permission to use Java. If the chunk doesn't have permission to use Java, then an error is thrown. |
1802 | 1801 |
1803 | 1802 |
1804 <h4 <%=heading_options%> ><a name="require"><tt>require (mod_uri)</tt></a></h4> | 1803 <h4 heading><a name="require"><code>require (mod_uri)</code></a></h4> |
1805 | 1804 |
1806 <p> | 1805 <p> |
1807 Example use: | 1806 Example use: |
1808 | 1807 |
1809 <p><tt><pre> | 1808 <pre> |
1810 local Table = require "luan:Table" | 1809 local Table = require "luan:Table" |
1811 </pre></tt></p> | 1810 </pre> |
1812 | 1811 |
1813 <p> | 1812 <p> |
1814 Could be defined as: | 1813 Could be defined as: |
1815 | 1814 |
1816 <p><tt><pre> | 1815 <pre> |
1817 local function require(mod_name) | 1816 local function require(mod_name) |
1818 return <a href="#Package.load">Package.load</a>(mod_name) or <a href="#Luan.error">Luan.error</a>("module '"..mod_name.."' not found") | 1817 return <a href="#Package.load">Package.load</a>(mod_name) or <a href="#Luan.error">Luan.error</a>("module '"..mod_name.."' not found") |
1819 end | 1818 end |
1820 </pre></tt></p> | 1819 </pre> |
1821 | 1820 |
1822 | 1821 |
1823 <h3 <%=heading_options%> ><a name="luan_lib">Basic Functions</a></h3> | 1822 <h3 heading><a name="luan_lib">Basic Functions</a></h3> |
1824 | 1823 |
1825 <p> | 1824 <p> |
1826 Include this library by: | 1825 Include this library by: |
1827 | 1826 |
1828 <p><tt><pre> | 1827 <pre> |
1829 local Luan = require "luan:Luan" | 1828 local Luan = require "luan:Luan" |
1830 </pre></tt></p> | 1829 </pre> |
1831 | 1830 |
1832 <p> | 1831 <p> |
1833 The basic library provides basic functions to Luan that don't depend on other libaries. | 1832 The basic library provides basic functions to Luan that don't depend on other libaries. |
1834 | 1833 |
1835 | 1834 |
1836 <h4 <%=heading_options%> ><a name="Luan.assert"><tt>Luan.assert (v [, message])</tt></a></h4> | 1835 <h4 heading><a name="Luan.assert"><code>Luan.assert (v [, message])</code></a></h4> |
1837 | 1836 |
1838 <p> | 1837 <p> |
1839 Could be defined as: | 1838 Could be defined as: |
1840 | 1839 |
1841 <p><tt><pre> | 1840 <pre> |
1842 function Luan.assert(v,message) | 1841 function Luan.assert(v,message) |
1843 return v or <a href="#Luan.error">Luan.error</a>(message or "assertion failed!") | 1842 return v or <a href="#Luan.error">Luan.error</a>(message or "assertion failed!") |
1844 end | 1843 end |
1845 </pre></tt></p> | 1844 </pre> |
1846 | 1845 |
1847 | 1846 |
1848 <h4 <%=heading_options%> ><a name="Luan.assert_binary"><tt>Luan.assert_binary (v)</tt></a></h4> | 1847 <h4 heading><a name="Luan.assert_binary"><code>Luan.assert_binary (v)</code></a></h4> |
1849 | 1848 |
1850 <p> | 1849 <p> |
1851 Could be defined as: | 1850 Could be defined as: |
1852 | 1851 |
1853 <p><tt><pre> | 1852 <pre> |
1854 function Luan.assert_binary(v) | 1853 function Luan.assert_binary(v) |
1855 local v_type = Luan.type(v) | 1854 local v_type = Luan.type(v) |
1856 return v_type == "binary" and v or <a href="#Luan.error">Luan.error</a>("bad argument #1 (binary expected, got "..v_type..")") | 1855 return v_type == "binary" and v or <a href="#Luan.error">Luan.error</a>("bad argument #1 (binary expected, got "..v_type..")") |
1857 end | 1856 end |
1858 </pre></tt></p> | 1857 </pre> |
1859 | 1858 |
1860 | 1859 |
1861 <h4 <%=heading_options%> ><a name="Luan.assert_boolean"><tt>Luan.assert_boolean (v)</tt></a></h4> | 1860 <h4 heading><a name="Luan.assert_boolean"><code>Luan.assert_boolean (v)</code></a></h4> |
1862 | 1861 |
1863 <p> | 1862 <p> |
1864 Like <a href="#Luan.assert_binary"><tt>assert_binary</tt></a> but for type <tt>boolean</tt>. | 1863 Like <a href="#Luan.assert_binary"><code>assert_binary</code></a> but for type <code>boolean</code>. |
1865 | 1864 |
1866 | 1865 |
1867 <h4 <%=heading_options%> ><a name="Luan.assert_integer"><tt>Luan.assert_integer (v)</tt></a></h4> | 1866 <h4 heading><a name="Luan.assert_integer"><code>Luan.assert_integer (v)</code></a></h4> |
1868 | 1867 |
1869 <p> | 1868 <p> |
1870 Asserts that <tt>v</tt> can be converted to Java type <a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Integer.html">Integer</a> and returns an Integer. | 1869 Asserts that <code>v</code> can be converted to Java type <a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Integer.html">Integer</a> and returns an Integer. |
1871 | 1870 |
1872 | 1871 |
1873 <h4 <%=heading_options%> ><a name="Luan.assert_long"><tt>Luan.assert_long (v)</tt></a></h4> | 1872 <h4 heading><a name="Luan.assert_long"><code>Luan.assert_long (v)</code></a></h4> |
1874 | 1873 |
1875 <p> | 1874 <p> |
1876 Asserts that <tt>v</tt> can be converted to Java type <a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Long.html">Long</a> and returns a Long. | 1875 Asserts that <code>v</code> can be converted to Java type <a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Long.html">Long</a> and returns a Long. |
1877 | 1876 |
1878 | 1877 |
1879 <h4 <%=heading_options%> ><a name="Luan.assert_number"><tt>Luan.assert_number (v)</tt></a></h4> | 1878 <h4 heading><a name="Luan.assert_number"><code>Luan.assert_number (v)</code></a></h4> |
1880 | 1879 |
1881 <p> | 1880 <p> |
1882 Like <a href="#Luan.assert_binary"><tt>assert_binary</tt></a> but for type <tt>number</tt>. | 1881 Like <a href="#Luan.assert_binary"><code>assert_binary</code></a> but for type <code>number</code>. |
1883 | 1882 |
1884 | 1883 |
1885 <h4 <%=heading_options%> ><a name="Luan.assert_string"><tt>Luan.assert_string (v)</tt></a></h4> | 1884 <h4 heading><a name="Luan.assert_string"><code>Luan.assert_string (v)</code></a></h4> |
1886 | 1885 |
1887 <p> | 1886 <p> |
1888 Like <a href="#Luan.assert_binary"><tt>assert_binary</tt></a> but for type <tt>string</tt>. | 1887 Like <a href="#Luan.assert_binary"><code>assert_binary</code></a> but for type <code>string</code>. |
1889 | 1888 |
1890 | 1889 |
1891 <h4 <%=heading_options%> ><a name="Luan.assert_table"><tt>Luan.assert_table (v)</tt></a></h4> | 1890 <h4 heading><a name="Luan.assert_table"><code>Luan.assert_table (v)</code></a></h4> |
1892 | 1891 |
1893 <p> | 1892 <p> |
1894 Like <a href="#Luan.assert_binary"><tt>assert_binary</tt></a> but for type <tt>table</tt>. | 1893 Like <a href="#Luan.assert_binary"><code>assert_binary</code></a> but for type <code>table</code>. |
1895 | 1894 |
1896 | 1895 |
1897 <h4 <%=heading_options%> ><a name="Luan.do_file"><tt>Luan.do_file ([uri])</tt></a></h4> | 1896 <h4 heading><a name="Luan.do_file"><code>Luan.do_file ([uri])</code></a></h4> |
1898 | 1897 |
1899 <p> | 1898 <p> |
1900 Could be defined as: | 1899 Could be defined as: |
1901 | 1900 |
1902 <p><tt><pre> | 1901 <pre> |
1903 function Luan.do_file(uri) | 1902 function Luan.do_file(uri) |
1904 return <a href="#Luan.load_file">Luan.load_file</a>(uri)() | 1903 return <a href="#Luan.load_file">Luan.load_file</a>(uri)() |
1905 end | 1904 end |
1906 </pre></tt></p> | 1905 </pre> |
1907 | 1906 |
1908 | 1907 |
1909 | 1908 |
1910 <h4 <%=heading_options%> ><a name="Luan.error"><tt>Luan.error (message)</tt></a></h4> | 1909 <h4 heading><a name="Luan.error"><code>Luan.error (message)</code></a></h4> |
1911 | 1910 |
1912 <p> | 1911 <p> |
1913 Throws an error containing the message. | 1912 Throws an error containing the message. |
1914 | 1913 |
1915 <p> | 1914 <p> |
1916 Could be defined as: | 1915 Could be defined as: |
1917 | 1916 |
1918 <p><tt><pre> | 1917 <pre> |
1919 function Luan.error(message) | 1918 function Luan.error(message) |
1920 <a href="#Luan.new_error">Luan.new_error</a>(message).throw() | 1919 <a href="#Luan.new_error">Luan.new_error</a>(message).throw() |
1921 end | 1920 end |
1922 </pre></tt></p> | 1921 </pre> |
1923 | 1922 |
1924 | 1923 |
1925 | 1924 |
1926 <h4 <%=heading_options%> ><a name="Luan.get_metatable"><tt>Luan.get_metatable (table)</tt></a></h4> | 1925 <h4 heading><a name="Luan.get_metatable"><code>Luan.get_metatable (table)</code></a></h4> |
1927 | 1926 |
1928 <p> | 1927 <p> |
1929 If <tt>table</tt> does not have a metatable, returns <b>nil</b>. | 1928 If <code>table</code> does not have a metatable, returns <b>nil</b>. |
1930 Otherwise, | 1929 Otherwise, |
1931 if the table's metatable has a <tt>"__metatable"</tt> field, | 1930 if the table's metatable has a <code>"__metatable"</code> field, |
1932 returns the associated value. | 1931 returns the associated value. |
1933 Otherwise, returns the metatable of the given table. | 1932 Otherwise, returns the metatable of the given table. |
1934 | 1933 |
1935 | 1934 |
1936 <h4 <%=heading_options%> ><a name="Luan.ipairs"><tt>Luan.ipairs (t)</tt></a></h4> | 1935 <h4 heading><a name="Luan.ipairs"><code>Luan.ipairs (t)</code></a></h4> |
1937 | 1936 |
1938 <p> | 1937 <p> |
1939 Returns an iterator function | 1938 Returns an iterator function |
1940 so that the construction | 1939 so that the construction |
1941 | 1940 |
1942 <p><tt><pre> | 1941 <pre> |
1943 for i,v in ipairs(t) do <i>body</i> end | 1942 for i,v in ipairs(t) do <em>body</em> end |
1944 </pre></tt></p> | 1943 </pre> |
1945 | 1944 |
1946 <p> | 1945 <p> |
1947 will iterate over the key–value pairs | 1946 will iterate over the key–value pairs |
1948 (<tt>1,t[1]</tt>), (<tt>2,t[2]</tt>), ..., | 1947 (<code>1,t[1]</code>), (<code>2,t[2]</code>), ..., |
1949 up to the first nil value. | 1948 up to the first nil value. |
1950 | 1949 |
1951 <p> | 1950 <p> |
1952 Could be defined as: | 1951 Could be defined as: |
1953 | 1952 |
1954 <p><tt><pre> | 1953 <pre> |
1955 function Luan.ipairs(t) | 1954 function Luan.ipairs(t) |
1956 local i = 0 | 1955 local i = 0 |
1957 return function() | 1956 return function() |
1958 if i < #t then | 1957 if i < #t then |
1959 i = i + 1 | 1958 i = i + 1 |
1960 return i, t[i] | 1959 return i, t[i] |
1961 end | 1960 end |
1962 end | 1961 end |
1963 end | 1962 end |
1964 </pre></tt></p> | 1963 </pre> |
1965 | 1964 |
1966 | 1965 |
1967 | 1966 |
1968 <h4 <%=heading_options%> ><a name="Luan.load"><tt>Luan.load (text, source_name [env, [, allow_expression]])</tt></a></h4> | 1967 <h4 heading><a name="Luan.load"><code>Luan.load (text, source_name [env, [, allow_expression]])</code></a></h4> |
1969 | 1968 |
1970 <p> | 1969 <p> |
1971 Loads a chunk. | 1970 Loads a chunk. |
1972 | 1971 |
1973 <p> | 1972 <p> |
1974 The <tt>text</tt> is compiled. | 1973 The <code>text</code> is compiled. |
1975 If there are no syntactic errors, | 1974 If there are no syntactic errors, |
1976 returns the compiled chunk as a function; | 1975 returns the compiled chunk as a function; |
1977 otherwise, throws an error. | 1976 otherwise, throws an error. |
1978 | 1977 |
1979 <p> | 1978 <p> |
1980 The <tt>source_name</tt> parameter is a string saying where the text came from. It is used to produce error messages. | 1979 The <code>source_name</code> parameter is a string saying where the text came from. It is used to produce error messages. |
1981 | 1980 |
1982 <p> | 1981 <p> |
1983 If the <tt>env</tt> parameter is supplied, it becomes the <tt>_ENV</tt> of the chunk. | 1982 If the <code>env</code> parameter is supplied, it becomes the <code>_ENV</code> of the chunk. |
1984 | 1983 |
1985 <p> | 1984 <p> |
1986 If the <tt>allow_expression</tt> parameter is <tt>true</tt> then the entire text can be nothing more than an expression in which case the chunk returns the value of this expression. | 1985 If the <code>allow_expression</code> parameter is <code>true</code> then the entire text can be nothing more than an expression in which case the chunk returns the value of this expression. |
1987 | 1986 |
1988 | 1987 |
1989 <h4 <%=heading_options%> ><a name="Luan.load_file"><tt>Luan.load_file (file_uri [, add_extension])</tt></a></h4> | 1988 <h4 heading><a name="Luan.load_file"><code>Luan.load_file (file_uri [, add_extension])</code></a></h4> |
1990 | 1989 |
1991 <p> | 1990 <p> |
1992 Similar to <a href="#Luan.load"><tt>load</tt></a>, | 1991 Similar to <a href="#Luan.load"><code>load</code></a>, |
1993 but gets the chunk from file <tt>file_uri</tt> | 1992 but gets the chunk from file <code>file_uri</code> |
1994 or from the standard input, | 1993 or from the standard input, |
1995 if no file uri is given. | 1994 if no file uri is given. |
1996 | 1995 |
1997 <p> | 1996 <p> |
1998 Could be defined as: | 1997 Could be defined as: |
1999 | 1998 |
2000 <p><tt><pre> | 1999 <pre> |
2001 function Luan.load_file(file_uri,add_extension) | 2000 function Luan.load_file(file_uri,add_extension) |
2002 file_uri = file_uri or "stdin:" | 2001 file_uri = file_uri or "stdin:" |
2003 local f = Io.uri(file_uri,add_extension) | 2002 local f = Io.uri(file_uri,add_extension) |
2004 f.exists() or <a href="#Luan.error">Luan.error</a>("file '"..file_uri.."' not found") | 2003 f.exists() or <a href="#Luan.error">Luan.error</a>("file '"..file_uri.."' not found") |
2005 return <a href="#Luan.load">Luan.load</a>( f.read_text(), file_uri ) | 2004 return <a href="#Luan.load">Luan.load</a>( f.read_text(), file_uri ) |
2006 end | 2005 end |
2007 </pre></tt></p> | 2006 </pre> |
2008 | 2007 |
2009 | 2008 |
2010 <h4 <%=heading_options%> ><a name="Luan.new_error"><tt>Luan.new_error (message)</tt></a></h4> | 2009 <h4 heading><a name="Luan.new_error"><code>Luan.new_error (message)</code></a></h4> |
2011 | 2010 |
2012 <p> | 2011 <p> |
2013 Creates a new error table containing the message assigned to "<tt>message</tt>". The error table also contains a <tt>throw</tt> function which throws the error. The table also contains a list of stack trace elements where each stack trace element is a table containing "<tt>source</tt>", "<tt>line</tt>", and possible "<tt>call_to</tt>". The table also has a metatable containing "<tt>__to_string</tt>" to render the error. | 2012 Creates a new error table containing the message assigned to "<code>message</code>". The error table also contains a <code>throw</code> function which throws the error. The table also contains a list of stack trace elements where each stack trace element is a table containing "<code>source</code>", "<code>line</code>", and possible "<code>call_to</code>". The table also has a metatable containing "<code>__to_string</code>" to render the error. |
2014 | 2013 |
2015 <p> | 2014 <p> |
2016 To print the current stack trace, you could do: | 2015 To print the current stack trace, you could do: |
2017 | 2016 |
2018 <p><tt><pre> | 2017 <pre> |
2019 Io.print( Luan.new_error "stack" ) | 2018 Io.print( Luan.new_error "stack" ) |
2020 </pre></tt></p> | 2019 </pre> |
2021 | 2020 |
2022 | 2021 |
2023 <h4 <%=heading_options%> ><a name="Luan.pairs"><tt>Luan.pairs (t)</tt></a></h4> | 2022 <h4 heading><a name="Luan.pairs"><code>Luan.pairs (t)</code></a></h4> |
2024 | 2023 |
2025 <p> | 2024 <p> |
2026 If <tt>t</tt> has a metamethod <tt>__pairs</tt>, | 2025 If <code>t</code> has a metamethod <code>__pairs</code>, |
2027 calls it with <tt>t</tt> as argument and returns the | 2026 calls it with <code>t</code> as argument and returns the |
2028 result from the call. | 2027 result from the call. |
2029 | 2028 |
2030 | 2029 |
2031 <p> | 2030 <p> |
2032 Otherwise, | 2031 Otherwise, |
2033 returns a function | 2032 returns a function |
2034 so that the construction | 2033 so that the construction |
2035 | 2034 |
2036 <p><tt><pre> | 2035 <pre> |
2037 for k,v in pairs(t) do <i>body</i> end | 2036 for k,v in pairs(t) do <em>body</em> end |
2038 </pre></tt></p> | 2037 </pre> |
2039 | 2038 |
2040 <p> | 2039 <p> |
2041 will iterate over all key–value pairs of table <tt>t</tt>. | 2040 will iterate over all key–value pairs of table <code>t</code>. |
2042 | 2041 |
2043 | 2042 |
2044 | 2043 |
2045 <h4 <%=heading_options%> ><a name="Luan.pcall"><tt>Luan.pcall (f [, arg1, ···])</tt></a></h4> | 2044 <h4 heading><a name="Luan.pcall"><code>Luan.pcall (f [, arg1, ···])</code></a></h4> |
2046 | 2045 |
2047 <p> | 2046 <p> |
2048 Calls function <tt>f</tt> with | 2047 Calls function <code>f</code> with |
2049 the given arguments in <i>protected mode</i>. | 2048 the given arguments in <em>protected mode</em>. |
2050 This means that any error inside <tt>f</tt> is not propagated; | 2049 This means that any error inside <code>f</code> is not propagated; |
2051 instead, <tt>pcall</tt> catches the error | 2050 instead, <code>pcall</code> catches the error |
2052 and returns a status code. | 2051 and returns a status code. |
2053 Its first result is the status code (a boolean), | 2052 Its first result is the status code (a boolean), |
2054 which is true if the call succeeds without errors. | 2053 which is true if the call succeeds without errors. |
2055 In such case, <tt>pcall</tt> also returns all results from the call, | 2054 In such case, <code>pcall</code> also returns all results from the call, |
2056 after this first result. | 2055 after this first result. |
2057 In case of any error, <tt>pcall</tt> returns <b>false</b> plus the error. | 2056 In case of any error, <code>pcall</code> returns <b>false</b> plus the error. |
2058 | 2057 |
2059 | 2058 |
2060 | 2059 |
2061 | 2060 |
2062 <p> | 2061 <p> |
2070 For complete control over the output, | 2069 For complete control over the output, |
2071 use <a href="#pdf-string.format"><code>string.format</code></a> and <a href="#pdf-io.write"><code>io.write</code></a>. | 2070 use <a href="#pdf-string.format"><code>string.format</code></a> and <a href="#pdf-io.write"><code>io.write</code></a>. |
2072 | 2071 |
2073 | 2072 |
2074 | 2073 |
2075 <h4 <%=heading_options%> ><a name="Luan.range"><tt>Luan.range (start, stop [, step])</tt></a></h4> | 2074 <h4 heading><a name="Luan.range"><code>Luan.range (start, stop [, step])</code></a></h4> |
2076 | 2075 |
2077 <p> | 2076 <p> |
2078 Based on <a href="https://docs.python.org/2/library/functions.html#range">the Python range() function</a>, this lets one iterate through a sequence of numbers. | 2077 Based on <a href="https://docs.python.org/2/library/functions.html#range">the Python range() function</a>, this lets one iterate through a sequence of numbers. |
2079 | 2078 |
2080 <p> | 2079 <p> |
2081 Example use: | 2080 Example use: |
2082 | 2081 |
2083 <p><tt><pre> | 2082 <pre> |
2084 for i in range(1,10) do | 2083 for i in range(1,10) do |
2085 Io.print("count up:",i) | 2084 Io.print("count up:",i) |
2086 end | 2085 end |
2087 for i in range(10,0,-1) do | 2086 for i in range(10,0,-1) do |
2088 Io.print("count down:",i) | 2087 Io.print("count down:",i) |
2089 end | 2088 end |
2090 </pre></tt></p> | 2089 </pre> |
2091 | 2090 |
2092 <p> | 2091 <p> |
2093 Could be defined as: | 2092 Could be defined as: |
2094 | 2093 |
2095 <p><tt><pre> | 2094 <pre> |
2096 function Luan.range(start, stop, step) | 2095 function Luan.range(start, stop, step) |
2097 step = step or 1 | 2096 step = step or 1 |
2098 step == 0 and <a href="#Luan.error">Luan.error</a> "bad argument #3 (step may not be zero)" | 2097 step == 0 and <a href="#Luan.error">Luan.error</a> "bad argument #3 (step may not be zero)" |
2099 local i = start | 2098 local i = start |
2100 return function() | 2099 return function() |
2103 i = i + step | 2102 i = i + step |
2104 return rtn | 2103 return rtn |
2105 end | 2104 end |
2106 end | 2105 end |
2107 end | 2106 end |
2108 </pre></tt></p> | 2107 </pre> |
2109 | 2108 |
2110 | 2109 |
2111 | 2110 |
2112 <h4 <%=heading_options%> ><a name="Luan.raw_equal"><tt>Luan.raw_equal (v1, v2)</tt></a></h4> | 2111 <h4 heading><a name="Luan.raw_equal"><code>Luan.raw_equal (v1, v2)</code></a></h4> |
2113 | 2112 |
2114 <p> | 2113 <p> |
2115 Checks whether <tt>v1</tt> is equal to <tt>v2</tt>, | 2114 Checks whether <code>v1</code> is equal to <code>v2</code>, |
2116 without invoking any metamethod. | 2115 without invoking any metamethod. |
2117 Returns a boolean. | 2116 Returns a boolean. |
2118 | 2117 |
2119 | 2118 |
2120 | 2119 |
2121 <h4 <%=heading_options%> ><a name="Luan.raw_get"><tt>Luan.raw_get (table, index)</tt></a></h4> | 2120 <h4 heading><a name="Luan.raw_get"><code>Luan.raw_get (table, index)</code></a></h4> |
2122 | 2121 |
2123 <p> | 2122 <p> |
2124 Gets the real value of <tt>table[index]</tt>, | 2123 Gets the real value of <code>table[index]</code>, |
2125 without invoking any metamethod. | 2124 without invoking any metamethod. |
2126 <tt>table</tt> must be a table; | 2125 <code>table</code> must be a table; |
2127 <tt>index</tt> may be any value. | 2126 <code>index</code> may be any value. |
2128 | 2127 |
2129 | 2128 |
2130 | 2129 |
2131 <h4 <%=heading_options%> ><a name="Luan.raw_len"><tt>Luan.raw_len (v)</tt></a></h4> | 2130 <h4 heading><a name="Luan.raw_len"><code>Luan.raw_len (v)</code></a></h4> |
2132 | 2131 |
2133 <p> | 2132 <p> |
2134 Returns the length of the object <tt>v</tt>, | 2133 Returns the length of the object <code>v</code>, |
2135 which must be a table or a string, | 2134 which must be a table or a string, |
2136 without invoking any metamethod. | 2135 without invoking any metamethod. |
2137 Returns an integer. | 2136 Returns an integer. |
2138 | 2137 |
2139 | 2138 |
2140 | 2139 |
2141 <h4 <%=heading_options%> ><a name="Luan.raw_set"><tt>Luan.raw_set (table, index, value)</tt></a></h4> | 2140 <h4 heading><a name="Luan.raw_set"><code>Luan.raw_set (table, index, value)</code></a></h4> |
2142 | 2141 |
2143 <p> | 2142 <p> |
2144 Sets the real value of <tt>table[index]</tt> to <tt>value</tt>, | 2143 Sets the real value of <code>table[index]</code> to <code>value</code>, |
2145 without invoking any metamethod. | 2144 without invoking any metamethod. |
2146 <tt>table</tt> must be a table, | 2145 <code>table</code> must be a table, |
2147 <tt>index</tt> any value different from <b>nil</b>, | 2146 <code>index</code> any value different from <b>nil</b>, |
2148 and <tt>value</tt> any Lua value. | 2147 and <code>value</code> any Lua value. |
2149 | 2148 |
2150 | 2149 |
2151 <h4 <%=heading_options%> ><a name="Luan.set_metatable"><tt>Luan.set_metatable (table, metatable)</tt></a></h4> | 2150 <h4 heading><a name="Luan.set_metatable"><code>Luan.set_metatable (table, metatable)</code></a></h4> |
2152 | 2151 |
2153 <p> | 2152 <p> |
2154 Sets the metatable for the given table. | 2153 Sets the metatable for the given table. |
2155 If <tt>metatable</tt> is <b>nil</b>, | 2154 If <code>metatable</code> is <b>nil</b>, |
2156 removes the metatable of the given table. | 2155 removes the metatable of the given table. |
2157 If the original metatable has a <tt>"__metatable"</tt> field, | 2156 If the original metatable has a <code>"__metatable"</code> field, |
2158 raises an error. | 2157 raises an error. |
2159 | 2158 |
2160 | 2159 |
2161 | 2160 |
2162 <h4 <%=heading_options%> ><a name="Luan.to_string"><tt>Luan.to_string (v)</tt></a></h4> | 2161 <h4 heading><a name="Luan.to_string"><code>Luan.to_string (v)</code></a></h4> |
2163 | 2162 |
2164 <p> | 2163 <p> |
2165 Receives a value of any type and | 2164 Receives a value of any type and |
2166 converts it to a string in a human-readable format. | 2165 converts it to a string in a human-readable format. |
2167 | 2166 |
2168 <p> | 2167 <p> |
2169 If the metatable of <tt>v</tt> has a <tt>"__to_string"</tt> field, | 2168 If the metatable of <code>v</code> has a <code>"__to_string"</code> field, |
2170 then <tt>to_string</tt> calls the corresponding value | 2169 then <code>to_string</code> calls the corresponding value |
2171 with <tt>v</tt> as argument, | 2170 with <code>v</code> as argument, |
2172 and uses the result of the call as its result. | 2171 and uses the result of the call as its result. |
2173 | 2172 |
2174 | 2173 |
2175 | 2174 |
2176 <h4 <%=heading_options%> ><a name="Luan.try"><tt>Luan.try (t)</tt></a></h4> | 2175 <h4 heading><a name="Luan.try"><code>Luan.try (t)</code></a></h4> |
2177 | 2176 |
2178 <p> | 2177 <p> |
2179 Implements try-catch as found in other languages where each block is in table <tt>t</tt>. <tt>t[1]</tt> is the "try" block. The <tt>t.catch</tt> and <tt>t.finally</tt> blocks are optional. Returns the result of the "try" block or the "catch" block. | 2178 Implements try-catch as found in other languages where each block is in table <code>t</code>. <code>t[1]</code> is the "try" block. The <code>t.catch</code> and <code>t.finally</code> blocks are optional. Returns the result of the "try" block or the "catch" block. |
2180 | 2179 |
2181 <p> | 2180 <p> |
2182 Example use: | 2181 Example use: |
2183 | 2182 |
2184 <p><tt><pre> | 2183 <pre> |
2185 try { | 2184 try { |
2186 function() | 2185 function() |
2187 a_dangerous_fn() | 2186 a_dangerous_fn() |
2188 end; | 2187 end; |
2189 catch = function(e) | 2188 catch = function(e) |
2191 end; | 2190 end; |
2192 finally = function() | 2191 finally = function() |
2193 -- clean up | 2192 -- clean up |
2194 end; | 2193 end; |
2195 } | 2194 } |
2196 </pre></tt></p> | 2195 </pre> |
2197 | 2196 |
2198 <p> | 2197 <p> |
2199 Could be defined as: | 2198 Could be defined as: |
2200 | 2199 |
2201 <p><tt><pre> | 2200 <pre> |
2202 function Luan.try(t) | 2201 function Luan.try(t) |
2203 local r = { <a href="#Luan.pcall">Luan.pcall</a>(t[1]) } | 2202 local r = { <a href="#Luan.pcall">Luan.pcall</a>(t[1]) } |
2204 if r[1] then | 2203 if r[1] then |
2205 Table.remove(r,1) | 2204 Table.remove(r,1) |
2206 elseif t.catch ~= nil then | 2205 elseif t.catch ~= nil then |
2210 r[2].throw() | 2209 r[2].throw() |
2211 end | 2210 end |
2212 t.finally and t.finally() | 2211 t.finally and t.finally() |
2213 return Table.unpack(r) | 2212 return Table.unpack(r) |
2214 end | 2213 end |
2215 </pre></tt></p> | 2214 </pre> |
2216 | 2215 |
2217 | 2216 |
2218 <h4 <%=heading_options%> ><a name="Luan.type"><tt>Luan.type (v)</tt></a></h4> | 2217 <h4 heading><a name="Luan.type"><code>Luan.type (v)</code></a></h4> |
2219 | 2218 |
2220 <p> | 2219 <p> |
2221 Returns the type of its only argument, coded as a string. | 2220 Returns the type of its only argument, coded as a string. |
2222 The possible results of this function are | 2221 The possible results of this function are |
2223 "<tt>nil</tt>" (a string, not the value <b>nil</b>), | 2222 "<code>nil</code>" (a string, not the value <b>nil</b>), |
2224 "<tt>number</tt>", | 2223 "<code>number</code>", |
2225 "<tt>string</tt>", | 2224 "<code>string</code>", |
2226 "<tt>binary</tt>", | 2225 "<code>binary</code>", |
2227 "<tt>boolean</tt>", | 2226 "<code>boolean</code>", |
2228 "<tt>table</tt>", | 2227 "<code>table</code>", |
2229 "<tt>function</tt>", | 2228 "<code>function</code>", |
2230 and "<tt>java</tt>". | 2229 and "<code>java</code>". |
2231 | 2230 |
2232 | 2231 |
2233 <h4 <%=heading_options%> ><a name="Luan.values"><tt>Luan.values (···)</tt></a></h4> | 2232 <h4 heading><a name="Luan.values"><code>Luan.values (···)</code></a></h4> |
2234 | 2233 |
2235 <p> | 2234 <p> |
2236 Returns a function so that the construction | 2235 Returns a function so that the construction |
2237 | 2236 |
2238 <p><tt><pre> | 2237 <pre> |
2239 for v in Luan.values(···) do <i>body</i> end | 2238 for v in Luan.values(···) do <em>body</em> end |
2240 </pre></tt></p> | 2239 </pre> |
2241 | 2240 |
2242 <p> | 2241 <p> |
2243 will iterate over all values of <tt>···</tt>. | 2242 will iterate over all values of <code>···</code>. |
2244 | 2243 |
2245 | 2244 |
2246 | 2245 |
2247 <h4 <%=heading_options%> ><a name="Luan.VERSION"><tt>Luan.VERSION</tt></a></h4> | 2246 <h4 heading><a name="Luan.VERSION"><code>Luan.VERSION</code></a></h4> |
2248 | 2247 |
2249 <p> | 2248 <p> |
2250 A global variable (not a function) that | 2249 A global variable (not a function) that |
2251 holds a string containing the current interpreter version. | 2250 holds a string containing the current interpreter version. |
2252 The current value of this variable is "<tt><%=Luan.VERSION%></tt>". | 2251 The current value of this variable is "<code><%=Luan.VERSION%></code>". |
2253 | 2252 |
2254 | 2253 |
2255 | 2254 |
2256 | 2255 |
2257 | 2256 |
2258 | 2257 |
2259 <h3 <%=heading_options%> ><a name="package_lib">Modules</a></h3> | 2258 <h3 heading><a name="package_lib">Modules</a></h3> |
2260 | 2259 |
2261 <p> | 2260 <p> |
2262 Include this library by: | 2261 Include this library by: |
2263 | 2262 |
2264 <p><tt><pre> | 2263 <pre> |
2265 local Package = require "luan:Package" | 2264 local Package = require "luan:Package" |
2266 </pre></tt></p> | 2265 </pre> |
2267 | 2266 |
2268 <p> | 2267 <p> |
2269 The package library provides basic | 2268 The package library provides basic |
2270 facilities for loading modules in Luan. | 2269 facilities for loading modules in Luan. |
2271 | 2270 |
2272 | 2271 |
2273 <h4 <%=heading_options%> ><a name="Package.load"><tt>Package.load (mod_uri)</tt></a></h4> | 2272 <h4 heading><a name="Package.load"><code>Package.load (mod_uri)</code></a></h4> |
2274 | 2273 |
2275 <p> | 2274 <p> |
2276 Loads the given module. | 2275 Loads the given module. |
2277 The function starts by looking into the <a href="#Package.loaded"><tt>Package.loaded</tt></a> table | 2276 The function starts by looking into the <a href="#Package.loaded"><code>Package.loaded</code></a> table |
2278 to determine whether <tt>mod_uri</tt> is already loaded. | 2277 to determine whether <code>mod_uri</code> is already loaded. |
2279 If it is, then <tt>Package.load</tt> returns the value stored | 2278 If it is, then <code>Package.load</code> returns the value stored |
2280 at <tt>Package.loaded[mod_uri]</tt>. | 2279 at <code>Package.loaded[mod_uri]</code>. |
2281 Otherwise, it tries to load a new value for the module. | 2280 Otherwise, it tries to load a new value for the module. |
2282 | 2281 |
2283 <p> | 2282 <p> |
2284 To load a new value, <tt>Package.load</tt> first checks if <tt>mod_uri</tt> starts with "<b>java:</b>". If yes, then this is a Java class which is loaded by special Java code. | 2283 To load a new value, <code>Package.load</code> first checks if <code>mod_uri</code> starts with "<b>java:</b>". If yes, then this is a Java class which is loaded by special Java code. |
2285 | 2284 |
2286 <p> | 2285 <p> |
2287 If <tt>mod_uri</tt> is not a Java class, then <tt>Package.load</tt> tries to read the text of the file referred to by <tt>mod_uri</tt> (using <tt>add_extension</tt>=true). If the file doesn't exist, then <tt>Package.load</tt> returns <b>nil</b>. If the file exists, then its content is compiled into a chunk calling <a href="#Luan.load"><tt>Luan.load</tt></a> and passing in an empty table as the <tt>env</tt> value. This chunk is run passing in <tt>mod_uri</tt> as an argument. If the chunk returns a value other than <b>nil</b>, then that value is the value of this module. Otherwise the <tt>env</tt> that was passed in is the value of this module. | 2286 If <code>mod_uri</code> is not a Java class, then <code>Package.load</code> tries to read the text of the file referred to by <code>mod_uri</code> (using <code>add_extension</code>=true). If the file doesn't exist, then <code>Package.load</code> returns <b>nil</b>. If the file exists, then its content is compiled into a chunk calling <a href="#Luan.load"><code>Luan.load</code></a> and passing in an empty table as the <code>env</code> value. This chunk is run passing in <code>mod_uri</code> as an argument. If the chunk returns a value other than <b>nil</b>, then that value is the value of this module. Otherwise the <code>env</code> that was passed in is the value of this module. |
2288 | 2287 |
2289 <p> | 2288 <p> |
2290 If a new value for the module successful loaded, then it is stored in <tt>Package.loaded[mod_uri]</tt>. The value is returned. | 2289 If a new value for the module successful loaded, then it is stored in <code>Package.loaded[mod_uri]</code>. The value is returned. |
2291 | 2290 |
2292 | 2291 |
2293 | 2292 |
2294 | 2293 |
2295 <h4 <%=heading_options%> ><a name="Package.loaded"><tt>Package.loaded</tt></a></h4> | 2294 <h4 heading><a name="Package.loaded"><code>Package.loaded</code></a></h4> |
2296 | 2295 |
2297 | 2296 |
2298 <p> | 2297 <p> |
2299 A table used by <a href="#Package.load"><tt>Package.load</tt></a> to control which | 2298 A table used by <a href="#Package.load"><code>Package.load</code></a> to control which |
2300 modules are already loaded. | 2299 modules are already loaded. |
2301 When you load a module <tt>mod_uri</tt> and | 2300 When you load a module <code>mod_uri</code> and |
2302 <tt>Package.loaded[mod_uri]</tt> is not <b>nil</b>, | 2301 <code>Package.loaded[mod_uri]</code> is not <b>nil</b>, |
2303 <a href="#Package.load"><tt>Package.load</tt></a> simply returns the value stored there. | 2302 <a href="#Package.load"><code>Package.load</code></a> simply returns the value stored there. |
2304 | 2303 |
2305 | 2304 |
2306 <p> | 2305 <p> |
2307 This variable is only a reference to the real table; | 2306 This variable is only a reference to the real table; |
2308 assignments to this variable do not change the | 2307 assignments to this variable do not change the |
2309 table used by <a href="#Package.load"><tt>Package.load</tt></a>. | 2308 table used by <a href="#Package.load"><code>Package.load</code></a>. |
2310 | 2309 |
2311 | 2310 |
2312 | 2311 |
2313 | 2312 |
2314 | 2313 |
2315 | 2314 |
2316 <h3 <%=heading_options%> ><a name="string_lib">String Manipulation</a></h3> | 2315 <h3 heading><a name="string_lib">String Manipulation</a></h3> |
2317 | 2316 |
2318 <p> | 2317 <p> |
2319 Include this library by: | 2318 Include this library by: |
2320 | 2319 |
2321 <p><tt><pre> | 2320 <pre> |
2322 local String = require "luan:String" | 2321 local String = require "luan:String" |
2323 </pre></tt></p> | 2322 </pre> |
2324 | 2323 |
2325 <p> | 2324 <p> |
2326 This library provides generic functions for string manipulation, | 2325 This library provides generic functions for string manipulation, |
2327 such as finding and extracting substrings, and pattern matching. | 2326 such as finding and extracting substrings, and pattern matching. |
2328 When indexing a string in Luan, the first character is at position 1 | 2327 When indexing a string in Luan, the first character is at position 1 |
2331 from the end of the string. | 2330 from the end of the string. |
2332 Thus, the last character is at position -1, and so on. | 2331 Thus, the last character is at position -1, and so on. |
2333 | 2332 |
2334 | 2333 |
2335 | 2334 |
2336 <h4 <%=heading_options%> ><a name="String.char"><tt>String.char (···)</tt></a></h4> | 2335 <h4 heading><a name="String.char"><code>String.char (···)</code></a></h4> |
2337 | 2336 |
2338 <p> | 2337 <p> |
2339 Receives zero or more integers. | 2338 Receives zero or more integers. |
2340 Returns a string with length equal to the number of arguments, | 2339 Returns a string with length equal to the number of arguments, |
2341 in which each character has the internal numerical code equal | 2340 in which each character has the internal numerical code equal |
2342 to its corresponding argument. | 2341 to its corresponding argument. |
2343 | 2342 |
2344 | 2343 |
2345 <h4 <%=heading_options%> ><a name="String.concat"><tt>String.concat (···)</tt></a></h4> | 2344 <h4 heading><a name="String.concat"><code>String.concat (···)</code></a></h4> |
2346 | 2345 |
2347 <p> | 2346 <p> |
2348 Concatenates the <a href="#Luan.to_string"><tt>to_string</tt></a> value of all arguments. | 2347 Concatenates the <a href="#Luan.to_string"><code>to_string</code></a> value of all arguments. |
2349 | 2348 |
2350 | 2349 |
2351 | 2350 |
2352 <h4 <%=heading_options%> ><a name="String.encode"><tt>String.encode (s)</tt></a></h4> | 2351 <h4 heading><a name="String.encode"><code>String.encode (s)</code></a></h4> |
2353 | 2352 |
2354 <p> | 2353 <p> |
2355 Encodes argument <tt>s</tt> into a string that can be placed in quotes so as to return the original value of the string. | 2354 Encodes argument <code>s</code> into a string that can be placed in quotes so as to return the original value of the string. |
2356 | 2355 |
2357 | 2356 |
2358 | 2357 |
2359 | 2358 |
2360 <h4 <%=heading_options%> ><a name="String.find"><tt>String.find (s, pattern [, init [, plain]])</tt></a></h4> | 2359 <h4 heading><a name="String.find"><code>String.find (s, pattern [, init [, plain]])</code></a></h4> |
2361 | 2360 |
2362 <p> | 2361 <p> |
2363 Looks for the first match of | 2362 Looks for the first match of |
2364 <tt>pattern</tt> (see <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">Pattern</a>) in the string <tt>s</tt>. | 2363 <code>pattern</code> (see <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">Pattern</a>) in the string <code>s</code>. |
2365 If it finds a match, then <tt>find</tt> returns the indices of <tt>s</tt> | 2364 If it finds a match, then <code>find</code> returns the indices of <code>s</code> |
2366 where this occurrence starts and ends; | 2365 where this occurrence starts and ends; |
2367 otherwise, it returns <b>nil</b>. | 2366 otherwise, it returns <b>nil</b>. |
2368 A third, optional numerical argument <tt>init</tt> specifies | 2367 A third, optional numerical argument <code>init</code> specifies |
2369 where to start the search; | 2368 where to start the search; |
2370 its default value is 1 and can be negative. | 2369 its default value is 1 and can be negative. |
2371 A value of <b>true</b> as a fourth, optional argument <tt>plain</tt> | 2370 A value of <b>true</b> as a fourth, optional argument <code>plain</code> |
2372 turns off the pattern matching facilities, | 2371 turns off the pattern matching facilities, |
2373 so the function does a plain "find substring" operation, | 2372 so the function does a plain "find substring" operation, |
2374 with no characters in <tt>pattern</tt> being considered magic. | 2373 with no characters in <code>pattern</code> being considered magic. |
2375 Note that if <tt>plain</tt> is given, then <tt>init</tt> must be given as well. | 2374 Note that if <code>plain</code> is given, then <code>init</code> must be given as well. |
2376 | 2375 |
2377 <p> | 2376 <p> |
2378 If the pattern has captures, | 2377 If the pattern has captures, |
2379 then in a successful match | 2378 then in a successful match |
2380 the captured values are also returned, | 2379 the captured values are also returned, |
2381 after the two indices. | 2380 after the two indices. |
2382 | 2381 |
2383 | 2382 |
2384 | 2383 |
2385 | 2384 |
2386 <h4 <%=heading_options%> ><a name="String.format"><tt>String.format (formatstring, ···)</tt></a></h4> | 2385 <h4 heading><a name="String.format"><code>String.format (formatstring, ···)</code></a></h4> |
2387 | 2386 |
2388 | 2387 |
2389 <p> | 2388 <p> |
2390 Returns a formatted version of its variable number of arguments | 2389 Returns a formatted version of its variable number of arguments |
2391 following the description given in its first argument (which must be a string). | 2390 following the description given in its first argument (which must be a string). |
2392 The format string follows the same rules as the Java function <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/String.html#format(java.lang.String,%20java.lang.Object...)"><tt>String.format</tt></a> because Luan calls this internally. | 2391 The format string follows the same rules as the Java function <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/String.html#format(java.lang.String,%20java.lang.Object...)"><code>String.format</code></a> because Luan calls this internally. |
2393 | 2392 |
2394 <p> | 2393 <p> |
2395 Note that Java's <tt>String.format</tt> is too stupid to convert between ints and floats, so you must provide the right kind of number. | 2394 Note that Java's <code>String.format</code> is too stupid to convert between ints and floats, so you must provide the right kind of number. |
2396 | 2395 |
2397 | 2396 |
2398 | 2397 |
2399 <h4 <%=heading_options%> ><a name="String.gmatch"><tt>String.gmatch (s, pattern)</tt></a></h4> | 2398 <h4 heading><a name="String.gmatch"><code>String.gmatch (s, pattern)</code></a></h4> |
2400 | 2399 |
2401 <p> | 2400 <p> |
2402 Returns an iterator function that, | 2401 Returns an iterator function that, |
2403 each time it is called, | 2402 each time it is called, |
2404 returns the next captures from <tt>pattern</tt> (see <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">Pattern</a>) | 2403 returns the next captures from <code>pattern</code> (see <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">Pattern</a>) |
2405 over the string <tt>s</tt>. | 2404 over the string <code>s</code>. |
2406 If <tt>pattern</tt> specifies no captures, | 2405 If <code>pattern</code> specifies no captures, |
2407 then the whole match is produced in each call. | 2406 then the whole match is produced in each call. |
2408 | 2407 |
2409 | 2408 |
2410 <p> | 2409 <p> |
2411 As an example, the following loop | 2410 As an example, the following loop |
2412 will iterate over all the words from string <tt>s</tt>, | 2411 will iterate over all the words from string <code>s</code>, |
2413 printing one per line: | 2412 printing one per line: |
2414 | 2413 |
2415 <p><tt><pre> | 2414 <pre> |
2416 local s = "hello world from Lua" | 2415 local s = "hello world from Lua" |
2417 for w in String.gmatch(s, [[\w+]]) do | 2416 for w in String.gmatch(s, [[\w+]]) do |
2418 print(w) | 2417 print(w) |
2419 end | 2418 end |
2420 </pre></tt></p> | 2419 </pre> |
2421 | 2420 |
2422 <p> | 2421 <p> |
2423 The next example collects all pairs <tt>key=value</tt> from the | 2422 The next example collects all pairs <code>key=value</code> from the |
2424 given string into a table: | 2423 given string into a table: |
2425 | 2424 |
2426 <p><tt><pre> | 2425 <pre> |
2427 local t = {} | 2426 local t = {} |
2428 local s = "from=world, to=Lua" | 2427 local s = "from=world, to=Lua" |
2429 for k, v in String.gmatch(s, [[(\w+)=(\w+)]]) do | 2428 for k, v in String.gmatch(s, [[(\w+)=(\w+)]]) do |
2430 t[k] = v | 2429 t[k] = v |
2431 end | 2430 end |
2432 </pre></tt></p> | 2431 </pre> |
2433 | 2432 |
2434 <p> | 2433 <p> |
2435 For this function, a caret '<tt>^</tt>' at the start of a pattern does not | 2434 For this function, a caret '<code>^</code>' at the start of a pattern does not |
2436 work as an anchor, as this would prevent the iteration. | 2435 work as an anchor, as this would prevent the iteration. |
2437 | 2436 |
2438 | 2437 |
2439 | 2438 |
2440 <h4 <%=heading_options%> ><a name="String.gsub"><tt>String.gsub (s, pattern, repl [, n])</tt></a></h4> | 2439 <h4 heading><a name="String.gsub"><code>String.gsub (s, pattern, repl [, n])</code></a></h4> |
2441 | 2440 |
2442 <p> | 2441 <p> |
2443 Returns a copy of <tt>s</tt> | 2442 Returns a copy of <code>s</code> |
2444 in which all (or the first <tt>n</tt>, if given) | 2443 in which all (or the first <code>n</code>, if given) |
2445 occurrences of the <tt>pattern</tt> (see <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">Pattern</a>) have been | 2444 occurrences of the <code>pattern</code> (see <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">Pattern</a>) have been |
2446 replaced by a replacement string specified by <tt>repl</tt>, | 2445 replaced by a replacement string specified by <code>repl</code>, |
2447 which can be a string, a table, or a function. | 2446 which can be a string, a table, or a function. |
2448 <tt>gsub</tt> also returns, as its second value, | 2447 <code>gsub</code> also returns, as its second value, |
2449 the total number of matches that occurred. | 2448 the total number of matches that occurred. |
2450 The name <tt>gsub</tt> comes from <i>Global SUBstitution</i>. | 2449 The name <code>gsub</code> comes from <em>Global SUBstitution</em>. |
2451 | 2450 |
2452 | 2451 |
2453 <p> | 2452 <p> |
2454 If <tt>repl</tt> is a string, then its value is used for replacement. | 2453 If <code>repl</code> is a string, then its value is used for replacement. |
2455 The character <tt>\</tt> works as an escape character. | 2454 The character <code>\</code> works as an escape character. |
2456 Any sequence in <tt>repl</tt> of the form <tt>$<i>d</i></tt>, | 2455 Any sequence in <code>repl</code> of the form <code>$<em>d</em></code>, |
2457 with <i>d</i> between 1 and 9, | 2456 with <em>d</em> between 1 and 9, |
2458 stands for the value of the <i>d</i>-th captured substring. | 2457 stands for the value of the <em>d</em>-th captured substring. |
2459 The sequence <tt>$0</tt> stands for the whole match. | 2458 The sequence <code>$0</code> stands for the whole match. |
2460 | 2459 |
2461 | 2460 |
2462 <p> | 2461 <p> |
2463 If <tt>repl</tt> is a table, then the table is queried for every match, | 2462 If <code>repl</code> is a table, then the table is queried for every match, |
2464 using the first capture as the key. | 2463 using the first capture as the key. |
2465 | 2464 |
2466 | 2465 |
2467 <p> | 2466 <p> |
2468 If <tt>repl</tt> is a function, then this function is called every time a | 2467 If <code>repl</code> is a function, then this function is called every time a |
2469 match occurs, with all captured substrings passed as arguments, | 2468 match occurs, with all captured substrings passed as arguments, |
2470 in order. | 2469 in order. |
2471 | 2470 |
2472 | 2471 |
2473 <p> | 2472 <p> |
2486 | 2485 |
2487 | 2486 |
2488 <p> | 2487 <p> |
2489 Here are some examples: | 2488 Here are some examples: |
2490 | 2489 |
2491 <p><tt><pre> | 2490 <pre> |
2492 x = String.gsub("hello world", [[(\w+)]], "$1 $1") | 2491 x = String.gsub("hello world", [[(\w+)]], "$1 $1") |
2493 --> x="hello hello world world" | 2492 --> x="hello hello world world" |
2494 | 2493 |
2495 x = String.gsub("hello world", [[\w+]], "$0 $0", 1) | 2494 x = String.gsub("hello world", [[\w+]], "$0 $0", 1) |
2496 --> x="hello hello world" | 2495 --> x="hello hello world" |
2504 --> x="4+5 = 9" | 2503 --> x="4+5 = 9" |
2505 | 2504 |
2506 local t = {name="lua", version="5.3"} | 2505 local t = {name="lua", version="5.3"} |
2507 x = String.gsub("$name-$version.tar.gz", [[\$(\w+)]], t) | 2506 x = String.gsub("$name-$version.tar.gz", [[\$(\w+)]], t) |
2508 --> x="lua-5.3.tar.gz" | 2507 --> x="lua-5.3.tar.gz" |
2509 </pre></tt></p> | 2508 </pre> |
2510 | 2509 |
2511 | 2510 |
2512 | 2511 |
2513 <h4 <%=heading_options%> ><a name="String.literal"><tt>String.literal (s)</tt></a></h4> | 2512 <h4 heading><a name="String.literal"><code>String.literal (s)</code></a></h4> |
2514 <p> | 2513 <p> |
2515 Returns a string which matches the literal string <tt>s</tt> in a regular expression. This function is simply the Java method <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html#quote(java.lang.String)"><tt>Pattern.quote</tt></a>. | 2514 Returns a string which matches the literal string <code>s</code> in a regular expression. This function is simply the Java method <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html#quote(java.lang.String)"><code>Pattern.quote</code></a>. |
2516 | 2515 |
2517 | 2516 |
2518 <h4 <%=heading_options%> ><a name="String.lower"><tt>String.lower (s)</tt></a></h4> | 2517 <h4 heading><a name="String.lower"><code>String.lower (s)</code></a></h4> |
2519 <p> | 2518 <p> |
2520 Receives a string and returns a copy of this string with all | 2519 Receives a string and returns a copy of this string with all |
2521 uppercase letters changed to lowercase. | 2520 uppercase letters changed to lowercase. |
2522 All other characters are left unchanged. | 2521 All other characters are left unchanged. |
2523 | 2522 |
2524 | 2523 |
2525 | 2524 |
2526 | 2525 |
2527 <h4 <%=heading_options%> ><a name="String.match"><tt>String.match (s, pattern [, init])</tt></a></h4> | 2526 <h4 heading><a name="String.match"><code>String.match (s, pattern [, init])</code></a></h4> |
2528 | 2527 |
2529 <p> | 2528 <p> |
2530 Looks for the first <i>match</i> of | 2529 Looks for the first <em>match</em> of |
2531 <tt>pattern</tt> (see <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">Pattern</a>) in the string <tt>s</tt>. | 2530 <code>pattern</code> (see <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">Pattern</a>) in the string <code>s</code>. |
2532 If it finds one, then <tt>match</tt> returns | 2531 If it finds one, then <code>match</code> returns |
2533 the captures from the pattern; | 2532 the captures from the pattern; |
2534 otherwise it returns <b>nil</b>. | 2533 otherwise it returns <b>nil</b>. |
2535 If <tt>pattern</tt> specifies no captures, | 2534 If <code>pattern</code> specifies no captures, |
2536 then the whole match is returned. | 2535 then the whole match is returned. |
2537 A third, optional numerical argument <tt>init</tt> specifies | 2536 A third, optional numerical argument <code>init</code> specifies |
2538 where to start the search; | 2537 where to start the search; |
2539 its default value is 1 and can be negative. | 2538 its default value is 1 and can be negative. |
2540 | 2539 |
2541 | 2540 |
2542 <h4 <%=heading_options%> ><a name="String.matches"><tt>String.matches (s, pattern)</tt></a></h4> | 2541 <h4 heading><a name="String.matches"><code>String.matches (s, pattern)</code></a></h4> |
2543 <p> | 2542 <p> |
2544 Returns a boolean indicating whether the entire string <tt>s</tt> matches <tt>pattern</tt>. | 2543 Returns a boolean indicating whether the entire string <code>s</code> matches <code>pattern</code>. |
2545 | 2544 |
2546 | 2545 |
2547 | 2546 |
2548 <h4 <%=heading_options%> ><a name="String.rep"><tt>String.rep (s, n [, sep])</tt></a></h4> | 2547 <h4 heading><a name="String.rep"><code>String.rep (s, n [, sep])</code></a></h4> |
2549 <p> | 2548 <p> |
2550 Returns a string that is the concatenation of <tt>n</tt> copies of | 2549 Returns a string that is the concatenation of <code>n</code> copies of |
2551 the string <tt>s</tt> separated by the string <tt>sep</tt>. | 2550 the string <code>s</code> separated by the string <code>sep</code>. |
2552 The default value for <tt>sep</tt> is the empty string | 2551 The default value for <code>sep</code> is the empty string |
2553 (that is, no separator). | 2552 (that is, no separator). |
2554 Returns the empty string if <tt>n</tt> is not positive. | 2553 Returns the empty string if <code>n</code> is not positive. |
2555 | 2554 |
2556 | 2555 |
2557 | 2556 |
2558 | 2557 |
2559 <h4 <%=heading_options%> ><a name="String.reverse"><tt>String.reverse (s)</tt></a></h4> | 2558 <h4 heading><a name="String.reverse"><code>String.reverse (s)</code></a></h4> |
2560 <p> | 2559 <p> |
2561 Returns a string that is the string <tt>s</tt> reversed. | 2560 Returns a string that is the string <code>s</code> reversed. |
2562 | 2561 |
2563 | 2562 |
2564 | 2563 |
2565 | 2564 |
2566 <h4 <%=heading_options%> ><a name="String.sub"><tt>String.sub (s, i [, j])</tt></a></h4> | 2565 <h4 heading><a name="String.sub"><code>String.sub (s, i [, j])</code></a></h4> |
2567 | 2566 |
2568 <p> | 2567 <p> |
2569 Returns the substring of <tt>s</tt> that | 2568 Returns the substring of <code>s</code> that |
2570 starts at <tt>i</tt> and continues until <tt>j</tt>; | 2569 starts at <code>i</code> and continues until <code>j</code>; |
2571 <tt>i</tt> and <tt>j</tt> can be negative. | 2570 <code>i</code> and <code>j</code> can be negative. |
2572 If <tt>j</tt> is absent, then it is assumed to be equal to -1 | 2571 If <code>j</code> is absent, then it is assumed to be equal to -1 |
2573 (which is the same as the string length). | 2572 (which is the same as the string length). |
2574 In particular, | 2573 In particular, |
2575 the call <tt>string.sub(s,1,j)</tt> returns a prefix of <tt>s</tt> | 2574 the call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code> |
2576 with length <tt>j</tt>, | 2575 with length <code>j</code>, |
2577 and <tt>string.sub(s, -i)</tt> returns a suffix of <tt>s</tt> | 2576 and <code>string.sub(s, -i)</code> returns a suffix of <code>s</code> |
2578 with length <tt>i</tt>. | 2577 with length <code>i</code>. |
2579 | 2578 |
2580 | 2579 |
2581 <p> | 2580 <p> |
2582 If, after the translation of negative indices, | 2581 If, after the translation of negative indices, |
2583 <tt>i</tt> is less than 1, | 2582 <code>i</code> is less than 1, |
2584 it is corrected to 1. | 2583 it is corrected to 1. |
2585 If <tt>j</tt> is greater than the string length, | 2584 If <code>j</code> is greater than the string length, |
2586 it is corrected to that length. | 2585 it is corrected to that length. |
2587 If, after these corrections, | 2586 If, after these corrections, |
2588 <tt>i</tt> is greater than <tt>j</tt>, | 2587 <code>i</code> is greater than <code>j</code>, |
2589 the function returns the empty string. | 2588 the function returns the empty string. |
2590 | 2589 |
2591 | 2590 |
2592 | 2591 |
2593 <h4 <%=heading_options%> ><a name="String.to_binary"><tt>String.to_binary (s)</tt></a></h4> | 2592 <h4 heading><a name="String.to_binary"><code>String.to_binary (s)</code></a></h4> |
2594 | 2593 |
2595 <p> | 2594 <p> |
2596 Converts a string to a binary by calling the Java method <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/String.html#getBytes()"><tt>String.getBytes</tt></a>. | 2595 Converts a string to a binary by calling the Java method <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/String.html#getBytes()"><code>String.getBytes</code></a>. |
2597 | 2596 |
2598 | 2597 |
2599 | 2598 |
2600 <h4 <%=heading_options%> ><a name="String.to_number"><tt>String.to_number (s [, base])</tt></a></h4> | 2599 <h4 heading><a name="String.to_number"><code>String.to_number (s [, base])</code></a></h4> |
2601 | 2600 |
2602 <p> | 2601 <p> |
2603 When called with no <tt>base</tt>, | 2602 When called with no <code>base</code>, |
2604 <tt>to_number</tt> tries to convert its argument to a number. | 2603 <code>to_number</code> tries to convert its argument to a number. |
2605 If the argument is | 2604 If the argument is |
2606 a string convertible to a number, | 2605 a string convertible to a number, |
2607 then <tt>to_number</tt> returns this number; | 2606 then <code>to_number</code> returns this number; |
2608 otherwise, it returns <b>nil</b>. | 2607 otherwise, it returns <b>nil</b>. |
2609 | 2608 |
2610 The conversion of strings can result in integers or floats. | 2609 The conversion of strings can result in integers or floats. |
2611 | 2610 |
2612 | 2611 |
2613 <p> | 2612 <p> |
2614 When called with <tt>base</tt>, | 2613 When called with <code>base</code>, |
2615 then <tt>s</tt> must be a string to be interpreted as | 2614 then <code>s</code> must be a string to be interpreted as |
2616 an integer numeral in that base. | 2615 an integer numeral in that base. |
2617 In bases above 10, the letter '<tt>A</tt>' (in either upper or lower case) | 2616 In bases above 10, the letter '<code>A</code>' (in either upper or lower case) |
2618 represents 10, '<tt>B</tt>' represents 11, and so forth, | 2617 represents 10, '<code>B</code>' represents 11, and so forth, |
2619 with '<tt>Z</tt>' representing 35. | 2618 with '<code>Z</code>' representing 35. |
2620 If the string <tt>s</tt> is not a valid numeral in the given base, | 2619 If the string <code>s</code> is not a valid numeral in the given base, |
2621 the function returns <b>nil</b>. | 2620 the function returns <b>nil</b>. |
2622 | 2621 |
2623 | 2622 |
2624 | 2623 |
2625 <h4 <%=heading_options%> ><a name="String.trim"><tt>String.trim (s)</tt></a></h4> | 2624 <h4 heading><a name="String.trim"><code>String.trim (s)</code></a></h4> |
2626 | 2625 |
2627 <p> | 2626 <p> |
2628 Removes the leading and trailing whitespace by calling the Java method <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/String.html#trim()"><tt>String.trim</tt></a>. | 2627 Removes the leading and trailing whitespace by calling the Java method <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/String.html#trim()"><code>String.trim</code></a>. |
2629 | 2628 |
2630 | 2629 |
2631 | 2630 |
2632 | 2631 |
2633 <h4 <%=heading_options%> ><a name="String.unicode"><tt>String.unicode (s [, i [, j]])</tt></a></h4> | 2632 <h4 heading><a name="String.unicode"><code>String.unicode (s [, i [, j]])</code></a></h4> |
2634 | 2633 |
2635 <p> | 2634 <p> |
2636 Returns the internal numerical codes of the characters <tt>s[i]</tt>, | 2635 Returns the internal numerical codes of the characters <code>s[i]</code>, |
2637 <tt>s[i+1]</tt>, ..., <tt>s[j]</tt>. | 2636 <code>s[i+1]</code>, ..., <code>s[j]</code>. |
2638 The default value for <tt>i</tt> is 1; | 2637 The default value for <code>i</code> is 1; |
2639 the default value for <tt>j</tt> is <tt>i</tt>. | 2638 the default value for <code>j</code> is <code>i</code>. |
2640 These indices are corrected | 2639 These indices are corrected |
2641 following the same rules of function <a href="#String.sub"><tt>String.sub</tt></a>. | 2640 following the same rules of function <a href="#String.sub"><code>String.sub</code></a>. |
2642 | 2641 |
2643 | 2642 |
2644 | 2643 |
2645 | 2644 |
2646 | 2645 |
2647 <h4 <%=heading_options%> ><a name="String.upper"><tt>String.upper (s)</tt></a></h4> | 2646 <h4 heading><a name="String.upper"><code>String.upper (s)</code></a></h4> |
2648 <p> | 2647 <p> |
2649 Receives a string and returns a copy of this string with all | 2648 Receives a string and returns a copy of this string with all |
2650 lowercase letters changed to uppercase. | 2649 lowercase letters changed to uppercase. |
2651 All other characters are left unchanged. | 2650 All other characters are left unchanged. |
2652 The definition of what a lowercase letter is depends on the current locale. | 2651 The definition of what a lowercase letter is depends on the current locale. |
4595 Last change: minor edit | 4594 Last change: minor edit |
4596 --> | 4595 --> |
4597 | 4596 |
4598 </div> | 4597 </div> |
4599 | 4598 |
4600 <% Html.simply_html_body_bottom() %> | |
4601 </body> | 4599 </body> |
4602 </html> | 4600 </html> |
4603 <% | 4601 <% |
4604 end | 4602 end |