changeset 382:8557581740db

added tutorial
author Franklin Schmidt <fschmidt@gmail.com>
date Wed, 22 Apr 2015 20:38:48 -0600
parents 83efd1e3685c
children 4118eb51c816
files website/src/docs.html website/src/examples/hi.luan website/src/examples/hi2.luan website/src/examples/shell.luan website/src/manual.html website/src/tutorial.html.luan
diffstat 6 files changed, 184 insertions(+), 27 deletions(-) [+]
line wrap: on
line diff
diff -r 83efd1e3685c -r 8557581740db website/src/docs.html
--- a/website/src/docs.html	Wed Apr 22 13:17:35 2015 -0600
+++ b/website/src/docs.html	Wed Apr 22 20:38:48 2015 -0600
@@ -20,7 +20,8 @@
 
 			<big>
 				<p>
-					<a href="pil.html">Programming in Lua</a><br>
+					<a href="tutorial.html">Tutorial</a><br>
+					<a href="pil.html">Programming in Lua (book)</a><br>
 					<a href="manual.html">Reference Manual</a><br>
 					<a href="diff.html">How Luan differs from Lua</a><br>
 				</p>
diff -r 83efd1e3685c -r 8557581740db website/src/examples/hi.luan
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/website/src/examples/hi.luan	Wed Apr 22 20:38:48 2015 -0600
@@ -0,0 +1,13 @@
+local Io = require "luan:Io"
+local Http = require "luan:web/Http"
+
+function service()
+	Io.stdout = Http.response.text_writer()
+	%>
+	<html>
+		<body>
+			Hello World
+		</body>
+	</html>
+	<%
+end
diff -r 83efd1e3685c -r 8557581740db website/src/examples/hi2.luan
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/website/src/examples/hi2.luan	Wed Apr 22 20:38:48 2015 -0600
@@ -0,0 +1,38 @@
+local Io = require "luan:Io"
+local Http = require "luan:web/Http"
+
+local function form()
+%>
+<html>
+	<body>
+		<h1>Hello</h1>
+		<form>
+		What is you name?
+		<input name="name">
+		<input type=submit>
+		</form>
+	</body>
+</html>
+<%
+end
+
+local function hello()
+%>
+<html>
+	<body>
+		<h1>Hello</h1>
+		<p>Hi <%= name %>!</p>
+	</body>
+</html>
+<%
+end
+
+function service()
+	Io.stdout = Http.response.text_writer()
+	name = Http.request.parameters.name
+	if name == nil then
+		form()
+	else
+		hello()
+	end
+end
diff -r 83efd1e3685c -r 8557581740db website/src/examples/shell.luan
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/website/src/examples/shell.luan	Wed Apr 22 20:38:48 2015 -0600
@@ -0,0 +1,1 @@
+return require "luan:web/shell"
diff -r 83efd1e3685c -r 8557581740db website/src/manual.html
--- a/website/src/manual.html	Wed Apr 22 13:17:35 2015 -0600
+++ b/website/src/manual.html	Wed Apr 22 20:38:48 2015 -0600
@@ -299,10 +299,9 @@
 You can emulate how Luan queries a metamethod for an object <tt>obj</tt>
 with the following code:
 
-<tt><pre>
+<p><tt><pre>
      raw_get(get_metatable(obj) or {}, "__" .. event_name)
-
-</pre></tt>
+</pre></tt></p>
 
 <p>
 Here are the events:
@@ -529,12 +528,12 @@
 and cannot be used as names:
 
 
-<pre>
+<p><pre>
      and       break     do        else      elseif    end
      false     for       function  goto      if        in
      local     nil       not       or        repeat    return
      then      true      until     while
-</pre>
+</pre></p>
 
 <p>
 Luan is a case-sensitive language:
@@ -545,14 +544,13 @@
 <p>
 The following strings denote other tokens:
 
-<pre>
+<p><pre>
      +     -     *     /     %     ^     #
      &amp;     ~     |     &lt;&lt;    &gt;&gt;    //
      ==    ~=    &lt;=    &gt;=    &lt;     &gt;     =
      (     )     {     }     [     ]     ::
      ;     :     ,     .     ..    ...
