TrainPlayer Programming Language v. 8.3

The vocabulary and grammar you use to write scripts is called TrainPlayer Programming Language, or TPL.  It recognizes a given list of commands and keywords -- some related to trains, such as setting speed and direction, and some standard programming constructs, like loops, ifs, and branches.  It allows you to create and substitute variables, and to separate frequently-used code into subroutines and procedures.  It is rudimentary but reasonably complete.

This document gives an overview of the components of the language.  It does not attempt to teach you programming, or even give you much more than a brief overview and a command reference.  The main documentation is built into the program, and can be found on the Reference tab of Script Central -- the same table of commands and variables as shown below, but with more detail and examples under each topic.

Further reading matter can be found on the Scripting page of the TrainPlayer web site. Of special note are two PDF documents giving a wealth of expert-level discussion and details:

• TrainPlayer 6.1 - Extensions to the Trainplayer Programming Language (TPL)
• TrainPlayer 8.1 - Introduction to Linked Layouts

Additions and changes for Version 8.1 are noted in the text below.  Version 8.3 (2024) added these features:

• multi-line blocks may be commented out by enclosing in /* ... */
• new keyword arguments to $OPS: set, show, hide, delete, duplicate
• new function to get distance between cars: $CAR (id, DistTo, idTo)
• to export layout to image file: $EXPIMAGE(path, [size, opts])
• $OUTPUT function to copy text from output window to variable
• $TIMER function to note current time or return time since last call
• $INT function to returns integer portion of numeric value
• $TRACK adds FindFromJxns argument to return track number between two given junctions
• $MSGBOX is now "pseudo-modal" -- does not lock application while visible

For complete information, see the Reference tab in Script Central.

TPL Overview

A script consists of a series of statements.  Some are comments -- text provided by the script author to annotate or explain -- and are skipped over when the script is executed.  Others are either executable statements, which cause actions to occur, or wait conditions, which cause the script to pause for some specified event or time period before proceeding.  The text in the script is sometimes referred to as code, and the act of creating it is called coding.

An executable statement begins with a command -- one of the words or phrases recognized by the language, such as those listed below -- followed by arguments providing data needed by the command. An argument might consist of a single string or numeric value, or an expression formed by combining multiple values using arithmetic operators. In place of a literal string or numeric value, you can use the name of a variable, and it will be replaced by the corresponding value when the statement is executed.

Statements are normally executed one after another as they appear in the script.  However, this behavior can be altered using flow commands.  A loop is a block of statements which are executed repeatedly a given number of times.  A branch is a jump to another place in the script, sometimes based on a decision made in an IF statement. 

A call is a jump to a separate external block of statements; these execute in their entirety, and then control jumps back to the statement after the call.  There are three variations on this.  A subroutine is a block of script code stored in a text file; a call to the subroutine executes the file and then returns.  A proc is a small routine stored between two tags within another script; the first time it is encountered, as its parent script executes, it is extracted and saved in memory under a specified name; subsequently it can be called using this name.  A function is a body of code which carries out a calculation and returns a result to be used by the calling script.

Whenever a train script or junction action is running, it is connected to a train.  Commands in the script which do not specify otherwise are directed to this train.  Train control commands can be used to redirect commands from the script-owning train to another one.

Variables are created and assigned using a Set statement, or the equivalent Let.  This takes the name of a variable and an expression; the expression is evaluated and its value assigned to the variable.   If the name is new, the variable is created, otherwise the existing variable is updated. 

TPL Statements

A script consists of a series of statements, usually one per line in a text file. Lines starting with * are comments, and are not executed.  By default, comments starting with a single asterisk are echoed to the output window as the script runs; those starting with ** are not.  Blank lines are ignored.

8.3 Update: multiple lines can be enclosed in /* ... */ to comment the entire block.

An executable statement consists of a command or wait condition name -- one of the words in the first column of the table below -- followed by any required arguments.

Multiple statements may be concatenated on a single line, using semicolon (;) as delimiter.  As a special case, a wait statement may be followed immediately by a command on the same line.

Built-in Commands

A command is an instruction telling the program to take some action.  There are two types: commands accessible from the program menus vs. those built into the language.  The menu commands are described in the next section.  The built-in commands are in these categories:

• Train commands: for setting speed and direction and operating the train owning the script.  This group of commands is the script equivalent of the control panel.
• Layout commands: for throwing switches, rotating turntables, and carrying out other layout-based actions.
• Train control commands: for directing movements of other trains, or turning control over to them.
• Flow commands: for looping, branching, choosing different courses of action based on conditions.
• Set/Let commands: for creating variables and assigning values.
• UI commands: for taking input from or providing feedback to the user.
• Subroutine commands: for calling and defining subroutines, plus special commands for use within them
• User interface commands: for communicating with the user, both input and output

