Plua

1. Introduction

More information on Lua can be found at Lua. (NOTE: I have no affiliation with TeCGraf or PUC-Rio)

This is a BETA software. This means that it may have some bugs. Although no damage has been observed so far, if you care about the data on your device it is advisable that you backup everything before running Plua.

THIS SOFTWARE COMES WITH ABSOLUTELY NO WARRANTY, SO USE IT AT YOUR OWN RISK. Beta versions of Plua are beeing distributed free of charge for testing. Plua can not be reverse engineered or modified in any way. To include Plua in any software collection, online or not, first contact the author for permission. No one is allowed to sell or charge for redistributing Plua.

Plua is Copyright (c) 2001 Marcio M. Andrade.

2. Operation

For example, if you type in the text field this program:
print("Result = ", 2*3) Plua will print the following in the result area:
Result = 6 The second mode also allows you to run Lua programs, but with two differences:

• The program is retrieved from a MemoPad record or a DOC file.
• The entire screen is available to display results.

In either option, a list of current available programs is displayed.

Select one program on the list and tap the Run button to run it. Plua will switch to a full screen mode and run the program. When it is finished Plua will return to the main screen. If you want avoid the automatic return to the main screen, you can add a pevent() function as the last statement of your program. If you want to stop a program before it is finished tap the Applications icon. Note that when a program is running the Power-off button will not respond.

If you do not want to run a program, tap the Back button to return to the main screen.

The button Compile is used to compile a program into a PRC file. The generated PRC is a standalone application that can be accessed like any other one in the Application Launcher. Note however, that it still needs Plua to be installed. If Plua is not installed and a compiled program is run, an error message will be displayed and the program will be aborted. Generated PRCs have a fixed icon and the program name whitout the suffix ".lua"

Note that it is not necessary to compile a program in order to run it. If you just to want to run a program from within Plua, you can use the Run button directly. The Compile button should be used only when you want to generate a standalone PRC with your program.

Preferences are accessible via Menu/Preferences in the main screen. If "Read-only mode" is checked, all attempts to open a database for writing or removing a database will be aborted, and an error message will be displayed. If "Clear output" is checked, the Clear button also clears the output area.

3. Technical notes

3.1. Compatibility

3.2. Limitations when compared to the standard Lua distribution

• The following functions of the standard I/O library (liolib) are missing: clock, debug, execute, getenv, rename, setlocale, tmpname. The date function is implemented partially (some formatting options are missing).
• There is no concept of "stdin", the standard input stream. Programs can read data from files, but not from user input. User input is restricted to pen/key events and interaction with UI components.
• Decimal is the only supported numerical base. Floating point numbers can not be expressed in exponential format, like "1e-5".
• Most of the functions in the standard mathematical library (lmathlib) require MathLib (a third-party library) to work properly.

3.3. Extensions to the standard Lua distribution

Database I/O functions:

• listdb("creator", "type"): returns a table with all databases matching the specified type and creator. Type and creator are either a 4 character string or an empty string to accept anything.
• opendb(name, mode): opens a PalmOS database. Mode can be "r" for read-only access, "r+" for read/write access, or "w" for write-only access. If mode is not read-only, the database is created if it does not exist. This function returns a handle to the open file and the number of records in the database. The handle is used as the first parameter in the other database I/O funtions.
• closedb(f): closes a database.
• openrec(f, i): opens the record with index i from an already open database f. Returns the size of the record or -1 if an error occurred.
• openrec(f, "type", id): opens the resource with specified type (4 character string) and id from an already open resource database f. Returns the size of the record or -1 if an error occurred.
• createrec(f, size): creates a new record with given size in (already open) database f. The record is added at the end of the database. Returns the index of the new record.
• deleterec(f, i): deletes the record with index i from (already open) database f. The record can not be open when it is deleted. Returns 0 if success or -1 if an error occurred.
• closerec(f): closes the current open record of (already open) database f. Returns nothing.
• resizerec(f, i, size): resizes the record with index i from (already open) database f to the specified size. If the record beeing resized is the currently open record, it is closed, resized and then reopened. Returns 0 if success or -1 if an error occurred.

• openser(name, baud [,mode]): opens an IO port using the New Serial Manager. Currently name can be either "serial0" or "ir0", to open the serial port or the infrared port respectivelly, baud is a number and the optinal mode is a string like "8N1" (the default) or "7E1". The first character is the word size (5, 6, 7 or 8), the second is the parity (N, E, or O) and the third is the number of stop bits (1 or 2). Returns a handle to the open port or nil if there was an error. Note that PalmOS does not allow more than one port open (you can open either the serial or the infrared, but not both).
• closeser(f): closes an open serial port. Returns nothing.

