Class Terminal

Executes scripts and provides a command line user interface with separate text fields for input and output. Executes EasyScript or JavaScript. Allows use of "short names" to replace full namespace pathnames of classes.

After the script is executed the result is converted to text and displayed in the output text field. The output is not displayed if the result is undefined or the script ends with a semicolon.

See also Customizing myPhysicsLab Software.

Getting Help

Type help in the Terminal input text area and press return to see the help message. Several useful Terminal commands are shown.

Perhaps the most useful command is vars which shows the list of variables that are available.

Summary: How Scripts Are Processed

Scripts entered into Terminal are transformed in these ways:

• Scripts are split at semi-colons into separate lines. Each line is executed separately. (Semi-colons within braces are ignored).

• EasyScript parser handles lines that it recognizes.

• var at start of a line becomes a z variable property. For example var foo becomes app.z.foo.

• Short-names are transformed to long-names. Example: DoubleRect becomes lab$util$DoubleRect. Also existing variables are transformed, for example foo becomes app.z.foo.

• Javascript's eval function executes the resulting line.

Turning on verbose mode with terminal.setVerbose(true) shows these transformations as they happen.

Two Types of Scripts

Terminal can execute two types of scripts:

1. JavaScript. The code is transformed so that short-names can be used.

2. EasyScript: a very simple scripting language for setting Parameter values. See EasyScriptParser for syntax details.

These two types of script can be intermixed in a single script as long as they are separated by a semicolon. For example, here are both types of scripts in one line which could be entered in PendulumApp.

DAMPING=0.1; GRAVITY=9.8; ANGLE=2.5; bob.setFillStyle('red');
Copy

The first three commands are EasyScript commands that set Parameter values; the last is a JavaScript command.

In most applications EasyScriptParser is available in the variable easyScript, which you can use to execute EasyScript from within JavaScript. Here are examples that can be entered (as individual lines) in PendulumApp.

easyScript.parse('angle')

easyScript.parse('angle='+Math.PI/2)

easyScript.getParameter('gravity').getValue()

easyScript.getParameter('gravity').setValue(2.5)
Copy

Long Names

To make class names accessible for scripting in Terminal, we create a global variable for each class. For example

lab$util$DoubleRect
Copy

is the global variable for the DoubleRect class. This naming scheme is used to avoid potential conflicts with other global variables.

Short Names

To allow for shorter scripts, we define a variety of regular expressions in Terminal which convert short names to their proper long expanded form. This allows typing for example:

new DoubleRect(0,0,1,1)
Copy

which is automatically converted to

new lab$util$DoubleRect(0,0,1,1)
Copy

Applications will typically also make their key objects available with short-names. So instead of app.sim you can just type sim.

You can see this short-name to long-name conversion by using setVerbose:

> terminal.setVerbose(true)
> new Vector(2,3)
>> new lab$util$Vector(2,3)
Vector{x: 2, y: 3}
Copy

In verbose mode, the command is echoed a second time to show how it appears after expansion. The terminal prompt symbol >> is doubled to distinguish the expanded version.

Short-names are implemented by defining a set of regular expression replacement rules which are applied to the Terminal input string before it is executed.

Regular expression rules are registered with Terminal using addRegex. Then whenever a command is evaluated it is first expanded to the long form using expand.

stdRegex defines a standard set of regular expressions for expanding myPhysicsLab class names (like DoubleRect) and for expanding a few function shortcuts like methodsOf, propertiesOf and prettyPrint. An application can add more shortcuts via addRegex.

Variables and the 'z' Object

Scripts are executed with indirect eval under strict mode. Each script line is eval'd separately, and a new scope is created for each eval(). Any variables created only exist during that eval(), then they disappear.

To allow making variables that persist between lines and commands, the app provides an object named z where properties can be added. A script like var a = 1; a is translated to define a property on the z object, instead of a new global variable. It looks something like this:

> z.a = 1
1
> z.a
1
Copy

This z object is itself a property of the application object usually called app; z is initially an object with no properties. We define a short name regular expression so that referring to z is replaced by app.z when a script line is executed. Using setVerbose you would see the following:

> terminal.setVerbose(true)
> var a=1
>> app.z.a=1
1
> a
>> app.z.a
1
Copy

Declaring a Variable

To hide the usage of the z object, Terminal interprets the var, let and const keywords in a special way.

When Terminal sees the var or let keywords at the start of a command, it changes the script to use the z object and defines a new short-name. For example the command

> var foo = 3
3
Copy

is translated to

> app.z.foo = 3
3
Copy

and thereafter every reference to foo will be changed to app.z.foo in later commands. You can see this at work by using setVerbose:

> terminal.setVerbose(true)
> foo
>> app.z.foo
3
Copy

Line Splitting Affects How Scripts Are Processed

A script is executed by splitting it up into lines of code that are separated by semi-colons.

Each execution of a line (via indirect eval) has it's own temporary scope where any created variables, functions, or classes go. That scope disappears as soon as the execution finishes.

Only lines that are at the "top level" are split by semi-colons; any semi-colons within braces or parenthesis (or inside of strings) are ignored. Braces turn off line splitting.

For example: this script creates a class and does a test within braces, but the class and variable disappear after execution. The value 7 is printed if you paste this entire script into Terminal input, but a and myClass are no longer defined.

{ class myClass {
    myField=7;
    constructor() {}
} 
var a = new myClass();
println(a.myField) }
Copy

To make things within braces persistent, assign them to something defined beforehand.

var a;
{ class myClass {
    myField=7;
    constructor() {}
} 
a = new myClass(); };
a.myField
Copy

To make a class (or function) persistent, assign it to a variable.

var myClass = class { myField=7; constructor() {} };
var a = new myClass();
a.myField
Copy

The Result Variable

The result of the last Terminal script is stored in a variable named result. Here is an example Terminal session:

> 2+2
4
> result*2
8
> result*2
16
Copy

Note that eval has an argument called output which if set to false prevents result from being updated. When output==false, then result is is defined for commands in the same string, but that version of result is temporary and independent of the permanent result variable.

The terminal Variable

Some features (such as the result variable) require that the name terminal is defined and resolves to the Terminal object.

In most applications this is accomplished by using addRegex something like this:

terminal.addRegex('terminal', 'app');
Copy

where app is the global variable containing the application. The purpose of the regex is to replace the word terminal with app.terminal which is a valid JavaScript reference.

(In unit tests of Terminal, we temporarily define a global variable named terminal.)

Cautions About Newline Character

When you paste a script into the Terminal text input field, be aware that newlines are replaced by spaces. For a multi-line script this can cause errors. To prevent problems:

• Use explicit semicolons instead of relying on JavaScript's policy about optional semicolons.

• Use slash-star style comments instead of double-slash style comments (which are terminated by a newline).

• If for some reason you really need a newline in the script, use \u000A or \x0A. These are replaced with the newline character before the script is evaluated.

• Put the multi-line script in a start-up HTML page. You can then call Terminal.eval() directly on a string that you create, and that string can include newline characters.

The tab character also cannot be input directly to the Terminal input field, because the browser interprets that to mean "move to the next field". You can use \u0009 or \x09 which are replaced by a tab character before the script is evaluated.

URL Query Script

A Terminal script can be embedded into a URL query string which will be executed when the page is loaded. This provides a convenient way to remember or share a customized simulation with someone else.

The script follows a question mark in the URL, so it is called a 'query script' or 'query URL'. Here is an example:

https://www.myphysicslab.com/pendulum/pendulum-en.html?DRIVE_AMPLITUDE=0;
DAMPING=0.1;GRAVITY=9.8;ANGLE=2.5;ANGLE_VELOCITY=0;
Copy

The URL Query Script is executed at startup by calling parseURL. Most myPhysicsLab applications do this.

Some websites will only accept user-supplied URLs that follow the strict guidelines of URL percent-encoding. Therefore we must substitute in the URL:

• %20 for space
• %22 for "
• %3C for <
• %3E for >
• %5C for \

See this character encoding chart to learn which other characters must be percent-encoded. You can use {@link encodeURIComponent} which is a more stringent version of doing the character encoding; it percent-encodes other symbols such as:

• %27 for '
• %28 for (
• %29 for )
• %3B for ;

Here is an example of a URL query script using JavaScript in an application:

https://www.myphysicslab.com/pendulum/double-pendulum-en.html?
simRun.pause();simRun.reset();sim.setGravity(5.0);statusView.getDisplayList()
.add(energyGraph);statusView.getDisplayList().add(displayClock);
var%20va=sim.getVarsList();va.setValue(0,0.15545);va.setValue(1,-0.33548);
va.setValue(2,-2.30681);va.setValue(3,2.68179);sim.saveInitialState();
simRun.resume();layout.showTerminal(true);
Copy

Try this link which contains the above code; you should also see the code in the Terminal output area.

Here is an interactive tool for trying out URL Encode/Decode. Note however that tool replaces a space with a + which instead should be replaced by %20.

Many websites and programming tools require that the URL be fully encoded with the more stringent version.

Session History

The session history feature recalls previous input lines; these are accessed using the up/down arrow keys. Command-K clears the output area.