Executes EasyScript commands which get or set Parameter values for a specified set of Subject's. Also executes some single word commands such as help. Can generate a script to recreate the current state of an application/ simulation.

EasyScriptParser takes a “snapshot” of the starting parameters and variables. But there are two snapshots: independent and dependent. The independent parameters have no effect on each other. The dependent parameters and variables are usually determined by a "configuration" parameter (for example, the number of pendulums in NewtonsCradle). The dependent snapshot is retaken when the config parameter is altered. The dependent snapshot should be the exact state that follows from setting that config parameter (this implies no randomness when creating the simulation).

Note that the EasyScriptParser "snapshot" is different from the "save initial conditions" feature in Simulation:

  • the EasyScriptParser "snapshot" is the "blank slate" starting conditions after the Simulation is created.

  • the "save initial conditions" is used when doing "reset" on the Simulation. These initial conditions can differ from the "blank slate" starting conditions.

Execute EasyScript Commands

EasyScriptParser (ESP) is given a list of Subjects in its constructor. ESP interrogates all the Subjects and remembers their settable Parameters and initial values.

ESP is typically used with Terminal. ESP is installed via Terminal.setParser. Note that saveStart must be called before using ESP; in Terminal this is done as part of Terminal.parseURL.

When a script is executed in Terminal, the script is first offered to ESP by calling parse.

  • If ESP recognizes the Subject and Parameter name in the script then parse will get or set the Parameter value and return the value.

  • If ESP doesn't recognize the Subject and Parameter name there is no error, instead parse returns undefined and Terminal will try to execute the script as JavaScript instead.

EasyScript Syntax

Here is an example EasyScript that can be entered in the Terminal interface of Newtons Cradle


The "setter" syntax is


The "getter" syntax is


where square brackets indicate optional elements. Multiple scripts can be on one line separated by a semicolon.

  • SubjectName is the language-independent name returned by Subject.getName. It is optional when ParameterName is unique among all specified Subjects. It is required when multiple Subjects have the same Parameter name.

  • ParameterName is the language-independent name returned by Parameter.getName.

  • value is a string that is given as input to Parameter.setFromString. The string can be optionally surrounded with quotes like a JavaScript string in which case the quotes are removed and backslash escaped characters (quote, newline, tab, etc.) are replaced. If not surrounded with quotes then the string ends at the semicolon or end of line.

With both setter and getter syntax the value of the Parameter is available as the result of the parse method, or in the result variable of Terminal, or displayed in the Terminal output area.

The English language version of Parameter or Subject names can also be given, they are converted to the language-independent form using Util.toName. Leading and trailing spaces are trimmed from names and (unquoted) values.

Single Word Commands

A small set of single word commands are recognized by EasyScriptParser. Use addCommand to add more single word commands. The built-in commands are:

  • help lists the available single word commands and other help information
  • names shows available Parameter names
  • script prints a script to recreate current state of application/ simulation
  • url prints URL of current web page along with script to recreate current state
  • values shows available Parameter names and their current values

Variables define Initial Conditions

The Variable's of a Simulation determine its state, and the starting Variables are the "initial conditions" which determine what will happen.

Because Variable extends Parameter, it is simple for EasyScriptParser to treat the set of Variables as part of the same process that reports or sets other available Parameters.

The Variables show up like this (when you give the values command)


and the variables can be set like any other Parameter with an EasyScript command like

angle_1 = -1

Generate a Script that Recreates the Simulation

The script method makes a script that sets all Parameters and Variables to match the current simulation state.

To keep the generated script as small as possible, EasyScriptParser remembers the initial value of all Parameters at startup (the saveStart method can be used to update the initial values after startup). The script method only creates commands to set Parameters whose value has changed. Computed Parameters are ignored because setting them has no effect (their value is always computed from other values).

The script method returns just the script without the URL of the current web page (see EasyScript Embedded in URL if you want the URL as well). The script can be pasted into the Terminal command line interface, or put in a start-up HTML page.

See Customizing myPhysicsLab Simulations for more about how to use scripts in myPhysicsLab.

Parameter Independence

To work well with EasyScriptParser, an application or simulation should strive to have all Parameters be independent of each other.

Suppose Parameter A modifies the value of Parameter B. Then the result of running the script generated by EasyScriptParser will depend on the order of the statements: setting Parameter B only has an effect if it is done after setting Parameter A.

Note that "configuration" Parameters violate this concept of Parameter Independence, which is why we specify the affected Subjects to be "dependent".

Dependent Subjects

A dependent Subject can be changed by a controlling "configuration" Parameter. The configuration Parameter determines the size, shape, initial positions and number of objects in the simulation. In essence, the configuration Parameter implies a new set of initial values for the dependent Subjects.

Many applications have multiple "configurations" that the user can choose between. For example, in Newtons Cradle the number of pendulums is controlled by a Parameter called PENDULUMS which is connected to the NewtonsCradleApp.setNumBodies method.

The dependent Subject is typically the VarsList that holds the Variables corresponding to the positions of the objects. If the configuration Parameter also sets the viewing rectangle, then the SimView might also a dependent Subject (an example is RollerSingleApp where selecting a path changes the viewing rectangle).

When the configuration changes, the application must call update to update the remembered initial values of the dependent Subjects. Having this new set of initial values makes it possible for the script method to generate a very short script like PENDULUMS=4; instead of setting all the Variables.

The script method ensures that dependent Subjects are modified at the end of the script, so that those changes are not overridden by a configuration Parameter.

EasyScript Embedded in URL

To save a customized version of a simulation, or share it with someone else, use scriptURL. That method returns the URL of the current page along with a script that sets Parameters to their current values.

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


A user can save or share this custom URL. When the URL is pasted into a browser, the scripts embedded in the URL will be executed.

