repo/luan: website/src/manual.html.luan comparison

comparison website/src/manual.html.luan @ 476:cd22e4694ea3

documentation

author	Franklin Schmidt <fschmidt@gmail.com>
date	Sun, 10 May 2015 22:41:00 -0600
parents	7ac0891718eb
children	eb6d90fb0b5c

comparison

equal deleted inserted replaced

-:7ac0891718eb
+:cd22e4694ea3
 <div margin-bottom="1em">
 	<a href="#libs">Standard Libraries</a>
 	<ul>
 		<li><a href="#default_lib">Default Environment</a></li>
 		<li><a href="#luan_lib">Basic Functions</a></li>
+		<li><a href="#package_lib">Modules</a></li>
 	</ul>
 </div>
 <hr/>
 <p>
 Could be defined as:
 <p><tt><pre>
 	local function require(mod_name)
-		return Package.load(mod_name) or <a href="#Luan.error">Luan.error</a>("module '"..mod_name.."' not found")
+		return <a href="#Package.load">Package.load</a>(mod_name) or <a href="#Luan.error">Luan.error</a>("module '"..mod_name.."' not found")
 	end
 </pre></tt></p>
 <h3 margin-top="1em"><a name="luan_lib">Basic Functions</a></h3>
 <p><tt><pre>
 	local Luan = require "luan:Luan"
 </pre></tt></p>
+<p>
 The basic library provides basic functions to Luan that don't depend on other libaries.
 <h4 margin-top="1em"><a name="Luan.assert"><tt>Luan.assert (v [, message])</tt></a></h4>
 For complete control over the output,
 use <a href="#pdf-string.format"><code>string.format</code></a> and <a href="#pdf-io.write"><code>io.write</code></a>.
+<h4 margin-top="1em"><a name="Luan.range"><tt>Luan.range (start, stop [, step])</tt></a></h4>
+<p>
+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.
+<p>
+Example use:
+<p><tt><pre>
+	for i in range(1,10) do
+		Io.print("count up:",i)
+	end
+	for i in range(10,0,-1) do
+		Io.print("count down:",i)
+	end
+</pre></tt></p>
+<p>
+Could be defined as:
+<p><tt><pre>
+	function Luan.range(start, stop, step)
+		step = step or 1
+		step == 0 and Luan.error "bad argument #3 (step may not be zero)"
+		local i = start
+		return function()
+			if step > 0 and i <= stop or step < 0 and i >= stop then
+				local rtn = i
+				i = i + step
+				return rtn
+			end
+		end
+	end
+</pre></tt></p>
 <h4 margin-top="1em"><a name="Luan.raw_equal"><tt>Luan.raw_equal (v1, v2)</tt></a></h4>
 <p>
 Checks whether <tt>v1</tt> is equal to <tt>v2</tt>,
 without invoking any metamethod.
 <tt>table</tt> must be a table,
 <tt>index</tt> any value different from <b>nil</b>,
 and <tt>value</tt> any Lua value.
 <p>
 This function returns <tt>table</tt>.
-<p>
-<hr><h3><a name="pdf-select"><code>select (index, &middot;&middot;&middot;)</code></a></h3>
-<p>
-If <code>index</code> is a number,
-returns all arguments after argument number <code>index</code>;
-a negative number indexes from the end (-1 is the last argument).
-Otherwise, <code>index</code> must be the string <code>"#"</code>,
-and <code>select</code> returns the total number of extra arguments it received.
 <h4 margin-top="1em"><a name="Luan.set_metatable"><tt>Luan.set_metatable (table, metatable)</tt></a></h4>
 <p>
 <p>
 If the metatable of <tt>v</tt> has a <tt>"__to_string"</tt> field,
 then <tt>to_string</tt> calls the corresponding value
 with <tt>v</tt> as argument,
 and uses the result of the call as its result.
+<h4 margin-top="1em"><a name="Luan.try"><tt>Luan.try (t)</tt></a></h4>
+<p>
+Implements try-catch as found in other languages where each block is in table <tt>t</tt>.
+<p>
+Example use:
+<p><tt><pre>
+try {
+	function()
+		a_dangerous_fn()
+	end;
+	catch = function(e)
+		-- handle error
+	end;
+	finally = function()
+		-- clean up
+	end;
+}
+</pre></tt></p>
 <h4 margin-top="1em"><a name="Luan.type"><tt>Luan.type (v)</tt></a></h4>
 "<tt>table</tt>",
 "<tt>function</tt>",
 and "<tt>userdata</tt>".
