First, I should state that we have had very few instances of spam on our site. Any user accounts must be verified by email and require the user to input a captcha from the reCaptcha project. Once this is done, the user is free to make edits to the API documentation and to post new topics and replies on the discussion forums. However, the process of posting spam on the site is very difficult to automate due to the honeypots, field hashing, and post tokens that a default Sputnik installation employs. That’s not to say that the software is bullet-proof, but in practice it seems to work for my needs on a real site.

The first few accounts, I simply removed from my authentication system via a simple mysql query (although removing it from a default installation would be a easier, a simple edit of the sputnik/passwords node.) But then I realised I was giving up information about the spammers, including the email addresses they were using to register, something I could share with some of the spam registration databases that exist. It was clear that I needed an easier way to stop those user accounts from posting on the site without simply nuking their user accounts from the system. Really what I wanted was a way to ‘ban’ a user account and prevent them from making edits on the site.

Permissions in Sputnik

Each node in a Sputnik document store is a Lua script that is compiled and assembled into a Lua object at runtime. Consider the following simple node:

    title = "Some Page"
    content = [[This is a simple test node for a Sputnik installation.
 
    Hello World!]]

Sputnik nodes can be more than just a symbolic representation of text data. For example, you can restrict the permissions of a node by adding a permissions field. Consider the following definition:

    permissions    = [[
      deny(all_users, all_actions)
      allow(all_users, show)  -- show, show_content, cancel
      allow(Authenticated, edit_and_save) -- edit, save, preview
      allow(all_users, "post")  -- needed for login
      allow(all_users, "rss")
      allow(Admin, all_actions)
    ]]

When this field is loaded, it’s obviously a string that we can then further process. Specifically, we load it in an environment where a few helpers functions are defined. The all_users function returns true for all users, all_actions does the same for all action types. Authenticated is a special function that returns true if the current user is authenticated, while Anonymous can be used when the user is not logged in. There’s also a special function called Admin that queries the authentication metadata for the current user and checks if the is_admin flag is set.

When I started looking for a way to ban users, I started looking in this section of the code and found the following gem that Yuri sneaked in after the definition for the Admin group:

      local groups = self.saci.permission_groups -- just a local alias
      -- Define group "Admin" as any user that has is_admin set to true
      groups.Admin = function(user)
         return user and self.auth:get_metadata(user, "is_admin") == "true"
      end
 
      -- Define any group that starts with "is.<group>" as including all users
      -- for whom "is_<group>" is set to true. For example, if is_clown is set
      -- to true than user is a member of group "is.clown" and we can set:
      --
      --     allow(is.clown, "show")
      --
      local groups_mt = {
         __index = function(table, key)
            return function (user)
                      return user and self.auth:get_metadata(user,
    "is_"..key) == "true"
                   end
         end
      }
      groups.is = setmetatable({}, groups_mt)

Bingo! With this bit of code, without making any changes to the Sputnik core, I had a way to ban users in my system, by setting the is_banned flag in their authentication metadata. For a simple authentication system (the default) this is just a matter of setting the given flag in the user’s authentication entry, whereas in a mysql authentication system I just add a row to the database. This was only part of the puzzle, since Sputnik doesn’t know anything about the new user group. I had to make a few edits to the @Root prototype to add the following at the end:

    deny(is.banned, edit_and_save)

Since earlier in the permissions script the edit_and_save permissions are granted to all authenticated users, I needed to make sure the denial runs after that point, since the final ‘permission’ is what really matters. Since I have custom forums in my system, I needed to make the same one-line change in a few other places.

It took a total of about 6 minutes to familiarize myself with the code and make the necessary changes, and now I have an easy way to ban a user from being able to post anywhere on my website.

Down with the spammers!

RISC OS offers a very simple interface to user software, via the ARM’s SWI (SoftWare Interrupt) instruction. Data is passed between the user’s software and the operating system in ARM registers; that data may consist of pointers to buffers in memory that hold further data. RISC OS has always contained the BBC BASIC programming language. This offers the user means of accessing the operating system using:

• DIM — to reserve a block of memory of a given size and pass back its address;
• Indirection operators ! (for words), ? (for bytes) and $ (for strings);
• SYS — to call an SWI with given values in the registers on entry and variables to receive register values on exit;
• an inbuilt ARM assembler and a CALL command to link to assembled code.

With these facilities BBC BASIC is sufficiently powerful to enable a user to control every aspect of her machine, if she is equipped with the RISC OS PRMs (Programming Reference Manuals) - these give details, for each of the modules constituting RISC OS, the protocols and input/output details for each of the SWIs available, and of the messages by which the kernel communicates with the modules.

Acorn Computers Ltd started out as manufacturers of laboratory equipment. Their computers (with the exception of the RISCix work stations) were always intended as single-user machines over which the user has total control. Security? An irrelevance in those days. Just as today’s motorist almost certainly does not carry a set of tappet-calipers in his hip-pocket and has never disassembled a carburettor on the kitchen table, so modern computer-owners are unlikely to want to know about SWIs or programming. But RISC OS developed in an era when computers had only just become affordable, and there was a sizable minority of people who wanted not just to do things with their computer but to understand how it did them, and how they could control it. In the end it was the association with education that did for Acorn Computers Ltd and for RISC OS, after ARM Holdings Ltd had been split off.

Porting Unix or Windows software to RISC OS is fraught with problems. RISC OS uses cooperative, not preemptive, multitasking. The RISC OS filing system is fundamentally different, too, and not just syntactically (a dot is the directory separator symbol). Filer objects have a filetype attribute that is not part of the object’s name.

RISC OS filing systems were designed on the supposition that they were part of a graphical user interface – the GUI is not just something tacked on later to a commandline interface. When a user clicks on the icon of an object in a directory-window the window manager broadcasts a message to all running tasks:

An object at coordinates (x,y) with pathname obj_name and
filetype obj_type has just been clicked on. Are any of you
guys interested?

If a task is interested it sends back an acknowledgment (so that the broadcast is aborted) and has its way with the object. If no task replies, the taskmanager looks to see if a system command (a sort of environment macro) Alias$@RunType_xxx has been defined, where xxx are the hexadecimal digits of obj_type. If it has, it is executed with obj_name as a commandline argument. This command generally starts up a task and passes on its argument to it. There is a special type for command files – known as “obeyfiles”. An obeyfile always “knows” where it is because the operating system sets the variable Obey$Dir to the pathname of the directory containing it when it is executed. Textfiles constitute a special type. Holding down the SHIFT key when clicking a file will always open it in a text editor (even if the user has not installed a text editor – there is a basic multifile texteditor incorporated in the OS, so fundamental is the role of editing ASCII text – the same principle applies to graphics, both bit-mapped and vector). Each type of object is displayed by its own icon, apart from application directories.

RISC OS has two types of directory. There are ordinary directories, and there are application directories.

• Click on the icon of an ordinary directory with the left mouse button and its window will open; with the right mouse button and the currently open directory window containing it will simultaneously close – this makes navigation and the avoidance of window clutter very simple and direct – no opening of menus needed.

• Application directories behave differently. Their appearance is governed by a file inside them called !Sprites – a bit-mapped graphics file. Click an application directory and the obeyfile !Run inside it will be executed. To open an application directory like an ordinary directory you must depress the SHIFT key when you click.

The point about application directories is that they can be treated as a package. There is no such thing as installing or deinstalling or registering an application. You simply load the application directory to wherever you want in the filing system and it will be launched when you click on it. To deinstall, simply delete it. This independence of position is achieved by a file called !Boot within an application. It is executed when the window manager is first made aware of the application’s existence by the opening of the window of the directory containing it; this action can be suppressed by holding down the CTRL key when opening a directory window. The !Boot file will define system variables and macros which will inform user software about where the application is, and anything else they need to know of it. Alternatively the user can “filer_boot” and “filer_run” applications from obeyfiles that are inserted into the boot sequence. This is done by loading the obeyfiles into appropriate places in the directory !Boot that must reside at the top level of any RISC OS filing system. Only the !Boot directory is off-limits for the user’s personal whims (though even that is highly customizable). In other words, the filing system is not a thing of labyrinthine complexity that belongs to the manufacturer or to tradition. It belongs to the user. This is made possible by the relocatability of applications.

In the RISC OS GUI, the window on top of the window stack is not necessarily the window with the input focus. I often find myself inputting text even though the window containing it is partially obscured by another window that I need to be reading at the same time, to compose my input. If I drag a window with the left-hand button it will come to the top of the window stack, and so be dragged over any other windows. If I drag with the right-hand button it will retain its position in the window stack, and so be dragged behind some windows and over others. The single most exasperating and thoughtless aspect in Microsoft Windows, to my mind, is the way windows leap to the top, obscuring what you need to be reading. Real desktops do not behave in this way, unless somebody has left the door open and there is a gale blowing through. It is a small detail, but a crucial one. I have not sufficient experience to know which Linux window managers, if any, get this right.

Of course, applications in read-only filing systems may need to rent space for their configuration files on another, writable filing system. RISC OS is usually held in ROM, so startup and switchoff are immediate. I can switch on both my computers, one RISC OS, an Iyonix, and the other Windows XP, an Advent 4211 notebook, at the same time, and by the time the Advent is ready to use I have read my emails, replied to them and switched off the Iyonix.

I mention all these details so that readers who are only familiar with Windows or Unix will understand that there are other operating systems which present a very different user experience. Many of the worries and tools to deal with them (defragmenting the hard disc, installing and removing packages, viruses, rootkits) that the Windows or Unix user must take into consideration do not exist for the RISC OS user. The other side of the coin is that RISC OS cannot deliver much that is now taken for granted – its user base is too small to catch up.

