Private allThe complete set of ParameterName strings. Can contain duplicate Parameter names. Same order as allSubjParamNames_, one string for each Parameter.
Private allThe complete set of SubjectName.ParameterName strings. One string for each Parameter.
Private allThe set of all Subjects, corresponding to each Parameter in allSubjParamNames_. Same order as allSubjParamNames_, one Subject for each Parameter.
Private dependent_The set of dependent Subjects to examine (usually a VarsList).
Private initialNames and initial values of dependent Parameters. Used for making the script shorter.
Private initialNames and initial values of non-dependent Parameters. Used for making the script shorter.
Private subjects_The set of Subjects to examine.
Private unique_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.
name of command
function to execute
description of the command for help text
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.
name of Parameter, optionally preceded by name of Subject and a dot
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 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.
true means return only Parameters belonging to the
set of dependent Subjects; false means return only non-dependent Parameters.
Optional includeComputed: booleantrue means include Parameters that are
automatically computed; default is false which means filter out Parameters
that are automatically computed.
Optional fullName: booleantrue means always return Subject and Parameter name;
default is false which means don't include Subject name when
Parameter name is unique.
a script which sets Parameters to their current values
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.
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.
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:
DisplayShape{polygon:Polygon{'chain3'}}
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:
Static checkCheck that each Subject name is unique among this set of Subjects
array of Subject names to check
if any duplicate Subject names are detected
Static unquoteRemoves quotes from start and end of a string, and replaces single character escape sequences with the corresponding character.
Generated using TypeDoc
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
parsewill 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
parsereturnsundefinedand 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.
SubjectNameis the language-independent name returned by Subject.getName. It is optional whenParameterNameis unique among all specified Subjects. It is required when multiple Subjects have the same Parameter name.ParameterNameis the language-independent name returned by Parameter.getName.valueis 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
resultvariable 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:
helplists the available single word commands and other help informationnamesshows available Parameter namesscriptprints a script to recreate current state of application/ simulationurlprints URL of current web page along with script to recreate current statevaluesshows available Parameter names and their current valuesVariables 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
valuescommand)and the variables can be set like any other Parameter with an EasyScript command like
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
scriptmethod 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
scriptmethod 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
PENDULUMSwhich 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%3Dand%3Brespectively:The application should call Terminal.parseURL in order to execute the query URL during application startup.