+<h4 margin-top="1em"><a name="Luan.values"><tt>Luan.values (&middot;&middot;&middot;)</tt></a></h4>
+<p>
+Returns a function so that the construction
+<p><tt><pre>
+	for v in Luan.values(&middot;&middot;&middot;) do <i>body</i> end
+</pre></tt></p>
+<p>
+will iterate over all values of <tt>&middot;&middot;&middot;</tt>.
 <h4 margin-top="1em"><a name="Luan.VERSION"><tt>Luan.VERSION</tt></a></h4>
 <p>
 A global variable (not a function) that
+<h3 margin-top="1em"><a name="package_lib">Modules</a></h3>
-<h2>6.3 &ndash; <a name="6.3">Modules</a></h2>
+<p>
+Include this library by:
+<p><tt><pre>
+	local Package = require "luan:Package"
+</pre></tt></p>
 <p>
 The package library provides basic
-facilities for loading modules in Lua.
+facilities for loading modules in Luan.
-It exports one function directly in the global environment:
-<a href="#pdf-require"><code>require</code></a>.
-Everything else is exported in a table <a name="pdf-package"><code>package</code></a>.
+<h4 margin-top="1em"><a name="Package.load"><tt>Package.load (mod_uri)</tt></a></h4>
-<p>
-<hr><h3><a name="pdf-require"><code>require (modname)</code></a></h3>
 <p>
 Loads the given module.
-The function starts by looking into the <a href="#pdf-package.loaded"><code>package.loaded</code></a> table
+The function starts by looking into the <a href="#Package.loaded"><tt>Package.loaded</tt></a> table
-to determine whether <code>modname</code> is already loaded.
+to determine whether <tt>mod_uri</tt> is already loaded.
-If it is, then <code>require</code> returns the value stored
+If it is, then <tt>Package.load</tt> returns the value stored
-at <code>package.loaded[modname]</code>.
+at <tt>Package.loaded[mod_uri]</tt>.
-Otherwise, it tries to find a <em>loader</em> for the module.
+Otherwise, it tries to load a new value for the module.
+<p>
-<p>
+To load a new value, <tt>Package.load</tt> first checks if <tt>mod_uri</tt> starts with "<b>java:</b>".  If yes, then this is a Java class which is loaded by special Java code.
-To find a loader,
-<code>require</code> is guided by the <a href="#pdf-package.searchers"><code>package.searchers</code></a> sequence.
+<p>
-By changing this sequence,
+If <tt>mod_uri</tt> is not a Java class, then <tt>Package.load</tt> tries to read the text of the file referred to by <tt>mod_uri</tt> (using <tt>add_extension</tt>=true).  If the file doesn't exist, then <tt>Package.load</tt> returns <b>nil</b>.  If the file exists, then its content is compiled into a chunk calling <a href="#Luan.load"><tt>Luan.load</tt></a> and passing in an empty table as the <tt>env</tt> value.  This chunk is run passing in <tt>mod_uri</tt> as an argument.  If the chunk returns a value other than <b>nil</b>, then that value is the value of this module.  Otherwise the <tt>env</tt> that was passed in is the value of this module.
-we can change how <code>require</code> looks for a module.
-The following explanation is based on the default configuration
+<p>
-for <a href="#pdf-package.searchers"><code>package.searchers</code></a>.
+If a new value for the module successful loaded, then it is stored in <tt>Package.loaded[mod_uri]</tt>.  The value is returned.
-<p>
-First <code>require</code> queries <code>package.preload[modname]</code>.
-If it has a value,
+<h4 margin-top="1em"><a name="Package.loaded"><tt>Package.loaded</tt></a></h4>
-this value (which must be a function) is the loader.
-Otherwise <code>require</code> searches for a Lua loader using the
-path stored in <a href="#pdf-package.path"><code>package.path</code></a>.
+<p>
-If that also fails, it searches for a C&nbsp;loader using the
+A table used by <a href="#Package.load"><tt>Package.load</tt></a> to control which
-path stored in <a href="#pdf-package.cpath"><code>package.cpath</code></a>.
-If that also fails,
-it tries an <em>all-in-one</em> loader (see <a href="#pdf-package.searchers"><code>package.searchers</code></a>).
-<p>
-Once a loader is found,
-<code>require</code> calls the loader with two arguments:
-<code>modname</code> and an extra value dependent on how it got the loader.
-(If the loader came from a file,
-this extra value is the file name.)
-If the loader returns any non-nil value,
-<code>require</code> assigns the returned value to <code>package.loaded[modname]</code>.
-If the loader does not return a non-nil value and
-has not assigned any value to <code>package.loaded[modname]</code>,
-then <code>require</code> assigns <b>true</b> to this entry.
-In any case, <code>require</code> returns the
-final value of <code>package.loaded[modname]</code>.
-<p>
-If there is any error loading or running the module,
-or if it cannot find any loader for the module,
-then <code>require</code> raises an error.
-<p>
-<hr><h3><a name="pdf-package.config"><code>package.config</code></a></h3>
-<p>
-A string describing some compile-time configurations for packages.
-This string is a sequence of lines:
-<ul>
-<li>The first line is the directory separator string.
-Default is '<code>\</code>' for Windows and '<code>/</code>' for all other systems.</li>
-<li>The second line is the character that separates templates in a path.
-Default is '<code>;</code>'.</li>
-<li>The third line is the string that marks the
-substitution points in a template.
-Default is '<code>?</code>'.</li>
-<li>The fourth line is a string that, in a path in Windows,
-is replaced by the executable's directory.
-Default is '<code>!</code>'.</li>
-<li>The fifth line is a mark to ignore all text after it
-when building the <code>luaopen_</code> function name.
-Default is '<code>-</code>'.</li>
-</ul>
-<p>
-<hr><h3><a name="pdf-package.cpath"><code>package.cpath</code></a></h3>
-<p>
-The path used by <a href="#pdf-require"><code>require</code></a> to search for a C&nbsp;loader.
-<p>
-Lua initializes the C&nbsp;path <a href="#pdf-package.cpath"><code>package.cpath</code></a> in the same way
-it initializes the Lua path <a href="#pdf-package.path"><code>package.path</code></a>,
-using the environment variable <a name="pdf-LUA_CPATH_5_3"><code>LUA_CPATH_5_3</code></a>
-or the environment variable <a name="pdf-LUA_CPATH"><code>LUA_CPATH</code></a>
-or a default path defined in <code>luaconf.h</code>.
-<p>
-<hr><h3><a name="pdf-package.loaded"><code>package.loaded</code></a></h3>
-<p>
-A table used by <a href="#pdf-require"><code>require</code></a> to control which
 modules are already loaded.