As BASICs go, BBC BASIC is very good. There is a version for Windows, I believe, with many improvements. It is almost unfair to call it BASIC, because the facilities I cited above give it a whiff of BCPL. Recall that BCPL was developed in Cambridge and was the grand-daddy of C. BCPL was untyped. Although I am an admirer of BBC BASIC, I am not blind to its limitations as a programming language. For a long time I wondered if it were possible to have the best of both worlds: something that incorporated the advances in programming language design since 1964, BASIC’s year of birth, and yet retained the integration with the operating system and the ease of use which BBC BASIC can boast. I spent many years on different attempts to realize this dream. Then I came across Lua.

Lua is portable to any platform with an ANSI C compiler. Lua is a modern phenomenon, if we take the development of C as the watershed dividing ancient from modern. Lua is safe, and it can make no assumptions about its host platform; it certainly cannot peek or poke memory. RISC OS is unsafe, tied to the ARM architecture, and uses memory references. It is written mostly in ARM assembler; it conflates 32-bit integers with addresses, with file-handles, task-handles, task-manager messages, … . It is in some ways a relic of the age before C. To marry Lua with RISC OS, to produce what I called in an unimaginative moment, RiscLua, these contradictions had to be squared.

The first problem is that ARM CPUs tend not to have floating-point hardware. Continual conversion between doubles and 32-bit integers would be a burden. This problem is solved by #defining LUA_NUMBER to int and leaving out the math library. I also extended the Lua VM with bit operations, putting them on an equal footing with the other arithmetic operations. For those that have to use floating point numbers I put in a library implementing doubles in the heap.

To integrate Lua with RISC OS, something along the lines of BBC BASIC’s DIM,!,?,$ and SYS was needed. To begin with I used userdata for holding the values of addresses. Then I could reserve blocks of garbage-collectible memory, and I could check that references were within set bounds. One downside was that the error-checking slowed things down. Much worse was the problem of how to convert the data returned in a register from an SWI call. To what sort of Lua value should it be converted? An integer, a userdatum holding an address, a file-handle, a string, …. ? Eventually I realised that this problem had no universal solution. The only answer was to play as dirty as BBC BASIC; to abandon userdata and simply conflate integers with addresses. This made RiscLua less safe, but faster, and allowed a syntax for indirection that was very close to that of BBC BASIC – an advantage for users more accustomed to BBC BASIC than to anything else. The latest versions of RiscLua have a riscos library containing dim, sys, !, ? and $ (these are allowable in variable names in RiscLua). Where BBC BASIC might have x!4 RiscLua can have ![x+4]. The symbols !,? and $ in the riscos environment are just empty tables with metamethods: __index peeks and __newindex pokes. The sys function has one little twist that SYS does not have: a nil argument for a register value means “use the value returned for that register by the previous call to sys”. This is useful because the register usage for SWI calls in RISC OS has been carefully optimized to minimize shuffling data between registers, something which can be exploited by this syntax.

There are a few other extensions: backslash is sugar for function and ‘=>’ is sugar for return.

This is a texteditor window displaying a short RiscLua script that uses Roberto’s lpeg library to run code enclosed in <lua> … </lua> tags (with the remainder of the text taking the value “text”). The point of the picture is the third icon with the green arrow pointing down. If you shift-drag the icon of a scriptfile onto the green arrow of a texteditor window, the script is run (with arg[1] holding the name of a pseudofile containing the contents of the window) and the contents of the window are replaced by the standard output of the script. This provides the texteditor with a convenient facility - any scripting language can be used so long as the texteditor has been configured to understand the right command line syntax for it. In this case, shift dragging “untangle” onto the green arrow of a window containing “<lua>print(text:upper())</lua>hello” would convert its contents to “HELLO”. Yes, I know it is contrived, but I hope it shows the general principle.

This shows the final dialogue box when the following program is run.

-- Fred, tiny wimp program using error dialogue
require "wimp.task"
do
 local dim,! in riscos
 local buffer, wimp_msgs = dim(256), dim(4)
 local title$ = dim "Fred\r"
 local ask = "Count is %d. CANCEL to stop now?"
 local goodbye = "You reached %d. Goodbye."
 local flags = 23  -- for dialogue window
 ![wimp_msgs] = 0  -- no wimp messages
 fred = task.new(title$,wimp_msgs,buffer)   -- create task "fred"
 in fred do
  count = 0                      -- give it a counter
  handler[0] = \ (self)      -- give it a null-event handler
    count = count + 1
    local click = self:report(ask:format(count),flags)
    => (click ~= 1)          -- OK button to continue
  end -- handler
  preclosedown = \ (self)     -- give it a farewell action
     self:report(goodbye:format(count))
  end -- preclosedown
 end -- do
 fred:init()                   -- register it
 fred:run()                    -- run it
end -- do

This is a toy example of a RiscLua wimp program. It puts up a window with two buttons, CANCEL for stopping, OK for carrying on, and it increments a counter showing the number of times OK is clicked. I hope the program is not too opaque. Note the use of Peter Shook’s patch in local dim,! in riscos and the convenient syntax provided by lexical environments in in fred do … end. The wimp.task library provides a single function task.new which returns a table, with methods “init”, “run”, “preclosedown”, etc and a table, “handler” of event-handlers, indexed by the event-codes sent by the taskmanager. Nothing much surprising about this approach.

I will not pretend that RiscLua can do all the things that BBC BASIC can do. It has no inbuilt ARM assembler, it does not have extensive commands for sound or graphics. But there are things that make RiscLua, for me, much more satisfying to use. It is more expressive, more modular, more consistent and more concise. It fulfils my quest, and still offers plenty of opportunities for further development.

RiscLua and its sources are available at http://lua.riscos.org.uk/ .

Gavin Wraith

Making a website just for yourself is one matter; doing it for others brings into play a range of quite separate considerations, that affect even the technical matters of design and implementation. You are the pig in the middle, the bacon in the sandwich, sitting between the site on one side and its commissioners on the other. I am a slow learner, but after a dozen years of experience of different commissions I have come to some definite general conclusions.

First, even for modest websites, plenty of time is needed for preparation, before you even start thinking about design or implementation; time for establishing a proper protocol between yourself and those who have commissioned you. Ensure that all communications between yourself and them pass through a single intermediary, a spokesperson who can shield you from the disagreements and internal rivalries into which it may be fatal to be drawn. Your commissioners may well have a committee charged with responsibility for the proposed website, and it will probably delegate its duties to a number of people: Mr X the timetable, Miss Y the graphics, Dr Z the document archive, … . Fine. Nice to know you, Mr X, Miss Y, Dr Z, … Have nothing to do with these arrangements. Insist that they all communicate only through the spokesperson. The spokesperson will have to channel information in both directions. That way, with any luck, you will not have to explain more than a dozen times why web pages look different in different browsers, and why enormous TIFF files intended for high quality printing are not appropriate for graphics on web pages, because they will take rather a long time to download.

To be realistic, it is too much to expect the more important members of the website committee to stick to this regime. In any case, out of friendliness they may want to express themselves personally. It is for that reason that I recommend that during the development phase of the website each page should contain within its header the tags

<meta  http-equiv="pragma" content="no-cache" />
<meta  http-equiv="cache-control" content="no-cache" />

because otherwise you will have the committee chairman sending you messages accusing you of not getting on with the job: “Hi Gavin, Mr X says he sent you that stuff about emergency car-parking three weeks ago and it still is not up on the website.”; and then you will have to explain to a deeply suspicious technophobe all about how browsers cache webpages and that he is still looking at the pages that his browser cached three weeks ago, and no, you cannot tell him how to clear the cache for himself because you do not know what operating system or browser he is using (“operating system? what is that, old boy?”).

I struck an extraordinary glitch when I was making the website for the twenty-first International Congress of Byzantine Studies, which took place in London from 21 to 26 August 2006. It was a prestigious affair, with the Prince of Wales as patron and a long list of eminent sponsoring organizations. Clarence House had been persuaded to send me a facsimile of a signed letter of welcome from HRH, in receipt of which I had to sign an undertaking that I would not permit any improper use of it. I put a link to it from the sponsors’ page.

The organizing committee of the conference had obtained a lovely jpeg from the British Museum, of a Byzantine wooden carving of an angel. They used this to make a poster. I used a jpeg of that to make the entry page of the site. Clicking on the angel was to bring one to a page listing the sponsors, including HRH, and inviting the viewer to choose either the English or the French version of the website. In my innocence, I called the page “sponsor.html”. When it was up for review by the organizing committee I began to get puzzled queries from them. “I clicked on the angel, and nothing happened”, about half of them reported. I had no problem, nor did the other half. It was very mysterious. Eventually research showed the culprit to be an arrogant piece of Norton AntiVirus software running on the computers of some committee members. It had decided that “sponsor” was obscene or dangerous, apparently. Thus was HRH’s letter censored by Norton. In the end I changed the file’s name to “spons.html” and the problem went away. The moral, I suppose, is that you have to fathom some pretty sick minds if your webpages are to be viewable by the public.

It is time to turn from the human to the coding side of things. I have always believed that the best principle is to keep all as simple as possible. As none of my sites have been designed for huge traffic I have always shunned client-side scripting. It is usually unnecessary. One should also keep in mind that many users may not have the latest browser. In any case, adoption of WAI (the Web Accessibility Initiative ) is mandatory for .gov.uk websites, and it makes sense for any site that is to be used by the public, especially an academic public that is not likely to have the latest hardware.

