The ability to run a Lua script before the publishing run is available since version 3.1.9.

The command line/configuration interface is the same as for the XProc filter:

sp --filter myfile.lua

or

filter=myfile.lua

The Lua script is run before any rendering gets done, so the main application is probably the transformation of input data into a format that is suitable for the speedata Publisher.

You can use anything that is allowed in Lua. Additionally the publisher provides the modules csv,runtimeandxml` which contain the following entries:

Note: the API is subject to change!

csv

csv.decode(filename,parameter): loads a CSV (comma separated values) file and returns (first argument) the boolean success. If true, the second return value contains the table, if false, the second return value contains an error message (string). The value parameter is an optional table which controls the CSV input and output. You can provide the following values:

Value Description
charset If the CSV file is encoded in Latin-1, you have to set this to the value ISO-8859-1. Ask us for more character sets.
separator The value of the field separator. Defaults to a comma, but can be any character.
columns A table that has the required columns in the given order. For example {3,2,1} limits the output to the first three columns in reverse order.

Example:

csv = require("csv")
result, msg = csv.decode("myfile.csv", { charset = "ISO-8859-1", separator = ";", columns = {1,2,5} })
if not result then
    print(msg)
    os.exit(-1)
end

The table has at index 1..n the rows of the CSV file and each rows is a table in which the index 1..m is each table cell.

runtime

Value Description
projectdir A value that contains the current working directory (the one with the layout.xml and publisher.cfg)
variables A table that contains all the variables given on the command line (-v) or in the configuration file (vars=...).
run_saxon A function that calls the external Java-program saxon. It accepts three mandatory arguments (the transformation stylesheet, the input file and the output file) and an optional argument that is passed as the parameter string to saxon. The function returns a boolean value (success) and optionally a string in case of a false success value.
validate_relaxng A function that validates an XML file against a RelaxNG schema. The first argument is the XML file, the second argument the RelaxNG schema. You can use relative paths for both.
runtime = require("runtime")
ok, err = runtime.run_saxon("transformation.xsl","source.xml","data.xml","param1=value1 param2=value2")

-- stop the publishing process if an error occurs
if not ok then
    print(err)
    os.exit(-1)
end

Validation:

ok, msg = runtime.validate_relaxng("layout.xml","../schema/layoutschema-de.rng")
if not ok then
    print(msg)
    os.exit(-1)
end

xml

xml.encode_table(table): Create an XML file from a table. It returns (first argument) the boolean “success”. If false, the second return value contains an error message (string).

The table has the following structure

A comment has the form

comment = {
         _type = "comment",
         _value = "This is a comment!"
   }

and an element:

element = {
    ["_type"] = "element",
    ["_name"] = "root",
    attribute1 = "value1",
    attribute2 = "value2",
    child1,
    child2,
    child3,
    ...
}

child1, ... are strings, elements or comments.

The XML file gets written with the name data.xml

Example:

xml = require("xml")
ok, msg = xml.encode_table(tbl)
if not ok then
    print(msg)
    os.exit(-1)
end

xlsx

open(filename): loads the given Excel file (file extension .xlsx) and in case of success returns an object which can be used to access the contents of the spreadsheet. In case of an error it returns two arguments. The first argument is false and the second argument contains the error message.

Usage:

xlsx = require("xlsx")
spreadsheet, err = xlsx.open("myfile.xlsx")
if not spreadsheet then
    print(err)
    os.exit(-1)
end

The object spreadsheet contains the worksheets. The number of worksheets can be obtained by the length operator (#) and each worksheet is indexed stating from one:

numWorksheets = #spreadsheet
ws = spreadsheet[1]

The object ws can be used to get the contents of each cell. Use the object as a function call with the coordinates as the arguments. It returns the cell contents as a string. The top left cell has the coordinate (1,1), the first cell in the second row (1,2) and so on.

cell1 = ws(1,1)
cell2 = ws(1,2)

Some properties can be queried in the worksheet object:

Value Description
minrow First row that contains data
maxrow Last row that contains data
mincol First column that contains data
maxcol Last column that contains data
name Name of the worksheet
Version: 3.5.6 | Start page | Element reference | Other language: German