Most commands consist of a single verb followed by one or more arguments telling what to act on or what to do.  In the table below, arguments are indicated by angle brackets -- you supply the value, not the brackets.  Optional arguments are enclosed in braces; if omitted, these take on default values.

speed 20	set speed of script owner to 20; start moving if stationary
echo "note to user!"	display message in output window
throw J35 1	throw switch at junction 35 to position 1
drive "Broadway Limited"	begin block of statements to be directed to another train

A complete list of commands is given below.  A better one is found in the Reference tab of Script Central.

Menu Commands

When you select any command from a menu, you see a cascading series of names starting with a top-level menu.  Write these names down one after another and you have a command you can use in a script.  Menu names must be separated by spaces, multi-word names must be quoted. 

Version 8.1 update: two special menu commands can now take an additional argument: File Open and File Save As can be followed by a full pathname, or a path relative to the layout owning the script.  If no filename is given, the file dialog comes up as before.

Examples:

Wait Conditions

A wait condition tells the script to wait for a certain event or until a certain time before proceeding.  There are only a few wait condition keywords, serving multiple purposes: AT a certain time on the clock, or when the first car of the train reaches a certain junction or track label; AFTER an elapsed time, or when the last car passes the given location; or ON specified events.

Flow Control

Script statements are normally executed one after another.  Commands in the "flow control" category change this behavior, by jumping to other parts of the code based on some criterion.  The following types of flow control are available:

• Conditionals.  Use If/Endif to evaluate a criterion and take different courses of action depending on the result.  A criterion is two expressions connected by a comparison operator, enclosed in parentheses.
• Loops.  Use While/Endwhile to execute the same block of statements as long as a given criterion is met.
• Branches.  Use Goto to jump to a specified location elsewhere in the code.
• Calls.  Use Call to jump to an external body of code, execute it, then return and continue at the next statement.
• Procs.  Use Proc to define a small subroutine within a script.

If Statement

An IF statement takes the form

if (val1 comp-op val2)
    code block 1
[else
    code block 2]
endif

where val1 and val2 are string or numeric values, variables, or expressions, and comp-op is a comparison operator, one of:

=  <  >  <>  <=  >=

The two values are compared using the given operator; if the result is TRUE, then code block 1 is executed; if FALSE, code block 1 is skipped, and control passes to the optional code block 2 or, if none, to the statement after the endif.

While statement

A while statement defines a loop.  It takes a form similar to IF:

while (val1 comp-op val2)
    code block
endwhile

where the code block executes once every time the comparison expression evaluates to TRUE; if it is FALSE, the code block is skipped and control passes to the statement after the endwhile.

Use a CONTINUE statement within a loop to go to the next iteration, or a BREAK statement to jump out and terminate the loop.

Let/Set statement

Set/Let statements take the form

set var expr
let var = expr

where var is the name of a new or existing variable, and expr is an expression, one or more components joined by operators:

comp [op comp [...]]

If expr is omitted, then the variable is deleted and removed from further use -- let x=  undefines the variable x if previously defined.

A component is one of:

•  a number
• an expression in parentheses
• a variable name, with or without prefix @
• a display string

Op is an arithmetic operator.  Between two numeric components, it can be one of these four:

+  -  /  *

Between strings, only the + operator is used, and means concatenation of strings.

Examples:

let v = (2 + 6) / 12
let v2 = v + 99
set AllowYardMode 0
let s = "speed is " + $x_speed
let myvar =

Variables and Functions

A variable is a named value.  You can make up a name, assign it a value, then use the name in place of the value in a script statement.  This is the key to writing abstract code which can work on different input data.

To create a variable and/or assign it a value, you use a LET or SET statement.  To represent it in a script statement, you normally* precede it with "@" -- a symbol you can read as "contents of," which identifies what follows as a variable name.

 Example:

let CruisingSpeed = 55
...
at j22
   speed @CruisingSpeed

* You don't need to precede a variable name with @ when you refer to it in a LET or SET statement.  If you want to embed a variable's contents into a larger string, use @ on both ends:

let s = "def"
echo The Alphabet: abc@s@ghi...

As of Version 6.3.1, you can edit a variable's value in the Reference tab of Script Central; see Editing Variables.

A system variable or function is a value supplied by the system.  You call for a system value by giving a function name, often followed by a list of arguments in parentheses.  An argument might be the id of an object, a keyword requesting a specific action or value, or an input value for a calculation or operation.  Sometimes you don't get a value back, you just call the function to do some work, using a CALL statement. 

System function names begin with "$".  A list of them is given below, and also in the Reference tab of Script Central.

 Examples:

echo Today's date is $DATE
echo Name of active layout is $LAYOUT(Name)
let r = $RAND(1,100)
echo A random percentage -> @r

let storedData = $READ("C:\myfile.txt")
let outputData = storedData + "additional info"
call $WRITE("C:\myfile_new.txt", @outputData)

