Mercurial Hosting > luan

comparison website/src/diff.html.luan @ 1653:418b610e887b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
docs work
author Franklin Schmidt <fschmidt@gmail.com>
date Thu, 31 Mar 2022 22:12:40 -0600
parents d5779a264a4a
children 2968e43cdd44
comparison
equal deleted inserted replaced
1652:d5779a264a4a 1653:418b610e887b
3 local Io = require "luan:Io.luan" 3 local Io = require "luan:Io.luan"
4 local Http = require "luan:http/Http.luan" 4 local Http = require "luan:http/Http.luan"
5 local Shared = require "site:/lib/Shared.luan" 5 local Shared = require "site:/lib/Shared.luan"
6 local head = Shared.head or error() 6 local head = Shared.head or error()
7 local docs_header = Shared.docs_header or error() 7 local docs_header = Shared.docs_header or error()
8 local show_toc = Shared.show_toc or error()
9 local show_content = Shared.show_content or error()
10
11
12 local content = {
13 intro = {
14 title = "Introduction"
15 content = function()
16 %>
17 <p>Lua is one of the simplest languages available, but Luan is even simpler. This means Luan removes more than it adds. Most of what is added is added in the library, not in the language itself.</p>
18
19 <p>Luan is implemented in Java and is tightly integrated with Java. This makes it an excellent scripting language for Java.</p>
20 <%
21 end
22 }
23 basic = {
24 title = "Basic Concepts"
25 subs = {
26 types = {
27 title = "Values and Types"
28 content = function()
29 %>
30 <p>Luan does not have the Lua <em>thread</em> type. Luan adds a <em>binary</em> type that Lua doesn't have. This is because Lua strings can represent binary while Luan strings cannot.</p>
31
32 <p>The Luan <em>Nil</em> type is implemented as the Java <em>null</em>. The Luan <em>Boolean</em> type is implemented as the Java <em>Boolean</em> type. The Luan <em>Number</em> type is implemented as the Java <em>Number</em> type. The Luan <em>String</em> type is implemented as the Java <em>String</em> type. Actual numbers may be any subclass of the Java <em>Number</em> class.</p>
33
34 <p>Luan functions may be written in Luan or may be wrappers around native Java methods. Any Java method may be called as a Luan function.</p>
35
36 <p>The Luan <em>java</em> type is a replacement for Lua's <em>userdata</em>. A Luan <em>java</em> value is nothing more than a Java object that doesn't fall into one of the other recognized types.</p>
37
38 <p>The Luan <em>binary</em> type is the Java <em>byte[ ]</em> type which is an array of bytes.</p>
39
40 <p>The Luan <em>table</em> type is just like its Lua equivalent, but implemented in Java.</p>
41 <%
42 end
43 }
44 env = {
45 title = "Environments"
46 content = function()
47 %>
48 <p>Luan has no global environment at all, no <code>_G</code>. By default, Luan doesn't define <code>_ENV</code> either, but if you define it as a local table in a chunk, then it acts like it does in Lua. When <code>_ENV</code> isn't defined, there are no global variables and an unrecognized variable name produces a compile error.</p>
49
50 <p>Every module is initialized with one local function: <code>require</code>. The module then uses this function to get access to whatever else it needs.</p>
51 <%
52 end
53 }
54 error = {
55 title = "Error Handling"
56 content = function()
57 %>
58 <p>Luan has the function <code>error</code> but does not have <code>pcall</code> or <code>xpcall</code>. Luan adds the <a href="#try">try statement</a> instead. Luan errors are implemented as an error table, not as a message object.</p>
59 <%
60 end
61 }
62 meta = {
63 title = "Metatables and Metamethods"
64 content = function()
65 %>
66 <p>Luan only has metatable for tables, not for other types.</p>
67
68 <p>Luan does not support the <b>call</b> metamethod. There is nothing that one can do with the <b>call</b> metamethod that can't be done more cleanly with closures, so this was left out.</p>
69 <%
70 end
71 }
72 gc = {
73 title = "Garbage Collection"
74 content = function()
75 %>
76 <p>Luan uses Java garbage collection. Luan has no special garbage collection methods.</p>
77
78 <p>Luan does not yet have weak tables but this will be added.</p>
79 <%
80 end
81 }
82 coroutines = {
83 title = "Coroutines"
84 content = function()
85 %>
86 <p>Luan does not have coroutines. Coroutines is a complex concept that isn't needed in a simple language, so it was left out.</p>
87 <%
88 end
89 }
90 }
91 }
92 lang = {
93 title = "The Language"
94 subs = {
95 lex = {
96 title = "Lexical Conventions"
97 content = function()
98 %>
99 <p>Unlike Lua, Luan considers the end of a line to be the end of a statement. This catches errors and encourages readability. If you want to continue a statement on another line, you can use a backslash followed by a newline which will be treated as white space.</p>
100
101 <p>Luan has exactly the same set of keywords as Lua and has the same other lexical conventions.</p>
102 <%
103 end
104 }
105 vars = {
106 title = "Variables"
107 content = function()
108 %>
109 <p>By default, there are no global variables and an undefined variable produces a compile error. To enable global variables, one must define <code>_ENV</code>. Avoiding global variables makes it much easier to catch errors at compile time.</p>
110 <%
111 end
112 }
113 stmt = {
114 title = "Statements"
115 content = function()
116 %>
117 <p>Luan adds the block terminators <b>end_do</b>, <b>end_for</b>, <b>end_function</b>, <b>end_if</b>, <b>end_try</b>, and <b>end_while</b>. These can be used to end the appropriate block type, but <b>end</b> can also be used to end any block.</p>
118
119 <p>Most statements in Luan are the same as Lua. Only those statements that differ will be listed here.</p>
120 <%
121 end
122 subs = {
123 control = {
124 title = "Control Structures"
125 content = function()
126 %>
127 <p>The Luan <b>if</b>, <b>while</b>, and <b>repeat</b> statement are the same as in Lua except that the condition expression must return a boolean value. Any other value type will produce an error. This helps catch errors and makes code more readable.</p>
128
129 <p>Luan adds the <b>continue</b> statement which is used inside loops.</p>
130
131 <p>Luan does not have a <b>goto</b> statement.</p>
132 <%
133 end
134 }
135 ["for"] = {
136 title = "For Statement"
137 content = function()
138 %>
139 <p>Luan has no numeric <b>for</b> statement. Luan only has generic <b>for</b> statement. Instead of the numeric <b>for</b> statement, Luan uses the <code>range</code> function in a generic <b>for</b> statement like this:</p>
140
141 <pre>
142 for i in range(from,to,step) do <em>block</em> end
143 </pre>
144
145 <p>The Luan generic <b>for</b> statement is simpler than the Lua version because Luan only uses an expression, not an explist. So a <b>for</b> statement like:</p>
146
147 <pre>
148 for var_1, &middot;&middot;&middot;, var_n in exp do block end
149 </pre>
150
151 <p>is equivalent to the code:</p>
152
153 <pre>
154 do
155 local f = exp
156 while true do
157 local var_1, &middot;&middot;&middot;, var_n = f()
158 if var_1 == nil then break end
159 block
160 end
161 end
162 </pre>
163 <%
164 end
165 }
166 ["try"] = {
167 title = "Try Statement"
168 content = function()
169 %>
170 <p>Unlike Lua, Luan has a <b>try</b> statement. See <a href="manual.html#try">Try Statement</a> in the Luan Reference Manual. This also eliminates the need for Lua's <b>pcall</b> function which Luan doesn't have.</p>
171 <%
172 end
173 }
174 logical = {
175 title = "Logical Statements"
176 content = function()
177 %>
178 <p>Unlike Lua, Luan allows <b>or</b> and <b>and</b> expressions to be stand-alone statements. This is useful in cases like this:</p>
179
180 <pre>
181 x==5 or error "x should be 5"
182 </pre>
183 <%
184 end
185 }
186 template_stmt = {
187 title = "Template Statements"
188 content = function()
189 %>
190 <p>Template statements are a Luan addition that don't exist in Lua. See <a href="manual.html#template_stmt">Template Statements</a> in the Luan Reference Manual.</p>
191 <%
192 end
193 }
194 }
195 }
196 expr = {
197 title = "Expressions"
198 subs = {
199 conversions = {
200 title = "Coercions and Conversions"
201 content = function()
202 %>
203 <p>Unlike Lua, Luan does not do automatic conversions of strings to numbers.</p>
204 <%
205 end
206 }
207 bit = {
208 title = "Bitwise Operators"
209 content = function()
210 %>
211 <p>Bitwise operators appear to be a new addition to Lua 5.3 and didn't exist in Lua 5.2. Luan does not support bitwise operators, but these can be added if there is a need.</p>
212 <%
213 end
214 }
215 logical_ops = {
216 title = "Logical Operators"
217 content = function()
218 %>
219 <p>The only change in Luan is that <b>not</b> must take a boolean argument. This helps catch errors and makes code more readable.</p>
220 <%
221 end
222 }
223 concatenation = {
224 title = "Concatenation"
225 content = function()
226 %>
227 <p>Unlike Lua, Luan converts all concatenation operands to strings.</p>
228 <%
229 end
230 }
231 constructors = {
232 title = "Table Constructors"
233 content = function()
234 %>
235 <p>Unlike Lua, Luan considers an <b>end_of_line</b> to be a field separator in a table constructor.</p>
236 <%
237 end
238 }
239 fn_calls = {
240 title = "Function Calls"
241 content = function()
242 %>
243 <p>Unlike Lua, Luan does not allow extra non-nil arguments to be passed to a function. In Luan, this causes an error. This change helps find coding mistakes that would be very hard to detect otherwise.</p>
244
245 <p>Luan does not support Lua's <code>v:name(args)</code> style object-oriented function call. Object oriented programming is done in Luan using closures, so this feature is not needed.</p>
246
247 <p>Luan doesn't support <em>proper tail calls</em>. Because Java doesn't support this cleanly, this was left out.</p>
248 <%
249 end
250 }
251 }
252 }
253 }
254 }
255 }
8 256
9 257
10 return function() 258 return function()
11 Io.stdout = Http.response.text_writer() 259 Io.stdout = Http.response.text_writer()
12 %> 260 %>
17 <title>How Luan differs from Lua</title> 265 <title>How Luan differs from Lua</title>
18 </head> 266 </head>
19 <body> 267 <body>
20 <% docs_header() %> 268 <% docs_header() %>
21 <div content> 269 <div content>
22 270 <h1><a href="diff.html">How Luan differs from Lua</a></h1>
23 <h1><a href="diff.html">How Luan differs from Lua</a></h1> 271 <p>This document explains how Luan differs from <a href="http://www.lua.org">Lua</a> as described in the <a href="http://www.lua.org/manual/5.3/">Lua 5.3 Reference Manual</a>.</p>
24 272 <hr>
25 <p>This document explains how Luan differs from <a href="http://www.lua.org">Lua</a> as described in the <a href="http://www.lua.org/manual/5.3/">Lua 5.3 Reference Manual</a>.</p> 273 <h2>Contents</h2>
26 274 <div toc>
27 <hr/> 275 <% show_toc(content) %>
28 276 </div>
29 <h2>Contents</h2> 277 <hr>
30 278 <% show_content(content,2) %>
31 <div contents><a href="#intro">Introduction</a></div>
32
33 <div contents>
34 <a href="#basic">Basic Concepts</a>
35 <ul>
36 <li><a href="#types">Values and Types</a></li>
37 <li><a href="#env">Environments</a></li>
38 <li><a href="#error">Error Handling</a></li>
39 <li><a href="#meta">Metatables and Metamethods</a></li>
40 <li><a href="#gc">Garbage Collection</a></li>
41 <li><a href="#coroutines">Coroutines</a></li>
42 </ul>
43 </div>
44
45 <div contents>
46 <a href="#lang">The Language</a>
47 <ul>
48 <li><a href="#lex">Lexical Conventions</a></li>
49 <li><a href="#vars">Variables</a></li>
50 <li>
51 <a href="#stmt">Statements</a>
52 <ul>
53 <li><a href="#control">Control Structures</a></li>
54 <li><a href="#for">For Statement</a></li>
55 <li><a href="#try">Try Statement</a></li>
56 <li><a href="#logical">Logical Statements</a></li>
57 <li><a href="#template_stmt">Template Statements</a></li>
58 </ul>
59 </li>
60 <li>
61 <a href="#expr">Expressions</a>
62 <ul>
63 <li><a href="#conversions">Coercions and Conversions</a></li>
64 <li><a href="#bit">Bitwise Operators</a></li>
65 <li><a href="#logical_ops">Logical Operators</a></li>
66 <li><a href="#concatenation">Concatenation</a></li>
67 <li><a href="#constructors">Table Constructors</a></li>
68 <li><a href="#fn_calls">Function Calls</a></li>
69 </ul>
70 </li>
71 </ul>
72 </div>
73
74 <hr/>
75
76 <h2 heading><a name="intro" href="#intro">Introduction</a></h2>
77
78 <p>Lua is one of the simplest languages available, but Luan is even simpler. This means Luan removes more than it adds. Most of what is added is added in the library, not in the language itself.</p>
79
80 <p>Luan is implemented in Java and is tightly integrated with Java. This makes it an excellent scripting language for Java.</p>
81
82 <h2 heading><a name="basic" href="#basic">Basic Concepts</a></h2>
83
84 <h3 heading><a name="types" href="#types">Values and Types</a></h3>
85
86 <p>Luan does not have the Lua <em>thread</em> type. Luan adds a <em>binary</em> type that Lua doesn't have. This is because Lua strings can represent binary while Luan strings cannot.</p>
87
88 <p>The Luan <em>Nil</em> type is implemented as the Java <em>null</em>. The Luan <em>Boolean</em> type is implemented as the Java <em>Boolean</em> type. The Luan <em>Number</em> type is implemented as the Java <em>Number</em> type. The Luan <em>String</em> type is implemented as the Java <em>String</em> type. Actual numbers may be any subclass of the Java <em>Number</em> class.</p>
89
90 <p>Luan functions may be written in Luan or may be wrappers around native Java methods. Any Java method may be called as a Luan function.</p>
91
92 <p>The Luan <em>java</em> type is a replacement for Lua's <em>userdata</em>. A Luan <em>java</em> value is nothing more than a Java object that doesn't fall into one of the other recognized types.</p>
93
94 <p>The Luan <em>binary</em> type is the Java <em>byte[ ]</em> type which is an array of bytes.</p>
95
96 <p>The Luan <em>table</em> type is just like its Lua equivalent, but implemented in Java.</p>
97
98 <h3 heading><a name="env" href="#env">Environments</a></h3>
99
100 <p>Luan has no global environment at all, no <code>_G</code>. By default, Luan doesn't define <code>_ENV</code> either, but if you define it as a local table in a chunk, then it acts like it does in Lua. When <code>_ENV</code> isn't defined, there are no global variables and an unrecognized variable name produces a compile error.</p>
101
102 <p>Every module is initialized with one local function: <code>require</code>. The module then uses this function to get access to whatever else it needs.</p>
103
104 <h3 heading><a name="error" href="#error">Error Handling</a></h3>
105
106 <p>Luan has the function <code>error</code> but does not have <code>pcall</code> or <code>xpcall</code>. Luan adds the <a href="#try">try statement</a> instead. Luan errors are implemented as an error table, not as a message object.</p>
107
108 <h3 heading><a name="meta" href="#meta">Metatables and Metamethods</a></h3>
109
110 <p>Luan only has metatable for tables, not for other types.</p>
111
112 <p>Luan does not support the <b>call</b> metamethod. There is nothing that one can do with the <b>call</b> metamethod that can't be done more cleanly with closures, so this was left out.</p>
113
114 <h3 heading><a name="gc" href="#gc">Garbage Collection</a></h3>
115
116 <p>Luan uses Java garbage collection. Luan has no special garbage collection methods.</p>
117
118 <p>Luan does not yet have weak tables but this will be added.</p>
119
120 <h3 heading><a name="coroutines" href="#coroutines">Coroutines</a></h3>
121
122 <p>Luan does not have coroutines. Coroutines is a complex concept that isn't needed in a simple language, so it was left out.</p>
123
124 <h2 heading><a name="lang" href="#lang">The Language</a></h2>
125
126 <h3 heading><a name="lex" href="#lex">Lexical Conventions</a></h3>
127
128 <p>Unlike Lua, Luan considers the end of a line to be the end of a statement. This catches errors and encourages readability. If you want to continue a statement on another line, you can use a backslash followed by a newline which will be treated as white space.</p>
129
130 <p>Luan has exactly the same set of keywords as Lua and has the same other lexical conventions.</p>
131
132 <h3 heading><a name="vars" href="#vars">Variables</a></h3>
133
134 <p>
135 By default, there are no global variables and an undefined variable produces a compile error. To enable global variables, one must define <code>_ENV</code>. Avoiding global variables makes it much easier to catch errors at compile time.
136
137 <h3 heading><a name="stmt" href="#stmt">Statements</a></h3>
138
139 <p>Luan adds the block terminators <b>end_do</b>, <b>end_for</b>, <b>end_function</b>, <b>end_if</b>, <b>end_try</b>, and <b>end_while</b>. These can be used to end the appropriate block type, but <b>end</b> can also be used to end any block.</p>
140
141 <p>Most statements in Luan are the same as Lua. Only those statements that differ will be listed here.</p>
142
143 <h4 heading><a name="control" href="#control">Control Structures</a></h4>
144
145 <p>The Luan <b>if</b>, <b>while</b>, and <b>repeat</b> statement are the same as in Lua except that the condition expression must return a boolean value. Any other value type will produce an error. This helps catch errors and makes code more readable.</p>
146
147 <p>Luan adds the <b>continue</b> statement which is used inside loops.</p>
148
149 <p>Luan does not have a <b>goto</b> statement.</p>
150
151 <h4 heading><a name="for" href="#for">For Statement</a></h4>
152
153 <p>Luan has no numeric <b>for</b> statement. Luan only has generic <b>for</b> statement. Instead of the numeric <b>for</b> statement, Luan uses the <code>range</code> function in a generic <b>for</b> statement like this:</p>
154
155 <pre>
156 for i in range(from,to,step) do <em>block</em> end
157 </pre>
158
159 <p>The Luan generic <b>for</b> statement is simpler than the Lua version because Luan only uses an expression, not an explist. So a <b>for</b> statement like:</p>
160
161 <pre>
162 for var_1, &middot;&middot;&middot;, var_n in exp do block end
163 </pre>
164
165 <p>is equivalent to the code:</p>
166
167 <pre>
168 do
169 local f = exp
170 while true do
171 local var_1, &middot;&middot;&middot;, var_n = f()
172 if var_1 == nil then break end
173 block
174 end
175 end
176 </pre>
177
178
179 <h4 heading><a name="try" href="#for">Try Statement</a></h4>
180
181 <p>Unlike Lua, Luan has a <b>try</b> statement. See <a href="manual.html#try">Try Statement</a> in the Luan Reference Manual. This also eliminates the need for Lua's <b>pcall</b> function which Luan doesn't have.</p>
182
183 <h4 heading><a name="logical" href="#logical">Logical Statements</a></h4>
184
185 <p>Unlike Lua, Luan allows <b>or</b> and <b>and</b> expressions to be stand-alone statements. This is useful in cases like this:</p>
186
187 <pre>
188 x==5 or error "x should be 5"
189 </pre>
190
191 <h4 heading><a name="template_stmt" href="#template_stmt">Template Statements</a></h4>
192
193 <p>Template statements are a Luan addition that don't exist in Lua. See <a href="manual.html#template_stmt">Template Statements</a> in the Luan Reference Manual.</p>
194
195
196 <h3 heading><a name="expr" href="#expr">Expressions</a></h3>
197
198 <h4 heading><a name="conversions" href="#conversions">Coercions and Conversions</a></h4>
199
200 <p>Unlike Lua, Luan does not do automatic conversions of strings to numbers.</p>
201
202 <h4 heading><a name="bit" href="#bit">Bitwise Operators</a></h4>
203
204 <p>Bitwise operators appear to be a new addition to Lua 5.3 and didn't exist in Lua 5.2. Luan does not support bitwise operators, but these can be added if there is a need.</p>
205
206 <h4 heading><a name="logical_ops" href="#logical_ops">Logical Operators</a></h4>
207
208 <p>The only change in Luan is that <b>not</b> must take a boolean argument. This helps catch errors and makes code more readable.</p>
209
210 <h4 heading><a name="concatenation" href="#concatenation">Concatenation</a></h4>
211
212 <p>Unlike Lua, Luan converts all concatenation operands to strings.
213
214 <h4 heading><a name="constructors" href="#constructors">Table Constructors</a></h4>
215
216 <p>Unlike Lua, Luan considers an <b>end_of_line</b> to be a field separator in a table constructor.</p>
217
218 <h4 heading><a name="fn_calls" href="#fn_calls">Function Calls</a></h4>
219
220 <p>Unlike Lua, Luan does not allow extra non-nil arguments to be passed to a function. In Luan, this causes an error. This change helps find coding mistakes that would be very hard to detect otherwise.</p>
221
222 <p>Luan does not support Lua's <code>v:name(args)</code> style object-oriented function call. Object oriented programming is done in Luan using closures, so this feature is not needed.</p>
223
224 <p>Luan doesn't support <em>proper tail calls</em>. Because Java doesn't support this cleanly, this was left out.</p>
225
226 </div> 279 </div>
227 </body> 280 </body>
228 </html> 281 </html>
229 <% 282 <%
230 end 283 end