Lua Scripting
The embedded Lua scripting engine allows users to extend SjASMPlus' functionality.
Use LUA and ENDLUA pseudo-ops to insert Lua code inline.
LUA
print ("Hello World!")
ENDLUATo include another LUA script in the first pass(!) use:
Using pseudo-ops LUA and ENDLUA you can insert Lua scripts inline.
The parameter is optional. It may be:
PASS1 - interpret Lua script in first pass only.
PASS2 - interpret Lua script in second pass only.
PASS3 - interpret Lua script in third pass only. By default.
ALLPASS - interpret Lua script in all passes.
Needed if you generate Z80 code from Lua.
LUA
-- some comments
print "Hi there! This is Lua!"
ENDLUA
; some code now:
LUA ALLPASS
_pl("LABEL LD A,10")
_pc("RET")
ENDLUATo include another LUA script in the first pass(!) use:
If the file cannot be found in the current directory (the current directory is the directory the current file comes from) the file will be searched for in the directories specified at the command line. When angle brackets are used, the command line directories are searched before the current directory.
INCLUDELUA <mylibrary1.lua>
INCLUDELUA mylibrary2.lua
INCLUDELUA "library_for_zx.lua"From Lua you can control some variables and use functions of the compiler. Complete list:
[integer] _c("expression")
Calculate expression using calculator of the compiler. Example: val = _c("SOMELABEL+12").
[void] _pc("code")
Parse string of Z80 assembly. Example: _pc("ADD A,B")
[void] _pl("label code")
Parse line of Z80 assembly. Example: _pc("SOMELABEL ADD A,B")
[integer] sj.calc("expression")
See _c
[void] sj.parse_code("label")
See _pc
[void] sj.parse_line("label code")
See _pl
[void] sj.error("message")
Print error message.
[void] sj.warning("message")
Print warning message.
[boolean] sj.file_exists("message")
Check for file exists.
[string] sj.get_define("name")
Get define value.
[boolean] sj.insert_define("name", "value")
Add new define.
[integer] sj.get_label("name")
Get label address.
[boolean] sj.insert_label("name", address)
Add new label.
[integer] sj.current_address
Variable. Current address.
[integer] sj.error_count
Variable. Count of Errors.
[integer] sj.warning_count
Variable. Count of Warnings.
[void] sj.exit(errorcode)
Shutdown the compiler.
[void] sj.add_byte(byte)
Add byte to output (or to memory) and increase sj.current_address
[void] sj.add_word(word)
Add word to output (or to memory) and twice increase sj.current_address
[integer] sj.get_byte(address)
Get byte from memory. Work only in real device emulation mode.
[integer] sj.get_word(address)
Get word from memory. Work only in real device emulation mode.
[string] sj.get_device()
Return current emulating device's identifier. Returns "NONE" if no emulation mode.
[boolean] sj.set_device("id")
Set current emulating device's identifier. Returns false if no device found.
[boolean] sj.set_page(number)
Set page with number "number" to the current slot. Works as pseudo-op PAGE.
[boolean] sj.set_slot(number)
Set current slot with number "number". Works as pseudo-op SLOT.
[void] sj.shellexec("programname")
See pseudo-op SHELLEXEC.
[void] zx.trdimage_create("filename")
Creates emptry TRD image file.
[void] zx.trdimage_add_file("filename", "somenameC", startaddress, length)
Save block of memory to TRD image file. Work only in real device emulation mode.
[void] zx.save_snapshot_sna("filename.sna", startaddressofprogram)
Save snapshot of memory in SNA format. Work only in real device emulation mode and only for ZXSPECTRUM48 and ZXSPECTRUM128..
lpack.c
a Lua library for packing and unpacking binary data
by Luiz Henrique de Figueiredo <lhf(at)tecgraf.puc-rio.br>
The library adds two functions to the string library: string.pack and string.unpack.
pack is called as follows: string.pack(F,x1,x2,...), where F is a string describing how the values x1, x2, ... are to be interpreted and formatted. Each letter in the format string F consumes one of the given values. Only values of type number or string are accepted. pack returns a (binary) string containing the values packed as described in F. The letter codes understood by pack are listed in lpack.c (they are inspired by Perl's codes but are not the same). Numbers following letter codes in F indicate repetitions.
unpack is called as follows: string.unpack(s,F,[init]), where s is a (binary) string containing data packed as if by pack, F is a format string describing what is to be read from s, and the optional init marks where in s to begin reading the values. unpack returns one value per letter in F until F or s is exhausted (the letters codes are the same as for pack, except that numbers following 'A' are interpreted as the number of characters to read into the string, not as repetitions).
The first value returned by unpack is the next unread position in s, which can be used as the init position in a subsequent call to unpack. This allows you to unpack values in a loop or in several steps. If the position returned by unpack is beyond the end of s, then s has been exhausted; any calls to unpack starting beyond the end of s will always return nil values.
List of types for F string:
z
zero-terminated string
p
string preceded by length byte
P
string preceded by length word
a
string preceded by length size_t
A
string
f
float
d
double
n
Lua number
c
char
b
byte = unsigned char
h
short = word
H
unsigned short
i
int
I
unsigned int
l
long
L
unsigned long
<
little endian
>
big endian
=
native endian
LUA PASS1
v = 1
ENDLUA
LUA PASS2
print (v)
-- console output: 1
v++
ENDLUA
LUA PASS3
print (v)
-- console output: 2
ENDLUA
LUA ALLPASS
_pl("ClearScreen LD (.savesp+1),SP")
_pc("LD SP,16384+6144")
_pc("LD HL,0")
for i = 32768, 38912, 2 do
_pc("PUSH HL")
end
_pl(".savesp: LD SP,0")
_pc("RET")
ENDLUA
LUA
function savetape_mytype(filename, startaddress)
local fp
fp = assert(io.open(fname, "wb"))
for i = 16384, 32767, 4 do
assert(fp:write( string.pack("bbbb",
sj.get_byte(i),
sj.get_byte(i+1),
sj.get_byte(i+2),
sj.get_byte(i+3)) ))
end
assert(fp:flush())
assert(fp:close())
end
ENDLUA
;somewhere in your program
LUA
savetape_mytype("tapefiles/myprogram.tape", _c("StartGameLabel"))
ENDLUA
LUA
-- Function reads number from file <fname>, increases it, creates define "BUILD" with the number and saves the number to <fname>.
-- With this function you can control count of compilations.
function increase_build(fname)
local fp
local build
fp = assert(io.open(fname, "rb"))
build = tonumber(fp:read("*all"))
assert(fp:close())
if type(build) == "nil" then
build = 0
end
build = build + 1;
sj.insert_define("BUILD", build)
fp = assert(io.open(fname, "wb"))
assert(fp:write( build ))
assert(fp:flush())
assert(fp:close())
end
-- Before using you must create empty file "build.txt"!
increase_build("build.txt")
-- Creates define "TIME" with current time
sj.insert_define("TIME", '"' .. os.date("%Y-%m-%d %H:%M:%S") .. '"')
ENDLUA
; print to console our time and build number
DISPLAY "Build time: ", TIME
DISPLAY "Build number: ", /D, BUILD