Mercurial Hosting > luan
diff 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 |
line wrap: on
line diff
--- a/website/src/manual.html.luan Sun May 10 20:44:55 2015 -0600 +++ b/website/src/manual.html.luan Sun May 10 22:41:00 2015 -0600 @@ -88,6 +88,7 @@ <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> @@ -1852,7 +1853,7 @@ <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> @@ -1866,6 +1867,7 @@ local Luan = require "luan:Luan" </pre></tt></p> +<p> The basic library provides basic functions to Luan that don't depend on other libaries. @@ -2086,6 +2088,42 @@ +<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> @@ -2125,27 +2163,10 @@ <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, ···)</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> @@ -2209,6 +2230,30 @@ +<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> <p> @@ -2224,6 +2269,19 @@ and "<tt>userdata</tt>". +<h4 margin-top="1em"><a name="Luan.values"><tt>Luan.values (···)</tt></a></h4> + +<p> +Returns a function so that the construction + +<p><tt><pre> + for v in Luan.values(···) do <i>body</i> end +</pre></tt></p> + +<p> +will iterate over all values of <tt>···</tt>. + + <h4 margin-top="1em"><a name="Luan.VERSION"><tt>Luan.VERSION</tt></a></h4> @@ -2237,347 +2295,57 @@ - -<h2>6.3 – <a name="6.3">Modules</a></h2> +<h3 margin-top="1em"><a name="package_lib">Modules</a></h3> + +<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. -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>. - - -<p> -<hr><h3><a name="pdf-require"><code>require (modname)</code></a></h3> - +facilities for loading modules in Luan. + + +<h4 margin-top="1em"><a name="Package.load"><tt>Package.load (mod_uri)</tt></a></h4> <p> Loads the given module. -The function starts by looking into the <a href="#pdf-package.loaded"><code>package.loaded</code></a> table -to determine whether <code>modname</code> is already loaded. -If it is, then <code>require</code> returns the value stored -at <code>package.loaded[modname]</code>. -Otherwise, it tries to find a <em>loader</em> for the module. - - -<p> -To find a loader, -<code>require</code> is guided by the <a href="#pdf-package.searchers"><code>package.searchers</code></a> sequence. -By changing this sequence, -we can change how <code>require</code> looks for a module. -The following explanation is based on the default configuration -for <a href="#pdf-package.searchers"><code>package.searchers</code></a>. - - -<p> -First <code>require</code> queries <code>package.preload[modname]</code>. -If it has a value, -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>. -If that also fails, it searches for a C loader using the -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 loader. - - -<p> -Lua initializes the C 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 +The function starts by looking into the <a href="#Package.loaded"><tt>Package.loaded</tt></a> table +to determine whether <tt>mod_uri</tt> is already loaded. +If it is, then <tt>Package.load</tt> returns the value stored +at <tt>Package.loaded[mod_uri]</tt>. +Otherwise, it tries to load a new value for the module. + +<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. + +<p> +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. + +<p> +If a new value for the module successful loaded, then it is stored in <tt>Package.loaded[mod_uri]</tt>. The value is returned. + + + + +<h4 margin-top="1em"><a name="Package.loaded"><tt>Package.loaded</tt></a></h4> + + +<p> +A table used by <a href="#Package.load"><tt>Package.load</tt></a> to control which modules are already loaded. -When you require a module <code>modname</code> and -<code>package.loaded[modname]</code> is not false, -<a href="#pdf-require"><code>require</code></a> simply returns the value stored there. +When you load a module <tt>mod_uri</tt> and +<tt>Package.loaded[modname]</tt> is not <b>nil</b>, +<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>. - - - - -<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 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 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 library, -including if necessary a path and an extension. -<code>funcname</code> must be the exact name exported by the C library -(which may depend on the C compiler and linker used). - - -<p> -This function is not supported by Standard 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 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 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 library, -this searcher first uses a dynamic link facility to link the -application with the library. -Then it tries to find a C function inside the library to -be used as the loader. -The name of this C 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 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 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 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.) - +table used by <a href="#Package.load"><tt>Package.load</tt></a>.