The contents of LPU command files are interpreted line by line. The first character (respectively the first visible character) tells LPU which kind of information is contained:
defines the start (and name) of a new procedure. The procedure continues up to the begin of the next procedure or the end of the current source file.
A procedure is called with the command `.do' and may be left at any time with the command `.return'.
defines a label within a program. This label may be used as the target for a branch instruction.
A label is always local to the procedure in which it is declared (the main program can be seen as a normal procedure with an implicit name).
The following dot commands are currently defined:
defines a new reference point on the current label. By default, the reference point is (0,0), which is the top left corner of the label.
The `.base' command moves the reference point horizontally by XPOS and vertically by YPOS DOT.
defines margins for the current window. The four values TOP, BOTTOM, LEFT and RIGHT set the values for the margins as DOT or UNIT values.
sets the default adjustment for text to `centered'. This command only has an effect on quoted lines and the command `.text'.
clears the current error number, which will also reset the error condition for the program.
disables single step mode.
positions the cursor to the leftmost position at the current vertical position. This is horizontal offset `0', or the amount of the left margin of the last `.border' command, whichever is greater.
is identical to the command `.text', but the text is always centered.
All commands that begin with `.db' are database commands. These will be described in detail in the section database support
evaluates all given expressions and prints them in an implicit format to STDERR, dependent on the type of the expression. Finally, a newline is emitted.
This command can be used to send messages to the user, or for debugging purposes.
defines a new color.
INK-NAME is a unique name for the new color. The format of INKDEF is:
( [cVALUE] [mVALUE] [yVALUE] [kVALUE] )
where VALUE is a percentage between `0' and `100'. `c', `m', `y' and `k' represent the color components `cyan', `magenta', `yellow' and `black'.
Missing color components are counted with `0' percent.
Alternatively, a predefined color may be specified in the form `@INK-NAME', where `INK-NAME' is the name of an already defined color.
defines a new pen with the unique name PEN-NAME. The format of PENDEF is:
linewidth
Alternatively, a predefined pen may be specified in the form `@PEN-NAME', where `PEN-NAME' is the name of an already defined pen.
defines a new style with the unique name STYLE-NAME. The format of STYLEDEF is:
basename size { attr }
where `basename' is the name of the font family, `size' is the font size in points, and `attr' is a list of any out of the following attribute flags:
Alternatively, a predefined style may be specified in the form `@STYLE-NAME', where `STYLE-NAME' is the name of an already defined style.
calls a procedure with the name `PROC-NAME'.
After returning from this procedure, execution continues with the next instruction behind this command. The return-code from the called procedure can be accessed afterwards by the system variable `$rc'.
Optionally, any number of parameters may be specified behind the procedure name. Within the called procedure, the system function `$parcnt' tells how many parameters were specified, and the system function `$param(PARNR)' can be used to access the parameter `PARNR' (where PARNR is in the range `1' to `$parcnt').
`$param(0)' contains the name of the currently executing procedure.
flushes all pending output to the current form, ejects it (if it is a sheet of paper) and prepares a new form.
The next `.label' commands starts on a new form. By default, the same form type is used, but after the `.eject' and before the first `.label', a new form type may be selected if necessary, using the `.form' command.
All commands that begin with `.eps' are related to eps file handling and will be described in detail in section Support for eps files.
stops the execution of the program and leaves LPU. The `MESSAGE' is printed to STDERR, and LPU's return-code is `9'.
evaluates the expression `EXPR' and stops the execution of the program and leaves LPU if the result is `true' (where `true' is any numerical value not equal to zero).
The `MESSAGE' is printed to STDERR, and LPU's return-code is `9'.
selects the given form type.
The `ID' must have been declared in the TAB-file within a `form' command.
draws a thin frame around the current window.
draws a rectangular box at the current cursor position (or at (XPOS, YPOS), if the `@' option is given), with a width of WIDTH and a height of HEIGHT DOT.
The option `.pen PENDEF' selects a new pen type. Without this option, the current pen is used.
The option `.ink INKDEF' selects a different drawing ink.
The option `.fill' tells LPU to fill the box with the selected color and the selected fill pattern.
The options `.dashed' and `.dotted' - or the combination of them - select one of the predefined line styles `solid' (which is the default), `dashed', `dotted' or `dashed dotted'.
draws a circle with the center at the current cursor position ( or at (XPOS, YPOS), if the `@' option is given), and a radius RAD.
The option `.pen PENDEF' selects a new pen type. Without this option, the current pen is used.
The option `.ink INKDEF' selects a different drawing ink.
The option `.fill' tells LPU to fill the circle with the selected color and the selected fill pattern.
The options `.dashed' and `.dotted' - or the combination of them - select one of the predefined line styles `solid' (which is the default), `dashed', `dotted' or `dashed dotted'.
draws a line with a relative endpoint (XOFF, YOFF) from the current cursor position (or from (XPOS, YPOS), if the `@' option is given).
The option `.pen PENDEF' selects a new pen type. Without this option, the current pen is used.
The option `.ink INKDEF' selects a different drawing ink.
The options `.dashed' and `.dotted' - or the combination of them - select one of the predefined line styles `solid' (which is the default), `dashed', `dotted' or `dashed dotted'.
unconditionally jumps to the given `LABEL'. The label must be found within the context of the current procedure.
draws a horizontal line at the current vertical position, with a length of `WIDTH', which is a DOT or UNIT value.
The option `.pen PENDEF' selects a new pen type. Without this option, the current pen is used.
The options `.left', `.right' and `.center' specify, where on the label the line will be drawn.
positions the cursor in the top left corner of the current window. If a top or left margin is given, then the cursor is set to this offset, else to the value `0'.
moves the cursor WIDTH DOTs to the right. The vertical position is not changed. If WIDTH is negative, the cursor is moved abs(WIDTH) DOTs to the left.
evaluates the expression `EXPR', which has to be of type `integer'.
If the result is `true' (any value not equal to zero), the command `STATEMENT' will be executed, else it will be ignored, and execution continues with the next instruction.
At this time, only `goto', `do', `return ' and `exit' are allowed as a replacement for `STATEMENT'.
selects a new color. The format of INKDEF is defined at the `.defink' command.
prints the `PROMPT' to STDERR, then reads a line (terminated by ENTER) from stdin and assigns it to variable `VAR-NAME'.
By default, the entered data is stored as a string, but if the `VAR-NAME' is preceded with a `#', the input is treated as a number. If it is no valid number, then an error message is printed to STDERR, and the input must be repeated.
this selects the first (after a `.form' or `.eject' command) or next label on the current form. If the parameter `ID' is given, the next label with this id is selected. If `=' is given instead, the next label must be of the same type as the current label.
If no labels of the requested type are left on the current form, the form is `ejected' and work continues on a new form.
This command defines the whole surface of the selected label as the new output area. No margins are set, and the cursor is positioned in the top left corner of the label.
sets the default adjustment for text to `left adjusted'. This command only has an effect on quoted lines and the command `.text'.
evaluates the expression `EXPR' and assigns the result to the variable `VAR'.
The variable must have been defined before.
The type of the variable is set to the type of the result of the computed expression.
is identical to the command `.text', but the text is always left adjusted.
positions the cursor at the beginning of the current line, and advances it afterwards `N' rows down.
If `N' is omitted, `1' is assumed.
The height of one character of the currently selected font is taken as the height of one row.
this is identical to the `.eject' command, but the current sheet is not ejected. So the following drawing objects are placed `on top' of the old ones.
defines the action which will take place on a program error.
The default is to abort the program, which can be set using `ABORT' as the action.
With the action `CONTINUE', execution of the program continues after an error. The occurrence of an error can be check with the system variable `$errno'.
selects a new pen. The format of PENDEF is defined at the `.defpen' command.
evaluates the text expressions `TEXPR' and prints them one by one starting from the current cursor position (or, if the `@' option is given, from position (XPOS, YPOS) ).
If the `@' option is missing, then the cursor is advanced to the new position after that.
The option `.ink' allowes to select a different text color. The format of INKDEF is defined at the `.defink' command.
the procedure `PROC-NAME' is called `COUNT' times in sequence.
During the first execution of the procedure, the system function `$count' reports `1', during the second execution, it reports `2', and so forth.
requests a `minimum version' of LPU. If the current version of LPU is below that number, the program will terminate with a corresponding error message.
The version has to be specified in the form `V.R-S', where V is the version, R is the release and S is the sub-release. An actual example would be `0.9-23' (without quotation marks).
leaves the current procedure and returns control back to the calling procedure.
The expression `EXPR' is evaluated and the result is returned to the calling procedure. There, the returned value may be accessed with the system function `$rc'.
sets the default adjustment for text to `right adjusted'. This command only has an effect on quoted lines and the command `.text'.
is identical to the command `.text', but the text is always right adjusted.
moves the cursor position to a new location within the label. XPOS and YPOS are DOT or UNIT values.
switches LPU to single step mode and invokes the runtime debugger.
In this mode, before executing a command, the command and a prompt are printed on STDERR, and then the debugger waits for instructions, entered on STDIN.
An empty input (only the `ENTER' key is pressed) executes the next lpu command.
A detailed description of the behavior is given in the section The debugger.
selects a new style. The format of STYLEDEF is defined at the `.defstyle' command.
prints the `STRING' (all after the colon until the end of the line) at the current vertical cursor position.
The default adjustment of the text is `centered', but this can be altered at any time using the commands `.left', `.right' and `.center'.
The vertical position is not advanced by default.
this disables output of trace information.
this enables output of trace information.
In this mode, every command will be printed to STDERR before execution.
this is identical to the command `.print' except that all text is underlined.
the procedure `PROC-NAME' will be executed again and again, until the database file with the handle `DBNUM' reports an `end of file' condition.
`DBNUM' is zero for the current database file, and greater zero for a dedicated database file.
this defines one or more variables.
Variables must have been declared, before they may be used.
A variable exists from the moment when it is defined, until the procedure where the variable was defined, is left.
If a variable is accessed, LPU searches for the variable in the current procedure first, then in the parent procedure, then in the parent's parent procedure, and so forth. Finally, the variable is searched in the main procedure.
moves the cursor HEIGHT DOTs to the bottom. The horizontal position is not changed. If HEIGHT is negative, the cursor is moved abs(HEIGHT) DOTs to the top.
Defines a list of expressions, which are `watched' during trace or single step mode. When in one of these modes, the given EXPRessions are calculated and printed to STDERR before the next LPU command is executed. This way, one can see what happens to variables while executing an LPU program.
evaluates the expression `EXPR' and executes the command `STATEMENT', if the result of `EXPR' is `true'.
This will be repeated, until the result of `EXPR' becomes `false' for the first time; in this case, execution continues with the next command.
If `EXPR' already evaluates to `false' at the first invocation, then `STATEMENT' is never executed.
defines a new output window within the current label. When a new label is selected, a default window with the full size of the label is defined. The same happens when `.window' is called without any parameters.
Otherwise, a window with the size WIDTH * HEIGHT is created at the current cursor position, or at position (XPOS, YPOS), the option `@(XPOS, YPOS)' is given.
If the option `.frame' is given, a thin frame is drawn around the currently selected window.
All coordinates are relative to the current window.
The current settings may at any time be overwritten by a new `.window' command.
After issuing the `.window' command, no margins are defined. Those may be defined (and altered again) later using the `.border' command.
A quoted line is a line in a LPU command file, which contains a `"' in the first column.
The line
"LINE OF TEXT
can be seen as a shorthand form of the two dot commands
.text :LINE OF TEXT
.nl
The `LINE OF TEXT' (everything after the `"' until the end of the line) is printed at the current vertical position with the active line adjustment (centered, left or right adjustment).
After that, the cursor is advanced to the beginning of the next line.
Within the text, some replacements can be performed. Details are explained in section text replacement.
LPU contains support for the import of structured text information from external files. This can be used to create address labels and so forth, where a label is printed many times, but with different information on each of them.
Currently, only a simple `text database' is supported. Other database types are planned for future releases of LPU.
Within LPU, this kind of `text database' is called a `TDB file', and the implied extension is `.tdb'.
A TDB file is a pure text file, where each line of text represents a database record, and a special character is defined as a separator, which divides a text line into single database fields.
By default, the separator is a null character, so that the whole line of text is seen as a single field. When opening a database file, a different separator can be defined.
Currently, database support is implemented by these dot commands:
opens an existing database file. `DBNAME' is the name of the database file, and if the extension is missing, `.tdb' is assumed. Note that this may change in future releases, if other database types are supported. The default type is `TDB'.
More than one database file may be open at any time, and a `handle' is assigned to every open database file. The handle is a small positive integer with values starting from `1'. The special handle `0' accesses the `current' database file.
If the option `#N' is given, the database file is assigned to handle `N', else LPU uses a free handle. This handle will become the new `current' handle. Also, the first record of the database file will become the `current record'.
If the option `/T' is given, the character `T' will become the new field separator for that database file. Without this option, there will only be one field in every record, which contains the whole line of text. Any printable character can be used for `T'.
closes the open database file with the current handle.
defines handle `N' as the new current handle and makes the open database file with this handle to the new current database file.
positions the `record pointer' to the first record of the current database file.
positions the `record pointer' to the next record within the current database file.
searches the current database file, beginning with the current record, for a record with the value `PATTERN' in field `N' of the record. Field numbers start with `1'.
If a record was found, then this will become the new current record, else an `end of data' condition will occur. In this case, the record pointer points to a position `behind the last record' of the database file.
The state and current values of the database may be accessed by a couple of functions (see System functions); most of them begin with `$db'.
Starting with version 0.9-23, LPU contains experimental support for `embedded postscript' files (eps).
The contents of an eps file is always shown as a `black box'; only the size and the position on the current label may be changed.
There is a simple way to show the contents of a eps file with one command (eps insert), where you supply position and size to the command as parameters, and a complex way where you can open the file (eps open), access file attributes ($eps{ATTR}), resize (eps resize) or rescale (eps rescale) and show (eps show) the file contents. You can repeat this process as often as you like. When you don't need the file any more, you can close it (eps close).
The second form is more complicated, but also more flexible.
As it was stated above, the eps support is experimental only, and the command syntax may still change.
Here is a description of the available eps commands in LPU:
this command prints the contents of an eps file on the current label.
FILENAME is the name of the eps file in Unix notation; the file extension must be given.
Without any options, the file will be printed at the current cursor position in its original size.
The following options are supported:
this command opens the eps file and makes it available to the other eps functions and commands.
FILENAME is the name of the eps file in Unix notation; the file extension must be given.
After opening the file, other eps commands may be used, until the file is closed again, using the `eps close' command. Only one eps file may be open at any time.
While the file is open, the system function `$eps{ATTR}' may be used to gather information about the eps file. This will be described in detail in the `system functions' section.
this changes the size of the eps object in the currently open file. XSIZE and YSIZE specify the new size in DOTs.
this is another way to change the size of the eps object. XSCALE and YSCALE are float values with give the scaling factor for the new size in relation to the original size. `1.0' for both values keep the original size, while '2.0' doubles the size in the corresponding direction.
The scaling factor always corresponds to the original size of the eps file. So, only the last `eps rescale' or `eps resize' has an effect on a following print command.
this commands prints the eps object once with the current size, as defined by the last `eps resize' or `eps rescale' (or the original size, if none of these commands was used after the last `eps open'). It can be called as often as required.
If no option is given, the object is printed at the current cursor position with the top left corner of the object as the reference point.
The position can be changed with the '@' option, and the reference point is modified by the options `.hcenter', `.vcenter' and `.center'.
Here is a list of the available options:
this command closes an open eps file. After that, a new eps file may be used.
Lines beginning with a `#', immediately followed by a keyword are preprocessor instructions. They are evaluated and executed when reading the source-code.
The following preprocessor instructions are available at this time:
reads and inserts the file `FILENAME' at the current position into the source code of the LPU program. If no extension is given, `.lpi' is appended to the filename.
Before a line of text is processed, the replacement of special symbols takes place.
These replacement symbols start with a backslash. The symbol will be replaced by the current value of the evaluated symbol.
The following replacement symbols are defined:
is replaced by a single backslash.
is replaced by the name of the current procedure.
is replaced by parameter `N' of the current procedure.
is replaced by the number of parameters.
is replaced by the return code of the last executed procedure.
is replaced by the field number `N' of the current record of the current database file.
is replaced by the number of fields in the current database record.
is replaced by the current record number of the current database file.
is replaced by the `end of data' state (`0' or `1') of the current database file.
is replaced by the contents of the variable `ID'.
is replaced by the result of the evaluated expression `EXPR'.
is replaced by the contents of the environment variable `ENV'.
Many times within this document, an expression can be specified. Here is an explanation of how expressions are constructed.
An expression contains operands and operators.
Operands may be numerical values, string values, variables, and system functions.
They are tied together by numerical, logical and comparison operators.
If an expression is evaluated, it results in a type and a value of that type. The result types of an expression can be:
this is an array of characters.
this is an integer value (32 bit int on most systems)
this is a floating point value (64 bit double on most systems)
Sometimes, one of the following expression types is required:
is an expression of any type.
requires a result type of T_STR.
requires a result type of T_NUM or T_FLT
requires a result type of T_NUM. The value `0' is defined as `false', and all other values are defined as `true'.
Here is a list of all currently defined operators, grouped by classes (you will see that most of them are equivalent to `C' operators):
`=', `<>', `<', `<=', `>', `>='
`+', `-', `*', `/', `%'
`&', `|', `&&', `||', `!'
`#' converts the following factor into a numerical value, if this is possible.
The following system functions are currently avaliable:
returns the distance between the baseline and the top edge of the bounding box of the currently selected font, measured in DOTs.
returns `1', if LPU is currently running in batch mode, `0' otherwise.
concatenates two or more strings to one longer string.
this is a loop counter within `.repeat' statements. Outside of `.repeat' statements, it usually returns `1'.
returns the contents of field `FLD' of the current record of database file `DB'.
returns the number of fields in the current record of database file `DB'.
evaluates a `unit' type expression and returns the result, converted to the unit DOT.
`EXPR' may be of type T_NUM or T_FLOAT, immediately followed by a unit id. The result will always be of type T_NUM.
returns `1', if the `end of data' is reached for the database file `DB', and `0' otherwise.
returns an attribute of the currently opened eps file.
The following attributes can be used:
returns the number of the last program error.
A value of 0 says, that there is no error, or that the last error has been processed and reset.
A value greater than 0 shows a pending error condition.
evaluates the expression `EXPR' and converts the result to the type T_FLT.
returns the number of defined fonts.
returns the height of the currently selected font, measured in DOTs.
returns the number of form types, that are defined in the TAB database.
returns the name of form number `FNR' in the TAB database.
`FNR' can be in the range `0' .. `$formcnt-1'. The special value `.' returns the name of the currently selected form.
returns the date of the generation of the currently running LPU image as a string value.
checks, if a variable with name `VAR' exists and has a numerical type. Returns `1' if true and `0' otherwise.
checks, if a variable with name `VAR' exists and has a textual type. Returns `1' if true and `0' otherwise.
checks, if a variable with name `VAR' exists. Returns `1' if true and `0' otherwise.
returns the number of different label types, which are defined with form number `FNR'.
For a description of `FNR', see the function `$formid'.
returns the name of the label type with index `LNR' in the form `FNR'.
For a description of `FNR', see the function `$formid'.
`LNR' can be in the range `0' .. `$lblcnt(FNR)-1'. The special value `.' returns the name of the currently selected label type.
returns the number of identical labels of type `LNR' in form `FNR', which are positioned in horizontal order.
For a description of `FNR', see the function `$formid'. For a description of `LNR', see the function `$lblid'.
returns the number of identical labels of type `LNR' in form `FNR', which are positioned in vertical order.
For a description of `FNR', see the function `$formid'. For a description of `LNR', see the function `$lblid'.
returns the string value `STR', with all leading blanks removed.
returns the bigger of the two given expressions E1 and E2.
returns the smaller of the two given expressions E1 and E2.
returns the current time as `ansi time' (the number of seconds since Jan, 1st 1970, 00:00 GMT) of type T_NUM.
converts the given expression to a full number and returns it.
evaluates the expression `EXPR' (which must be of type T_NUM), and returns `1', if the result is odd, `0' otherwise.
returns the value of parameter `N' of the current procedure. Parameter numbers range from `1' to '$parcnt', while parameter `0' returns the name of the current procedure.
returns the number of parameters, that were passed to the current procedure.
tells, if the currently selected font is proportional.
returns the exit state of the last procedure that was called from the current procedure.
returns the string value `STR', with all trailing blanks removed.
converts the numerical value `VAL' to a string representation with a minimum width of `LEN' digits. If the parameter `DEC' is specified, and greater than zero, then the string represents a fixed point number with `DEC' digits behind the decimal point.
creates a string with a time format.
The parameter `TIME' must be of type T_NUM, and is interpreted as an `ansi time' value.
The parameter `FORMAT' contains a format specification, which is identical to the format string of the `C' function `strftime'.
returns the number of characters in the T_STR type expression `STRING'.
returns a string which is constructed by appending the string expression `PAT' repeatedly to the string expression `STRING', until the length `LEN' is reached. If the resulting string is too long, it is truncated to the length `LEN'.
returns a string, which is constructed by concatenating the string expression `STRING' `COUNT' times.
returns a segment of the string expression `STRING', starting at offset `POS' (starting with `0') with a length of `LEN' characters.
If `LEN' is negative, then the last `abs(LEN)' characters are extracted from the string, but not starting before offset `POS' of the string.
returns the offset, where the substring `PAT' appears the first time within the string `STRING'; the offset starts with `0'. If `PAT' doesn't appear within `STRING', the function returns `-1'.
returns the first or next token of string `STR'. The first time, the function must be called in the form
$strtok(STR, LIM)
In this case, a copy of 'STR' is stored internally, and the first part of the string, up to the first occurrence of any of the characters from within string `LIM' is returned.
All following calls to this function should have the form
$strtok(LIM).
This will return the next part of the internally stored string, up to the first occurrence of any of the characters from within string `LIM'.
This will continue until the stored string is empty. After that, all subsequent calls to this function in the second form will return an empty string.
returns the width of the given string expression `STR' for the current font, measured in DOTs.
returns the string value `STR', with all leading and trailing blanks removed.
returns the current version of LPU as a string in the form `X.Y-Z'.
returns the horizontal offset of the current window within the current label in DOT.
returns the horizontal position of the cursor within the current window in DOT.
returns the width of the current window in DOT.
returns the vertical offset of the current window within the current label in DOT.
returns the vertical position of the cursor within the current window in DOT.
returns the height of the current window in DOT.