changeset 482:7e9fcfbf22ec

documentation
author Franklin Schmidt <fschmidt@gmail.com>
date Mon, 11 May 2015 21:05:10 -0600
parents 5d4a78c93383
children 0db144c98564
files core/src/luan/modules/Luan.luan website/src/manual.html.luan
diffstat 2 files changed, 45 insertions(+), 8 deletions(-) [+]
line wrap: on
line diff
diff -r 5d4a78c93383 -r 7e9fcfbf22ec core/src/luan/modules/Luan.luan
--- a/core/src/luan/modules/Luan.luan	Mon May 11 20:26:36 2015 -0600
+++ b/core/src/luan/modules/Luan.luan	Mon May 11 21:05:10 2015 -0600
@@ -32,6 +32,8 @@
 
 VERSION = do_file "classpath:luan/version.luan"
 
+local new_error = new_error
+
 function error(message)
 	new_error(message).throw()
 end
diff -r 5d4a78c93383 -r 7e9fcfbf22ec website/src/manual.html.luan
--- a/website/src/manual.html.luan	Mon May 11 20:26:36 2015 -0600
+++ b/website/src/manual.html.luan	Mon May 11 21:05:10 2015 -0600
@@ -278,14 +278,9 @@
 
 <p>
 Whenever there is an error,
-an <i>error object</i> (also called an <i>error message</i>)
+an <i>error table</i>
 is propagated with information about the error.
-Luan itself only generates errors whose error object is a string,
-but programs may generate errors with
-any value as the error object.
-It is up to the Luan program or its host to handle such error objects.
-
-
+See <a href="#Luan.new_error"><tt>Luan.new_error</tt></a>.
 
 
 
@@ -1950,7 +1945,17 @@
 <h4 <%=heading_options%> ><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.
+Throws an error containing the message.
+
+<p>
+Could be defined as:
+
+<p><tt><pre>
+	function Luan.error(message)
+		<a href="#Luan.new_error">Luan.new_error</a>(message).throw()
+	end
+</pre></tt></p>
+
 
 
 <h4 <%=heading_options%> ><a name="Luan.get_metatable"><tt>Luan.get_metatable (table)</tt></a></h4>
@@ -2037,6 +2042,18 @@
 </pre></tt></p>
 
 
+<h4 <%=heading_options%> ><a name="Luan.new_error"><tt>Luan.new_error (message)</tt></a></h4>
+
+<p>
+Creates a new error table containing the message assigned to "<tt>message</tt>".  The error table also contains a <tt>throw</tt> function which throws the error.  The table also contains a list of stack trace elements where each stack trace element is a table containing "<tt>source</tt>", "<tt>line</tt>", and possible "<tt>call_to</tt>".  The table also has a metatable containing "<tt>__to_string</tt>" to render the error.
+
+<p>
+To print the current stack trace, you could do:
+
+<p><tt><pre>
+	Io.print( Luan.new_error "stack" )
+</pre></tt></p>
+
 
 <h4 <%=heading_options%> ><a name="Luan.pairs"><tt>Luan.pairs (t)</tt></a></h4>
 
@@ -2254,6 +2271,24 @@
 }
 </pre></tt></p>
 
+<p>
+Could be defined as:
+
+<p><tt><pre>
+	function Luan.try(t)
+		local r = { <a href="#Luan.pcall">Luan.pcall</a>(t[1]) }
+		if r[1] then
+			Table.remove(r,1)
+		elseif t.catch ~= nil then
+			r = { t.catch(r[2]) }
+		else
+			t.finally and t.finally()
+			r[2].throw()
+		end
+		t.finally and t.finally()
+		return Table.unpack(r)
+	end
+</pre></tt></p>
 
 
 <h4 <%=heading_options%> ><a name="Luan.type"><tt>Luan.type (v)</tt></a></h4>