Difference between revisions of "Analytica Script"

Latest revision as of 21:59, 17 October 2017

Analytica Script is a variant of the standard Analytica modeling language with a slightly different and more limited syntax. It is now rare that Analytica users need to learn about Script, since most of its commands are now have equivalent Functions in the standard Analytica language -- for example, CreateObject, ShowWindow, CloseWindow. The main use of Analytica Script is in the Typescript window, an interpreted text-based user-interface to Analytica. The Typescript is a relic of predecessor to Analytica, now used only occasionally by Analytica experts -- usually as an aid for debugging. Analytica Script is required in the Script attribute of a Button or Picture, but this attribute is now obsolete, having been replaced by the OnClick, and OnChange attributes, which use standard Analytica syntax. The Script attribute is retained only for legacy models. This page (and its links) are for those intrepid few that still want to learn about Script.

You can define Scripts in:

The Script Attribute of a Button, Picture, or input varibale. The Script is executed when the end user clicks the button, or changes the definition of an Input variable. The Script attribute is deprecated, having been replaced in Analytica 4.6 by OnClick, and OnChange attributes, which use standard Analytica syntax, and also allow assignment to Global variables.

The Typescript Window: Press Ctrl+' (control+apostrophe) to open this window. It offers a command line interface to Analytica.
In the special function EvaluateScript(script), which may be used in normal Analytica language. It evaluates its text parameter, script, as a script, and so lets you execute a script anywhere -- very powerful and a bit dangerous.

Button Scripts

You create a button in a Diagram like any other object type:

In Edit mode, drag the button icon from the far right of node type toolbar to the position on the diagram you want (or press control-0).
Double-click the button to open its Object Window.

Now you can review and edit its Script attribute.

Choice and Checkbox variables

You can add a Script that gets executed when the user selects a new Choice or (un)checks a Checkbox for a user-input variable defined as Choice(i, n) or as Checkbox(bool):

If Script attribute does not appear in Object view of the variable, you set it to appear:

In Edit mode, select Attributes... from the Object menu.
In the list of attributes, scroll down until you find Script. Check it, and click OK.

You can then type into the Script attribute of a selected variable.

Script syntax

Each line in a Script may be a standard expression from the Analytica language, such as a call to a function. There are some minor differences in syntax: You can put expressions or commands on separate lines, without needing a semicolon ";" between the lines

Assigning to globals

Within a Script, you can assign a new Definition or other Attribute to a global Variable, e.g.

Y := X + 100

Definition OF Y --> X + 100

When you execute the script (e.g. click the button), it assigns X + 100 as the new Definition of Y.

If you enclose the assignment in parentheses, it assigns the value, rather than the expression, as the new Definition:

(Y := X + 100)

Definition OF Y --> 110

Analytica does not usually let you assign a new value to the Definition (or other Attribute) of a Global variable (or other Object). This is to maintain the no side-effects rule, which makes Analytica models so much easier to understand and debug than normal programs. Computer scientists would say it is a functionalrather than procedurallanguage.
But, sometimes you do want to write a procedure that makes assignments to Global (i.e. nonlocal) variables. You may also include assignments to Globals in a Function that is called from a Button script -- or from a Function that is called from a Function called from a Button script, etc. In this case, the end user is explicitly pressing the button and initiating the change to the model -- and so, side-effects are allowed.

Script Commands

A third key difference of Scripts is that the availability of a variety of Script commands -- e.g.

Open Object Y

opens the Object window of Y. Script commands take a list of parameters, usually object names, without parentheses around the parameters and without separating commas.

These Script commands are mostly a relic of Demos, an early predecessor of Analytica. Some no longer work or are otherwise deprecated (discouraged), but a few can be useful for special purposes. For more, see Commands and Scripting Guide.

@@ Line 1: / Line 1: @@
+[[Category: Typescript Commands]]
+[[Category:Doc_Status_D]]
   <!-- For Lumina use, do not change -->
-Analytica Script is a variant of the Analytica modeling language used in Definitions. &nbsp;It is of value to advanced users, and may be ignored by most users. &nbsp;Most useful, you can assign new definitions and other attributes to global variables in a Script. (Assignments to global variables are not allowed in Analytica definitions, except in user-defined functions called from a Script, directly or indirectly.) &nbsp;You can use a range of special Scripting Commands in a Script, such as commands to open or close Windows, which are&nbsp;not available in the standard modeling language. &nbsp;Scripts have&nbsp;some slight differences in syntax from the standard language, described below.&nbsp;
+Analytica Script is a variant of the standard Analytica modeling language with a slightly different and more limited syntax.  It is now rare that Analytica users need to learn about Script, since most of its commands are  now have equivalent Functions in the standard Analytica language -- for example, [[CreateObject]], [[ShowWindow]], [[CloseWindow]]. The main use of Analytica Script is in the Typescript window,  an interpreted text-based user-interface to Analytica. The Typescript is a relic of predecessor to Analytica, now  used only occasionally by Analytica experts -- usually as an aid for debugging.   Analytica Script is required in the Script attribute of a Button or Picture, but this attribute is now obsolete, having been replaced by the  [[OnClick]], and [[OnChange]] attributes, which use standard Analytica syntax. The Script attribute is retained only for legacy models.  This page (and its links) are for those intrepid few that still  want to learn about Script.
+__TOC__
 You can define Scripts in:
-*The Script Attribute of a Button. The Script is executed when the end user clicks the button.
+* The Script Attribute of a Button, Picture, or input varibale. The Script is executed when the end user clicks the button, or changes the definition of an Input variable.  The Script attribute is deprecated, having been replaced in Analytica 4.6 by [[OnClick]], and [[OnChange]] attributes, which use standard Analytica syntax, and also allow assignment to Global variables.
-*The Script Attribute of a Variable defined as a&nbsp;Choice or Checkbox user input. The Script is executed when the user changes the selection from the Choice, or the check in a Checkbox.
-*The Typescript Window: Press control+' (control+apostrophe) to open this window. It offers a command line interface to Analytica.
+* The Typescript Window: Press ''Ctrl+''' (''control+apostrophe'') to open this window. It offers a command line interface to Analytica.
-*In the special function EvaluateScript(script), which may be used in normal Analytica language. It evaluates its text parameter, script, as a script, and so lets you execute a script anywhere -- very powerful and a bit dangerous.
+*In the special function [[EvaluateScript]](script), which may be used in normal Analytica language. It evaluates its text parameter, script, as a script, and so lets you execute a script anywhere -- very powerful and a bit dangerous.
 === Button Scripts  ===
 You create a button in a Diagram like any other object type:
@@ Line 21: / Line 24: @@
 === Choice and Checkbox variables ===
-You can add a Script that gets executed when the user selects a new Choice or (un)checks a Checkbox for a user-input variable defined as Choice(i, n) or as Checkbox(bool):
+You can add a Script that gets executed when the user selects a new Choice or (un)checks a Checkbox for a user-input variable defined as [[Choice]](i, n) or as [[Checkbox]](bool):
 If Script attribute does not appear in Object view of the variable, you set it to appear:
-#In Edit mode, select '''Attributes...''' from the '''Object '''menu.<br>
+#In Edit mode, select '''Attributes...''' from the [[Object menu]].
-#In the list of attributes, scroll down until you find Script. Check it, and click '''OK'''.
+#In the list of attributes, scroll down until you find ''Script''. Check it, and click '''OK'''.
 You can then type into the Script attribute of a selected variable.
 === Script syntax  ===
 Each line in a Script may be a standard expression from the Analytica language, such as a call to a function. There are some minor differences in syntax:&nbsp;You can put expressions or commands on separate lines, without needing a semicolon ";" between the lines
 === Assigning to globals  ===
+Within a [[Script]], you can assign a new [[Definition]] or other Attribute to a global Variable, e.g.
-Within a Script, you can assign a new Definition or other Attribute to a global Variable, e.g.
+:<code>Y&nbsp;:= X + 100</code>
+:<code>Definition OF Y --&gt; X + 100</code>
-   Y&nbsp;:= X + 100
+When you execute the script (e.g. click the button), it assigns <code>X + 100</code> as the new Definition of <code>Y</code>.
-  Definition OF Y --&gt; X + 100
-When you execute the script (e.g. click the button), it assigns X + 100 as the new Definition of Y.
 If you enclose the assignment in parentheses, it assigns the value, rather than the expression, as the new Definition:
-  (Y&nbsp;:= X + 100)
+:<code>(Y&nbsp;:= X + 100)</code>
- Definition OF Y --&gt; 110
+:<code>Definition OF Y --&gt; 110</code>
-Analytica does not usually let you assign a new value to the Definition (or other Attribute) of a Global variable (or other Object). This is to maintain the '''''no side-effects rule''''', which makes Analytica models so much easier to understand and debug than normal programs. Computer scientists would say it is a '''''functional'''''rather than '''''procedural'''''language.<br>But, sometimes you do want to write a procedure that makes assignments to Global (i.e. nonlocal) variables. You may also include assignments to Globals in a Function that is called from a Button script -- or from a Function that is called from a Function called from a Button script, etc. In this case, the end user is explicitly pressing the button and initiating the change to the model -- and so, side-effects are allowed.
+Analytica does not usually let you assign a new value to the [[Definition]] (or other Attribute) of a Global variable (or other Object). This is to maintain the '''''no side-effects rule''''', which makes Analytica models so much easier to understand and debug than normal programs. Computer scientists would say it is a '''''functional'''''rather than '''''procedural'''''language.<br>But, sometimes you do want to write a procedure that makes assignments to Global (i.e. nonlocal) variables. You may also include assignments to Globals in a Function that is called from a Button script -- or from a Function that is called from a Function called from a Button script, etc. In this case, the end user is explicitly pressing the button and initiating the change to the model -- and so, side-effects are allowed.
 === Script Commands ===
+A third key difference of Scripts is that the availability of a variety of [[:Category:Typescript Commands|Script commands]] -- e.g.
-A third key difference of Scripts is that the availability of a variety of Script commands -- e.g.
+:<code>Open Object Y</code>
-  Open Object Y
-opens the Object window of Y. Script commands take a list of parameters, usually object names, ''without parentheses around the parameters and without separating commas''.
+opens the '''Object''' window of <code>Y</code>. Script commands take a list of parameters, usually object names, without parentheses around the parameters and without separating commas.
 These Script commands are mostly a relic of Demos, an early predecessor of Analytica. Some no longer work or are otherwise deprecated (discouraged), but a few can be useful for special purposes.  For more, see [[:Category:Typescript Commands|Commands]] and [[Scripting Guide]].
-=== <br> ===
+=== See Also ===
+* [[Script]]
-[[Category:Doc_Status_D]]
+* [[EvaluateScript]]
+* [[OnClick]]
+* [[OnChange]]
+* [[Scripting Guide]]
+* [[Commands]]
+* [[:Category:Typescript Commands]]