While the above URL will work, some websites will not accept it as a valid user-supplied URL. Therefore scriptURL() percent-encodes many symbols to ensure the URL is valid, see URL Query Script Here is the fully encoded version of the above URL, where the symbols = and ; are encoded with %3D and %3B respectively:


The application should call Terminal.parseURL in order to execute the query URL during application startup.



  • Parameters

    • subjects: Subject[]

      list of Subject's to gather Parameters from.

    • Optional dependent: Subject[]

      those Subject's whose set of Parameters and initial values can change depending on a "configuration" Parameter. Typically this is the VarsList of a simulation.

    Returns EasyScriptParser


allParamNames_: string[] = []

The complete set of ParameterName strings. Can contain duplicate Parameter names. Same order as allSubjParamNames_, one string for each Parameter.

allSubjParamNames_: string[] = []

The complete set of SubjectName.ParameterName strings. One string for each Parameter.

allSubjects_: Subject[] = []

The set of all Subjects, corresponding to each Parameter in allSubjParamNames_. Same order as allSubjParamNames_, one Subject for each Parameter.

dependent_: Subject[]

The set of dependent Subjects to examine (usually a VarsList).

initialDependent_: string[] = []

Names and initial values of dependent Parameters. Used for making the script shorter.

initialNonDependent_: string[] = []

Names and initial values of non-dependent Parameters. Used for making the script shorter.

subjects_: Subject[]

The set of Subjects to examine.

unique_: boolean[] = []

For each Parameter, whether it has a unique name among Parameter names in allParamNames_. Same order as allSubjParamNames_, one boolean for each Parameter.


  • Adds a single-word command to this Parser. When the Parser sees this command during Parser.parse it will execute the given function. The function result is returned as the result of parse.

    The function must return a value other than undefined, otherwise a script syntax error will be indicated to the user.


    • commandName: string

      name of command

    • commandFnc: (() => any)

      function to execute

        • (): any
        • Returns any

    • helpText: string

      description of the command for help text

    Returns void

  • Returns the Parameter corresponding to the given EasyScriptParser name such as X_Y_GRAPH_LINE.GRAPH_COLOR. The name can consist of either just the name of a Parameter (if unique among all Subjects) or be both Subject name and Parameter name separated by a dot. This is used in Terminal scripts to find the Parameter, so that we can call methods like getValue() or setValue() on the Parameter.


    • fullName: string

      name of Parameter, optionally preceded by name of Subject and a dot

    Returns null | Parameter

    the Parameter corresponding to the given name, or null if no Parameter found


    when only Parameter name is given, but multiple Subjects have that Parameter.

  • Returns the Subject with the given EasyScriptParser name.


    • name: string

      name of Subject

    Returns null | Subject

    the Subject corresponding to the given name, or null if no Subject found

  • Returns the "help" string which gives information on available commands.

    Returns string

    the "help" string which gives information on available commands.

  • Returns the list of Parameter names that can be modified by this EasyScriptParser. Each Parameter name is preceded by the name of its Subject and a dot.

    Returns string[]

    the set of Parameter names that can be set by this EasyScriptParser

  • Returns a script which sets Parameters to their current values. See EasyScriptParser for the syntax of the script.

    Uses Parameter.isComputed to exclude Parameters that are being automatically computed, unless includeComputed is true.


    • dependent: boolean

      true means return only Parameters belonging to the set of dependent Subjects; false means return only non-dependent Parameters.

    • Optional includeComputed: boolean

      true means include Parameters that are automatically computed; default is false which means filter out Parameters that are automatically computed.

    • Optional fullName: boolean

      true means always return Subject and Parameter name; default is false which means don't include Subject name when Parameter name is unique.

    Returns string

    a script which sets Parameters to their current values

  • Interprets and executes a script.


    • script: string

      the script to parse and execute

    Returns any

    the value of the script, or undefined if the script did not fit the allowed syntax


    if executing the script causes an error

  • Saves current application and simulation state to compare against when generating a script later on. This helps shorten the script by not including settings that are unchanged.

    Returns void

  • Returns a script which sets Parameters to their current values.

    To keep the length of the script as short as possible

    • this ignores Parameters that are automatically computed, see Parameter.isComputed.

    • this ignores Parameters whose value is unchanged since saveStart was called (or for a dependent Subject, since update was called).

    • when a Parameter name is unique, we don't include the Subject name.

    Returns string

    script that sets Parameters to current values

  • Returns a URL for the current page along with query script to set Parameters to their current values. The query part of the URL is the part following the question mark. When pasted into a browser, the Terminal.parseURL method can be used to extract the script from the URL query and execute it. The script is percent-encoded to ensure it forms a valid URL.

    See script for details about how the script is created.

    Returns string

    percent-encoded URL query script that sets Parameters to current values

  • Returns a minimal string representation of this object, usually giving just identity information like the class name and name of the object.

    For an object whose main purpose is to represent another Printable object, it is recommended to include the result of calling toStringShort on that other object. For example, calling toStringShort() on a DisplayShape might return something like this:


    Returns string

    a minimal string representation of this object.

  • Updates the set of Parameters associated with the Subjects, and remembers the initial settings of any "dependent" Subject's Parameters.

    This is different from saveStart in two ways:

    1. this updates initial values only for dependent Subjects.
    2. this updates the remembered list of available Parameter names.

    Returns void

  • Returns the set of Parameter names that can be set by this EasyScriptParser, and their current values. Each Parameter name is preceded by the name of its Subject and a dot.

    Returns string

    the set of Parameter names that can be set by this EasyScriptParser and their current values

  • Check that each Subject name is unique among this set of Subjects


    • subjects: Subject[]

      array of Subject names to check

    Returns void


    if any duplicate Subject names are detected

Generated using TypeDoc