• pmode(): returns 4 numbers: screen width, screen height, screen depth and 1 or 0 indicating if the screen supports color.
• pclear([c]): erases the screen with the background color or with the optional c color, and moves the cursor to 0,0. Returns nothing.
• pcolor(fg [,bg]): sets the foreground color (fg) and optionally the background color (bg). Returns nothing.
• prgb(r, g, b): returns the color equivalent to the (Red,Green,Blue) components.
• ppos(): returns 2 numbers with the current x,y cursor position.
• pmoveto(x, y): moves the screen cursor to the x,y position.
• pline(x1, y1, x2, y2 [,c]): draws a line from x1,y1 to x2,y2 using the fg color or the optional c color.
• plineto(x, y [,c]): draws a line from current position to x,y using the fg color or the optional c color.
• pset(x, y [,c]): draws a pixel at position x,y using the fg color or the optional c color.
• pget(x, y): return a number with the color of pixel at position x,y.
• prect(x, y, dx, dy [,c]): draws a rectangle at x,y, extending dx,dy pixels, using the fg color or the optional c color.
• pbox(x, y, dx, dy [,c]): draws a filled rectangle at x,y, extending dx,dy pixels, using the fg color or the optional c color.
• pcircle(x, y, rx, ry [,c]): draws an ellipse centered at x,y, with rx,ry as x,y radius, using the fg color or the optional c color. Use rx=ry for a circle.
• pdisc(x, y, rx, ry [,c]): draws a filled ellipse centered at x,y, with rx,ry as x,y radius, using the fg color or the optional c color. Use rx=ry for a filled circle.
• pfont(f): sets the text font to number f. Returns two numbers with the "average" width of a character and the height of a character, both in pixels. Note that PalmOS fonts are not fixed-width fonts, so if the returned width is used in calculations, you get just an approximation.
• pheading(g): turns the graphical "turtle" to the specified heading g (in degrees). 0 points to the right, 90 points up, and so on. Returns nothing.
• pturn(g): turns the graphical "turtle" g degrees. g can be positive or negative and it is added to the current heading. Returns nothing.
• pwalk(d): draws a line from the current cursor position, with extent d and following the current "turtle" heading. The cursor is positioned at the end of the line. Returns nothing.
• popenbmp(id [,file]): searches for a bitmap resource identified by the given ID. If a file name was not specified, the search is done in all open PalmOS databases. If file was specified, the search is done only in this file. If the bitamp was found, three values are returned: a handle to the bitmap, and 2 number with its width and height in pixels. If it was not found, nil is returned.
• pdrawbmp(h): draws the bitmap associated with the handle h in the current cursor position. The cursor is advanced to the right of the bitmap. Bitmap handles can be obtained by using popenbmp(). Returns nothing.
• pclosebmp(h): cloese the bitmap associated with the handle h. Returns nothing.

