User Tools

Site Tools


manual:Variables

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
Next revision Both sides next revision
manual:Variables [2018/08/05 21:56]
peternlewis
manual:Variables [2019/09/14 18:18]
JMichaelTX
Line 1: Line 1:
 ====== Variables ====== ====== Variables ======
  
-Like most programming languages, Keyboard Maestro allows you, the Macro builder, ​to create Variables to store data for use later on in the same Macro, or in other Macros.  ​Soyour use of Variables can include ​the following:+Like most programming languages, Keyboard Maestro allows you to create Variables to store data for use later on in the same Macro, or in other Macros
 + 
 +Variables can be set from many actions.  ​You can set variables to specific [[manual:​Tokens| tokenised]] textto the result ​of a [[manual:​Calculations| calculations]],​ from user input, from the Keychain, by searching other variables, from the [[token:CurrentClipboard| clipboard]] or [[token:​NamedClipboard|Named Clipboards]],​ as the result of [[:​Scripting|scripts]],​ and from many other sources. 
 + 
 +===== Variable Naming Rules ===== 
 + 
 +Anywhere an [[:​Actions|Action]] requires a Variable, you can enter any name you like (even though often  a default name is provided), as long as it conforms to these rules: 
 +  - Variable names must start with a letter, and then can contain letters, numbers, spaces, or underscores. 
 +  - Some Variable kinds require a specific prefix (see _Scope_ below). 
 +  - Variable names are case insensitive,​ but their case is remembered. 
 +  - Variable names should not include a function or operator name with spaces around it. 
 +     *(eg “ MOD ” , so “A MOD B” would not be a valid variable, although “MODULE” would be fine).
  
-* Set a Variable using any of these [[:​Actions|Macro Actions]]: 
-  * [[action:​Set_Variable_to_Text|Set Variable to Text Action]] 
-  * [[action:​Set_Variable_to_Calculation|Set Variable to Calculation Action]] 
-  * [[action:​Prompt_for_User_Input|Prompt For User Input]] and other _Prompt_ Actions 
-  * [[action:​Search_Variable|Capture Groups from RegEx Search]] of Variable or Clipboard 
-  * The [[token:​CurrentClipboard|System Clipboard]] and [[token:​NamedClipboard|Named Clipboards]] 
-  * Other [[:​Actions|Macro Actions]] 
-  * Other [[:​Tokens|Tokens]] 
-* Get or Set Keyboard Maestro Variables using [[:​Scripting|Scripting]] 
-* Reference a Variable using the [[token:​Variable|Variable Token]]: ​ `%Variable%YourVarName%` 
-* And other means discussed below. 
  
 ===== Scope ===== ===== Scope =====
  
  
-Keyboard Maestro includes variables with three different scopes ​of allowed access, in order of scope, with broadest scope first:+Keyboard Maestro includes variables with different ​breadth or scopes, in order of scope, with broadest scope first:
  
 ^ Scope ^ Availability ^ ^ Scope ^ Availability ^
-| **Global**, Permanent variables | • Available Everywhere, including Scripts and Preferences. | +| **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**, ​Permanent ​variables | • Available to macros but not displayed.\\ • Not directly accessible via AppleScript.\\ ​Displayed ​in password fields in Prompt For User Input actions. | +| **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. | 
-| **Instance** Variables (v8+) | • 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.\\ • So these Variables are private to each execution of the same Macro, even when running simultaneously.\\ • Available to [[action:​Prompt_for_User_Input|Prompt For User Input]]\\ • As of v8.0.3, is available to scripts (when used in an Execute Script Action)[[action:​Custom_HTML_Prompt|HTML Prompt]] | +| **[[#​Instance_Variables_v8|Instance]]** Variables (v8+)\\ Auto-deleted when Macro terminates ​• 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. ​
-| **Local** Variables (v8+) | • Restricted to Macro where it was created\\ • //​Not// ​Available ​to any of its Sub-Macros\\ • Available to [[action:​Prompt_for_User_Input|Prompt For User Input]]\\ • As of v8.0.3, is available to scripts (when used in an Execute Script Action), [[action:​Custom_HTML_Prompt|HTML Prompt]] ​+| **[[#​Local_Variables_v8|Local]]** Variables (v8+)\\ Auto-deleted when Macro terminates ​• 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. | • Available Almost ​Everywhere, including Scripts, but //not// Preferences.\\ • Dictionaries consist of the //​Dictionary Name//, One or more pairs of //Key Name//, and //Value//\\ • Although Dictionaries are like //​Variables//,​ they are kept in a separate category called //​[[manual:​Dictionaries|Dictionaries]]//​. |+| **[[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).+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 text field in an action, as well as in [[Calculations]] in a numerical field, or within the in [[token:​Calculate|Calculate Token]].  Variable may be used in [[Calculations]] if they contain a valid number or expression.+Variables contain only plainun-styledtext 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.
  
  
Line 38: Line 38:
  
 Global Variables are permanently stored on your Mac drive (like a file), and are available for read/write in any Macro or Action, not just the Macro where the Variable was created. ​ These variables persist between logins and restarts of your Mac. Global Variables are permanently stored on your Mac drive (like a file), and are available for read/write in any Macro or Action, not just the Macro where the Variable was created. ​ These variables persist between logins and restarts of your Mac.
- 
-Variable names must start with a letter, and then can contain letters, numbers, spaces, or underscores. ​ Variable names are case insensitive,​ but their case is remembered. Variable names should not include a function or operator name with spaces around it (eg " MOD " , so "A MOD B" would not be a valid variable, although "​MODULE"​ would be fine). 
  
 ==== 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 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 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 (v8+) ====
  
-Variables with names that start with "​Instance"​ (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 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). ​ 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]].
Line 54: Line 52:
 ==== Local Variables (v8+) ==== ==== Local Variables (v8+) ====
  
