Mercurial Hosting > luan
changeset 512:d96944467ffc
update documentation for luan changes
author | Franklin Schmidt <fschmidt@gmail.com> |
---|---|
date | Fri, 22 May 2015 16:08:23 -0600 |
parents | e3fb9768dbb3 |
children | 0dfc01d8d42d |
files | website/src/diff.html.luan website/src/manual.html.luan website/src/tutorial.html.luan |
diffstat | 3 files changed, 17 insertions(+), 47 deletions(-) [+] |
line wrap: on
line diff
diff -r e3fb9768dbb3 -r d96944467ffc website/src/diff.html.luan --- a/website/src/diff.html.luan Fri May 22 10:47:56 2015 -0600 +++ b/website/src/diff.html.luan Fri May 22 16:08:23 2015 -0600 @@ -44,6 +44,7 @@ <a href="#lang">The Language</a> <ul> <li><a href="#lex">Lexical Conventions</a></li> + <li><a href="#vars">Variables</a></li> <li> <a href="#stmt">Statements</a> <ul> @@ -93,7 +94,7 @@ <h3 <%=heading_options%> ><a name="env">Environments</a></h3> -<p>Luan has an <tt>_ENV</tt> which is like its Lua equivalent. However Luan has no global environment at all, no <tt>_G</tt>.</p> +<p>Luan has no global environment at all, no <tt>_G</tt>. By default, Luan doesn't define <tt>_ENV</tt> either, but if you define it as a local table in a chunk, then it acts like it does in Lua. When <tt>_ENV</tt> isn't defined, there are no global variables and an unrecognized variable name produces a compile error.</p> <p>Every module is initialized with two local functions: <tt>require</tt> and <tt>java</tt>. The module then uses these functions to get access to whatever else it needs.</p> @@ -123,6 +124,11 @@ <p>Luan has exactly the same set of keywords as Lua and has the same other lexical conventions.</p> +<h3 <%=heading_options%> ><a name="vars">Variables</a></h3> + +<p> +By default, there are no global variables and an undefined variable produces a compile error. To enable global variables, one must define <tt>_ENV</tt>. Avoiding global variables makes it much easier to catch errors at compile time. + <h3 <%=heading_options%> ><a name="stmt">Statements</a></h3> <p>Most statements in Luan are the same as Lua. Only those statements that differ will be listed here.</p>
diff -r e3fb9768dbb3 -r d96944467ffc website/src/manual.html.luan --- a/website/src/manual.html.luan Fri May 22 10:47:56 2015 -0600 +++ b/website/src/manual.html.luan Fri May 22 16:08:23 2015 -0600 @@ -232,38 +232,13 @@ <h3 <%=heading_options%> ><a name="env">Environments</a></h3> <p> +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>. + +<p> As will be discussed in <a href="#vars">Variables</a> and <a href=#assignment">Assignment</a>, any reference to a free name (that is, a name not bound to any declaration) <tt>var</tt> -is syntactically translated to <tt>_ENV.var</tt>. -Moreover, every chunk is compiled in the scope of -an external local variable named <tt>_ENV</tt> (see <a href="#chunks">Chunks</a>), -so <tt>_ENV</tt> itself is never a free name in a chunk. - - -<p> -Despite the existence of this external <tt>_ENV</tt> variable and -the translation of free names, -<tt>_ENV</tt> is a completely regular name. -In particular, -you can define new variables and parameters with that name. -Each reference to a free name uses the <tt>_ENV</tt> that is -visible at that point in the program, -following the usual visibility rules of Luan (see <a href="#visibility">Visibility Rules</a>). - - -<p> -Any table used as the value of <tt>_ENV</tt> is called an <i>environment</i>. - - -<p> -When Luan loads a chunk, -the default value for its <tt>_ENV</tt> is an empty table. - -<p> -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. - - +can be syntactically translated to <tt>_ENV.var</tt> if <tt>_ENV</tt> is defined. <h3 <%=heading_options%> ><a name="error">Error Handling</a></h3> @@ -723,7 +698,6 @@ There are three kinds of variables in Luan: global variables, local variables, and table fields. - <p> A single name can denote a global variable or a local variable (or a function's formal parameter, @@ -736,10 +710,7 @@ <p> Name denotes identifiers, as defined in <a href="#lex">Lexical Conventions</a>. - -<p> -Any variable name is assumed to be global unless explicitly declared -as a local (see <a href="#local_stmt">Local Declarations</a>). +<p> Local variables are <i>lexically scoped</i>: local variables can be freely accessed by functions defined inside their scope (see <a href="#visibility">Visibility Rules</a>). @@ -748,7 +719,6 @@ <p> Before the first assignment to a variable, its value is <b>nil</b>. - <p> Square brackets are used to index a table: @@ -775,7 +745,7 @@ </pre></tt></p> <p> -An access to a global variable <tt>x</tt> +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> is equivalent to <tt>_ENV.x</tt>. Due to the way that chunks are compiled, <tt>_ENV</tt> is never a global name (see <a href="#env">Environments</a>). @@ -943,7 +913,7 @@ An assignment to a global name <tt>x = val</tt> is equivalent to the assignment <tt>_ENV.x = val</tt> (see <a href="#env">Environments</a>). - +Global names are only available when <tt>_ENV</tt> is defined. @@ -1824,12 +1794,6 @@ These are provided by default as local variables for any Luan code as described in <a href="#env">Environments</a>. -<h4 <%=heading_options%> ><a name="_ENV"><tt>_ENV</tt></a></h4> - -<p> -This is a table that holds the global variables of a module as described in <a href="#env">Environments</a>. - - <h4 <%=heading_options%> ><a name="require"><tt>java ()</tt></a></h4> <p>
diff -r e3fb9768dbb3 -r d96944467ffc website/src/tutorial.html.luan --- a/website/src/tutorial.html.luan Fri May 22 10:47:56 2015 -0600 +++ b/website/src/tutorial.html.luan Fri May 22 16:08:23 2015 -0600 @@ -59,7 +59,7 @@ local Io = require "luan:Io" local print = Io.print - function hello(name) + local function hello(name) print("Hello "..name) end @@ -74,7 +74,7 @@ local Io = require "luan:Io" local Http = require "luan:http/Http" - function respond() + return function() Io.stdout = Http.response.text_writer() %> <html> @@ -88,7 +88,7 @@ <p>Now go back to the parent directory and do <b>luan luan:http/serve file:site</b>. This will run the Luan web server on port 8080. Try going to <a href="http://localhost:8080/">http://localhost:8080/</a>. You should see the directory. If you click on <b>hi.luan</b> you will see the source. But if you remove the <b>.luan</b> and just go to <a href="http://localhost:8080/hi">http://localhost:8080/hi</a> then you will run the program which will generate the web page.</p> -<p>The Luan webserver looks for function named <b>respond</b> in the file and calls it to generate the page. Code of the form <b><%=Html.encode[[%>...<%]]%></b> writes its output to <b>Io.stdout</b> which by default is the standard output of the command line. So in <b>respond</b> one usually starts by setting <b>Io.stdout</b> to a <tt>text_writer</tt> which writes its output to the HTTP response (to the web browser).</p> +<p>The Luan webserver expects the file to return a function and calls it to generate the page. Code of the form <b><%=Html.encode[[%>...<%]]%></b> writes its output to <b>Io.stdout</b> which by default is the standard output of the command line. So in the returned function one usually starts by setting <b>Io.stdout</b> to a <tt>text_writer</tt> which writes its output to the HTTP response (to the web browser).</p> <p>You can find this example and others in the <a href="examples">examples directory</a>. Take a look at <a href="examples/hi2.luan">hi2.luan</a> next. Remember to remove the <b>.luan</b> from the URL to run the code. And by the way, you can see the source for this page at <a href="tutorial.html.luan">tutorial.html.luan</a>.</p>