• ptitle([text]): sets the title of the current form. Works only in full-screen mode. If the parameter is omited, the title is erased.
• pmenu(t): defines the menu items. Currently there is one fixed menu item that is always available: "About Plua". It is possible to define additional items by passing a table with strings to pmenu(). If a string starts with a letter followed by a colon, the letter is used as the item's shortcut.
• plabel(text): creates a label with given text in the current cursor position. The cursor is positioned to the right of the component. Returns the ID of the component or nil if it could not be created.
• pbutton(text): creates a button with given text in the current cursor position. The cursor is positioned to the right of the component. Returns the ID of the component or nil if it could not be created.
• ppbutton(text [,g]): creates a pushbutton with given text in the current cursor position. Pushbutons can be optionally placed in a given group number g. The cursor is positioned to the right of the component. Returns the ID of the component or nil if it could not be created.
• prbutton(text): creates a repeating button with given text in the current cursor position. The cursor is positioned to the right of the component. Returns the ID of the component or nil if it could not be created.
• pcheckbox(text): creates a pushbutton with given text in the current cursor position. The cursor is positioned to the right of the component. Returns the ID of the component or nil if it could not be created.
• pfield(lines, cols, max [,text [, e, u]]): creates a text field with given number of lines and columns in the current cursor position. The field will accpet at most max chars. The field is optionally initialized with the specified text. The optional parameter "e" and "u" are values indicating if the field is editable and underlined, respectively. A nil value means false, and not nil value means true. If these parameters are passed, the text parameter must also be passed. The cursor is positioned below the component. Returns the ID of the component or nil if it could not be created. For fields with more than 1 line, a scroll bar is automatically placed to the right of the field if the user enters more text than the number of lines can display.
• pfieldattr(id, e, u): sets the attributes of an existing field identified by the given ID. The next two parameters are the same as in pfield(). Returns nothing.
• psetfocus(id): sets the focus to the field identified by the given ID. Works only with text fields. Returns nothing.
• plist(lines, cols, t): creates a list with given number of lines and columns in the current cursor position. The list is filled with the elements of table t. The cursor is positioned to the right of the component. Returns the ID of the component or nil if it could not be created.
• pgettext(id): returns a string with the text of the component identified by the given ID. For labels, buttons, pushbuttons, repeating buttons and checkboxes, the text is the label of the component. For field, the the text is its current contents. For list, the text is the current selected element.
• psettext(id, text): sets the text of the component identified by the given ID. Works with buttons, pushbuttons, repeating buttons, checkboxes, lables and fields. For labels, the text is changed only if the new length is not greater than the current length. Returns nothing.
• pgetstate(id): returns a number with the state of the component identified by the given ID. For pushbuttons and checkboxes, the number is 1 if selected, 0 if not selected. For lists, the number is the index of the selected item.
• psetstate(id, n): sets the state (or index for lists) of the component identified by the given ID. Works pushbuttons, checkboxes and lists. Returns nothing.
• pnl(): positions the cursor at (x,y), where x is the leftmost position and y is below the "tallest" component of the current "line". Returns nothing.
• ptab([n]): advances the cursor 8 pixels to the right. It is useful when separating UI components on the same line. If n is specified the cursor is advanced 8*n pixels. Returns nothing.
• pdestroy(): destroys all UI components currently in the screen. Returns nothing.
• palert(text): opens a information dialog with specified text. The user must press the Ok button to close the dialog. Returns nothing.
• pconfirm(text): opens a confirmation dialog with specified text. The user must press either the Yes or the No button to close the dialog. Returns 1 if Yes was pressed or nil if No was pressed.
• pinput([text [,initial]]): opens an input dialog with an optional text as title. A second optional parameter defines the initial value of the input. The user can enter up to 255 characters of input. The user must press either the Ok or the Cancel button to close the dialog. Returns a string with the input entered if Ok was pressed, or nil if Cancel was pressed.
• pselectdate([text [, y, m, d]]): opens the PalmOS day selection dialog. Text is an optional title, and y/m/d are the year, month and day initially shown by the dialog. Returns three numbers with the selected year, month and day, in this order, or nil if Cancel was pressed.
• pselecttime([text [, h, m]]): opens the PalmOS time selection dialog. Text is an optional title, and h and m are the hour and minute initially shown by the dialog. Returns two numbers with the selected hour and minute, in this order, or nil if Cancel was pressed.
• pgsi(): creates a Graffiti State Indicator in the current cursor position. Works only in full screen mode. Returns nothing.

• pevent(): blocks until an event is generated. Events can be a hard button press, a pen event, a UI control selection or whether there is IO pending. The first returned value is always the event type: penDown, penUp, penMove, keyDown, ctlSelect, ctlRepeat, lstSelect, menuSelect, ioPending (these constants are already pre-defined). For pen events, 2 more number are returned: the x,y cursor position. For key events, 1 more number is returned: the key code. For UI control events, 2 more number are returned: the control ID and the control state (1=selected, 0=not selected). For list events, 2 more number are returned: the list ID and the selected element. For menu event, the index of the menu item (starting with 1) is also returned. The IO pending event (nothing else is returned) is a efficient way for a program to wait for IO without polling (this event will only be sent if openser() was called before and data has arrived).

• pbeep(n): plays the system sound identified by the number n. Returns nothing.
• psound(freq,len [,amp]): plays a tone with frequency freq (in Hz), duration len (in millisenconds), and optionally volume amp (0-64). Returns nothing.

• psleep(n): pauses the execution for n seconds.

• _VERSION: a string with the Lua version number (this is a standard Lua feature).
• _PLUA_VERSION: a string with the Plua version number.
• _OS_VERSION: a string with the PalmOS version number.

4. A small tutorial

• Comments start with -- and extend to the end of line.
• Statements are not ended by ";"
• Variables do not need to be declared.
• Variables are not typed, but values are. Values can be numbers, strings, functions or tables. Values are automatically converted to the right type when possible. For example, the code 1+"2" evaluates to 3.
• String concatenation is done with the .. operator. For example, the code "abc".."def" evaluates to "abcdef".
• Multiple assignments are supported. For example, the code x,y=2,3,4 assigns 2 to x and 3 to y. Non-used values are discarded (like 4 above).
• Functions can return multiple values. For example, if function f return 2 values, they can be retrieved using x,y=f()
• You can print a list of expressions using the function print: print(123,"abc",4*5,sin(45))
• Take a look at the supplied samples.
• There is much more you can do with Lua, now take a look the docs :-)

