User Tools
manual:Variables
Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision Last revision Both sides next revision | ||
|
manual:Variables [2019/09/14 18:06] JMichaelTX [Variable Naming Rules] |
manual:Variables [2023/09/29 04:19] peternlewis [Scope] |
||
|---|---|---|---|
| Line 21: | Line 21: | ||
| ^ Scope ^ Availability ^ | ^ Scope ^ Availability ^ | ||
| - | | **Global**, Permanent variables | • Accessible basically everywhere, including Scripts.\\ • You can also see and edit variables in the Preferences.\\ • You can see global variables in the [[Windows#Value_Inspector_Window |Value Inspector]]. | | + | | **Global**, permanent variables | • Accessible basically everywhere, including Scripts.\\ • You can also see and edit variables in the Preferences.\\ • You can see global variables in the [[Windows#Value_Inspector_Window |Value Inspector]]. | |
| - | | **Password**, Semi-permanent variables | • Available to macros but not displayed.\\ • Not directly accessible via AppleScript.\\ • Concealed in password fields in Prompt For User Input actions.\\ • Not saved to disk. | | + | | **Password**, semi-permanent variables | • Name must begin or end with “PW” or “password” (case insensitive).\\ • Available to macros but not displayed.\\ • Not directly accessible via AppleScript.\\ • Concealed in password fields in Prompt For User Input actions.\\ • Not saved to disk. | |
| - | | **Instance** Variables (v8+) | • Name must begin with "instance" (case insensitive).\\ • Restricted to a specific execution sequence.\\ • Available to the Macro where it was created and Sub-Macros of that Macro, for a given execution instance of the main macro.\\ • These Variables are private to each execution of the same Macro, even when running simultaneously.\\ • Accessible by [[action:Prompt_for_User_Input|Prompt For User Input]]\\ • As of v8.0.3, is accessible by scripts (when used in an Execute Script Action).\\ • Accessible by [[action:Custom_HTML_Prompt|Custom HTML Prompt]] (v8.0.3+).\\ • Accessible by AppleScript with the instance specifier. | | + | | **[[#Instance_Variables|Instance Variables]]**, local to a specific macro execution instance | • Name must begin with “instance” (case insensitive).\\ • Restricted to a specific execution sequence.\\ • Available to the Macro where it was created and Sub-Macros of that Macro, for a given execution instance of the main macro.\\ • These variables are private to each execution of the same Macro, even when running simultaneously.\\ • Accessible by [[action:Prompt_for_User_Input|Prompt For User Input]]\\ • Accessible by scripts (when used in an Execute Script Action).\\ • Accessible by [[action:Custom_HTML_Prompt|Custom HTML Prompt]].\\ • Accessible by AppleScript with the `instance` specifier. | |
| - | | **Local** Variables (v8+) | • Name must begin with "local" (case insensitive)\\ • Restricted to the specific Macro it is in.\\ • //Not// available to any of its Sub-Macros\\ • Same accessibility as Instance Variables. | | + | | **[[#Local_Variables|Local Variables ]]**, local to a specific macro | • Name must begin with "local" (case insensitive)\\ • Restricted to the specific Macro it is in.\\ • //Not// available to any of its Sub-Macros\\ • Same accessibility as Instance Variables. | |
| - | | **[[manual:Dictionaries|Dictionary]]**, Permanent, global in scope. | • Accessible basically Everywhere, including Scripts.\\ • Dictionaries consist of the //Dictionary Name//, One or more pairs of //Key Name//, and //Value//.\\ • Although Dictionaries are sort of like structured //Variables//, they are kept in a separate category called //[[manual:Dictionaries|Dictionaries]]//. | | + | |
| Macros can create or read existing variables, which persist and are permanently stored (except Local and Instance variables which are transient, and Password variables which are never saved to disk). | Macros can create or read existing variables, which persist and are permanently stored (except Local and Instance variables which are transient, and Password variables which are never saved to disk). | ||
| - | Variables contain only plain, un-styled, text and may be used in any token text field in an action, as well as in [[Calculations]] in a numerical field. Variable may be used in [[Calculations]] if they contain a valid number or expression. | + | Variables contain only plain, un-styled, text and may be used in any token text field in an action, as well as in [[Calculations]] in a numerical field if they contain a valid number or expression. |
| Line 41: | Line 40: | ||
| ==== Password Variables ==== | ==== Password Variables ==== | ||
| - | Variables with names that start or end with “Password” or “PW” are considered passwords – their values will not be stored (except in memory) and they cannot be read directly by shell scripts or AppleScripts, though their consequences can easily be extracted, eg with the Set Clipboard to Text action, so you should clear them as soon as they have served their purpose. The Prompt For User Input dialog will display such variables concealed in a password field. | + | Variables with names that start or end with “Password” or “PW” are considered passwords – their values will not be stored (except in memory) and they cannot be read directly by shell scripts, JavaScripts or AppleScripts, though their consequences can easily be extracted, eg with the Set Clipboard to Text action, so you should clear them as soon as they have served their purpose. The Prompt For User Input dialog will display such variables concealed in a password field. |
| - | ==== Instance Variables (v8+) ==== | + | ==== Instance Variables ==== |
| - | Variables with names that start with "Instance" (case insensitive, trailing space not necessary) are considered private to a specific execution sequence. Each time the macro is run, they will start empty but their value can be seen and changed by other macros within the same execution sequence (for example, if you execute a macro using the [[action:Execute_a_Macro|Execute Macro]] action, that macro can see and change the instance variable). Since two instances of a macro can be running at the same time, this is useful to ensure they each have their own version of the variable. | + | Variables with names that start with "Instance" (case insensitive, trailing space not necessary) are considered private to a specific execution sequence. Each time the macro is run, they will start empty but their value can be seen and changed by other macros within the same execution sequence (for example, if you execute a macro using the [[action:Execute_a_Macro|Execute Macro]] action, that macro can see and change the instance variable (unless you execute it asynchronously which would create a new instance)). Since two instances of a macro can be running at the same time, this is useful to ensure they each have their own version of the variable. |
| Since Local and Instance variables are transient, they are not shown in the [[manual:Preferences#Variables_Preferences| Variables preferences pane]]. | Since Local and Instance variables are transient, they are not shown in the [[manual:Preferences#Variables_Preferences| Variables preferences pane]]. | ||
| - | ==== Local Variables (v8+) ==== | + | ==== Local Variables ==== |
| Variables with names that start with "Local" (case insensitive, trailing space not necessary) are considered local to a specific execution of a specific macro. Each time the macro is run, they will start empty and no other macro will see or be able to change values. | Variables with names that start with "Local" (case insensitive, trailing space not necessary) are considered local to a specific execution of a specific macro. Each time the macro is run, they will start empty and no other macro will see or be able to change values. | ||
| **Note that //Local// and //Instance// Variables are available in scripts //only// when the script is called in an //Execute Script// action, ** unless you specify the execution instance explicitly. | **Note that //Local// and //Instance// Variables are available in scripts //only// when the script is called in an //Execute Script// action, ** unless you specify the execution instance explicitly. | ||
| - | |||
| - | For a good discussion on the new Version 8 Local and Instance Variables, see this Forum topic:\\ | ||
| - | [[https://forum.keyboardmaestro.com/t/km8-local-and-instance-variables/7946|KM8: Local and Instance Variables]] | ||
| ===== Setting Variables ===== | ===== Setting Variables ===== | ||
| Line 69: | Line 65: | ||
| This action processes the tokens and backslashed characters in the text and sets the variable. As will all [[:Text_Fields|text fields]], if you wish to use another variable in the text you must use the [[token:Variable|%Variable%]] token, eg `The value is %Variable%VarName%`. | This action processes the tokens and backslashed characters in the text and sets the variable. As will all [[:Text_Fields|text fields]], if you wish to use another variable in the text you must use the [[token:Variable|%Variable%]] token, eg `The value is %Variable%VarName%`. | ||
| - | You can also use the [[action:Set_Variable_to_Calculation]] action. This action evaluates the numeric expression and then sets the variable to the result. As with all numeric fields, if you wish to use another variable in the calculation, you use the variable unadorned, eg `VarName * 3`. | + | You can also use the [[action:Set_Variable_to_Calculation|Set Variable to Calculation]] action. This action evaluates the numeric expression and then sets the variable to the result. As with all numeric fields, if you wish to use another variable in the calculation, you use the variable unadorned, eg `VarName * 3`. |
| - | There are many other actions that set variables. | + | There are many other [[:Actions|actions]] that set variables. |
| ===== Using Variables ===== | ===== Using Variables ===== | ||
| Line 97: | Line 93: | ||
| - | While technically all Variables are just strings, you can access a variable as if it were an array (v7.2+) by setting the Variable to a delimited list of text, and then using the following notation: | + | While technically all Variables are just strings, you can access a variable as if it were an array by setting the Variable to a delimited list of text, and then using the following notation: |
| `%Variable%<VariableName>[<IndexNumber>]%` | `%Variable%<VariableName>[<IndexNumber>]%` | ||
| Line 123: | Line 119: | ||
| {{:manual:variable-array-example-for-each.png?nolink|}} | {{:manual:variable-array-example-for-each.png?nolink|}} | ||
| - | |||
| - | For a **real-world example**, see this Forum post: [Combine Two Lists Using Keyboard Maestro Variable Array](https://forum.keyboardmaestro.com/t/easiest-way-to-align-2-collections/8372/5) | ||
| ==== Variables in Calculation Fields ==== | ==== Variables in Calculation Fields ==== | ||
| Line 134: | Line 128: | ||
| === Variable Dot Notation === | === Variable Dot Notation === | ||
| - | In a Calculation field you can reference the numbers in a variable (which is always a string) using dot notation: | + | In a Calculation field you can reference the numbers in a variable which contains a coordinate or rectangle (which is always a string, eg "100,100,200,200") using dot notation: |
| | Variable.x | x coordinate | | | Variable.x | x coordinate | | ||
| Line 166: | Line 160: | ||
| ===== Deleting Variables ===== | ===== Deleting Variables ===== | ||
| - | * //Global// Variables, including //Password// Variables, continue to exist (remained stored) until their value is set to `""`, the empty string. | + | * //Global// Variables continue to exist (remained stored) until their value is set to `""`, the empty string, even when the Keyboard Maestro Engine is quit and relaunched. |
| + | * //Password// Variables, continue to exist (remained stored) until their value is set to `""`, the empty string, or until you quit the Keyboard Maestro Engine. | ||
| * Setting a Variable to `%Delete%` does //not// technically delete it. It continues to exist. It is just //hidden// from view in all of the Variable lists and in the //Preferences//. | * Setting a Variable to `%Delete%` does //not// technically delete it. It continues to exist. It is just //hidden// from view in all of the Variable lists and in the //Preferences//. | ||
| * However, a Variable set to `%Delete%` will behave as if it does //not// exist in most Actions, like a [[action:If_Then_Else|If Then Else]] Action using a //Variable Condition// comparing to //exists//. | * However, a Variable set to `%Delete%` will behave as if it does //not// exist in most Actions, like a [[action:If_Then_Else|If Then Else]] Action using a //Variable Condition// comparing to //exists//. | ||
| - | It may be a good idea to set a Variable to `""` do if you no longer need it, or if it contains sensitive information (like a password) or a large value (like a file or web page contents). | + | It may be a good idea to set a Variable to `""` if you no longer need it, or if it contains sensitive information (like a password) or a large value (like a file or web page contents). |
| Perhaps the best way to avoid variable clutter and eliminate sensitive and/or large values is to use either //Local// or //Instance// Variables when you do not need the Variable after completion of the Macro in which the Variable is used. | Perhaps the best way to avoid variable clutter and eliminate sensitive and/or large values is to use either //Local// or //Instance// Variables when you do not need the Variable after completion of the Macro in which the Variable is used. | ||
| Line 183: | Line 178: | ||
| ===== View Your Entire List of Variables ===== | ===== View Your Entire List of Variables ===== | ||
| - | You can add, delete, see or change global variables in the [[Windows#Preferences_Variables_Pane|Variables preference pane]] that have been created by your macros and scripts. There are no variable preferences to be set here. This is sometimes called the "Variables Panel" or "Variables Tab" in Keyboard Maestro Preferences. | + | You can add, delete, see or change global variables in the [[Windows#Preferences_Variables_Pane|Variables preference pane]] that have been created by your macros and scripts. |
| Local and Instance Variables are _not_ accessible from either the Preferences Window. | Local and Instance Variables are _not_ accessible from either the Preferences Window. | ||
manual/Variables.txt · Last modified: 2023/09/29 04:44 by peternlewis
Page Tools