-When you require a module <code>modname</code> and
+When you load a module <tt>mod_uri</tt> and
-<code>package.loaded[modname]</code> is not false,
+<tt>Package.loaded[modname]</tt> is not <b>nil</b>,
-<a href="#pdf-require"><code>require</code></a> simply returns the value stored there.
+<a href="#Package.load"><tt>Package.load</tt></a> simply returns the value stored there.
 <p>
 This variable is only a reference to the real table;
 assignments to this variable do not change the
-table used by <a href="#pdf-require"><code>require</code></a>.
+table used by <a href="#Package.load"><tt>Package.load</tt></a>.
-<p>
-<hr><h3><a name="pdf-package.loadlib"><code>package.loadlib (libname, funcname)</code></a></h3>
-<p>
-Dynamically links the host program with the C&nbsp;library <code>libname</code>.
-<p>
-If <code>funcname</code> is "<code>*</code>",
-then it only links with the library,
-making the symbols exported by the library
-available to other dynamically linked libraries.
-Otherwise,
-it looks for a function <code>funcname</code> inside the library
-and returns this function as a C&nbsp;function.
-So, <code>funcname</code> must follow the <a href="#lua_CFunction"><code>lua_CFunction</code></a> prototype
-(see <a href="#lua_CFunction"><code>lua_CFunction</code></a>).
-<p>
-This is a low-level function.
-It completely bypasses the package and module system.
-Unlike <a href="#pdf-require"><code>require</code></a>,
-it does not perform any path searching and
-does not automatically adds extensions.
-<code>libname</code> must be the complete file name of the C&nbsp;library,
-including if necessary a path and an extension.
-<code>funcname</code> must be the exact name exported by the C&nbsp;library
-(which may depend on the C&nbsp;compiler and linker used).
-<p>
-This function is not supported by Standard&nbsp;C.
-As such, it is only available on some platforms
-(Windows, Linux, Mac OS X, Solaris, BSD,
-plus other Unix systems that support the <code>dlfcn</code> standard).
-<p>
-<hr><h3><a name="pdf-package.path"><code>package.path</code></a></h3>
-<p>
-The path used by <a href="#pdf-require"><code>require</code></a> to search for a Lua loader.
-<p>
-At start-up, Lua initializes this variable with
-the value of the environment variable <a name="pdf-LUA_PATH_5_3"><code>LUA_PATH_5_3</code></a> or
-the environment variable <a name="pdf-LUA_PATH"><code>LUA_PATH</code></a> or
-with a default path defined in <code>luaconf.h</code>,
-if those environment variables are not defined.
-Any "<code>;;</code>" in the value of the environment variable
-is replaced by the default path.
-<p>
-<hr><h3><a name="pdf-package.preload"><code>package.preload</code></a></h3>
-<p>
-A table to store loaders for specific modules
-(see <a href="#pdf-require"><code>require</code></a>).
-<p>
-This variable is only a reference to the real table;
-assignments to this variable do not change the
-table used by <a href="#pdf-require"><code>require</code></a>.
-<p>
-<hr><h3><a name="pdf-package.searchers"><code>package.searchers</code></a></h3>
-<p>
-A table used by <a href="#pdf-require"><code>require</code></a> to control how to load modules.
-<p>
-Each entry in this table is a <em>searcher function</em>.
-When looking for a module,
-<a href="#pdf-require"><code>require</code></a> calls each of these searchers in ascending order,
-with the module name (the argument given to <a href="#pdf-require"><code>require</code></a>) as its
-sole parameter.
-The function can return another function (the module <em>loader</em>)
-plus an extra value that will be passed to that loader,
-or a string explaining why it did not find that module
-(or <b>nil</b> if it has nothing to say).
-<p>
-Lua initializes this table with four searcher functions.
-<p>
-The first searcher simply looks for a loader in the
-<a href="#pdf-package.preload"><code>package.preload</code></a> table.
-<p>
-The second searcher looks for a loader as a Lua library,
-using the path stored at <a href="#pdf-package.path"><code>package.path</code></a>.
-The search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>.
-<p>
-The third searcher looks for a loader as a C&nbsp;library,
-using the path given by the variable <a href="#pdf-package.cpath"><code>package.cpath</code></a>.
-Again,
-the search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>.
-For instance,
-if the C&nbsp;path is the string
-<pre>
-"./?.so;./?.dll;/usr/local/?/init.so"
-</pre><p>
-the searcher for module <code>foo</code>
-will try to open the files <code>./foo.so</code>, <code>./foo.dll</code>,
-and <code>/usr/local/foo/init.so</code>, in that order.
-Once it finds a C&nbsp;library,
-this searcher first uses a dynamic link facility to link the
-application with the library.
-Then it tries to find a C&nbsp;function inside the library to
-be used as the loader.
-The name of this C&nbsp;function is the string "<code>luaopen_</code>"
-concatenated with a copy of the module name where each dot
-is replaced by an underscore.
-Moreover, if the module name has a hyphen,
-its suffix after (and including) the first hyphen is removed.
-For instance, if the module name is <code>a.b.c-v2.1</code>,
-the function name will be <code>luaopen_a_b_c</code>.
-<p>
-The fourth searcher tries an <em>all-in-one loader</em>.
-It searches the C&nbsp;path for a library for
-the root name of the given module.
-For instance, when requiring <code>a.b.c</code>,
-it will search for a C&nbsp;library for <code>a</code>.
-If found, it looks into it for an open function for
-the submodule;
-in our example, that would be <code>luaopen_a_b_c</code>.
-With this facility, a package can pack several C&nbsp;submodules
-into one single library,
-with each submodule keeping its original open function.
-<p>
-All searchers except the first one (preload) return as the extra value
-the file name where the module was found,
-as returned by <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>.
-The first searcher returns no extra value.
-<p>
-<hr><h3><a name="pdf-package.searchpath"><code>package.searchpath (name, path [, sep [, rep]])</code></a></h3>
-<p>
-Searches for the given <code>name</code> in the given <code>path</code>.
-<p>
-A path is a string containing a sequence of
-<em>templates</em> separated by semicolons.
-For each template,
-the function replaces each interrogation mark (if any)
-in the template with a copy of <code>name</code>
-wherein all occurrences of <code>sep</code>
-(a dot, by default)
-were replaced by <code>rep</code>
-(the system's directory separator, by default),
-and then tries to open the resulting file name.
-<p>
-For instance, if the path is the string
-<pre>
-"./?.lua;./?.lc;/usr/local/?/init.lua"
-</pre><p>
-the search for the name <code>foo.a</code>
-will try to open the files
-<code>./foo/a.lua</code>, <code>./foo/a.lc</code>, and
-<code>/usr/local/foo/a/init.lua</code>, in that order.
-<p>
-Returns the resulting name of the first file that it can
-open in read mode (after closing the file),
-or <b>nil</b> plus an error message if none succeeds.
-(This error message lists all file names it tried to open.)

Mercurial Hosting > luan

comparison website/src/manual.html.luan @ 476:cd22e4694ea3