-Variables with names that start with "​Local"​ (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.**+**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:\\ For a good discussion on the new Version 8 Local and Instance Variables, see this Forum topic:\\
Line 77: Line 75:
 ===== Using Variables ===== ===== Using Variables =====
  
-There are many Macro Actions that can use variables. ​ Some of these explicitly provide for entry of the variable name, but most provide for a more general text entry that accepts either token text or a numeric expression. ​ +There are many Macro Actions that can use variables. ​ Some of these explicitly provide for entry of the variable name, but most provide for a more general text entry that accepts either token text or a numeric expression.
  
 When editing a field: When editing a field:
Line 126: Line 124:
 {{:​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 KM Variable Array](https://​forum.keyboardmaestro.com/​t/​easiest-way-to-align-2-collections/​8372/​5)+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 ====
  
-Variables can be used in calculations if their value holds a number or a numeric expression that can be evaluated. ​ Variables are used *unadorned* in calculations,​ for example `My Variable * 7`.  +Variables can be used in calculations if their value holds a number or a numeric expression that can be evaluated. ​ Variables are used *unadorned* in calculations,​ for example `My Variable * 7`.
  
 You can also access variables in a token field numerically using the [[token:​Calculate|%Calculate%]] token. ​ **It is important to note that calculations can contain only numeric values**. ​ When you use the [[token:​Calculate|%Calculate%]] token to reference a variable or variable array element, it will convert the element to a number. You can also access variables in a token field numerically using the [[token:​Calculate|%Calculate%]] token. ​ **It is important to note that calculations can contain only numeric values**. ​ When you use the [[token:​Calculate|%Calculate%]] token to reference a variable or variable array element, it will convert the element to a number.
Line 168: Line 166:
 ===== 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, including //​Password//​ Variables, continue to exist (remained stored) until their value is set to `""​`,​ the empty string. 
-    * 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//.
-  * //​Dictionaries//​ continue to exist as long as there is at least one //Key// that has a value that is not `""​`. +
-  * //​Dictionary Keys// continue to exist until their value is set to `""​`.+
  
  
Line 181: Line 177:
 ===== Inserting In Actions ===== ===== Inserting In Actions =====
  
-You can add a variable to an action using the [[Menus#Edit_Insert_Variable|Insert Variable menu]] ​in the [[Menus#Edit|Edit menu]] or [[Menus#​Edit_Insert_Function_Variable|Variable menu]] in the [[Menus#​Edit_Insert_Function|Insert Function ​sub-menu]] ​in the [[Menus#Edit|Edit menu]] or [[Menus#​Edit_Insert_Token_Variable|Variable menu]] in the [[Menus#​Edit_Insert_Token|Insert Token sub-menu]] in the [[Menus#​Edit|Edit ​menu]], or by selecting from the popup menu next to some variable fields.+You can add a variable to an action using the [[Menus#Insert_Variable|Edit ➤ Insert Variable menu]] ​or [[Menus#Insert_Function|Edit ➤ Insert Function ​➤ Variable ​menu]] ​or [[Menus#Insert_Token|Edit ➤ Insert Token ➤ Variable ​menu]], or by selecting from the popup menu next to some variable fields.
  
 Fields that expect just a variable show a small BUTTON{{{V}}} in the field while editing it, and you can use Type Completion to complete variable names in such fields. Fields that expect just a variable show a small BUTTON{{{V}}} in the field while editing it, and you can use Type Completion to complete variable names in such fields.
Line 189: Line 185:
 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. ​ There are no variable preferences to be set here.  This is sometimes called the "​Variables Panel" or "​Variables Tab" in Keyboard Maestro Preferences.
  
-Local and Instance Variables are _not_ accessible from either the Preferences Window ​or from Scripting.+Local and Instance Variables are _not_ accessible from either the Preferences Window
 + 
 +===== Watching a Variable’s Value ===== 
 + 
 +You can use the [[Windows#​Value_Inspector_Window |Value Inspector]] to watch the value of a global variable.
  
manual/Variables.txt · Last modified: 2023/09/29 04:44 by peternlewis