I always create my websites on my own machine. I generally divide the directory for website-creation into two subdirectories: “site”, to contain all the stuff to be uploaded to the server, and “data” to hold the gubbins from which the website is to be created, usually as a “make” project. The contents of the webpages I classify into three groups:

1. furniture – the graphics and css stuff that determine a common theme;
2. permanent content – usually text;
3. formatted mutable data – usually held as a textual database, as lists of labelled records, for ease of updating with a text editor.

I use Lua format for the databases and Lua scripts to input from the data-directory and output the finished pages to the site-directory. To begin with, for the Art Historians’ Millennium bash, I used a Lua program, called Weave, which I had developed for creating web pages. Over time I improved it by generalizing to the production of any sort of marked-up text. Eventually it simply got replaced by a Lua library. I must make another blog about this, because Lua’s way with strings was a key factor in the design of this software. I also produced a Lua program, Infuse, to perform the abstract task of pouring content into template files – a sort of mail-merge. It was the actual experience of coping with the commissioned websites that drove me to keep reinventing. The frustrating thing was that I dared not change over to a newer regime until the project was completed. By starting sufficiently early I could create my templates for the approval of the commissioners, before the flood of content hit me. It was important to have a design sufficiently flexible to cope with sudden changes of tack. The Lua format for labelled records was good in this respect, because extra fields could always be added. By contrast, CSV format would have been hopeless.

Lua’s extreme portability was handy. My own machine ran neither Windows, Linux nor MacOS. Yet when I did a website for an artist, whose agent needed to take over the running of it, even though the agent used Windows, there was no problem getting everything working on his machine.

For the Byzantine Congress I was told that I had been appointed ἐπὶ τοῠ κανικλείου , guardian of the imperial inkstand, so named because it was in the shape of a little dog (canicula). To find out more about this prestigious office, use Google.

Gavin Wraith

Ropes are better than Strings: A Technical Appendix

In Lua strings are immutable values. This means that you should avoid building up strings out of small pieces, because although they will eventually be garbage-collected, all the intermediate stages of your construction will still be there taking up storage. Building up a string of n characters by consecutive concatenations will use a number of bytes varying quadratically with n. So concatenations are something to be avoided. What about the construction of web pages, where markup and text must be intertwined? Surely that will involve lots of concatenations?

Actually, no – it need not. Whether we think of an html document as text with markup inserted, or whether we think of it as a structure of nested tag-pairs with text inserted, either way we are led to the concept of strings-with-holes. To be more formal we define the datatype of “ropes” recursively by:

rope = string | list of rope

In Lua syntax, a rope either looks like

[[ ..... ]]

or like

{ ........ }

where the contents of the braces are a comma separated list of ropes.

Put another way, a rope is a tree whose leaves are strings. We can think of it as a string that has been broken apart leaving gaps. If we walk over a rope, depth first, printing out the leaves to a file, then we can construct our marked-up text without doing any string-concatenation at all.

So this code

<a href="http://luanova.org/">LuaNova</a>

