title logo

by

Gavin Wraith

contents forward

Chapter 1

introduction

My aim with these pages is to teach the elements of programming in RiscLua, a dialect of the scripting language, lua, which is specialized to RISC OS. They are in no way a substitute for the manual. From time to time they will be enlarged or updated; so keep checking back.

For viewing these pages you get better results with browsers, such as NetSurf, that can interpret a reasonable amount of CSS1. No Javascript is used.

why not Basic?

It has been traditional to use Basic to demonstrate programming ideas, because it is already built into the RISC OS ROMs. In the early days of Acorn this made good sense, because memory constraints prevented the implementation of more modern programming languages. The chief drawback nowadays of Basic as a vehicle for learning about programming is that it misses out on ideas that have been accepted as central to programming many decades ago, simply because those ideas were developed long after Basic was born (1964). About twenty years ago, so-called scripting languages started to become popular. These languages were originally intended as a sort of glue for binding applications together. They let you accomplish a lot of work for very little effort. The languages Lua, Perl, Python, Ruby and Tcl are leading examples today. Lua is probably the fastest among them (a contentious matter which depends on which mix of benchmarks you take), but what is more important for our purposes is that it is the smallest, and has the simplest syntax. Different languages are designed for different purposes, so comparisons must always be taken with a pinch of salt.

Lua has its origins in a need for a simple data description format for surveyors working for Petrobras, the Brazilian state oil company. They were not expected to have any programming skills. What has been unique about the evolution of Lua has been its founders' determination to keep it simple. That has made it an appropriate language for beginners. It is also one of the most popular languages in the commercial games programming community; knowing Lua has become a marketable skill. In August 2007 Lua rose for the first time into the ranks of the top 20 most popular programming languages, coming into the 15-th place, ahead of Ada and Fortran. You can see the current rankings at TIOBE. RiscLua differs from standard Lua in certain minor particulars.

what skills are prerequisite?

I assume that you know how to use a text editor, such as Edit, StrongEd or Zap, and that you know how to create, edit and save text files. You should know how to change a file's type. You should know that RISC OS filing systems are hierarchical, and understand the difference between a file's pathname (which specifies where in the directory hierarchy it lives) and its leafname (which only distinguishes it from other objects in the same directory).

do I need to know any Basic?

For certain notions that would help. For others it could be a hindrance. For the sake of those who do have prior experience of Basic I will at times be drawing attention to the ways in which Lua and Basic differ. In any case, the programming ideas that Basic does not cater for will be the ones on which I will be aiming the spotlight.

Typographic conventions

We will use a monospaced font for Lua code:

print "Hello World"
and an italic font for metalanguage syntax:
print stringliteral
which is used for describing the syntax of the language.
resources

The version of RiscLua treated here is version 5.20. It is based on Lua version 5.2. A reference manual for Lua 5.2 is supplied inside the RiscLua application, !lua. It is available online at http://www.lua.org/manual/. It is available at small cost in printed form, ISBN 85-903798-3-3. There is also an excellent book, Programming in Lua, by Roberto Ierusalimschy, ISBN 85-903798-2-5, which contains both elementary and advanced material. I recommend it to anybody interested in programming, whatever language they use. There is a StrongHelp manual that gives details about RiscLua, albeit tersely. At various points you will need to consult these resources, to find out about aspects of standard Lua not covered here, and to find out about the contents of Lua's standard libraries. It would be sensible, for example, to look up in the reference manual the precise details about the arguments and return values of functions in the standard libraries, as these functions appear in the examples given later. It is not the role of this work to supply every detail but to give an overall picture. Too much too soon is more likely to be a distraction.

setting up

little lualogoLua filetype icon Copy the application !lua to somewhere appropriate on your hard disc. When the !lua application is booted (this happens when you first click on it or when the filer first sees it) it will create a new filetype called Lua (18C).

running Lua

We present four ways of running Lua programs.

In immediate mode

Just like Basic, Lua can be used in immediate mode for simple calculations. Open a taskwindow by pressing CTRL-F12. The command  lua at the * prompt will give

*lua
Lua 5.1.3 Copyright (C) 1994-2006 Lua.org, PUC-Rio
>
The  >  prompt shows that Lua is expecting input.
> print (0x50)
80
We have entered a statement to output the value of the expression 0x50. The prefix 0x is used to indicate hexadecimal notation for numbers. The equivalent Basic is
*Basic
ARM BBC BASIC V version 1.37 (C) Acorn 1989

Starting with 651516 bytes free

>PRINT &50
        80
