Mercurial Hosting > luan

annotate website/src/tutorial.html.luan @ 1830:d72a52232f79

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mail - minor
author Franklin Schmidt <fschmidt@gmail.com>
date Tue, 24 Sep 2024 17:17:57 -0600
parents 50e570b598b2
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1651
5b8f056527a3 docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1647
diff changeset
1 local Luan = require "luan:Luan.luan"
5b8f056527a3 docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1647
diff changeset
2 local error = Luan.error
5b8f056527a3 docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1647
diff changeset
3 local Io = require "luan:Io.luan"
5b8f056527a3 docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1647
diff changeset
4 local Http = require "luan:http/Http.luan"
5b8f056527a3 docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1647
diff changeset
5 local Shared = require "site:/lib/Shared.luan"
5b8f056527a3 docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1647
diff changeset
6 local head = Shared.head or error()
1735
4b56eff90040 add hosting.html
Franklin Schmidt <fschmidt@gmail.com>
parents: 1659
diff changeset
7 local header = Shared.docs_header or error()
1651
5b8f056527a3 docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1647
diff changeset
8
5b8f056527a3 docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1647
diff changeset
9
5b8f056527a3 docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1647
diff changeset
10 return function()
5b8f056527a3 docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1647
diff changeset
11 Io.stdout = Http.response.text_writer()
5b8f056527a3 docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1647
diff changeset
12 %>
1216
5dbb552075ff doctype
Franklin Schmidt <fschmidt@gmail.com>
parents: 1045
diff changeset
13 <!doctype html>
391
2f5cc9c2cbf0 replace Html.simply_html_page with simply_html_head and simply_html_body_bottom
Franklin Schmidt <fschmidt@gmail.com>
parents: 387
diff changeset
14 <html>
1651
5b8f056527a3 docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1647
diff changeset
15 <head>
5b8f056527a3 docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1647
diff changeset
16 <% head() %>
5b8f056527a3 docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1647
diff changeset
17 <title>Luan Tutorial</title>
5b8f056527a3 docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1647
diff changeset
18 </head>
5b8f056527a3 docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1647
diff changeset
19 <body>
1735
4b56eff90040 add hosting.html
Franklin Schmidt <fschmidt@gmail.com>
parents: 1659
diff changeset
20 <% header() %>
1651
5b8f056527a3 docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1647
diff changeset
21 <div content>
1324
1660136ac451 website - remove Shared.luan
Franklin Schmidt <fschmidt@gmail.com>
parents: 1323
diff changeset
22
562
7cc9d4a53d3b remove SimplyHTML from documentation
Franklin Schmidt <fschmidt@gmail.com>
parents: 512
diff changeset
23 <h1>Luan Tutorial</h1>
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
24
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
25
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
26 <p>Create a file <b>hello.luan</b> containing:</p>
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
27
1812
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
28 <code block>
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
29 %&gt;
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
30 Hello World
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
31 &lt;%
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
32 </code>
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
33
1045
48506d03e230 tutorial fix
Franklin Schmidt <fschmidt@gmail.com>
parents: 736
diff changeset
34 <p>To run this, type <b>luan hello.luan</b> on the command line. This should print <b>Hello World</b>.</p>
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
35
1827
50e570b598b2 security
Franklin Schmidt <fschmidt@gmail.com>
parents: 1812
diff changeset
36 <p>The syntax here is based on <a href="https://en.wikipedia.org/wiki/Jakarta_Server_Pages">JSP</a>. Let's change it a little:</p>
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
37
1812
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
38 <code block>
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
39 local name = "Bob"
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
40 %&gt;
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
41 Hello &lt;%= name %&gt;
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
42 &lt;%
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
43 </code>
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
44
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
45 <p>This should print <b>Hello Bob</b>. Now let's try a more conventional approach:</p>
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
46
1812
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
47 <code block>
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
48 local Io = require "luan:Io.luan"
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
49 local print = Io.print
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
50
1812
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
51 print("Hello World")
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
52 </code>
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
53
693
ca169567ce07 module URIs must now include ".luan"
Franklin Schmidt <fschmidt@gmail.com>
parents: 686
diff changeset
54 <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.luan"</b> is the same as <b>require("luan:Io.luan")</b>. Both <b>require</b> and <b>print</b> are functions.</p>
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
55
1827
50e570b598b2 security
Franklin Schmidt <fschmidt@gmail.com>
parents: 1812
diff changeset
56 <p>The <b>require</b> function takes a <a href="https://en.wikipedia.org/wiki/Uniform_Resource_Identifier">URI</a> as an argument. Examples of URIs are "<b>luan:Io.luan</b>" and "<b>file:hello.luan</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>
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
57
1647
Franklin Schmidt <fschmidt@gmail.com>
parents: 1576
diff changeset
58 <p>Luan starts with only one defined function: <b>require</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>
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
59
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
60 <p>Let's a make fancier version:</p>
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
61
1812
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
62 <code block>
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
63 local Io = require "luan:Io.luan"
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
64 local print = Io.print
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
65
1812
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
66 local function hello(name)
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
67 print("Hello "..name)
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
68 end
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
69
1812
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
70 hello("Bob")
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
71 </code>
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
72
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
73 <p>The <b>..</b> operator does concatenation. This will print <b>Hello Bob</b>.</p>
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
74
1647
Franklin Schmidt <fschmidt@gmail.com>
parents: 1576
diff changeset
75 <p>Now let's make a web page. First we need a directory for our website. So create a directory <b>src</b>. In this directory, create a file <b>hi.html.luan</b> containing:
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
76
1812
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
77 <code block>
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
78 local Io = require "luan:Io.luan"
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
79 local Http = require "luan:http/Http.luan"
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
80
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
81 return function()
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
82 Io.stdout = Http.response.text_writer()
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
83 %&gt;
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
84 &lt;!doctype html>
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
85 &lt;html>
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
86 &lt;body>
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
87 Hello World
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
88 &lt;/body>
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
89 &lt;/html>
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
90 &lt;%
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
91 end
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
92 </code>
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
93
1652
d5779a264a4a docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
94 <p>Now go back to the parent directory and do <b>luan luan:http/serve.luan src</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.html.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.html">http://localhost:8080/hi.html</a> then you will run the program which will generate the web page. In fact the page that you are currently looking at <b>tutorial.html</b> is generated from <a href="tutorial.html.luan">tutorial.html.luan</a>.</p>
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
95
1651
5b8f056527a3 docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1647
diff changeset
96 <p>The Luan webserver expects the file to return a function and calls it to generate the page. Code of the form <b>%&gt;...&lt;%</b> writes its output to <b>Io.stdout</b> which by default is the standard output of the command line. So in the returned function one usually starts by setting <b>Io.stdout</b> to a <code>text_writer</code> which writes its output to the HTTP response (to the web browser).</p>
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
97
1659
Franklin Schmidt <fschmidt@gmail.com>
parents: 1652
diff changeset
98 <p>You can find this example and others in the <a href="examples/">examples directory</a>. Take a look at <a href="examples/hi2.html.luan">hi2.html.luan</a> next. Remember to remove the <b>.luan</b> from the URL to run the code.</p>
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
99
1647
Franklin Schmidt <fschmidt@gmail.com>
parents: 1576
diff changeset
100 <p>So now you have built your website and you want to publish it to the web. If you have your own domain, create a CNAME record for it pointing to <b>s1.luan.software</b>. If you don't have a domain, just use a domain like <b>bob.s1.luan.software</b> (anything of the form <b>*.s1.luan.software</b>). Assuming your directory is <b>src</b> and you will use the password <b>secret</b>, do the following from the command line:
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
101
1812
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
102 <code block>
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
103 luan luan:host/push.luan bob.s1.luan.software secret src
f44dcb3fedf7 docs - add code block
Franklin Schmidt <fschmidt@gmail.com>
parents: 1735
diff changeset
104 </code>
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
105
693
ca169567ce07 module URIs must now include ".luan"
Franklin Schmidt <fschmidt@gmail.com>
parents: 686
diff changeset
106 <p>The form is <b>luan luan:host/push.luan 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.luan domain password</b>.</p>
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
107
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
108 <p>Hopefully this short tutorial gave you an idea of how to use Luan to make a website.</p>
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
109
1651
5b8f056527a3 docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1647
diff changeset
110 </div>
5b8f056527a3 docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1647
diff changeset
111 </body>
391
2f5cc9c2cbf0 replace Html.simply_html_page with simply_html_head and simply_html_body_bottom
Franklin Schmidt <fschmidt@gmail.com>
parents: 387
diff changeset
112 </html>
1651
5b8f056527a3 docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1647
diff changeset
113 <%
5b8f056527a3 docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1647
diff changeset
114 end