Mercurial Hosting > luan

comparison website/src/manual.html.luan @ 479:1285c52ea9d4

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
add manual heading_options
author Franklin Schmidt <fschmidt@gmail.com>
date Mon, 11 May 2015 15:29:29 -0600
parents eb6d90fb0b5c
children 7e9fcfbf22ec
comparison
equal deleted inserted replaced
478:eb6d90fb0b5c 479:1285c52ea9d4
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:web/Http" 4 local Http = require "luan:web/Http"
5 local Shared = require "site:/Shared" 5 local Shared = require "site:/Shared"
6 6
7 heading_options = [[margin-top="1em"]]
7 8
8 function service() 9 function service()
9 Io.stdout = Http.response.text_writer() 10 Io.stdout = Http.response.text_writer()
10 %> 11 %>
11 <html> 12 <html>
94 </div> 95 </div>
95 96
96 <hr/> 97 <hr/>
97 98
98 99
99 <h2 margin-top="1em"><a name="intro">Introduction</a></h2> 100 <h2 <%=heading_options%> ><a name="intro">Introduction</a></h2>
100 101
101 <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>
102 103
103 <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>
104 105
105 <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>
106 107
107 108
108 <h2 margin-top="1em"><a name="basic">Basic Concepts</a></h2> 109 <h2 <%=heading_options%> ><a name="basic">Basic Concepts</a></h2>
109 110
110 <p>This section describes the basic concepts of the language.</p> 111 <p>This section describes the basic concepts of the language.</p>
111 112
112 <h3 margin-top="1em"><a name="types">Values and Types</a></h3> 113 <h3 <%=heading_options%> ><a name="types">Values and Types</a></h3>
113 114
114 <p> 115 <p>
115 Luan is a <i>dynamically typed language</i>. 116 Luan is a <i>dynamically typed language</i>.
116 This means that 117 This means that
117 variables do not have types; only values do. 118 variables do not have types; only values do.
226 227
227 228
228 229
229 230
230 231
231 <h3 margin-top="1em"><a name="env">Environments</a></h3> 232 <h3 <%=heading_options%> ><a name="env">Environments</a></h3>
232 233
233 <p> 234 <p>
234 As will be discussed in <a href="#vars">Variables</a> and <a href=#assignment">Assignment</a>, 235 As will be discussed in <a href="#vars">Variables</a> and <a href=#assignment">Assignment</a>,
235 any reference to a free name 236 any reference to a free name
236 (that is, a name not bound to any declaration) <tt>var</tt> 237 (that is, a name not bound to any declaration) <tt>var</tt>
263 Luan also provides all chunks with two other local values: <tt>require</tt> and <tt>java</tt>. These are functions used to load and access libraries and other modules. 264 Luan also provides all chunks with two other local values: <tt>require</tt> and <tt>java</tt>. These are functions used to load and access libraries and other modules.
264 265
265 266
266 267
267 268
268 <h3 margin-top="1em"><a name="error">Error Handling</a></h3> 269 <h3 <%=heading_options%> ><a name="error">Error Handling</a></h3>
269 270
270 <p> 271 <p>
271 Luan code can explicitly generate an error by calling the 272 Luan code can explicitly generate an error by calling the
272 <a href="#Luan.error"><tt>error</tt></a> function. 273 <a href="#Luan.error"><tt>error</tt></a> function.
273 If you need to catch errors in Luan, 274 If you need to catch errors in Luan,
286 287
287 288
288 289
289 290
290 291
291 <h3 margin-top="1em"><a name="meta">Metatables and Metamethods</a></h3> 292 <h3 <%=heading_options%> ><a name="meta">Metatables and Metamethods</a></h3>
292 293
293 <p> 294 <p>
294 Every table in Luan can have a <i>metatable</i>. 295 Every table in Luan can have a <i>metatable</i>.
295 This <i>metatable</i> is an ordinary Luan table 296 This <i>metatable</i> is an ordinary Luan table
296 that defines the behavior of the original value 297 that defines the behavior of the original value
510 </ul> 511 </ul>
511 512
512 513
513 514
514 515
515 <h3 margin-top="1em"><a name="gc">Garbage Collection</a></h3> 516 <h3 <%=heading_options%> ><a name="gc">Garbage Collection</a></h3>
516 517
517 <p> 518 <p>
518 Luan uses Java's garbage collection. 519 Luan uses Java's garbage collection.
519 520
520 521
521 522
522 523
523 524
524 <h2 margin-top="1em"><a name="lang">The Language</a></h2> 525 <h2 <%=heading_options%> ><a name="lang">The Language</a></h2>
525 526
526 <p> 527 <p>
527 This section describes the lexis, the syntax, and the semantics of Luan. 528 This section describes the lexis, the syntax, and the semantics of Luan.
528 In other words, 529 In other words,
529 this section describes 530 this section describes
543 The complete syntax of Luan can be found in <a href="#9">&sect;9</a> 544 The complete syntax of Luan can be found in <a href="#9">&sect;9</a>
544 at the end of this manual. 545 at the end of this manual.
545 546
546 547
547 548
548 <h3 margin-top="1em"><a name="lex">Lexical Conventions</a></h3> 549 <h3 <%=heading_options%> ><a name="lex">Lexical Conventions</a></h3>
549 550
550 <p> 551 <p>
551 Luan ignores spaces and comments 552 Luan ignores spaces and comments
552 between lexical elements (tokens), 553 between lexical elements (tokens),
553 except as delimiters between names and keywords. 554 except as delimiters between names and keywords.
718 719
719 720
720 721
721 722
722 723
723 <h3 margin-top="1em"><a name="vars">Variables</a></h3> 724 <h3 <%=heading_options%> ><a name="vars">Variables</a></h3>
724 725
725 <p> 726 <p>
726 Variables are places that store values. 727 Variables are places that store values.
727 There are three kinds of variables in Luan: 728 There are three kinds of variables in Luan:
728 global variables, local variables, and table fields. 729 global variables, local variables, and table fields.
786 787
787 788
788 789
789 790
790 791
791 <h3 margin-top="1em"><a name="stmts">Statements</a></h3> 792 <h3 <%=heading_options%> ><a name="stmts">Statements</a></h3>
792 793
793 <p> 794 <p>
794 Luan supports an almost conventional set of statements, 795 Luan supports an almost conventional set of statements,
795 similar to those in Pascal or C. 796 similar to those in Pascal or C.
796 This set includes 797 This set includes
797 assignments, control structures, function calls, 798 assignments, control structures, function calls,
798 and variable declarations. 799 and variable declarations.
799 800
800 801
801 802
802 <h4 margin-top="1em"><a name="blocks">Blocks</a></h4> 803 <h4 <%=heading_options%> ><a name="blocks">Blocks</a></h4>
803 804
804 <p> 805 <p>
805 A block is a list of statements, 806 A block is a list of statements,
806 which are executed sequentially: 807 which are executed sequentially:
807 808
835 836
836 837
837 838
838 839
839 840
840 <h4 margin-top="1em"><a name="chunks">Chunks</a></h4> 841 <h4 <%=heading_options%> ><a name="chunks">Chunks</a></h4>
841 842
842 <p> 843 <p>
843 The unit of compilation of Luan is called a <i>chunk</i>. 844 The unit of compilation of Luan is called a <i>chunk</i>.
844 Syntactically, 845 Syntactically,
845 a chunk is simply a block: 846 a chunk is simply a block:
865 866
866 867
867 868
868 869
869 870
870 <h4 margin-top="1em"><a name="assignment">Assignment</a></h4> 871 <h4 <%=heading_options%> ><a name="assignment">Assignment</a></h4>
871 872
872 <p> 873 <p>
873 Luan allows multiple assignments. 874 Luan allows multiple assignments.
874 Therefore, the syntax for assignment 875 Therefore, the syntax for assignment
875 defines a list of variables on the left side 876 defines a list of variables on the left side
949 <tt>_ENV.x = val</tt> (see <a href="#env">Environments</a>). 950 <tt>_ENV.x = val</tt> (see <a href="#env">Environments</a>).
950 951
951 952
952 953
953 954
954 <h4 margin-top="1em"><a name="control">Control Structures</a></h4> 955 <h4 <%=heading_options%> ><a name="control">Control Structures</a></h4>
955 956
956 <p> 957 <p>
957 The control structures 958 The control structures
958 <b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and 959 <b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and
959 familiar syntax: 960 familiar syntax:
1010 </pre></tt></p> 1011 </pre></tt></p>
1011 1012
1012 1013
1013 1014
1014 1015
1015 <h4 margin-top="1em"><a name="for">For Statement</a></h4> 1016 <h4 <%=heading_options%> ><a name="for">For Statement</a></h4>
1016 1017
1017 <p> 1018 <p>
1018 The <b>for</b> statement works over functions, 1019 The <b>for</b> statement works over functions,
1019 called <i>iterators</i>. 1020 called <i>iterators</i>.
1020 On each iteration, the iterator function is called to produce a new value, 1021 On each iteration, the iterator function is called to produce a new value,
1076 </ul> 1077 </ul>
1077 1078
1078 1079
1079 1080
1080 1081
1081 <h4 margin-top="1em"><a name="fn_stmt">Function Calls as Statements</a></h4> 1082 <h4 <%=heading_options%> ><a name="fn_stmt">Function Calls as Statements</a></h4>
1082 1083
1083 <p> 1084 <p>
1084 To allow possible side-effects, 1085 To allow possible side-effects,
1085 function calls can be executed as statements: 1086 function calls can be executed as statements:
1086 1087
1092 In this case, all returned values are thrown away. 1093 In this case, all returned values are thrown away.
1093 Function calls are explained in <a href="#fn_calls">Function Calls</a>. 1094 Function calls are explained in <a href="#fn_calls">Function Calls</a>.
1094 1095
1095 1096
1096 1097
1097 <h4 margin-top="1em"><a name="local_stmt">Local Declarations</a></h4> 1098 <h4 <%=heading_options%> ><a name="local_stmt">Local Declarations</a></h4>
1098 1099
1099 <p> 1100 <p>
1100 Local variables can be declared anywhere inside a block. 1101 Local variables can be declared anywhere inside a block.
1101 The declaration can include an initial assignment: 1102 The declaration can include an initial assignment:
1102 1103
1117 1118
1118 <p> 1119 <p>
1119 The visibility rules for local variables are explained in <a href="#visibility">Visibility Rules</a>. 1120 The visibility rules for local variables are explained in <a href="#visibility">Visibility Rules</a>.
1120 1121
1121 1122
1122 <h4 margin-top="1em"><a name="template_stmt">Template Statements</a></h4> 1123 <h4 <%=heading_options%> ><a name="template_stmt">Template Statements</a></h4>
1123 1124
1124 <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> 1125 <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>
1125 1126
1126 <p><tt><pre><%=Html.encode[[ 1127 <p><tt><pre><%=Html.encode[[
1127 local name = "Bob" 1128 local name = "Bob"
1141 <% ) 1142 <% )
1142 ]]%></pre></tt></p> 1143 ]]%></pre></tt></p>
1143 1144
1144 1145
1145 1146
1146 <h3 margin-top="1em"><a name="expressions">Expressions</a></h3> 1147 <h3 <%=heading_options%> ><a name="expressions">Expressions</a></h3>
1147 1148
1148 <p> 1149 <p>
1149 The basic expressions in Luan are the following: 1150 The basic expressions in Luan are the following:
1150 1151
1151 <p><tt><pre> 1152 <p><tt><pre>
1227 (The value of <tt>(f(x,y,z))</tt> is the first value returned by <tt>f</tt> 1228 (The value of <tt>(f(x,y,z))</tt> is the first value returned by <tt>f</tt>
1228 or <b>nil</b> if <tt>f</tt> does not return any values.) 1229 or <b>nil</b> if <tt>f</tt> does not return any values.)
1229 1230
1230 1231
1231 1232
1232 <h4 margin-top="1em"><a name="arithmetic">Arithmetic Operators</a></h4> 1233 <h4 <%=heading_options%> ><a name="arithmetic">Arithmetic Operators</a></h4>
1233 1234
1234 <p> 1235 <p>
1235 Luan supports the following arithmetic operators: 1236 Luan supports the following arithmetic operators:
1236 1237
1237 <ul> 1238 <ul>
1252 that rounds the quotient towards minus infinite (floor division). 1253 that rounds the quotient towards minus infinite (floor division).
1253 (The Java modulo operator is not used.) 1254 (The Java modulo operator is not used.)
1254 1255
1255 1256
1256 1257
1257 <h4 margin-top="1em"><a name="conversions">Coercions and Conversions</a></h4> 1258 <h4 <%=heading_options%> ><a name="conversions">Coercions and Conversions</a></h4>
1258 1259
1259 <p> 1260 <p>
1260 Luan generally avoids automatic conversions. 1261 Luan generally avoids automatic conversions.
1261 String concatenation automatically converts all of its arguments to strings. 1262 String concatenation automatically converts all of its arguments to strings.
1262 1263
1264 Luan provides library functions for explicit type conversions. 1265 Luan provides library functions for explicit type conversions.
1265 1266
1266 1267
1267 1268
1268 1269
1269 <h4 margin-top="1em"><a name="relational">Relational Operators</a></h4> 1270 <h4 <%=heading_options%> ><a name="relational">Relational Operators</a></h4>
1270 1271
1271 <p> 1272 <p>
1272 Luan supports the following relational operators: 1273 Luan supports the following relational operators:
1273 1274
1274 <ul> 1275 <ul>
1330 1331
1331 1332
1332 1333
1333 1334
1334 1335
1335 <h4 margin-top="1em"><a name="logical_ops">Logical Operators</a></h4> 1336 <h4 <%=heading_options%> ><a name="logical_ops">Logical Operators</a></h4>
1336 1337
1337 <p> 1338 <p>
1338 The logical operators in Luan are 1339 The logical operators in Luan are
1339 <b>and</b>, <b>or</b>, and <b>not</b>. 1340 <b>and</b>, <b>or</b>, and <b>not</b>.
1340 The <b>and</b> and <b>or</b> operators consider both <b>false</b> and <b>nil</b> as false 1341 The <b>and</b> and <b>or</b> operators consider both <b>false</b> and <b>nil</b> as false
1370 (In this manual, 1371 (In this manual,
1371 <tt>--&gt;</tt> indicates the result of the preceding expression.) 1372 <tt>--&gt;</tt> indicates the result of the preceding expression.)
1372 1373
1373 1374
1374 1375
1375 <h4 margin-top="1em"><a name="concatenation">Concatenation</a></h4> 1376 <h4 <%=heading_options%> ><a name="concatenation">Concatenation</a></h4>
1376 1377
1377 <p> 1378 <p>
1378 The string concatenation operator in Luan is 1379 The string concatenation operator in Luan is
1379 denoted by two dots ('<tt>..</tt>'). 1380 denoted by two dots ('<tt>..</tt>').
1380 All operands are converted to strings. 1381 All operands are converted to strings.
1381 1382
1382 1383
1383 1384
1384 <h4 margin-top="1em"><a name="length">The Length Operator</a></h4> 1385 <h4 <%=heading_options%> ><a name="length">The Length Operator</a></h4>
1385 1386
1386 <p> 1387 <p>
1387 The length operator is denoted by the unary prefix operator <tt>#</tt>. 1388 The length operator is denoted by the unary prefix operator <tt>#</tt>.
1388 The length of a string is its number of characters. 1389 The length of a string is its number of characters.
1389 The length of a binary is its number of bytes. 1390 The length of a binary is its number of bytes.
1413 1414
1414 1415
1415 1416
1416 1417
1417 1418
1418 <h4 margin-top="1em"><a name="precedence">Precedence</a></h4> 1419 <h4 <%=heading_options%> ><a name="precedence">Precedence</a></h4>
1419 1420
1420 <p> 1421 <p>
1421 Operator precedence in Luan follows the table below, 1422 Operator precedence in Luan follows the table below,
1422 from lower to higher priority: 1423 from lower to higher priority:
1423 1424
1441 1442
1442 1443
1443 1444
1444 1445
1445 1446
1446 <h4 margin-top="1em"><a name="constructors">Table Constructors</a></h4> 1447 <h4 <%=heading_options%> ><a name="constructors">Table Constructors</a></h4>
1447 1448
1448 <p> 1449 <p>
1449 Table constructors are expressions that create tables. 1450 Table constructors are expressions that create tables.
1450 Every time a constructor is evaluated, a new table is created. 1451 Every time a constructor is evaluated, a new table is created.
1451 A constructor can be used to create an empty table 1452 A constructor can be used to create an empty table
1509 1510
1510 1511
1511 1512
1512 1513
1513 1514
1514 <h4 margin-top="1em"><a name="fn_calls">Function Calls</a></h4> 1515 <h4 <%=heading_options%> ><a name="fn_calls">Function Calls</a></h4>
1515 1516
1516 <p> 1517 <p>
1517 A function call in Luan has the following syntax: 1518 A function call in Luan has the following syntax:
1518 1519
1519 <p><tt><pre> 1520 <p><tt><pre>
1578 </pre></tt></p> 1579 </pre></tt></p>
1579 1580
1580 1581
1581 1582
1582 1583
1583 <h4 margin-top="1em"><a name="fn_def">Function Definitions</a></h4> 1584 <h4 <%=heading_options%> ><a name="fn_def">Function Definitions</a></h4>
1584 1585
1585 <p> 1586 <p>
1586 The syntax for function definition is 1587 The syntax for function definition is
1587 1588
1588 <p><tt><pre> 1589 <p><tt><pre>
1726 If control reaches the end of a function 1727 If control reaches the end of a function
1727 without encountering a <b>return</b> statement, 1728 without encountering a <b>return</b> statement,
1728 then the function returns with no results. 1729 then the function returns with no results.
1729 1730
1730 1731
1731 <h4 margin-top="1em"><a name="template_expr">Template Expressions</a></h4> 1732 <h4 <%=heading_options%> ><a name="template_expr">Template Expressions</a></h4>
1732 1733
1733 <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> 1734 <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>
1734 1735
1735 <p><tt><pre><%=Html.encode[[ 1736 <p><tt><pre><%=Html.encode[[
1736 local name = "Bob" 1737 local name = "Bob"
1746 1747
1747 <p>The strings in template expressions may be multiple lines.</p> 1748 <p>The strings in template expressions may be multiple lines.</p>
1748 1749
1749 1750
1750 1751
1751 <h3 margin-top="1em"><a name="visibility">Visibility Rules</a></h3> 1752 <h3 <%=heading_options%> ><a name="visibility">Visibility Rules</a></h3>
1752 1753
1753 <p> 1754 <p>
1754 Luan is a lexically scoped language. 1755 Luan is a lexically scoped language.
1755 The scope of a local variable begins at the first statement after 1756 The scope of a local variable begins at the first statement after
1756 its declaration and lasts until the last non-void statement 1757 its declaration and lasts until the last non-void statement
1809 1810
1810 1811
1811 1812
1812 1813
1813 1814
1814 <h2 margin-top="1em"><a name="libs">Standard Libraries</a></h2> 1815 <h2 <%=heading_options%> ><a name="libs">Standard Libraries</a></h2>
1815 1816
1816 <p> 1817 <p>
1817 The standard Luan libraries provide useful functions 1818 The standard Luan libraries provide useful functions
1818 that are implemented both in Java and in Luan itself. 1819 that are implemented both in Java and in Luan itself.
1819 How each function is implemented shouldn't matter to the user. 1820 How each function is implemented shouldn't matter to the user.
1820 Some of these functions provide essential services to the language 1821 Some of these functions provide essential services to the language
1821 (e.g., <a href="#Luan.type"><tt>type</tt></a> and <a href="#Luan.get_metatable"><tt>get_metatable</tt></a>); 1822 (e.g., <a href="#Luan.type"><tt>type</tt></a> and <a href="#Luan.get_metatable"><tt>get_metatable</tt></a>);
1822 others provide access to "outside" services (e.g., I/O). 1823 others provide access to "outside" services (e.g., I/O).
1823 1824
1824 1825
1825 <h3 margin-top="1em"><a name="default_lib">Default Environment</a></h3> 1826 <h3 <%=heading_options%> ><a name="default_lib">Default Environment</a></h3>
1826 1827
1827 <p> 1828 <p>
1828 These are provided by default as local variables for any Luan code as described in <a href="#env">Environments</a>. 1829 These are provided by default as local variables for any Luan code as described in <a href="#env">Environments</a>.
1829 1830
1830 1831
1831 <h4 margin-top="1em"><a name="_ENV"><tt>_ENV</tt></a></h4> 1832 <h4 <%=heading_options%> ><a name="_ENV"><tt>_ENV</tt></a></h4>
1832 1833
1833 <p> 1834 <p>
1834 This is a table that holds the global variables of a module as described in <a href="#env">Environments</a>. 1835 This is a table that holds the global variables of a module as described in <a href="#env">Environments</a>.
1835 1836
1836 1837
1837 <h4 margin-top="1em"><a name="require"><tt>java ()</tt></a></h4> 1838 <h4 <%=heading_options%> ><a name="require"><tt>java ()</tt></a></h4>
1838 1839
1839 <p> 1840 <p>
1840 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. 1841 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.
1841 1842
1842 1843
1843 <h4 margin-top="1em"><a name="require"><tt>require (mod_uri)</tt></a></h4> 1844 <h4 <%=heading_options%> ><a name="require"><tt>require (mod_uri)</tt></a></h4>
1844 1845
1845 <p> 1846 <p>
1846 Example use: 1847 Example use:
1847 1848
1848 <p><tt><pre> 1849 <p><tt><pre>
1857 return <a href="#Package.load">Package.load</a>(mod_name) or <a href="#Luan.error">Luan.error</a>("module '"..mod_name.."' not found") 1858 return <a href="#Package.load">Package.load</a>(mod_name) or <a href="#Luan.error">Luan.error</a>("module '"..mod_name.."' not found")
1858 end 1859 end
1859 </pre></tt></p> 1860 </pre></tt></p>
1860 1861
1861 1862
1862 <h3 margin-top="1em"><a name="luan_lib">Basic Functions</a></h3> 1863 <h3 <%=heading_options%> ><a name="luan_lib">Basic Functions</a></h3>
1863 1864
1864 <p> 1865 <p>
1865 Include this library by: 1866 Include this library by:
1866 1867
1867 <p><tt><pre> 1868 <p><tt><pre>
1870 1871
1871 <p> 1872 <p>
1872 The basic library provides basic functions to Luan that don't depend on other libaries. 1873 The basic library provides basic functions to Luan that don't depend on other libaries.
1873 1874
1874 1875
1875 <h4 margin-top="1em"><a name="Luan.assert"><tt>Luan.assert (v [, message])</tt></a></h4> 1876 <h4 <%=heading_options%> ><a name="Luan.assert"><tt>Luan.assert (v [, message])</tt></a></h4>
1876 1877
1877 <p> 1878 <p>
1878 Could be defined as: 1879 Could be defined as:
1879 1880
1880 <p><tt><pre> 1881 <p><tt><pre>
1882 return v or <a href="#Luan.error">Luan.error</a>(message or "assertion failed!") 1883 return v or <a href="#Luan.error">Luan.error</a>(message or "assertion failed!")
1883 end 1884 end
1884 </pre></tt></p> 1885 </pre></tt></p>
1885 1886
1886 1887
1887 <h4 margin-top="1em"><a name="Luan.assert_binary"><tt>Luan.assert_binary (v)</tt></a></h4> 1888 <h4 <%=heading_options%> ><a name="Luan.assert_binary"><tt>Luan.assert_binary (v)</tt></a></h4>
1888 1889
1889 <p> 1890 <p>
1890 Could be defined as: 1891 Could be defined as:
1891 1892
1892 <p><tt><pre> 1893 <p><tt><pre>
1895 return v_type == "binary" and v or <a href="#Luan.error">Luan.error</a>("bad argument #1 (binary expected, got "..v_type..")") 1896 return v_type == "binary" and v or <a href="#Luan.error">Luan.error</a>("bad argument #1 (binary expected, got "..v_type..")")
1896 end 1897 end
1897 </pre></tt></p> 1898 </pre></tt></p>
1898 1899
1899 1900
1900 <h4 margin-top="1em"><a name="Luan.assert_boolean"><tt>Luan.assert_boolean (v)</tt></a></h4> 1901 <h4 <%=heading_options%> ><a name="Luan.assert_boolean"><tt>Luan.assert_boolean (v)</tt></a></h4>
1901 1902
1902 <p> 1903 <p>
1903 Like <a href="#Luan.assert_binary"><tt>assert_binary</tt></a> but for type <tt>boolean</tt>. 1904 Like <a href="#Luan.assert_binary"><tt>assert_binary</tt></a> but for type <tt>boolean</tt>.
1904 1905
1905 1906
1906 <h4 margin-top="1em"><a name="Luan.assert_integer"><tt>Luan.assert_integer (v)</tt></a></h4> 1907 <h4 <%=heading_options%> ><a name="Luan.assert_integer"><tt>Luan.assert_integer (v)</tt></a></h4>
1907 1908
1908 <p> 1909 <p>
1909 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. 1910 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.
1910 1911
1911 1912
1912 <h4 margin-top="1em"><a name="Luan.assert_long"><tt>Luan.assert_long (v)</tt></a></h4> 1913 <h4 <%=heading_options%> ><a name="Luan.assert_long"><tt>Luan.assert_long (v)</tt></a></h4>
1913 1914
1914 <p> 1915 <p>
1915 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. 1916 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.
1916 1917
1917 1918
1918 <h4 margin-top="1em"><a name="Luan.assert_number"><tt>Luan.assert_number (v)</tt></a></h4> 1919 <h4 <%=heading_options%> ><a name="Luan.assert_number"><tt>Luan.assert_number (v)</tt></a></h4>
1919 1920
1920 <p> 1921 <p>
1921 Like <a href="#Luan.assert_binary"><tt>assert_binary</tt></a> but for type <tt>number</tt>. 1922 Like <a href="#Luan.assert_binary"><tt>assert_binary</tt></a> but for type <tt>number</tt>.
1922 1923
1923 1924
1924 <h4 margin-top="1em"><a name="Luan.assert_string"><tt>Luan.assert_string (v)</tt></a></h4> 1925 <h4 <%=heading_options%> ><a name="Luan.assert_string"><tt>Luan.assert_string (v)</tt></a></h4>
1925 1926
1926 <p> 1927 <p>
1927 Like <a href="#Luan.assert_binary"><tt>assert_binary</tt></a> but for type <tt>string</tt>. 1928 Like <a href="#Luan.assert_binary"><tt>assert_binary</tt></a> but for type <tt>string</tt>.
1928 1929
1929 1930
1930 <h4 margin-top="1em"><a name="Luan.assert_table"><tt>Luan.assert_table (v)</tt></a></h4> 1931 <h4 <%=heading_options%> ><a name="Luan.assert_table"><tt>Luan.assert_table (v)</tt></a></h4>
1931 1932
1932 <p> 1933 <p>
1933 Like <a href="#Luan.assert_binary"><tt>assert_binary</tt></a> but for type <tt>table</tt>. 1934 Like <a href="#Luan.assert_binary"><tt>assert_binary</tt></a> but for type <tt>table</tt>.
1934 1935
1935 1936
1936 <h4 margin-top="1em"><a name="Luan.do_file"><tt>Luan.do_file ([uri])</tt></a></h4> 1937 <h4 <%=heading_options%> ><a name="Luan.do_file"><tt>Luan.do_file ([uri])</tt></a></h4>
1937 1938
1938 <p> 1939 <p>
1939 Could be defined as: 1940 Could be defined as:
1940 1941
1941 <p><tt><pre> 1942 <p><tt><pre>
1944 end 1945 end
1945 </pre></tt></p> 1946 </pre></tt></p>
1946 1947
1947 1948
1948 1949
1949 <h4 margin-top="1em"><a name="Luan.error"><tt>Luan.error (message)</tt></a></h4> 1950 <h4 <%=heading_options%> ><a name="Luan.error"><tt>Luan.error (message)</tt></a></h4>
1950 1951
1951 <p> 1952 <p>
1952 Throws an error containing the message. This uses Java exceptions internally and the implementation is likely to change. So this documentation is likely to change. 1953 Throws an error containing the message. This uses Java exceptions internally and the implementation is likely to change. So this documentation is likely to change.
1953 1954
1954 1955
1955 <h4 margin-top="1em"><a name="Luan.get_metatable"><tt>Luan.get_metatable (table)</tt></a></h4> 1956 <h4 <%=heading_options%> ><a name="Luan.get_metatable"><tt>Luan.get_metatable (table)</tt></a></h4>
1956 1957
1957 <p> 1958 <p>
1958 If <tt>table</tt> does not have a metatable, returns <b>nil</b>. 1959 If <tt>table</tt> does not have a metatable, returns <b>nil</b>.
1959 Otherwise, 1960 Otherwise,
1960 if the table's metatable has a <tt>"__metatable"</tt> field, 1961 if the table's metatable has a <tt>"__metatable"</tt> field,
1961 returns the associated value. 1962 returns the associated value.
1962 Otherwise, returns the metatable of the given table. 1963 Otherwise, returns the metatable of the given table.
1963 1964
1964 1965
1965 <h4 margin-top="1em"><a name="Luan.ipairs"><tt>Luan.ipairs (t)</tt></a></h4> 1966 <h4 <%=heading_options%> ><a name="Luan.ipairs"><tt>Luan.ipairs (t)</tt></a></h4>
1966 1967
1967 <p> 1968 <p>
1968 Returns an iterator function 1969 Returns an iterator function
1969 so that the construction 1970 so that the construction
1970 1971
1992 end 1993 end
1993 </pre></tt></p> 1994 </pre></tt></p>
1994 1995
1995 1996
1996 1997
1997 <h4 margin-top="1em"><a name="Luan.load"><tt>Luan.load (text, source_name [env, [, allow_expression]])</tt></a></h4> 1998 <h4 <%=heading_options%> ><a name="Luan.load"><tt>Luan.load (text, source_name [env, [, allow_expression]])</tt></a></h4>
1998 1999
1999 <p> 2000 <p>
2000 Loads a chunk. 2001 Loads a chunk.
2001 2002
2002 <p> 2003 <p>
2013 2014
2014 <p> 2015 <p>
2015 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. 2016 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.
2016 2017
2017 2018
2018 <h4 margin-top="1em"><a name="Luan.load_file"><tt>Luan.load_file (file_uri [, add_extension])</tt></a></h4> 2019 <h4 <%=heading_options%> ><a name="Luan.load_file"><tt>Luan.load_file (file_uri [, add_extension])</tt></a></h4>
2019 2020
2020 <p> 2021 <p>
2021 Similar to <a href="#Luan.load"><tt>load</tt></a>, 2022 Similar to <a href="#Luan.load"><tt>load</tt></a>,
2022 but gets the chunk from file <tt>file_uri</tt> 2023 but gets the chunk from file <tt>file_uri</tt>
2023 or from the standard input, 2024 or from the standard input,
2035 end 2036 end
2036 </pre></tt></p> 2037 </pre></tt></p>
2037 2038
2038 2039
2039 2040
2040 <h4 margin-top="1em"><a name="Luan.pairs"><tt>Luan.pairs (t)</tt></a></h4> 2041 <h4 <%=heading_options%> ><a name="Luan.pairs"><tt>Luan.pairs (t)</tt></a></h4>
2041 2042
2042 <p> 2043 <p>
2043 If <tt>t</tt> has a metamethod <tt>__pairs</tt>, 2044 If <tt>t</tt> has a metamethod <tt>__pairs</tt>,
2044 calls it with <tt>t</tt> as argument and returns the 2045 calls it with <tt>t</tt> as argument and returns the
2045 result from the call. 2046 result from the call.
2057 <p> 2058 <p>
2058 will iterate over all key&ndash;value pairs of table <tt>t</tt>. 2059 will iterate over all key&ndash;value pairs of table <tt>t</tt>.
2059 2060
2060 2061
2061 2062
2062 <h4 margin-top="1em"><a name="Luan.pcall"><tt>Luan.pcall (f [, arg1, &middot;&middot;&middot;])</tt></a></h4> 2063 <h4 <%=heading_options%> ><a name="Luan.pcall"><tt>Luan.pcall (f [, arg1, &middot;&middot;&middot;])</tt></a></h4>
2063 2064
2064 <p> 2065 <p>
2065 Calls function <tt>f</tt> with 2066 Calls function <tt>f</tt> with
2066 the given arguments in <i>protected mode</i>. 2067 the given arguments in <i>protected mode</i>.
2067 This means that any error inside&nbsp;<tt>f</tt> is not propagated; 2068 This means that any error inside&nbsp;<tt>f</tt> is not propagated;
2087 For complete control over the output, 2088 For complete control over the output,
2088 use <a href="#pdf-string.format"><code>string.format</code></a> and <a href="#pdf-io.write"><code>io.write</code></a>. 2089 use <a href="#pdf-string.format"><code>string.format</code></a> and <a href="#pdf-io.write"><code>io.write</code></a>.
2089 2090
2090 2091
2091 2092
2092 <h4 margin-top="1em"><a name="Luan.range"><tt>Luan.range (start, stop [, step])</tt></a></h4> 2093 <h4 <%=heading_options%> ><a name="Luan.range"><tt>Luan.range (start, stop [, step])</tt></a></h4>
2093 2094
2094 <p> 2095 <p>
2095 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. 2096 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.
2096 2097
2097 <p> 2098 <p>
2124 end 2125 end
2125 </pre></tt></p> 2126 </pre></tt></p>
2126 2127
2127 2128
2128 2129
2129 <h4 margin-top="1em"><a name="Luan.raw_equal"><tt>Luan.raw_equal (v1, v2)</tt></a></h4> 2130 <h4 <%=heading_options%> ><a name="Luan.raw_equal"><tt>Luan.raw_equal (v1, v2)</tt></a></h4>
2130 2131
2131 <p> 2132 <p>
2132 Checks whether <tt>v1</tt> is equal to <tt>v2</tt>, 2133 Checks whether <tt>v1</tt> is equal to <tt>v2</tt>,
2133 without invoking any metamethod. 2134 without invoking any metamethod.
2134 Returns a boolean. 2135 Returns a boolean.
2135 2136
2136 2137
2137 2138
2138 <h4 margin-top="1em"><a name="Luan.raw_get"><tt>Luan.raw_get (table, index)</tt></a></h4> 2139 <h4 <%=heading_options%> ><a name="Luan.raw_get"><tt>Luan.raw_get (table, index)</tt></a></h4>
2139 2140
2140 <p> 2141 <p>
2141 Gets the real value of <tt>table[index]</tt>, 2142 Gets the real value of <tt>table[index]</tt>,
2142 without invoking any metamethod. 2143 without invoking any metamethod.
2143 <tt>table</tt> must be a table; 2144 <tt>table</tt> must be a table;
2144 <tt>index</tt> may be any value. 2145 <tt>index</tt> may be any value.
2145 2146
2146 2147
2147 2148
2148 <h4 margin-top="1em"><a name="Luan.raw_len"><tt>Luan.raw_len (v)</tt></a></h4> 2149 <h4 <%=heading_options%> ><a name="Luan.raw_len"><tt>Luan.raw_len (v)</tt></a></h4>
2149 2150
2150 <p> 2151 <p>
2151 Returns the length of the object <tt>v</tt>, 2152 Returns the length of the object <tt>v</tt>,
2152 which must be a table or a string, 2153 which must be a table or a string,
2153 without invoking any metamethod. 2154 without invoking any metamethod.
2154 Returns an integer. 2155 Returns an integer.
2155 2156
2156 2157
2157 2158
2158 <h4 margin-top="1em"><a name="Luan.raw_set"><tt>Luan.raw_set (table, index, value)</tt></a></h4> 2159 <h4 <%=heading_options%> ><a name="Luan.raw_set"><tt>Luan.raw_set (table, index, value)</tt></a></h4>
2159 2160
2160 <p> 2161 <p>
2161 Sets the real value of <tt>table[index]</tt> to <tt>value</tt>, 2162 Sets the real value of <tt>table[index]</tt> to <tt>value</tt>,
2162 without invoking any metamethod. 2163 without invoking any metamethod.
2163 <tt>table</tt> must be a table, 2164 <tt>table</tt> must be a table,
2166 2167
2167 <p> 2168 <p>
2168 This function returns <tt>table</tt>. 2169 This function returns <tt>table</tt>.
2169 2170
2170 2171
2171 <h4 margin-top="1em"><a name="Luan.set_metatable"><tt>Luan.set_metatable (table, metatable)</tt></a></h4> 2172 <h4 <%=heading_options%> ><a name="Luan.set_metatable"><tt>Luan.set_metatable (table, metatable)</tt></a></h4>
2172 2173
2173 <p> 2174 <p>
2174 Sets the metatable for the given table. 2175 Sets the metatable for the given table.
2175 If <tt>metatable</tt> is <b>nil</b>, 2176 If <tt>metatable</tt> is <b>nil</b>,
2176 removes the metatable of the given table. 2177 removes the metatable of the given table.
2215 the function returns <b>nil</b>. 2216 the function returns <b>nil</b>.
2216 2217
2217 2218
2218 2219
2219 2220
2220 <h4 margin-top="1em"><a name="Luan.to_string"><tt>Luan.to_string (v)</tt></a></h4> 2221 <h4 <%=heading_options%> ><a name="Luan.to_string"><tt>Luan.to_string (v)</tt></a></h4>
2221 2222
2222 <p> 2223 <p>
2223 Receives a value of any type and 2224 Receives a value of any type and
2224 converts it to a string in a human-readable format. 2225 converts it to a string in a human-readable format.
2225 2226
2229 with <tt>v</tt> as argument, 2230 with <tt>v</tt> as argument,
2230 and uses the result of the call as its result. 2231 and uses the result of the call as its result.
2231 2232
2232 2233
2233 2234
2234 <h4 margin-top="1em"><a name="Luan.try"><tt>Luan.try (t)</tt></a></h4> 2235 <h4 <%=heading_options%> ><a name="Luan.try"><tt>Luan.try (t)</tt></a></h4>
2235 2236
2236 <p> 2237 <p>
2237 Implements try-catch as found in other languages where each block is in table <tt>t</tt>. 2238 Implements try-catch as found in other languages where each block is in table <tt>t</tt>.
2238 2239
2239 <p> 2240 <p>
2253 } 2254 }
2254 </pre></tt></p> 2255 </pre></tt></p>
2255 2256
2256 2257
2257 2258
2258 <h4 margin-top="1em"><a name="Luan.type"><tt>Luan.type (v)</tt></a></h4> 2259 <h4 <%=heading_options%> ><a name="Luan.type"><tt>Luan.type (v)</tt></a></h4>
2259 2260
2260 <p> 2261 <p>
2261 Returns the type of its only argument, coded as a string. 2262 Returns the type of its only argument, coded as a string.
2262 The possible results of this function are 2263 The possible results of this function are
2263 "<tt>nil</tt>" (a string, not the value <b>nil</b>), 2264 "<tt>nil</tt>" (a string, not the value <b>nil</b>),
2268 "<tt>table</tt>", 2269 "<tt>table</tt>",
2269 "<tt>function</tt>", 2270 "<tt>function</tt>",
2270 and "<tt>userdata</tt>". 2271 and "<tt>userdata</tt>".
2271 2272
2272 2273
2273 <h4 margin-top="1em"><a name="Luan.values"><tt>Luan.values (&middot;&middot;&middot;)</tt></a></h4> 2274 <h4 <%=heading_options%> ><a name="Luan.values"><tt>Luan.values (&middot;&middot;&middot;)</tt></a></h4>
2274 2275
2275 <p> 2276 <p>
2276 Returns a function so that the construction 2277 Returns a function so that the construction
2277 2278
2278 <p><tt><pre> 2279 <p><tt><pre>
2282 <p> 2283 <p>
2283 will iterate over all values of <tt>&middot;&middot;&middot;</tt>. 2284 will iterate over all values of <tt>&middot;&middot;&middot;</tt>.
2284 2285
2285 2286
2286 2287
2287 <h4 margin-top="1em"><a name="Luan.VERSION"><tt>Luan.VERSION</tt></a></h4> 2288 <h4 <%=heading_options%> ><a name="Luan.VERSION"><tt>Luan.VERSION</tt></a></h4>
2288 2289
2289 <p> 2290 <p>
2290 A global variable (not a function) that 2291 A global variable (not a function) that
2291 holds a string containing the current interpreter version. 2292 holds a string containing the current interpreter version.
2292 The current value of this variable is "<tt><%=Luan.VERSION%></tt>". 2293 The current value of this variable is "<tt><%=Luan.VERSION%></tt>".
2294 2295
2295 2296
2296 2297
2297 2298
2298 2299
2299 <h3 margin-top="1em"><a name="package_lib">Modules</a></h3> 2300 <h3 <%=heading_options%> ><a name="package_lib">Modules</a></h3>
2300 2301
2301 <p> 2302 <p>
2302 Include this library by: 2303 Include this library by:
2303 2304
2304 <p><tt><pre> 2305 <p><tt><pre>
2308 <p> 2309 <p>
2309 The package library provides basic 2310 The package library provides basic
2310 facilities for loading modules in Luan. 2311 facilities for loading modules in Luan.
2311 2312
2312 2313
2313 <h4 margin-top="1em"><a name="Package.load"><tt>Package.load (mod_uri)</tt></a></h4> 2314 <h4 <%=heading_options%> ><a name="Package.load"><tt>Package.load (mod_uri)</tt></a></h4>
2314 2315
2315 <p> 2316 <p>
2316 Loads the given module. 2317 Loads the given module.
2317 The function starts by looking into the <a href="#Package.loaded"><tt>Package.loaded</tt></a> table 2318 The function starts by looking into the <a href="#Package.loaded"><tt>Package.loaded</tt></a> table
2318 to determine whether <tt>mod_uri</tt> is already loaded. 2319 to determine whether <tt>mod_uri</tt> is already loaded.
2330 If a new value for the module successful loaded, then it is stored in <tt>Package.loaded[mod_uri]</tt>. The value is returned. 2331 If a new value for the module successful loaded, then it is stored in <tt>Package.loaded[mod_uri]</tt>. The value is returned.
2331 2332
2332 2333
2333 2334
2334 2335
2335 <h4 margin-top="1em"><a name="Package.loaded"><tt>Package.loaded</tt></a></h4> 2336 <h4 <%=heading_options%> ><a name="Package.loaded"><tt>Package.loaded</tt></a></h4>
2336 2337
2337 2338
2338 <p> 2339 <p>
2339 A table used by <a href="#Package.load"><tt>Package.load</tt></a> to control which 2340 A table used by <a href="#Package.load"><tt>Package.load</tt></a> to control which
2340 modules are already loaded. 2341 modules are already loaded.