Whereas Basic uses upper case letters for built-in words, Lua tends to use lowercase, or uppercase words preceded by an underscore. Note that, in Lua, number arguments to  print must be in parentheses. In Basic's immediate mode you must enter a complete statement on a single line. In Lua's immediate mode if you enter an incomplete statement the prompt will change to  >> , to remind you that more is needed.
> print (
>> 0x50)
80
You can alter Lua's prompt to suit your own tastes:
> _PROMPT = "ok then:"
ok then:
The default value of the variable _PROMPT is ">". You can alter the second prompt too:
ok then: _PROMPT2 = "finished?"
ok then: print (
finished? 0x50)
80
We have not made very explicit what we mean by an incomplete statement. Indeed, we have not defined what a statement is yet.
from the desktop

To run a Lua (or Basic) program, write it in an editor, save it with filetype Lua (Basic), and doubleclick on its icon.

running manTo run a Lua (Basic) file in a taskwindow, which is often more convenient, you can use !TaskW. First run the !TaskW application, so that its running man icon appears on the iconbar, and then drag the Lua (Basic) program's icon onto the running man. Output from the program will now appear in a taskwindow, from where you can save it if necessary.

from StrongED

If you have version 4.67 of StrongED or higher there is a way of running certain kinds of Lua programs that you may find particularly convenient. You may need first to check your version of StrongED. If your version is 4.68xx look at the file 

!StrongED.Defaults.Tools.!ScriptSED.Tools.Despatch
by SHIFT-doubleclicking its icon. About 16 lines down there should be a section commented as 
| Set script language if it's a known filetype
The section should contain the line
If "<StrongED$Script_Filetype>" = "18C" Then
Set StrongED$Script_Language "lua"
If it does not, add this line, with no line breaks, into the section and resave the file. In the directory 
!StrongED.Defaults.Tools.!ScriptSED.Languages
there should be an Obey file called  lua . If not, create one, containing the single line
do lua <StrongED$Script_Script>
<StrongED$Script_Infile> >
<StrongED$Script_Outfile>
If your version of StrongED is 4.67xx look at the Obey file  !StrongED.Defaults.Tools.DoScript . This also should contain the line
If "<StrongED$Script_Filetype>" = "18C" Then
Set StrongED$Script_Language "lua"
in the section 
| Set script language if it's a known filetype
Again if it does not, add it in, with no line breaks in it. Further down, in the section
| Now run the script using the correct syntax
for the language specified
there should be a line, with no line breaks,
If "<StrongED$Script_Language>" = "lua"  Then
lua  <StrongED$Script_Script>
<StrongED$Script_Infile> >
<StrongED$Script_Outfile>
Again, add it in with no line breaks, if it is not there.

Note the apply icon among the smarticons along the top of a StrongED window.Once !lua has been booted you can make a Lua program manipulate text in a StrongED window. You can do this either by shift-dragging or by control-dragging the icon of the file containing the program onto the apply icon. Shift dragging replaces the contents of the window with the output of the Lua program (so that the original content is lost - it can be recovered using the Undo button). Control-dragging opens a new StrongED window into which the output goes. Shift-control-dragging will cause the Lua program to operate on all the currently open StrongED windows, replacing each by its output - useful for mailmerging. For these things to work the Lua program must either be in a file of type Lua or have

#! lua
as its first line. The program must be written to take its input from the file named in the expression arg[1] and must write to the standard output (as the print command does).

Here, for example, is a program to strip out all lines containing the word sport :

      #! lua
      for line in io.lines(arg[1]) do
        if not line:match "sport" then
         print(line)
        end -- if
      end -- for
Look up io.lines and string.match in the reference manual.
using Obey and TaskObey files

Obey files are RISC OS's way of running any sort of program that takes command line arguments (TaskObey files if you want it to run in a taskwindow). Applications use their specially named !Run files for this purpose. Once !lua has been filerbooted the command needed to run a Lua program to act on, say a text file, is

*lua <progpathname> <textfilepathname>
Some of the example programs we will be looking at will be in the form needed for using with StrongED 4.67. If you do not have StrongED then you will need to make a TaskObey file instead, with the appropriate command. Running the program then amounts to doubleclicking the TaskObey file. The output will appear in a taskwindow instead of in a StrongED window. So long as the output does not involve control characters, the results should look the same.
the lua virtual machine

What happens when a RiscLua program is run? First, the textual program is compiled into a sequence of 32-bit instructions for an imaginary processor, the Lua virtual machine. Then this virtual machine executes the instructions. You can convert the textual program, say  myprog , into this intermediate form, with a command such as 

luac -o myprog/vm myprog
which will produce a data file  myprog/vm  containing the virtual machine instructions. You can use either  myprog  or  myprog/vm  for running your program. To see a disassembly of the intermediate code run the application  !DisAsmLua  and drag either file to its iconbar icon. Using the intermediate code gives a small gain in time, because the parsing and compiling stages are already done, but for editing and debugging one has to use the textual source of the program.
contents forward