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
--- 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>
--- 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>
--- 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>