A function family is a set of related functions with the same name, and a list of arguments which usually includes the identifier of an object and/or a keyword representing a specific value.  Several function families provide access to objects on the layout -- cars, trains, tracks, junctions, the layout itself -- while others work with general objects, like strings and files. 

Some functions are "writable," meaning their values can be changed in LET or SET statements.  Writable functions are indicated by "r/w" in the Reference listing in Script Central.

Example:

echo The load in box 44 is $CAR(x44, Loadname)
let newLoad = "Toy Tractors"
echo Changing load to @newLoad!
set $CAR(x44, Loadname) = newLoad

A local variable is one which is inaccessible outside of a certain limited region of code (or "scope").  Normally, when a variable is defined and assigned a value, it is "global" -- it can be referenced by any scripts or actions anywhere.  But if it is named in a preceding LOCAL statement, then it is known only to the script (or subroutine or proc) where it is defined.  Example:

* train script 1
let gv = "a global value"
local lv
let lv = "a local value"

* train script 2
echo global value was defined as: @gv
echo value local to script 1 is undefined here: @lv

An excellent discussion with detailed descriptions of each system function can be found on the web in TrainPlayer 6.1 - Extensions to the Trainplayer Programming Language (TPL).

Subroutines

A subroutine is a named body of code stored in a file outside a script.  The code can be executed within the script by inserting a CALL statement including the name of the file. 

To pass data into and out of the subroutine, one or more arguments may be included in the call.  Arguments are numbered from left to right in the call, and are represented within the subroutine as placeholders starting with "%".  For example, wherever the subroutine contains "%1", it will be replaced by the first argument in the call.

Here is a simple example of a subroutine which takes a single argument.  It doesn't do anything particularly useful, but the point of making it into a subroutine is that it could be made fancier if needed.

These lines become a subroutine if stored as a text file sitandwait.txt in the TP Scripts folder.

A proc is a type of subroutine which is not defined in an external file, but in a section of another script.  Using proc and endproc statements within a script, you define a callable block of code and give it a name.

This becomes callable once the script containing it is run.  Including it within the master script guarantees this.

If either of the above is available, a script can then say

call sitandwait 5

to cause 5 seconds of idleness.

Display Strings

The term "display string" (DS) means a lengthy string for conveying information to the user or to a file. Each of the following commands takes a ds as argument, and all process it in exactly the same way:

• ECHO ds
• NOTE ds
• NOTEBOX ds
• $MSGBOX([type,] ds)
• $WRITE(fname, ds)

Display strings:

• may contain references to variables. User variables are prefixed by @, globals by $. These are substituted by appropriate values before the string is output.
•  may be surrounded by quotes, or not -- author's choice. Quotes are removed before output.
•  may be multi-line text blocks containing returns and blank lines. A multi-line string must be quoted, and any embedded quotes must be doubled.
•  may be components of LET statements.

Special $MSGBOX feature introduced in Version 8.3: this box is now "pseudo-modal," which means you no longer need to dismiss it in order to continue interacting with the program.  The msgbox stays up while you work, until you click OK.  This happens only when you do not supply a type argument (and are thus not waiting for a result).

Quotes in TPL

Our general philosophy is: quotes are not required (except in certain situations listed below), but may be used if desired. Programmers used to formal languages tend to prefer quoted strings. Thus either of these is valid:

echo this is a string to be output
echo "this is a string to be output"

In a display string, variables are substituted whether or not the string is quoted. Examples:

echo the speed of the crossing train is $train($x_train, speed)
echo "today is $date and it is already $time"

Quotes are optional around most function arguments and keywords. Thus both of these work:

echo the speed is $train(train66, speed)
echo the speed is $train("train66", "speed")

Where quotes are required:

1. Around a multi-word command, registry setting name, or filename -- that is, any of these which contains a space. In a menu, this applies only to a single level of a cascading menu. Examples:

file open "c:\my file.txt"   <== filename with space
file "revert to saved"       <== menu command
set "Default Car Length" 400 <== reg setting name

3. Around a string containing a parsable character, where the meaning of that depends on the context. In a function call, an unquoted string must not contain the character ")", because that would terminate the call. In a comma-delimited list, a string must be quoted if it contains comma. Examples:

call $write(c:\myfile.txt, a string with ) paren)   <== WRONG
call $write(c:\myfile.txt, "a string with ) paren") <== OK

4. Around a multi-line text block. This is the only way to define such a block, by enclosing it in double quotes and including carriage returns:

echo "this is a string
  with multiple lines

   and a blank line"

Note that if you want the string itself to include a quote, you must double it:

echo "string with embedded "" quote"

Table 1.  TPL Command Reference

This table shows the command vocabulary with brief descriptions.  For a more complete and up-to-date listing, consult the Reference tab in Script Central.  Contents of that tab can be exported for printing if desired.