changeset 470:5627eb637eb4

documentation
author Franklin Schmidt <fschmidt@gmail.com>
date Sat, 09 May 2015 23:54:22 -0600
parents 85467f95ab13
children f3a24435d04d
files website/src/manual.html.luan
diffstat 1 files changed, 125 insertions(+), 142 deletions(-) [+]
line wrap: on
line diff
--- a/website/src/manual.html.luan	Sat May 09 21:10:08 2015 -0600
+++ b/website/src/manual.html.luan	Sat May 09 23:54:22 2015 -0600
@@ -87,6 +87,7 @@
 	<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>
 	</ul>
 </div>
 
@@ -1824,156 +1825,138 @@
 <p>
 These are provided by default as local variables for any Luan code as described in <a href="#env">Environments</a>.
 
+
 <h4 margin-top="1em"><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>.
 
 
-
-<h2>6.1 &ndash; <a name="6.1">Basic Functions</a></h2>
-
-<p>
-The basic library provides core functions to Lua.
-If you do not include this library in your application,
-you should check carefully whether you need to provide
-implementations for some of its facilities.
-
-
-<p>
-<hr><h3><a name="pdf-assert"><code>assert (v [, message])</code></a></h3>
-
-
-<p>
-Calls <a href="#pdf-error"><code>error</code></a> if
-the value of its argument <code>v</code> is false (i.e., <b>nil</b> or <b>false</b>);
-otherwise, returns all its arguments.
-In case of error,
-<code>message</code> is the error object;
-when absent, it defaults to "<code>assertion failed!</code>"
-
-
-
-
-<p>
-<hr><h3><a name="pdf-collectgarbage"><code>collectgarbage ([opt [, arg]])</code></a></h3>
-
-
-<p>
-This function is a generic interface to the garbage collector.
-It performs different functions according to its first argument, <code>opt</code>:
-
-<ul>
-
-<li><b>"<code>collect</code>": </b>
-performs a full garbage-collection cycle.
-This is the default option.
-</li>
-
-<li><b>"<code>stop</code>": </b>
-stops automatic execution of the garbage collector.
-The collector will run only when explicitly invoked,
-until a call to restart it.
-</li>
-
-<li><b>"<code>restart</code>": </b>
-restarts automatic execution of the garbage collector.
-</li>
-
-<li><b>"<code>count</code>": </b>
-returns the total memory in use by Lua in Kbytes.
-The value has a fractional part,
-so that it multiplied by 1024
-gives the exact number of bytes in use by Lua
-(except for overflows).
-</li>
-
-<li><b>"<code>step</code>": </b>
-performs a garbage-collection step.
-The step "size" is controlled by <code>arg</code>.
-With a zero value,
-the collector will perform one basic (indivisible) step.
-For non-zero values,
-the collector will perform as if that amount of memory
-(in KBytes) had been allocated by Lua.
-Returns <b>true</b> if the step finished a collection cycle.
-</li>
-
-<li><b>"<code>setpause</code>": </b>
-sets <code>arg</code> as the new value for the <em>pause</em> of
-the collector (see <a href="#2.5">&sect;2.5</a>).
-Returns the previous value for <em>pause</em>.
-</li>
-
-<li><b>"<code>setstepmul</code>": </b>
-sets <code>arg</code> as the new value for the <em>step multiplier</em> of
-the collector (see <a href="#2.5">&sect;2.5</a>).
-Returns the previous value for <em>step</em>.
-</li>
-
-<li><b>"<code>isrunning</code>": </b>
-returns a boolean that tells whether the collector is running
-(i.e., not stopped).
-</li>
-
-</ul>
-
-
-
-<p>
-<hr><h3><a name="pdf-dofile"><code>dofile ([filename])</code></a></h3>
-Opens the named file and executes its contents as a Lua chunk.
-When called without arguments,
-<code>dofile</code> executes the contents of the standard input (<code>stdin</code>).
-Returns all values returned by the chunk.
-In case of errors, <code>dofile</code> propagates the error
-to its caller (that is, <code>dofile</code> does not run in protected mode).
-
-
-
-
-<p>
-<hr><h3><a name="pdf-error"><code>error (message [, level])</code></a></h3>
-Terminates the last protected function called
-and returns <code>message</code> as the error object.
-Function <code>error</code> never returns.
-
-
-<p>
-Usually, <code>error</code> adds some information about the error position
-at the beginning of the message, if the message is a string.
-The <code>level</code> argument specifies how to get the error position.
-With level&nbsp;1 (the default), the error position is where the
-<code>error</code> function was called.
-Level&nbsp;2 points the error to where the function
-that called <code>error</code> was called; and so on.
-Passing a level&nbsp;0 avoids the addition of error position information
-to the message.
-
-
-
-
-<p>
-<hr><h3><a name="pdf-_G"><code>_G</code></a></h3>
-A global variable (not a function) that
-holds the global environment (see <a href="#2.2">&sect;2.2</a>).
-Lua itself does not use this variable;
-changing its value does not affect any environment,
-nor vice versa.
-
-
-
-
-<p>
-<hr><h3><a name="pdf-getmetatable"><code>getmetatable (object)</code></a></h3>
-
-
-<p>
-If <code>object</code> does not have a metatable, returns <b>nil</b>.
+<h4 margin-top="1em"><a name="require"><tt>java ()</tt></a></h4>
+
+<p>
+This function enables Java in the current chunk if that chunk has permission to use Java.  If the chunk doesn't have permission to use Java, then an error is thrown.
+
+
+<h4 margin-top="1em"><a name="require"><tt>require (mod_uri)</tt></a></h4>
+
+<p>
+Example use:
+
+<p><tt><pre>
+	local Table = require "luan:Table"
+</pre></tt></p>
+
+<p>
+Could be defined as:
+
+<p><tt><pre>
+	local function require(mod_name)
+		return Package.load(mod_name) or Luan.error("module '"..mod_name.."' not found")
+	end
+</pre></tt></p>
+
+
+<h3 margin-top="1em"><a name="luan_lib">Basic Functions</a></h3>
+
+<p>
+Include this library by:
+
+<p><tt><pre>
+	local Luan = require "luan:Luan"
+</pre></tt></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>
+
+<p>
+Could be defined as:
+
+<p><tt><pre>
+	function Luan.assert(v,message)
+		return v or Luan.error(message or "assertion failed!")
+	end
+</pre></tt></p>
+
+
+<h4 margin-top="1em"><a name="Luan.assert_binary"><tt>Luan.assert_binary (v)</tt></a></h4>
+
+<p>
+Could be defined as:
+
+<p><tt><pre>
+	function Luan.assert_binary(v)
+		local v_type = Luan.type(v)
+		return v_type == "binary" and v or Luan.error("bad argument #1 (binary expected, got "..v_type..")")
+	end
+</pre></tt></p>
+
+
+<h4 margin-top="1em"><a name="Luan.assert_boolean"><tt>Luan.assert_boolean (v)</tt></a></h4>
+
+<p>
+Like <a href="#Luan.assert_binary"><tt>assert_binary</tt></a> but for type <tt>boolean</tt>.
+
+
+<h4 margin-top="1em"><a name="Luan.assert_integer"><tt>Luan.assert_integer (v)</tt></a></h4>
+
+<p>
+Asserts that <tt>v</tt> can be converted to Java type <a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Integer.html">Integer</a> and returns an Integer.
+
+
+<h4 margin-top="1em"><a name="Luan.assert_long"><tt>Luan.assert_long (v)</tt></a></h4>
+
+<p>
+Asserts that <tt>v</tt> can be converted to Java type <a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Long.html">Long</a> and returns a Long.
+
+
+<h4 margin-top="1em"><a name="Luan.assert_number"><tt>Luan.assert_number (v)</tt></a></h4>
+
+<p>
+Like <a href="#Luan.assert_binary"><tt>assert_binary</tt></a> but for type <tt>number</tt>.
+
+
+<h4 margin-top="1em"><a name="Luan.assert_string"><tt>Luan.assert_string (v)</tt></a></h4>
+
+<p>
+Like <a href="#Luan.assert_binary"><tt>assert_binary</tt></a> but for type <tt>string</tt>.
+
+
+<h4 margin-top="1em"><a name="Luan.assert_table"><tt>Luan.assert_table (v)</tt></a></h4>
+
+<p>
+Like <a href="#Luan.assert_binary"><tt>assert_binary</tt></a> but for type <tt>table</tt>.
+
+
+<h4 margin-top="1em"><a name="Luan.do_file"><tt>Luan.do_file ([uri])</tt></a></h4>
+
+<p>
+Could be defined as:
+
+<p><tt><pre>
+	function Luan.do_file(uri)
+		return load_file(uri)()
+	end
+</pre></tt></p>
+
+
+
+<h4 margin-top="1em"><a name="Luan.error"><tt>Luan.error (message)</tt></a></h4>
+
+<p>
+Throws an error containing the message.  This uses Java exceptions internally and the implementation is likely to change.  So this documentation is likely to change.
+
+
+<h4 margin-top="1em"><a name="Luan.get_metatable"><tt>Luan.get_metatable (table)</tt></a></h4>
+
+<p>
+If <tt>table</tt> does not have a metatable, returns <b>nil</b>.
 Otherwise,
-if the object's metatable has a <code>"__metatable"</code> field,
+if the table's metatable has a <tt>"__metatable"</tt> field,
 returns the associated value.
-Otherwise, returns the metatable of the given object.
+Otherwise, returns the metatable of the given table.