changeset 474:00646edc9d92

documentation
author Franklin Schmidt <fschmidt@gmail.com>
date Sun, 10 May 2015 16:09:45 -0600
parents bab5607a0eed
children 7ac0891718eb
files website/src/manual.html.luan
diffstat 1 files changed, 61 insertions(+), 120 deletions(-) [+]
line wrap: on
line diff
--- a/website/src/manual.html.luan	Sun May 10 00:25:48 2015 -0600
+++ b/website/src/manual.html.luan	Sun May 10 16:09:45 2015 -0600
@@ -1937,7 +1937,7 @@
 
 <p><tt><pre>
 	function Luan.do_file(uri)
-		return Luan.load_file(uri)()
+		return <a href="#Luan.load_file">Luan.load_file</a>(uri)()
 	end
 </pre></tt></p>
 
@@ -1959,137 +1959,78 @@
 Otherwise, returns the metatable of the given table.
 
 
-
-
-<p>
-<hr><h3><a name="pdf-ipairs"><code>ipairs (t)</code></a></h3>
-
-
-<p>
-Returns three values (an iterator function, the table <code>t</code>, and 0)
+<h4 margin-top="1em"><a name="Luan.ipairs"><tt>Luan.ipairs (t)</tt></a></h4>
+
+<p>
+Returns an iterator function
 so that the construction
 
-<pre>
-     for i,v in ipairs(t) do <em>body</em> end
-</pre><p>
+<p><tt><pre>
+	for i,v in ipairs(t) do <i>body</i> end
+</pre></tt></p>
+
+<p>
 will iterate over the key&ndash;value pairs
-(<code>1,t[1]</code>), (<code>2,t[2]</code>), ...,
+(<tt>1,t[1]</tt>), (<tt>2,t[2]</tt>), ...,
 up to the first nil value.
 
-
-
-
-<p>
-<hr><h3><a name="pdf-load"><code>load (chunk [, chunkname [, mode [, env]]])</code></a></h3>
-
+<p>
+Could be defined as:
+
+<p><tt><pre>
+	function Luan.ipairs(t)
+		local i = 0
+		return function()
+			if i < #t then
+				i = i + 1
+				return i, t[i]
+			end
+		end
+	end
+</pre></tt></p>
+
+
+
+<h4 margin-top="1em"><a name="Luan.load"><tt>Luan.load (text, source_name [env, [, allow_expression]])</tt></a></h4>
 
 <p>
 Loads a chunk.
 
-
-<p>
-If <code>chunk</code> is a string, the chunk is this string.
-If <code>chunk</code> is a function,
-<code>load</code> calls it repeatedly to get the chunk pieces.
-Each call to <code>chunk</code> must return a string that concatenates
-with previous results.
-A return of an empty string, <b>nil</b>, or no value signals the end of the chunk.
-
-
-<p>
+<p>
+The <tt>text</tt> is compiled.
 If there are no syntactic errors,
 returns the compiled chunk as a function;
-otherwise, returns <b>nil</b> plus the error message.
-
-
-<p>
-If the resulting function has upvalues,
-the first upvalue is set to the value of <code>env</code>,
-if that parameter is given,
-or to the value of the global environment.
-Other upvalues are initialized with <b>nil</b>.
-(When you load a main chunk,
-the resulting function will always have exactly one upvalue,
-the <code>_ENV</code> variable (see <a href="#2.2">&sect;2.2</a>).
-However,
-when you load a binary chunk created from a function (see <a href="#pdf-string.dump"><code>string.dump</code></a>),
-the resulting function can have an arbitrary number of upvalues.)
-All upvalues are fresh, that is,
-they are not shared with any other function.
-
-
-<p>
-<code>chunkname</code> is used as the name of the chunk for error messages
-and debug information (see <a href="#4.9">&sect;4.9</a>).
-When absent,
-it defaults to <code>chunk</code>, if <code>chunk</code> is a string,
-or to "<code>=(load)</code>" otherwise.
-
-
-<p>
-The string <code>mode</code> controls whether the chunk can be text or binary
-(that is, a precompiled chunk).
-It may be the string "<code>b</code>" (only binary chunks),
-"<code>t</code>" (only text chunks),
-or "<code>bt</code>" (both binary and text).
-The default is "<code>bt</code>".
-
-
-<p>
-Lua does not check the consistency of binary chunks.
-Maliciously crafted binary chunks can crash
-the interpreter.
-
-
-
-
-<p>
-<hr><h3><a name="pdf-loadfile"><code>loadfile ([filename [, mode [, env]]])</code></a></h3>
-
-
-<p>
-Similar to <a href="#pdf-load"><code>load</code></a>,
-but gets the chunk from file <code>filename</code>
+otherwise, throws an error.
+
+<p>
+The <tt>source_name</tt> parameter is a string saying where the text came from.  It is used to produce error messages.
+
+<p>
+If the <tt>env</tt> parameter is supplied, it becomes the <tt>_ENV</tt> of the chunk.
+
+<p>
+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.
+
+
+<h4 margin-top="1em"><a name="Luan.load_file"><tt>Luan.load_file (file_uri [, add_extension])</tt></a></h4>
+
+<p>
+Similar to <a href="#Luan.load"><tt>load</tt></a>,
+but gets the chunk from file <tt>file_uri</tt>
 or from the standard input,
-if no file name is given.
-
-
-
-
-<p>
-<hr><h3><a name="pdf-next"><code>next (table [, index])</code></a></h3>
-
-
-<p>
-Allows a program to traverse all fields of a table.
-Its first argument is a table and its second argument
-is an index in this table.
-<code>next</code> returns the next index of the table
-and its associated value.
-When called with <b>nil</b> as its second argument,
-<code>next</code> returns an initial index
-and its associated value.
-When called with the last index,
-or with <b>nil</b> in an empty table,
-<code>next</code> returns <b>nil</b>.
-If the second argument is absent, then it is interpreted as <b>nil</b>.
-In particular,
-you can use <code>next(t)</code> to check whether a table is empty.
-
-
-<p>
-The order in which the indices are enumerated is not specified,
-<em>even for numeric indices</em>.
-(To traverse a table in numeric order,
-use a numerical <b>for</b>.)
-
-
-<p>
-The behavior of <code>next</code> is undefined if,
-during the traversal,
-you assign any value to a non-existent field in the table.
-You may however modify existing fields.
-In particular, you may clear existing fields.
+if no file uri is given.
+
+<p>
+Could be defined as:
+
+<p><tt><pre>
+	function Luan.load_file(file_uri,add_extension)
+		file_uri = file_uri or "stdin:"
+		local f = Io.uri(file_uri,add_extension)
+		f.exists() or <a href="#Luan.error">Luan.error</a>("file '"..file_uri.."' not found")
+		return <a href="#Luan.load">Luan.load</a>( f.read_text(), file_uri )
+	end
+</pre></tt></p>