4.1. Working with the display

The statement pline(0,0,19,19) will draw a line from position (0,0) to (19,19) and will update the current cursor position to (19,19). If the next statement is write("abc") the string "abc" will be printed starting at position (19,19) and the cursor will be placed at (19,19+d), where d is the width in pixels of string "abc" written with the current font.

Besides the cursor position, Plua also stores the current foregroung color, the current background color and the current font. The following example writes the string "Plua" in red over black with the bold font:
pcolor(prgb(255,0,0), prgb(0,0,0))
pfont(1) print("Plua")
Plua works with 1-bit monochromatic displays, 2-bit or 4-bit grayscale displays and with 8-bit color displays. The foreground and background colors are mapped to the closest grayscale tone in your device, if color is not available. You can find the display properties of your device by calling the pmode() function:
width, height, depth, hasColor = pmode()
print(width, height, depth, hasColor)
Width and height are the display dimensions in pixels. Depth is 1, 2, 4, or 8, and hasColor is 1 if the display supports color, or 0 otherwise. On color devices, you can use the prgb() function to get the index of a color given its red, green and blue components. The example below will print 125 on 8-bit color device using the standard color pallete.
red = prgb(255,0,0)
print(red)
Plua supports a Logo-like "turtle" pointer. Using pwalk() and pturn() you can walk around the display drawing lines. The example below clears the display, positions the cursor at the middle of the display and draws a small expiral.
pclear() w,h = pmode() pmoveto(w/2,h/2)
for d = 1,20,1 do
pwalk(d) pturn(-40)
end
The following example shows how to draw a bitmap. 11000 is the resource ID of the "Taxi" bitmap stored in Palm ROMs.
pclear()
bmp = popenbmp(11000)
pdrawbmp(bmp)
pclosebmp(bmp)
One final note on the display: writing at the end of a line does not make it to wrap, and writing at bottom line does not make the display to scroll up.

4.2. Working with User Interface

NOTE: since this program enters an infinite loop, the only way to stop it is to tap the Applications icon.

The example below shows pinput(), palert() and pconfirm().
s = pinput("Write something")
if s ~= nil then
palert("You wrote "..s)
end

if pconfirm("Are you tired ?") then
print("Me too")
else
print("Me neither")
end
In order to set a menu for your application, you can use pmenu() as following.
pmenu({"O:Open", "Preferences", "-", "Q:Quit"})
The menu will have 4 items: the fixed "About Plua" item, a fixed separator, an "Open" item with "O" as shortcut, a "Preferences" item with no shortcut, a separator, and a "Quit" item with "Q" as shortcut. Limitations: currently pmenu() will work ONLY on PalmOS 3.5 or greater (earlier versions do not allow dynamic menu configuration), it works only in full-screen mode, and it is not possible to define more than one menu in the same menu bar. pmenu() can be called any time, and it will replace the current menu with the new one.

When one of the menu items is selected (except the About item), a menuSelect event is returned by pevent(). In the example above, if "Preferences" was selected, pevent() would return menuSelect and the number 2, meaning that the second user defined item was selected.

4.3. Working with file I/O

Regular files are implemented using the File Stream API of PalmOS, so Lua programs can open, create, read from and write to files normaly, without knowing about database types or database creators. The following example shows this:
f = openfile("MyOutput", "w")
write(f, "This is being written to a PalmOS stream database")
closefile(f)
The database MyOutput is open for writting (it is created if it does not exist), a string is written to it, and it is closed.

There are also functions that allow a program to manipulate a PalmOS database directly, if desired. They were listed in the section "Extensions to the standard Lua distribution" above. The example below iterates through all MemoPad records and prints the first line of each record:
f,n = opendb("MemoDB", "r")
for i = 0,n-1,1 do
openrec(f, i)
s = read(f, "*l")
print(s)
end
closedb(f)
If the open database is a resource database, the second form of the openrec() function can be used. The example below prints the version resource of the MemoPad application:
f = opendb("Memo Pad", "r")
openrec(f, "tver", 1)
s = read(f, "*l")
print(s)
closedb(f)
The read() function belongs to the standard I/O Lua library. The I/O functions work with both stream files and regular databases. With regular databases, each record works like a sub-file, that is, they can be read from the begining to the end, when an EOF conditions is signaled. In order to continue to read the database, openrec() must be called to open the next record and so on.

The available modes for opendb() are:

• "r": opens the database for reading only.
• "r+": opens the database for reading and writing. The database is created if it does not exist. In this case, the creator is inherited from Plua and the type is always 'data'.
• "w": opens the database for writing only. The database is created if it does not exist. In this case, the creator is inherited from Plua and the type is always 'data'.

4.4. Working with serial I/O