-
-</pre>
+</pre></p>
 
 <p>
 <i>Literal strings</i>
@@ -631,7 +629,7 @@
 As an example
 the five literal strings below denote the same string:
 
-<pre>
+<p><pre>
      a = 'alo\n123"'
      a = "alo\n123\""
      a = '\97lo\10\04923"'
@@ -640,8 +638,7 @@
      a = [==[
      alo
      123"]==]
-
-</pre>
+</pre></p>
 
 <p>
 A <i>numerical constant</i> (or <i>numeral</i>)
@@ -658,17 +655,17 @@
 otherwise it denotes an integer.
 Examples of valid integer constants are
 
-<pre>
+<p><pre>
      3   345   0xff   0xBEBADA
-
-</pre><p>
+</pre></p>
+
+<p>
 Examples of valid float constants are
 
-<pre>
+<p><pre>
      3.0     3.1416     314.16e-2     0.31416E1     34e1
      0x0.1E  0xA23p-4   0X1.921FB54442D18P+1
-
-</pre>
+</pre></p>
 
 <p>
 A <i>comment</i> starts with a double hyphen (<tt>--</tt>)
@@ -697,10 +694,11 @@
 (or a function's formal parameter,
 which is a particular kind of local variable):
 
-<pre>
+<p><pre>
 	var ::= Name
-
-</pre><p>
+</pre></p>
+
+<p>
 Name denotes identifiers, as defined in <a href="#3.1">&sect;3.1</a>.
 
 
@@ -719,10 +717,11 @@
 <p>
 Square brackets are used to index a table:
 
-<pre>
+<p><pre>
 	var ::= prefixexp &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo;
-
-</pre><p>
+</pre></p>
+
+<p>
 The meaning of accesses to table fields can be changed via metatables.
 An access to an indexed variable <tt>t[i]</tt> is equivalent to
 a call <tt>gettable_event(t,i)</tt>.
@@ -736,10 +735,9 @@
 The syntax <tt>var.Name</tt> is just syntactic sugar for
 <tt>var["Name"]</tt>:
 
-<pre>
+<p><pre>
 	var ::= prefixexp &lsquo;<b>.</b>&rsquo; Name
-
-</pre>
+</pre></p>
 
 <p>
 An access to a global variable <tt>x</tt>
diff -r 83efd1e3685c -r 8557581740db website/src/tutorial.html.luan
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/website/src/tutorial.html.luan	Wed Apr 22 20:38:48 2015 -0600
@@ -0,0 +1,106 @@
+local Io = require "luan:Io"
+local Html = require "luan:Html"
+local Http = require "luan:web/Http"
+
+function service()
+	Io.stdout = Http.response.text_writer()
+	Io.stdout = Http.response.text_writer()
+	Html.simply_html_page{
+		head = function() %>
+			<title>Luan Tutorial</title>
+<%		end;
+		body = function() %>
+
+<div container>
+<div><small><a href="/">Luan</a></small></div>
+<h1 margin-bottom="1em">Luan Tutorial</h1>
+
+
+<p>Create a file <b>hello.luan</b> containing:</p>
+
+<p><tt><pre><%=Html.encode[[
+	%>
+	Hello World
+	<%
+]]%></pre></tt></p>
+
+<p>To run this, type <b>luan file:hello</b> on the command line.  This should print <b>Hello World</b>.</p>
+
+<p>The syntax here is based on <a href="http://en.wikipedia.org/wiki/JavaServer_Pages">JSP</a>.  Let's change it a little:</p>
+
+<p><tt><pre><%=Html.encode[[
+	name = "Bob"
+	%>
+	Hello <%= name %>
+	<%
+]]%></pre></tt></p>
+
+<p>This should print <b>Hello Bob</b>.  Now let's try a more conventional approach:</p>
+
+<p><tt><pre>
+	local Io = require "luan:Io"
+	local print = Io.print
+
+	print("Hello World")
+</pre></tt></p>
+
+<p>In Luan, a function call with one string argument doesn't require parenthesis, so <b>print("Hello World")</b> is the same as <b>print "Hello World"</b> and <b>require "luan:Io"</b> is the same as <b>require("luan:Io")</b>.  Both <b>require</b> and <b>print</b> are functions.</p>
+
+<p>The <b>require</b> function takes a <a href="http://en.wikipedia.org/wiki/Uniform_resource_identifier">URI</a> as an argument.  Examples of URIs are "<b>luan:Io</b>" and "<b>file:hello</b>".  <b>require</b> is used to import a module, which is returned from the <b>require</b> function call.  In the case above, we assign the module to the local variable <b>Io</b>.  The function <b>print</b> is a member of this module.  We could have done <b>Io.print("Hello World")</b> but instead we chose to assign <b>print</b> to a local variable and use that to call the function.</p>
+
+<p>Luan starts with only two defined functions: <b>require</b> and <b>java</b>.  You will use <b>require</b> to import whatever you need.  This is a little more work, but makes it clear in each file where each function comes from.</p>
+
+<p>Let's a make fancier version:</p>
+
+<p><tt><pre>
+	local Io = require "luan:Io"
+	local print = Io.print
+
+	function hell(name)
+		print("Hello "..name)
+	end
+
+	hello("Bob")
+</pre></tt></p>
+
+<p>The <b>..</b> operator does concatenation.  This will print <b>Hello Bob</b>.</p>
+
+<p>Now let's make a web page.  First we need a directory for our website.  So create a directory <b>site</b>.  In this directory, create a file <b>hi.luan</b> containing:
+
+<p><tt><pre><%=Html.encode[[
+	local Io = require "luan:Io"
+	local Http = require "luan:web/Http"
+	
+	function service()
+		Io.stdout = Http.response.text_writer()
+		%>
+		<html>
+			<body>
+				Hello World
+			</body>
+		</html>
+		<%
+	end
+]]%></pre></tt></p>
+
+<p>Now go back to the parent directory and do <b>luan luan:web/serve file:site</b>.  This will run the Luan web server on port 8080.  Try going to <a href="http://localhost:8080/">http://localhost:8080/</a>.  You should see the directory.  If you click on <b>hi.luan</b> you will see the source.  But if you remove the <b>.luan</b> and just go to <a href="http://localhost:8080/hi">http://localhost:8080/hi</a> then you will run the program which will generate the web page.</p>
+
+<p>The Luan webserver looks for function named <b>service</b> in the file and calls it to generate the page.  Code of the form <b><%=Html.encode[[%>...<%]]%></b> writes its output to <b>Io.stdout</b> which by default is the standard output of the command line.  So in <b>service</b> one usually starts by setting <b>Io.stdout</b> to a <tt>text_writer</tt> which writes its output to the HTTP response (to the web browser).</p>
+
+<p>You can find this example and others in the <a href="examples">examples directory</a>.  Take a look at <a href="examples/hi2.luan">hi2.luan</a> next.  Remember to remove the <b>.luan</b> from the URL to run the code.  And by the way, you can see the source for this page at <a href="tutorial.html.luan">tutorial.html.luan</a>.</p>
+
+<p>So now you have built your website and you want publish it to the web.  If you have your own domain, create a CNAME record for it pointing to <b>s1.luanhost.com</b>.  If you don't have a domain, just use a domain like <b>bob.s1.luanhost.com</b> (anything of the form <b>*.s1.luanhost.com</b>).  Assuming your directory is <b>site</b> and you will use the password <b>secret</b>, do the following from the command line:
+
+<p><tt><pre>
+	luan luan:host/push bob.s1.luanhost.com secret site
+</pre></tt></p>
+
+<p>The form is <b>luan luan:host/push domain password directory</b>.  If you change your site, just run this again and your site will be updated.  To delete your site, do <b>luan luan:host/delete domain password</b>.</p>
+
+<p>Hopefully this short tutorial gave you an idea of how to use Luan to make a website.</p>
+
+</div>
+		
+<%		end;
+	}
+end