can be obtained by printing out the rope

     {
     {
      [[<a ]],
      {
       [[href="]],
       [[http://luanova.org/]],
       [["]],
      },
      [[>]],
     },
     [[LuaNova]],
     [[</a>]],
     }

If we define

     link = function (url)
            return function (label)
                    return {
     {
      [[<a ]],
      {
       [[href="]],
       url,
       [["]],
      },
      [[>]],
     },
     label,
     [[</a>]],
     } end end

then our rope is just the value of

    link "http://luanova.org/" "LuaNova"

There are two sorts of markup: “monotags” and “tags”.

By a monotag I mean something like

<tag_name attr />

and we can implement this as a function from ropes to ropes:

    function(attr) return {"<tag_name ",attr," />"} end

By a tag I mean something like

<tag_id attr>stuff</tag_id>

which we can implement as a function from ropes to functions from ropes to ropes:

     function(attr)
      return function(stuff) return
             {"<tag_id ",attr,">",stuff,"</tag_id>"}
             end
     end

To simplify construction of webpages I invented a little language, which I called Weave, as a fragment of Lua using strings and ropes and named functions for the tags and monotags of HTML (see Lua technical note 30 .) After a while I broadened Weave’s abilities so that it could cope with any sort of markup and no longer had HTML’s tags and monotags built in. I introduced empty tables called “TAG” and “MONOTAG” with metatables, so that using the __index key I could define tag and monotag functions with notations like “TAG.a” and “MONOTAG.img” and so on. This was more flexible, but it did mean that the user had to define her own tags before building a webpage. That did not matter, because by then CSS had appeared and most webpages needed only a handful of tags and monotags. Eventually I did away with Weave as a separate entity and simply used the Lua module “xhtml” instead.

To create a very trivial webpage “foo.html” in the current directory, run a Lua script as follows:

     #! lua
     require "xhtml"
     do
     local mydoc = BEGIN "foo.html"
     local hstyle = [[style="text-align: centre;"]]
     local myheader, link = xhtml.TAG.h1, xhtml.link
     mydoc.BODY = {
                   myheader (hstyle) "Try this";
                   link "http://luanova.org/" "Lua Nova";
                  }
     END(mydoc) -- write the rope out to file
     end -- do

OK, this takes almost as long as creating the webpage by hand, for this trivial example. But it should not take too much imagination to see the possibilities. Practically every webpage I have created for the last ten years has used this method.

Here are the relevant modules:

weave.lua

     --[[
         The rope datatype is defined recursively:
 
         data rope = string | list of rope.
 
       Use:  status,err = rope.walk(rope,function)
             print(table.concat(err,"."))
       Error message prints out index at each level.
     ]]
     local pcall = pcall
     local type = type
     local ipairs = ipairs
     local tostring = tostring
     local assert = assert
     local setmetatable = setmetatable
     local open = io.open
 
     module "weave"
 
     -- ropes -------
 
     local t_err = "<bad type: %s>"
     local a_err = "<bad arg: %s>"
 
     walk = function(x,f)  -- apply f to leaves of tree x, depth first
          local g
          g = function(x,e) -- e = error stack
             local x_type, status = type(x)
             if x_type == "string" then
              status = pcall(f,x)
              if not status then e[1+#e] = a_err:format(x) end -- if
                  return status,e
              elseif x_type == "table" then
                  e[1+#e] = ""
                  for i,y in ipairs(x) do
                    e[#e] = tostring(i)
                    status = g(y,e)
                    if not status then return nil,e end -- if
                  end -- for
                  e[#e] = nil
                  return true
                else
                  e[1+#e] = t_err:format(x_type)
                  return nil,e
                end -- if
              end -- function
              return g(x,{})
        end
 
       local file_err = "cannot open %s"
       out = function(x,file)
             local o = assert(open(file,"w"),file_err:format(file))
             local f = function(s)
                       o:write(s or "")
                       return true
                       end -- function
             local status,err = walk(x,f)
             o:close()
             return status,err
             end -- function
 
       ------ markup stuff --------------
       --[[
       Two types of tag:
 
         monotag    <foo attributestring />
         tag    <foo attributestring> rope </foo>
 
       where attributestring could be empty.
         ]]
 
       local monotagger = {
       __index = function (_,tag)
                 assert(type(tag) == "string")
                 return function (attr)
                        local o = {"<",tag}
                        if attr and (#attr > 0) then
                          o[1+#o] = " "
                          o[1+#o] = attr
                        end -- if
                        o[1+#o] = " />"
                        return o
                        end -- function
                  end -- function
                 }
 
       local bitagger = {
       __index = function (_,tag)
                 assert(type(tag) == "string")
                 return function (attr)
                        return function (rope)
                         local o = {"<",tag}
                         if attr and (#attr > 0) then
                          o[1+#o] = " "
                          o[1+#o] = attr
                         end -- if
                         o[1+#o] = ">"
                         o[1+#o] = rope
                         o[1+#o] = "</"
                         o[1+#o] = tag
                         o[1+#o] = ">"
                         return o
                  end end end
                  }
       MONOTAG, TAG = {},{}
       setmetatable(MONOTAG,monotagger)
       setmetatable(TAG,bitagger)

xhtml.lua

       --[[ The xhtml library exports
 
         TAG, MONOTAG, BEGIN, END, TEXT, SPACE, REM and link
 
       ]]
 
 
       require "weave"
 
       local assert = assert
       local type = type
       local pairs = pairs
       local print = print
       local this = arg[0]
       local leaf = this:match("\\([^\\]*)$")
       local weave = weave
       local walk = weave.walk
       local out = weave.out
 
       local concat = table.concat
 
       module "xhtml"
 
       MONOTAG = weave.MONOTAG
       TAG = weave.TAG
 
       local doctype = [[
       <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
       "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">]]
 
       local HTML = TAG.html [[
       xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"]]
 
       local nl = "\n"
 
       BEGIN = function(filename)
               if filename then
                 assert(type(filename) == "string","BEGIN takes a string or nil")
               end -- if
               return { FILE = filename or this..".html"; }
               end
 
       local META,LINK = MONOTAG.meta,MONOTAG.link
       local HEAD,BODY,TITLE = TAG.head "",TAG.body,TAG.title ""
       local css = [[rel="stylesheet" type="text/css" media="screen" href=""]]
 
       END = function(rope)
             local file = rope.FILE
             local style = rope.STYLE
             local doc = {
              rope.DOCTYPE or doctype;
              nl;
              HTML {
               nl;
               HEAD {
                nl;
                TITLE (rope.TITLE or leaf);
                nl;
                META [[name="Generator" content="Lua"]];
                nl;
                META [[name="MSSmartTagsPreventParsing" content="TRUE"]];
                nl;
                rope.HEAD or "";
                style and LINK {css;style;'"'} or "";
                    };
                nl;
                BODY (rope.ATTR or "") (rope.BODY or "");
                nl;
                  };
                          }
              status, err = out(doc,file)
              if not status then print(concat(err,'.')) end -- if
              end --function
 
       local entity = {
         ["<"] = "&lt;",
         [">"] = "&gt;",
         ["&&"] = "&amp;",
                      }
       local catchall = "(.)"
       local entify = function (c)
                      local n,fmts = c:byte(),"&#%s;"
                      return (n > 127) and fmts:format(n) or c
                      end -- function
 
       TEXT = function(rope)
              local o = {}
              local f = function(s)
                  local status = type(s) == "string"
                  if status then
                    for symb,ent in pairs(entity) do
                      s = s:gsub(symb,ent)
                    end -- for
                    s = s:gsub(catchall,entify)
                    o[1+#o] = s
                  end -- if
                   return status
                 end -- function
              walk(rope,f)
              return o
              end -- function
 
       SPACE = function(n)
               assert(type(n) == "number","SPACE takes a number")
               local s = "&nbsp;"
               return s:rep(n)
               end -- function
 
       REM = function(s) return { "\n<!-- ";s;" -->\n"; } end -- function
       link = function(url) return TAG.a { 'href="'; url; '"'; } end -- function

Orbit is a lightweight framework for Web applications written in Lua. Unlike Sputnik, Orbit gives you the basic tools for constructing applications built on WSAPI. If you want authentication, standard look-and-feel, wiki-like functionality, you are better off starting with Sputnik; but Orbit is a satisfying way to build web applications from scratch.

The easiest way to install Orbit on a Unix machine is using LuaRocks, but here for a change I will assume that you already have Lua for Windows which already has most of the dependencies for Orbit. Then download orbit-2.0.2-all.zip, unzip it somewhere preserving folder names, and run lua install-orbit.lua from this directory in a command prompt.

The examples in this tutorial are then in the orbit-2.0.2\samples\basic folder.

The Basics

The simplest Orbit application is one that serves up a single HTML page:

    -- basic1.lua
    require"orbit"
 
    -- declaration
    module("basic1", package.seeall, orbit.new)
 
    -- handler
    function index(web)
      return render_index()
    end
 
    -- dispatch
    basic1:dispatch_get(index, "/", "/index")
 
    -- render
    function render_index()
       return [[
        <head></head>
        <html>
        <h2>Pretty Easy!</h2>
        </html>
        ]]
    end

An Orbit application is a Lua module, declared in the usual way except for the extra ‘orbit.new’. Lua’s module function can take a number of extra arguments, which are all functions which modify the module table in some way: package.seeall makes the global environment accessible to the module, and orbit.new adds some extra methods to the new module (you may think of this as ‘inheritance’.)

Any HTML request is mapped onto handler functions – in this case, the result of doing a GET request on ‘/’ or ‘/index’. index just asks render_index to actually generate the HTML for this particular page. You can then run this application using the default Xavante server:

c:\basic> orbit basic1.lua
Starting Orbit server at port 8080

And you can view the result by going to http://localhost:8080 in your favourite browser.

Not perhaps very impressive, seeing as the result could be achieved by a simple static page, but the render function can return any dynamically created string. And this example will work with Xavante, FastCGI or CGI, because Orbit is a WSAPI application.

All the usual web request variables are parsed and available to you. The web variable returned from the handler contains a table GET which has all the parameters passed to the server from a GET request. Call this script with http://localhost:8080/?cat=felix&dog=fido and you will see that cat and dog are fields of web.GET, appropriately translated from URL encoding.

    -- basic3.lua
    require"orbit"
 
    module("basic3", package.seeall, orbit.new)
 
    basic3:dispatch_get(function(web)
        local ls = {}
        for k,v in pairs(web.GET) do
            table.insert(ls,('<li>%s = %s</li>'):format(k,v))
        end
        ls = '<ul>'..table.concat(ls,'\n')..'</ul>'
        return ([[
        <html><head></head><body>
        Web Variables <br/>
        %s
        </body></html>
        ]]):format(ls)
    end, "/", "/index")

This is not a pretty script; it’s only virtue is that it is short. It is ugly for two basic reasons; first, generating HTML with regular string operations is awkward, and second, it does not separate the logical parts out neatly. The HTML problem will be discussed in the next section, but the next example separates the various operations into their own sections.

This also shows how Orbit can serve up static content as well, in this case anything inside the /images directory:

    -- basic2.lua
    require"orbit"
 
    module("basic2", package.seeall, orbit.new)
 
    function index(web)
      return render_index(collectgarbage("count"))
    end
 
    basic2:dispatch_get(index, "/", "/index")
    -- any file in this directory will be served statically
    basic2:dispatch_static ("/images/.+")
 
    local template = [[
    <head></head>
    <html>
    %s
    </html>
    ]]
 
    function render_page(contents)
        return template:format(contents)
    end
 
    function render_index(mem)
       return ([[
        <img src="/images/lua.png"/>
        <h2>Memory used by Lua is %6.0f kB<h2>
       ]]):format(mem)
    end

Note that dispatch_static is passed a Lua string pattern, not a file mask; in this case, anything in the directory.

We are now presenting true dynamic content (the amount of memory managed by Lua) and made a first start to prettifying the result. It is convenient to only generate the ‘inner’ HTML and use a template to generate the full page, so render_page has been factored out.

Orbit follows the Model-View-Controller (MVC) pattern that separates an application into three distinct parts. The Controller acts as the executive, the Model manages the data, and the View presents the data to the user; here the dispatch rules calls index which uses the renderer render_index to present the HTML form of the data. This pattern comes from a basic principle, Separation of Concerns. You do not want to mix database access, application logic and visual presentation together because the result is not clear and may become unmaintainable quickly.

HTML the Orbit Way

The HTML problem is usually solved using templates, such as Cosmo as discussed in the last article on Sputnik. Orbit provides another option, which is that Lua code can generate HTML:

    -- html1.lua
    require"orbit"
 
    function generate()
        return html {
            head{title "HTML Example"},
            body{
                h2{"Here we go again!"}
            }
        }
    end
 
    orbit.htmlify(generate)
 
    print(generate())
 
    ==>
    C:\basic>lua html1.lua
    <html ><head ><title >HTML Example</title>></head><body ><h2 >
    Here we go again!</h2></body></html>

This certainly reads better if you are used to Lua, but the magic involved needs some explanation. You may imagine that Orbit has introduced a whole bunch of little functions into the module, but this is not how it is done. Instead, orbit.htmlify modifies the environment of the function generate so that any undefined variable is assumed to be a HTML tag and becomes a suitable function. So you can generate anything, even with unknown tags. So if generate was:

    function generate()
        return sensors {
            sensor {name="one"},
            sensor {name="two"},
        }
    end

Then the result would be this syntactically valid XML:

<sensors ><sensor name="one"></sensor>
<sensor name="two"></sensor></sensors>

In presenting the resulting markup I’ve inserted a few line breaks for making reading a bit easier. Naturally you might like to beautify the output for debugging purposes; web browsers do not care. HTML Tidy is another option. which will also give you a host of other diagnostic checks.

One problem to watch out for is that a mistyped tag name will give you odd HTML, not a Lua error. And there are some HTML tags which are valid Lua globals, such as table – the solution is to say H(‘table’), etc. But HTML can now be generated without making your eyes bleed, as with the ugly web variables script. This little snippet uses the fact that tag functions take table arguments:

    function generate (web)
        local list = {}
        for name,value in pairs(web.GET) do
            table.insert(list,li(name.." = "..value))
        end
        return ul(list)
    end

Any technique can produce over-elaborate code, as this program which generates an HTML form formatted with a table:

    require"orbit"
 
    function wrap (inner)
        return html{ head(), body(inner) }
    end
 
    function test ()
        return wrap(form (H'table' {
            tr{td"First name",td( input{type='text', name='first'})},
            tr{td"Second name",td(input{type='text', name='second'})},
            tr{ td(input{type='submit', value='Submit!'}),
                td(input{type='submit',value='Cancel'})
            },
        }))
    end
 
 
    orbit.htmlify(wrap,test)
 
    print(test())

Not quite eye-bleeding, but getting there! The solution is to capture common patterns in a library. The util module in the basic folder makes for much more readable code:

    function show_form (web)
        return wrap(form {
            htable {
                {text("First name",'first')},
                {text("Second name",'second')},
                {submit 'Submit', submit 'Cancel'},
            }
        })
    end

Databases the Orbit Way

Orbit can create an Object-Relational Mapping (ORM) between the tables of a relational database and Lua tables. The restriction is that the SQL table is required to have a numeric key called id. In the following discussion, we must switch between two very different meanings of the word table, so I’ll use ‘array’ to mean ‘an array-like Lua table’ and ‘map’ to mean ‘a hash-like Lua table’.

Consider the following SQL table definition found in the blog example database:

CREATE TABLE blog_post
       ("id" INTEGER PRIMARY KEY NOT NULL,
       "title" VARCHAR(255) DEFAULT NULL,
       "body" TEXT DEFAULT NULL,
       "n_comments" INTEGER DEFAULT NULL,
       "published_at" DATETIME DEFAULT NULL);

This code uses LuaSQL’s sqlite3 driver to dump out a particular row of this table by defining a mapper:

    -- ORM1.lua
    require "orbit"
    require "luasql.sqlite3"
    local env = luasql.sqlite3()
 
    function dump (t)
        if #t > 0 then
            for _,row in ipairs(t) do
                dump(row)
            end
        else
            for field,value in pairs(t) do
                if type(value) == 'string' then
                    value = value:sub(1,60)
                end
                print(field,type(value),value)
            end
            print '-----'
        end
    end
 
    mapper = orbit.model.new()
    mapper.conn = env:connect("../blog/blog.db")
    mapper.driver = "sqlite3"
    mapper.table_prefix = 'blog_'
 
    posts = mapper:new 'post'  -- maps to blog_post table
 
    -- print out the second post
    second = posts:find(2)
 
    dump(second)
 
    ==>
    published_at	number	1096923480
    title	string	The Care And Feeding Of Your Sleeping Bicycle
    id	number	2
    n_comments	number	0
    body	string
    Thunder, thunder, thundercats, Ho! Thundercats are on the m
    -----

posts:find(2) gets the database row with id equal to 2 and returns a map with corresponding fields and values.

SQL is a more strongly-typed language than Lua, so that both published_at and n_comments are mapped to the number type. However, the mapper does preserve this information in its field meta; for instance, mapper.meta.published_at.type is ‘datetime’.

Orbit’s ORM mappers simplify database access by bridging the gap between the underlying database and the language; the most involved code here is just to dump out Lua maps and arrays.

As always, the interactive prompt is the best way to explore the available mapper methods:

C:\basic>lua -lmapper
Lua 5.1.4  Copyright (C) 1994-2008 Lua.org, PUC-Rio
> posts = mapper:new 'post'
> dump(posts:find_first('n_comments > 0'))
published_at    number  1097769720
title   string  'Star Wars' As Written By A Princess
id      number  4
n_comments      number  1
body    string
Ten years ago a crack commando unit was sent to prison by a
-----

find_first also returns a row, but by an explicit condition; find_all is similar, but returns an array of all matching rows. Note that the condition is a SQL expression, not Lua; this is effectively a more friendly way to create an SQL query:

    dump(posts:find_all("id = ? or id = ?",
        {2,4,order = "published_at asc"}))

ORM mapping works particularly nicely with dynamic languages, but there are some downsides. consider the case that the table blog_post had many thousands of rows; the default mapper will grab all the columns, including the potentially rather large body. So opportunities for optimizing queries are lost, if we were only interested in searching the title for a match. It’s possible to reorganize things so that blog_post only contained ‘meta’ data about each post (plus perhaps a short summary) and a new table blog_text would contain the actual text of each post, indexable using the same id.

Putting it Together

The next example will bring together these three concerns: request pattern matching (Controller), ORM mapping to a database (Model) and Orbit htmlification (View). It uses the database from the blog example but presents it in summary form. For each row, it puts out a nicely formatted summary. The actual rows are selected by a user set of keywords.

All our HTML-generating functions begin with ‘render_’. orbit.htmlify can be called in another way, where you give the module first, and then specify a string pattern to match the functions in the module that you want to htmlify.

	orbit.htmlify(blog1,'render_.+')

Initially, the actual model-controller part of the application is simply this:

    function index(web)
      return render_index(posts:find_all())
    end
 
    blog1:dispatch_get(index, "/", "/index")

And the view part:

    local function limit (s,maxlen)
        if #s > maxlen then
            return s:sub(1,maxlen)..'...'
        else
            return s
        end
    end
 
    function render_page(contents)
        return html {
            head { title 'Blog Example' },
            body (contents)
        }
    end
 
    function render_post(post)
        return div {
            h3 (post.id .. ' ' .. post.title),
            p (limit(post.body,128)),
            em(os.date('%a %b %d %H:%M %Y',post.published_at)),
            ' ',post.n_comments,' comments'
        }
    end
 
    function render_index(posts)
        local res = {}
        for i,post in ipairs(posts) do
            res[i] = render_post(post)
        end
        return render_page(res)
    end

The heart of the view is render_post, which formats each row from the model. You will only achieve date formatting happiness once you have learned the formating characters for os.date; these are the same as those used in the C strftime function.

All in all, not bad for a 55-line program. The next step is to add simple keyword searching, which takes an extra line:

    function index(web)
      local keyword = web.GET.keyword or ''
      if keyword == '' then return {}
      else
        return render_index(posts:find_all('title like ?',{'%'..keyword..'%'}))
      end
    end

The SQL like operator works with patterns, so that finding a title containing the word ‘Chicken’ would be “title like ‘%Chicken%’”, where ‘%’ means ‘any sequence of characters’. The keyword is passed as a GET request variable: enter the following URL to see the results of the search: http://localhost:8080/?keyword=Chicken.

It would be useful to have some user interface, especially when we start passing multiple keywords. render_index becomes:

    function render_index(posts)
        local res = {}
        append(res,p (form {
            input {type='text',name='keyword'},
            input {type='submit',value='Submit'},
        }))
        append(res,hr())
        append(res,h2(('Found %d posts'):format(#posts)))
        for _,post in ipairs(posts) do
            append(res,render_post(post))
        end
        return render_page(res)
    end

By default, HTML forms submit their values to the same URL as the page, so this works fine.

This introduction was intended to help you begin reading the Orbit samples, documentation and tutorials. In the next in this series, we will discuss building more complicated applications, caching generated pages, and Orbit Pages, which is a powerful Lua-powered template engine for generating HTML.

Sputnik is a second-generation extensible wiki engine written in Lua. First generation wikis (like the original WikiWIki) opened our eyes to the possibility of easy collaborative content generation, with automatic revision control. However, anybody who has been involved with a Wiki knows that they are not self-organizing, and so behind any Wiki is a core of busy elves correcting and ‘refactoring’ content. Plus, all content is usually in the form of marked-up text, plus uploaded binary data like images. For instance, Wiki pages often turn into discussions, but there is usually no way to structure these discussions and no support for creating them.

A second-generation wiki allows for ‘virtual’ pages, pages with explicit data fields, structured discussions, complete control of permissions, and namespace management. The site designer can choose the right balance between freedom and structure that is appropriate for the community and its common purpose.

Frameworks and Libraries

There are two basic approaches to software development; either start small, pulling as much functionality in using libraries, or to start with a framework, which does most of the job, and customize it to fit your functionality. Frameworks have a bad reputation because framework developers can get just a little mad in the process of writing them. But if you want something that can do wiki-like things, manage the content and control the revisions, handle authentication, then it’s time to get a Wiki framework, because these are not easy applications to get right. As the Sputnik git page says, “Sputnik provides a good foundation for anything that’s kind of like a wiki but not quite.”

It is true that the first trade-off is the freedom to do things your way, since you must learn how the framework does things, and cooperate with it. In a way, it is like collaboration with another developer on a project which you have just joined. I am assuming here that you want to get something done, which is not a million miles from a Wiki, and don’t want to rewrite a whole bunch of wheels, just maybe update the hubcaps. A better analogy would be this: if you want to equip a kitchen, then using a framework that includes the kitchen sink is appropriate (and not just a joke). Maybe you just want different fittings for your kitchen sink.

Getting Sputnik

Installing Sputnik is straightforward, providing you are on a Unix-like platform (like Linux or OS X) although it does also run on Windows. In this introduction, I assume that it is an Unix environment (although out of convenience, not religious fervour; it is very easy to get a Linux virtual machine and set it up for Sputnik testing.) After following instructions, you will have a Sputnik install in ~/sputnik, no special permissions necessary. Starting the webserver is then just:

  ~/sputnik$ ./bin/sputnik.lua start-xavante sputnik.ws

Sputnik comes with the Kepler stack, including the Lua webserver Xavante. This is quite good enough for testing and experimentation.

A useful change is to first edit sputnik.ws and set BASE_URL to ‘/’ and to add SHOW_STACK_TRACE = true. Sputnik will then give you Lua error traces when some hitch occurs. Then just open http://localhost:8080 in your favourite browser and start playing. Create a special user Admin to view and edit the configuration nodes.

All Sputnik configuration is via nodes with Lua content. For instance, sputnik/config assigns a set of fields to values. If you are editing this file (as Admin) and make a syntax error (such as ‘Sputnik”, mismatching string delimiters) the edit field will turn pink. sputnik/navigation controls the navigation bar menu:

  NAVIGATION = {
     {id="index", title="Start",
       {id="snippets", title="Snippets"},
       {id="tags", title="Tags"},
       {id="sputnik",title="Configure"},
     },
     {id="News", title="Timeline",
       {id="News"},
       {id="Future Plans"},
       {id="history", title="Recent Wiki Edits"},
       {id="history/edits_by_recent_users", title="Edits by Recent Users"},
       {id="history.rss", title="RSS Feed"},
     },
  }

Creating a new node is easy; if you ask for a node test then it will tell you that this node does not exist, but then will give you several types to choose from. The ‘Basic’ type is a plain Wiki page, and the link provided is something like http://localhost:8080/?p=test.edit&prototype=. In general, a Sputnik request has a node id (‘test’), an action (‘edit’) and parameters (‘prototype=’)

If you click on this link you can edit your new Wiki node. The markup used is Markdown which has a clean, readable syntax. In addition, Sputnik supports Wiki links; a link to your new page would be [[test]] and a link with some text would be [[test|My First Page]] . There is a convenient toolbar providing the most common operations when editing.

Customizing Sputnik

A lot can be done with basic Sputnik, just by editing the configuration nodes. (And, yes, the configuration nodes are Wiki nodes, so you can revert to an earlier version.) Also, like any modern Web framework, style and functionality are kept separate as CSS and HTML; these Sputnik sites show that you can get just about any look and feel.

Since the configuration is done with Lua data, it technically involves programming, but not in any serious sense of the word. Lua is particularly well-suited to expressing configuration, since it was originally conceived as a data-description language. This data is converted into Lua table structures using Lua itself, using a sandbox so that it will not execute any dangerous stuff.

The first ‘real’ customization we will do is make a whole set of pages default to a particular node type. That is, any node like pages/GeneralInfo or pages/Introduction will be created as ‘Basic’ nodes.

If Sputnik cannot find a node, it will first attempt to find a node default with that name. The request for ‘pages’ results in Sputnik attempting to load a Lua module like so: require “sputnik.node_defaults.pages”. So we have to create a file pages.lua in a directory so that Sputnik can resolve this module.

Sputnik itself is distributed as a LuaRocks application. In my system, the Sputnik package sits at ~/sputnik/rocks/sputnik/9.03.16-0/lua – call this $SPUTNIK. The relevant package directory structure is:

    sputnik
        actions
        hooks
        node_defaults
        ....

It is possible to customize Sputnik by putting a suitable pages.lua in $SPUTNIK/sputnik/node_defaults, but that is a road of misery that will end in tears. However, it’s useful to acquaint yourself with the contents of this directory because it defines the standard namespaces.

The best quick solution is to add directories to the LUA_PATH environment variable before launching Sputnik:

  ~/sputnik$ export LUA_PATH=";;$HOME/sputnik/examples/?.lua"

Then create a directory ~/sputnik/examples/sputnik/node_defaults containing this file, pages.lua:

  module(..., package.seeall)
 
  NODE = {
     title="Pages",
     content = "",
     child_defaults = [[
          any='prototype = ""'
      ]],
  }

It is structured as a Lua module, which contains a single exported table, NODE . The definition of the field child_defaults may appear a little hairy at first, but it’s now time to get the three different ways to do string literals in Lua straight. Whether you use single or double quotes for a string, does not matter; it is a convenience so that you can embed the other kind of quotes: ‘prototype = “”‘. This string is then further embedded in a Lua ‘long string’ literal.

After restarting Sputnik, go to pages: nothing much to see at this point – but note that Sputnik can find the node. If you go to pages/Introduction you will get another blank page with a title, which you can edit directly as a Wiki page. The child_defaults field tells Sputnik that any ‘child’ of pages like pages/Introduction has a particular prototype value which corresponds to the ‘Basic’ node type.

If you enter this text

    Some text for the Introduction node. See [[pages/Basic]]

and save, the result will have a link to a new page, which you can in turn edit.

To see how Sputnik saves pages by default, look at the ~/sputnik/wiki-data directory. There will be a subdirectory pages%2FIntroduction with files 000001 and index. (The subdirectory is just the URL-encoded form of ‘pages/Introduction’ ). index will contain something like this:

  add_version{
  version   = "000001",
  timestamp = "2009-11-01 14:33:07",
  author    = "",
  comment   = "",
   ["minor"] = "",
   ["ip"] = "127.0.0.1",
  }

And 000001 contains the node text:

  title          = "pages/Introduction"
  category       = ""
  content        = [=[Some text for the Introduction node. See [[pages/Basic]]
 
  ]=]
  breadcrumb     = ""

As the node is edited, each revision is saved in a similar format, 000002, etc. In this way, edit history is managed in a simple way, easily readable by humans, as opposed to being stored in some relational database. However, using a database for storage is also supported by the Sputnik content manager, which is called Saci.

Custom Output

Before actually starting with code, it’s useful to have a handy shortcut to the Lua executable used by Sputnik. I suggest creating a little executable script like this on your path:

  $> cat ~/bin/slua
  ~/sputnik/bin/lua -lluarocks.require $*

Before we actually get round to generating dynamic content, here is a quick review of Cosmo, which is a powerful template engine used by Sputnik.

  ~$ slua

  Lua 5.1.4  Copyright (C) 1994-2008 Lua.org, PUC-Rio
  > require "cosmo"
  > template = "$rank of $suit"
  > values = {rank="Ace",suit="Spades"}
  > = cosmo.fill(template,values)
  Ace of Spades

That’s useful, although only a little more friendly than Lua’s string.format function. However, Cosmo goes way beyond simple string interpolation.

  -- testcosmo.lua
  require "cosmo"
  template = [==[
  <h1>$list_name</h1>
  <ul>
   $do_items[[<li>$item</li>]]
  </ul>
  ]==]
 
  print(cosmo.fill(template, {
      list_name = "My List",
      do_items  = function()
          for i=1,5 do
             cosmo.yield { item = i }
          end
      end
  }
  ))

  ~$ slua testcosmo.lua

  <h1>My List</h1>
  <ul>
   <li>1</li><li>2</li><li>3</li><li>4</li><li>5</li>
  </ul>

Subtemplates are a powerful feature which makes generating HTML straightforward.

Now, we create a node which creates custom HTML output. First, put Memory.lua in your node_defaults directory:

  module(..., package.seeall)
 
  NODE = {
      title = "Lua Memory",
      content = "",
      actions = [[
          show="Memory.show_memory"
      ]],
  }

Create a directory actions (that is, ~/sputnik/examples/sputnik/actions) and put this Memory.lua in it:

  module(..., package.seeall)
 
  actions = {}
 
  local template = [=[
     <h2>Memory used by Lua is $mem kb</h2>
  ]=]
 
  function actions.show_memory (node, request, sputnik)
      node.inner_html = cosmo.f(template) {
          mem = ('%6.0f'):format(collectgarbage('count')),
      }
      return node.wrappers.default(node, request, sputnik)
  end

The convention is that any action functions are in the actions directory; these functions must be in a nested actions table. Visiting the node Memory will show the memory managed by Lua (as returned by the collectgarbage(‘count’) call).

The node’s inner_html is the source for the node’s display area, that is, not including the menu and all other frame decorations. node.wrappers.default is the actual function which generates the source for the whole page.

So, we now have a customized node with generated output. Please note that it does not appear in wiki-data; the node is fully ‘virtual’ and has no storage associated with it.

To take this example further, let us wrap the output of the ps command:

  ~$ ps aux --cols 256
  USER       PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
  ...
  sdonovan  2867  0.8  2.3  41972 15932 pts/1    Sl   10:47   3:57 /home/sdonovan/lua/scite/SciTE
  sdonovan  2902  1.2 12.4 179152 83160 ?        Sl   10:48   5:19 /usr/lib/iceweasel/firefox-bin -a firefox
  sdonovan  5993  0.0  0.4   5360  2844 pts/2    Ss   16:13   0:00 bash
  sdonovan  7118  0.0  0.3   5360  2024 pts/0    S+   18:03   0:00 bash
  sdonovan  7119  0.4  1.1   8384  7380 pts/0    S+   18:03   0:01 /home/sdonovan/sputnik/bin/lua -lluarocks.require /home/sdonovan/sputnik/rocks/sputnik/9.03.16-0/bin/sputnik.lua start-xavante sputnik.ws

(The –cols flag is necessary to prevent ps from thoughtfully truncating the line length to fit the terminal screen)

Chopping lines up is easy using sputnik.util.split – notice that it returns multiple values, not a table:

  ~$ slua

  Lua 5.1.4  Copyright (C) 1994-2008 Lua.org, PUC-Rio
  > util = require 'sputnik.util'
  > = util.split('one two three','%s+')
  one     two     three

With this, a more exciting version of actions/Memory.lua can be written:

  module(..., package.seeall)
  local util = require 'sputnik.util'
  actions = {}
 
  local template = [=[
     <h2>Memory used by Lua is $mem kb</h2>
     <h2>Processes</h2>
     <table>
     <tr>
      <th>User</th><th>CPU</th><th>Mem</th><th>Command</th>
     </tr>
     $do_processes[[
          <tr>
          <td>$user</td><td>$cpu</td><td>$mem</td><td>$cmd</td>
          </tr>
     ]]
     </table>
  ]=]
 
  function actions.show_memory (node, request, sputnik)
      node.inner_html = cosmo.f(template) {
          mem = ('%6.0f'):format(collectgarbage('count')),
          do_processes = function()
              local user = os.getenv 'USER'
              -- this works on LInux, may need some mods for BSD/OS X.
              local f = io.popen('ps --cols 256 aux','r')
              f:read() -- not interested in column headers
              for line in f:lines() do
                  local fields = {util.split(line,'%s+')}
                  if fields[1] == user then
                      cosmo.yield {
                          user = fields[1], cpu = fields[3], mem = fields[4], cmd = fields[11],
                      }
                  end
              end
          end
      }
      return node.wrappers.default(node, request, sputnik)
  end

Now the node Memory is actually useful for the administrator of the website – but probably not a good idea to expose to the world!

Permissions

The node Memory should be restricted; only the Admin user should be able to view it. Also, it does not make sense to edit it, even as an administrator. actions/Memory.lua needs to have a permissions field:

  module(..., package.seeall)
 
  NODE = {
      title = "Lua Memory",
      content = "",
      actions = [[
          show="Memory.show_memory"
      ]],
      permissions = [[
          deny(all_users,all_actions)
          allow(Admin,show)
      ]]
  }

We start by prohibiting everything, and then only let Admin view the page. Notice that all of the usual little action icons on the right-hand side have disappeared.

To get back to the pages example; we may insist that only authenticated users can edit the pages. There are two kinds of solution to this, make it site-wide policy or only for children of pages. The first solution requires no code; as Admin, go to the @Root node, and choose the ‘configure’ action (which is usually the little gear icon next to ‘edit’ on the actions toolbar) Now open the ‘Advanced Fields’ section, and you can then edit the ‘Permissions’ field. By default, Sputnik comments out this line:

  -- deny(Anonymous, edit_and_save)

Remove the comment and save. Now anonymous users have lost their power to make edits anywhere on the site.

We’ve already seen with Memory how to enforce permissions for a single node. But how to do this for a group of nodes? Sputnik prototypes provide the solution. A prototype acts as the ‘type’ of a node. When a node is retrieved from storage, Sputnik copies default values from its prototype node. The basic prototype of all nodes is @Root.

Previously, the pages node has insisted that its children have an ‘empty’ prototype. The idea is to create an explicit prototype that will apply to the children, which will be called @pages. (By convention, all prototypes begin with ‘@’)

node_defaults/pages.lua becomes:

  module(..., package.seeall)
 
  NODE = {
     title="Pages",
     content = "",
     child_defaults = [[
          any='prototype = "@pages"'
      ]]
  }

and create a new file node_defaults/@pages.lua to define the @pages prototype:

  module(..., package.seeall)
 
  NODE = {
     content = "",
     permissions=[[
          deny(Anonymous,edit_and_save)
     ]]
  }

It does very little, just explicitly overrides the permissions.

Hooks

Continuing with the pages example, it would be useful if we could track the author of a particular page, defined simply as the user that first edited it. Also, we would like to track the creation date. So the prototype for all pages must include these new_fields and define a save hook which will be called when the node is saved:

  -- node_defaults/@pages.lua
  module(..., package.seeall)
 
  NODE = {
     content = "",
     permissions=[[
          deny(Anonymous,edit_and_save)
     ]],
     fields = [[
        author = {1.1}
        creation_time = {1.2}
    ]],
     save_hook = "pages.save_page"
  }

Create a directory ‘sputnik/hooks’ as before, and put pages.lua in it:

  -- hooks/pages.lua
  module(..., package.seeall)
 
  function save_page(node, request, sputnik)
      if not node.creation_time then
         local params = {}
         params.author = request.user
         params.creation_time = tostring(os.time())
         node = sputnik:update_node_with_params(node, params)
      end
      return node
  end

When a node’s save_hook field is set to MODULE.FUNCTION , then Sputnik will try to load sputnik.hooks.MODULE and use the FUNCTION defined by that module. In this case, the save hook is only interested in a new node, where the author and creation time fields have not been assigned yet. It uses the update_node_with_params method to write the new key/value pairs into the node.

Now, after saving pages/fred, the revision in the pages%2Ffred directory will look like this:

  title          = "pages/fred"
  category       = ""
  prototype      = "@pages"
  content        = [[Some content!
  ]]
  breadcrumb     = ""
  author         = "sdonovan"
  creation_time  = "1257157113"

This shows that we are saving the new information, although these fields are not displayed yet.

Wrapping up

Currently, pages is blank, and like Memory we can output something sensible by defining a ‘show’ action that will display a table of the existing pages.

If you are accustomed to regular Web frameworks, you are probably tempted to maintain and use a relational database at this point. Sputnik does not exclude that, you are free to store things as you wish, but it’s best to work with the underlying ‘document-oriented’ database machinery provided by Saci.

The existing pages can be found by querying Saci, which provides a get_nodes_by_prefix method. The prefix identifies the namespace for the nodes, which is pages in this case. This method returns a table where the keys are the identifiers (e.g. pages/fred) and the values are the node objects. Here is code that creates a list of nodes from this table, and sorts it by creation time.

  local function pages_in_order (sputnik)
      local pages = sputnik.saci:get_nodes_by_prefix 'pages'
      local res = {}
      for id,page in pairs(pages) do
          res[#res+1] = page
      end
      table.sort(res,function(p1,p2) return p1.creation_time < p2.creation_time end)
      return res
  end

node_defaults/pages.lua gets an actions field, just as with node_defaults/Memory.lua:

  actions=[[
      show="pages.show_pages"
  ]]

And actions/pages.lua will be:

  module (...,package.seeall)
 
  actions = {}
 
  local template = [=[
     <h2>Existing Pages</h2>
     <table>
     <tr>
      <th>Page</th><th>Author</th><th>Created</th>
     </tr>
     $do_pages[[
          <tr>
          <td><a href="?p=$id">$name</a></td><td>$author</td><td>$created</td>
          </tr>
     ]]
     </table>
  ]=]
 
  local function pages_in_order(sputnik)
  ....
  end
 
  function actions.show_pages(node, request, sputnik)
      node.inner_html = cosmo.f(template) {
          do_pages = function()
              local pages = pages_in_order(sputnik)
              for _,page in ipairs(pages) do
                  cosmo.yield{
                      id = page.id,
                      name = page.id:gsub('pages/',''),
                      author = page.author,
                      created = sputnik:format_time(page.creation_time,"%d %b %Y")
                  }
              end
          end
      }
      return node.wrappers.default(node, request, sputnik)
  end

Beyond the Basics

If you are curious about how Sputnik creates the whole page, note that node.wrappers.default is usually implemented by the wrappers.default function in sputnik/actions/wiki.lua which does a Cosmo expansion of the node.html_main template (see NODE.html_main in sputnik/node_defaults/@Root.lua)

If you don’t like a visual feature, then it is often easy to remove it. For instance, editing @Root as Admin (using @Root.configure as before) you can open up the ‘HTML Fields’ and modify the templates directly. Removing the menu bar is as easy as clearing out the text in the ‘Menu’ field.

For a good overview of Sputnik permissions, see this list question and its reply.

The next part of this tutorial will deal with further customizations, like internationalization, providing a custom form for editing a node’s fields, and using the built-in @Collection prototype to simplify the common pattern of groups of content nodes. And Sputnik’s ability to create custom actions will change the way you look at file extensions forever.

Today we’re going to talk about a different wombat, with a different destiny.

Spear-headed by Brian McCallister, mod_wombat embeds the Lua programming language into the Apache HTTP server in the same fashion as mod_perl, mod_php and mod_python bring their respective languages into the Apache world of web development.

How mod_wombat differs has a lot to do with how Lua differs from other languages. Lua is a very lightweight scripting language originally designed for non-programmers to customize the software it is embedded in. It is simple to pick up, while offering a good amount of flexibility and power. Its popularity in game scripting has pushed its’ interpreter towards being very efficient and multi-thread ready.

Apache is the heavy-weight champion of HTTP servers, responsible for serving up half the Internet. Apache 2.x was a substantial reworking, providing:

• The Apache Portable Runtime (APR) so Module writers don’t need to deal with all the OS-specific issues.
• Swappable multi-processing modules (MPMs) including Prefork (non-threaded), Worker threads, and an Event MPM that decouples server threads from the HTTP connection (read: very efficient).

Lua is designed for embedding in C-based programs, which allows mod_wombat to take advantage of the substantial infrastructure Apache provides. More than any other language module, mod_wombat endeavors to work with Apache.

Matthew Burke is looking for students to work on mod_wombat as part of the 2008 Google Summer of Code. If you are a student who is interested, you should definitely get in touch with Matthew Burke and Brian McCallister to discuss your ideas. Who knows, this could be your destiny?

This is gonna be great

Lua atop Apache could make for a very sweet development platform for web applications, both large and small.

• Lua is simpler than other scripting languages used for web development, making it easy to pick-up. This is exemplified by the use of tables as a universal data structure (like PHP Arrays, but unlike Python or Ruby).
• Lua has several commonalities with JavaScript, like first-class functions, closures, and prototype-based object orientation. Yet it steps beyond most languages with proper tail calls and coroutines.
• There is a fairly clean slate to start with, meaning it doesn’t carry the baggage of hundreds of procedural methods like PHP, or code mixed into HTML templates. APIs can be nicely organized and designed for simplicity (i.e. ColdFusion’s DateFormat and TimeFormat make it easier to reason about date formatting than Ruby or PHP’s methods).
• Apache’s efficient threading modules combined with Lua’s low-overhead and thread-safety make for a very performant platform. That means it is able to handle a load of traffic without a huge hardware investment.
• Deploying with an Apache module is often the preferred method, as opposed to more complicated reverse proxy setups or FastCGI. For ease of deployment, this is an advantage over the popular Ruby platform, which has no true mod_ruby.
• The mod_wombat project was started by Apache Software Foundation members, is hosted with Apache, and has their backing as a supported module for Apache users.

Ideas

If you are a student joining the GSoC, you will need to come up with your own proposal. I’m not a student, so I don’t qualify, but I will post here a few of the basic ideas that I believe are of general consensus.

Simplify installation

For mod_wombat to become a platform of choice, it needs to be dead-simple to deploy, whether as a development environment or a production server. This would be served by relying only on those modules included with the Apache distribution.

There has been a desire to remove the dependency on libapreg2, which is used to parse HTTP cookies, query-strings and POST data. The required functionality would need to be incorporated into mod_wombat directly.

Tighter integration with Apache HTTP Server 2.2

There is a lot that can be done to further integrate Lua with Apache, whether using Lua to configure Apache, or to pull Apache functionality into Lua.

Perhaps the most significant and obvious, would be integration with Apache’s Database Framework. With DBD, the database drivers for your web application are bundled with Apache, and Apache manages a pool of database connections in an intelligent way appropriate for the MPM being used. With mod_wombat, Lua could be the first language to really take advantage of this feature, new to Apache 2.2.

Write something with it

What mod_wombat provides is an API to higher-level web frameworks and applications. It’s hard to know how those APIs should be written without using them. Building a small project atop mod_wombat could go a long way in designing a concise and friendly API.

Preferably using some sort of code standards.

Resources

If you choose to partake in this endeavor, there a few things you must know.

• Working knowledge of ANSI C, perhaps C: A Reference Manual will help.
• Programming in Lua is an excellent resource for both the Lua programming language and how to interface it with C.
• The Apache Modules Book goes over Apache’s architecture and writing Modules for it, including a chapter on DBD.
• A willingness to work with autoconf and related build tools. There is but one book dedicated to the subject, and the online version is more up-to-date.
• Familiarity with existing web development environments and experience with database systems.
• An understanding of just how Google Summer of Code works.
• Go through Brian’s slides and download the source code from Subversion to familiarize yourself with mod_wombat.

And that’s all there’s to it. Ready to get coding?

Follow-up

Maxime Petazzoni has accepted the role of working on mod_wombat for GSoC this year. See the Apache mailing list.

We haven’t heard a lot about Lua on the web, even though there are a number of developers working with Lua on the server-side. Lets take a brief look.

The Kepler Project

Kepler is a “web development platform” named after astronomer Johannes Kepler. It looks to be the most ambitious project of the bunch. Kepler is written as a number of modules that fit together, and includes its’ own web server named Xavante.

There is also an endeavor to build WSAPI, in similar fashion to Python’s WSGI interface, that support pretty much any web server and configuration (CGI, FastCGI, SCGI, etc, etc.)

Nanoki

When I joined to Kepler mailing list, “Petite Abeille” was the first person to respond. He has been developing a Wiki called Nanoki.

However, it is not built on top of Kepler. Instead there is a small built-in web server or will run atop the Unix tcp command. All the source code is released under a MIT license, and is instructive in building a light, focussed web application vs. the broad scope of Kepler.

mod_wombat

Brian McCallister spear-headed a project to embed Lua in an Apache HTTP Server module. Going through Brian’s slides is quite inspiring as to just how good a fit this is. Apache does all the heavy-lifting, such as providing a fully multi-threaded “worker MPM” (multi-processing module) and a portable runtime (APR) environment. Lua is a thread-safe language, with “share-nothing” Lua states, so it fits right in and is super-efficient.

Skimming through The Apache Modules Book is even more inspiring, as you can see the potential of mod_wombat if it took advantage of Apache’s database connection pooling (DBD) and the various other facilities of Apache HTTP Server.

Wombat is still a little rough around the edges, but you can find the Apache-licensed source code at: http://svn.apache.org/repos/asf/httpd/mod_wombat/trunk.

Building

First, you need to have Apple’s Developer Tools installed. They should be your Mac OS X disc, under Optional Installs -> Xcode Tools. Run the XcodeTools package to install. You can also download Xcode if you sign up for a free ADC account (but note: they are large!).

Next, download Lua source code and unpack the archive in Finder. Or you can use Terminal to download the current release (5.1.2) to your Downloads folder (or a suitable location of your choice):

cd Downloads curl -O http://www.lua.org/ftp/lua-5.1.2.tar.gz tar xzvf lua-5.1.2.tar.gz cd lua-5.1.2

Either way, you need Terminal (from Application/Utilities) to do the rest. Make sure you are in the lua-5.1.2/ folder, and type: make macosx

Several lines should scroll by. On Leopard you will see some deprecated warnings in loadlib.c. Don’t worry about it. To make sure everything is okay, run: make test You should see “Hello world, from Lua 5.1!”

Installing

It is possible to run the Lua interpreter from right here, but let’s install it the rest of the way. For this we will need to run “make install”. By default Lua installs to /usr. This will work, but it’s recommended to install under /usr/local.

So from the lua-5.1.2/ folder, run: sudo make install INSTALL_TOP=/usr/local and provide your password.

It appears that Leopard ships with /usr/local/bin in your path. You can check by running: (make sure PATH is uppercase) env | grep PATH

If you don’t see it there, you need to modify your .profile file. pico ~/.profile

and include:

export PATH="/usr/local/bin:/usr/local/sbin:$PATH" export MANPATH="/usr/local/man:$MANPATH"

If you are using TextMate, and will be installing the Lua bundle later, you may also want to include:

export SVN_EDITOR="mate -w" export LC_CTYPE=en_US.UTF-8

With pico, press Ctrl-X followed by Y to exit and save.

The changes will take affect when you open a new Terminal window.

Running

With Lua installed in your path, you can run it in Terminal from any folder. Just type: lua

This brings up the interactive interpreter. You can type in Lua code: print "Hi" = 2 + 3

Press Ctrl-C to exit when you’re done.

Now that Lua is installed, you could remove the Downloads/lua-5.1.2 folder. But you may want to check out the test/ folder for some example code. You can run these examples from within the lua-5.1.2/test/ folder like this:

lua factorial.lua

A local copy of the Reference Manual can be found under doc/manual.html.

TextMate

If you are using TextMate, there is a Lua bundle to give it color syntax highlighting and a few snippets. Unfortunately the Lua bundle isn’t included by default. You can either use GetBundle, or you can grab it with the command line as follows.

The bundles are stored in a Subversion repository, which requires Subversion (svn) on your computer. Leopard comes with Subversion, but for Tiger or prior you need to install it. I’ve had good success with Martin Ott’s Subversion package.

As per the TextMate manual:

mkdir -p /Library/Application\ Support/TextMate/Bundles cd /Library/Application\ Support/TextMate/Bundles svn co http://svn.textmate.org/trunk/Bundles/Lua.tmbundle

You need to restart TextMate or navigate to to Bundles -> Bundle Editor -> Reload Bundles in the menu.

Files with a .lua extension will be associated with the Lua language bundle. One nice feature is that you can press Command-R to run them.

So that’s about it for getting setup. Now we just need to write some code!

Lua was started in 1993, near the same time as Matz began working on Ruby. It was designed to be a small and efficient scripting language that could easily be embedded in C/C++ on practically any platform.

Aiming for simplicity, Lua implements a single collection type called “tables”. PHP also takes this approach, with Arrays that can act as hashes (associative arrays) and standard arrays. Python uses its dictionaries (hashes) for namespaces and passing named parameters to functions. Lua does this and more, making extensive use of tables.

One of Lua’s precepts is to “provide mechanisms instead of policies.” You won’t find Ruby’s emphasis on object-oriented programming in Lua, but it still is easy enough to OOP. In fact, Lua works somewhat like the prototype system in today’s JavaScript.

First-class functions allow functions to be passed as arguments, stored in tables, and basically treated like any other value. Proper tail calls allow for recursion without stack overflows. Closures are a bit hard to explain without an example. You are free to make use of all these mechanisms, which originated in functional programming, a distinct discipline from the typical C-style of programming.

Lua isn’t alone in mixing programming paradigms, but its overall simplicity as a language makes it a good place to begin computer programming.

In 1996, Lua found its way into Dr. Dobb’s Journal and from there into adventure game Grim Fandango and many other games since the 1999 Game Developers’ Conference, including the ever-popular World of Warcraft.

Lua has grown in response to the demands of game programmers. It now posesses an incremental garbage collector to avoid long pauses. Coroutines provide programmers with co-operative multitasking. Lua’s virtual machine is register-based, making it one of the fastest interpreted languages available.

Due to a rather strict adherence to ANSI C, Lua doesn’t run multi-core out of the box. But Lua can take advantage of your OS-dependent threading code, having a fully reentrant API. Lua states isolate each thread, so scripters don’t need to concern themselves with the typical locking complexities of concurrency. Perhaps a future version of Lua 5.2 could see an optional library with OS-specific threading support.

If you want to dig deep into Lua’s history, take a look at The Evolution of Lua paper (26 pages), as was presented at the 2007 History of Programming Languages (HOPL) Conference. I will conclude with a quote from the paper:

“It is much easier to add features later than to remove them. This development process has been essential to keep the language simple, and simplicity is our most important asset. Most other qualities of Lua — speed, small size, portability — derive from its simplicity.”

And contrast it with a quote from Yukihiro “Matz” Matsumoto from Beautiful Code:

“When simpler tools are used to solve a complex problem, complexity is merely shifted to the programmer, which is really putting the cart before the horse.”

While there is validity to his statement, the beauty of Lua is how it manages to be a quite powerful language, despite its simplicity.

Adobe Lightroom won out for me. It provided enough of the Photoshop functionality (curves, etc.) that I often wouldn’t need to launch Elements. Just as important, the reviews proclaimed Lightroom to be more responsive and less of a resource hog. So what does all this have to do with Lua?

Adobe Lightroom is programmed with C/C++/Objective-C and… 40% Lua. An interpreted scripting language making up 40% of the code, and it feels more responsive and uses less resources?! That deserves a second look…

Adobe Lightroom puts Lua’s coroutines to good use, keeping the user interface responsive while images visually rotate or exports process. Coroutines are a form of “cooperative multitasking,” where the programmer controls task-switching rather then being preempted as with “real” threads.

I’ve taken a great interest in the Lua language. The more I learn, the more intrigued I am. This blog exists in order to share these findings with you. Lua is Portuguese for moon, and “lua nova” means new moon.

Welcome to Lua, welcome to the moon…