This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision Next revision Both sides next revision | ||
Variables [2016/07/31 19:57] JMichaelTX REVISE intro to clarify unique aspects of KM vars |
Variables [2017/09/20 01:07] peternlewis [Local Variables] |
||
---|---|---|---|
Line 1: | Line 1: | ||
====== Keyboard Maestro Variables ====== | ====== Keyboard Maestro Variables ====== | ||
- | Keyboard Maestro variables are used much like variables in any scripting or macro language. They provide for the storage of data (only plain text) as determined by you, the Keyboard Maestro user. | + | Keyboard Maestro [[manual:Variables|variables]] are used much like variables in any scripting or macro language. They provide for the storage of data (only plain text, no styles) as determined by you, the Keyboard Maestro user. |
===== Key Facts about Variables ===== | ===== Key Facts about Variables ===== | ||
- | **Keyboard Maestro Variables have some aspects that are quite different from traditional programming languages:** | + | Keyboard Maestro has four types of variables, distinguished based on their name. |
- | * Each Macro generally creates its own Variables, but it can use existing Variables | + | * [[#Password_Variables|Password Variables]] — names start or end with "Password" or "PW". |
- | * **All Variables persist, permanently stored on your Mac (much like a file) until deleted** | + | * [[#Local_Variables|Local Variables]] — names start or end with "Local " or "𝕃". |
- | * All Variables are global, fully accessible (create, read, write, delete) by: | + | * [[#Instance_Variables|Instance Variables]] — names start or end with "Instance " or "𝕀". |
- | * All other Macros | + | * Variables — All other variables. |
- | * Future executions of the same macro | + | |
- | * Scripts | + | As described in the [[manual:Variables|user manual]], variables contain text, but may be used as numbers in calculations if they contain a valid expression (eg "10*5"). |
- | * //Keyboard Maestro Editor Preferences// panel (Variables tab) | + | |
- | * :!: **Note:** When deleted, there is no warning, and there is no _Trash_ to recover deleted Variables from | + | * Each Macro may create Variables and read existing Variables. |
- | * **All Keyboard Maestro variables can contain only plain text**. | + | * Variables persist, permanently stored on your Mac (much like a file) until deleted. |
- | * However, you can use variables that contain numbers in calculations, by using the [[token:Calculate|Calculate Token]]. | + | * Variables are global, fully accessible (create, read, write, delete) by: |
+ | * All other Macros. | ||
+ | * Future or simultaneous executions of some macro. | ||
+ | * Scripts. | ||
+ | * AppleScript. | ||
+ | * //Keyboard Maestro Editor Preferences// panel (Variables tab). :!: **Note:** When deleted, there is no warning, and there is no _Trash_ to recover deleted Variables from. | ||
+ | * **All Keyboard Maestro variables can contain only plain text**. | ||
+ | * However, you can use variables that contain numbers in calculations in [[https://wiki.keyboardmaestro.com/Text_Fields|numeric fields]], or by using the [[token:Calculate|Calculate Token]] in [[https://wiki.keyboardmaestro.com/Text_Fields|text fields]]. | ||
Line 30: | Line 37: | ||
There are a number of other [[:Actions|Actions]] to set variables: | There are a number of other [[:Actions|Actions]] to set variables: | ||
* [[action:Set_Variable_to_Calculation]] | * [[action:Set_Variable_to_Calculation]] | ||
- | * [[action:Set_Variable_to_Google_Chrome_Field]] | + | * [[actions:Browser_Form_Actions#Set_Variable_to_Field|Set Variable to Browser Field]] |
* [[action:Set_Variable_to_Keychain_Password]] | * [[action:Set_Variable_to_Keychain_Password]] | ||
- | * [[action:Set_Variable_to_Safari_Field]] | ||
- | In addition to these, there are a number of more complex Actions that can also set a variable. The [[action:For_Each|For Each]] Action is an example. | + | In addition to these, there are a number of more complex Actions that can also set a variable. The [[action:For_Each|For Each]] Action is an example. Variables can also contain the results of many actions, such as the [[action:Execute_a_Shell_Script|Execute a Shell Script]] action. |
When setting a variable, you will be using a text field in most cases. :!: Be aware that [[:Text_Fields|Text fields]] (that are not regular expression fields), process backslashed characters \a,\b,\e,\f,\t,\r,\n (bell,backspace,escape,form feed,tab,return,line feed). For more information, see the [[:Text_Fields|Text fields]] Wiki article. | When setting a variable, you will be using a text field in most cases. :!: Be aware that [[:Text_Fields|Text fields]] (that are not regular expression fields), process backslashed characters \a,\b,\e,\f,\t,\r,\n (bell,backspace,escape,form feed,tab,return,line feed). For more information, see the [[:Text_Fields|Text fields]] Wiki article. | ||
- | |||
===== Using Variables ===== | ===== Using Variables ===== | ||
Line 45: | Line 50: | ||
The //%Variable%//`<VariableName>`% token allows you to include a variable in a token text field,\\ | The //%Variable%//`<VariableName>`% token allows you to include a variable in a token text field,\\ | ||
- | where `<VariableName>` is the name of the variable. | + | where `<VariableName>` is the name of the variable. |
For Example, using the [[action:Insert_Text|Insert Text]] Action: | For Example, using the [[action:Insert_Text|Insert Text]] Action: | ||
Line 51: | Line 56: | ||
{{ :token:km-wiki-insert-text-action.png?nolink |}} | {{ :token:km-wiki-insert-text-action.png?nolink |}} | ||
- | You can (v7.2+) access a variable as if it is a comma separated array of text using the notation //%Variable%//`<VariableName>[3]`% where 3 can be any [[manual:Calculations|Calculations]]. You can use a different item separator b=y putting the text between the ] and % characters, eg //%Variable%//`<VariableName>[3]:`%. | + | You can (v7.2+) access a variable as if it is a comma separated array of text using the notation //%Variable%//`<VariableName>[3]`% where 3 can be any [[manual:Calculations|Calculations]]. You can use a different item separator by putting the text between the ] and % characters, eg //%Variable%//`<VariableName>[3]:`%. Arrays are indexed starting from 1. |
You can also use a short form of just //%Variable Name%// to include variables as long as the variable exists and has a value and there is no corresponding text token, although generally it is better and clearer to use the longer form //%Variable%Variable Name%//. | You can also use a short form of just //%Variable Name%// to include variables as long as the variable exists and has a value and there is no corresponding text token, although generally it is better and clearer to use the longer form //%Variable%Variable Name%//. | ||
+ | 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. | ||
- | ==== Variable Arrays ==== | + | ==== Variables in Calculations ==== |
- | Variables can contain an array of comma separated **numbers**, like the image size (123,456) or window frame (100,120,600,550). In a calculation field, you can refer to these using a normal (1-based) index notation, like Variable[2]. So you can use ClipboardImageSize[1] and ClipboardImageSize[2]. | + | 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`. If a variable contains a sequence of comma-separated numbers, it can be accessed as an array, for example `My Variable[7]`, or using dot notation, for example `My Variable.x`. See the [[manual:Calculations#Variable_Array_Access|Calculations]] user manual section for more information on calculations and using variables in numeric fields. |
- | + | ||
- | **It is important to note that variable arrays can contain only numeric values**. When you use the [[token:Calculate|%Calculate%]] function to reference a variable array element, it will convert the element to a number. So, in effect, you can only use variable arrays to store/reference numbers. | + | |
- | + | ||
- | For example, suppose the variable `MyArray` has this value: `10,05,00,12`. In any Keyboard Maestro Action where you would like to use the array element `%Calculate%MyArray[2]%`, it will return "5" because it has evaluated it as number, not the actual string of the element "05". | + | |
===== Using Variables in Scripts ===== | ===== Using Variables in Scripts ===== | ||
Line 71: | Line 73: | ||
* [[action:Execute_a_JavaScript_in_Google_Chrome|JavaScript in Safari or Google Chrome]]\\ | * [[action:Execute_a_JavaScript_in_Google_Chrome|JavaScript in Safari or Google Chrome]]\\ | ||
* (Browser JavaScript can only GET Keyboard Maestro Variables. They cannot be set there) | * (Browser JavaScript can only GET Keyboard Maestro Variables. They cannot be set there) | ||
- | * [[action:Custom_HTML_Prompt|JavaScript in Custom HTML Prompts]] | + | * [[action:Custom_HTML_Prompt#Using_JavaScript|JavaScript in Custom HTML Prompts]] |
* [[action:Execute_a_Shell_Script|Shell Scripts]] | * [[action:Execute_a_Shell_Script|Shell Scripts]] | ||
* [[action:Execute_a_Swift_Script|Swift Scripts]] | * [[action:Execute_a_Swift_Script|Swift Scripts]] | ||
Line 79: | Line 81: | ||
Click on the above links for example scripts. | Click on the above links for example scripts. | ||
- | ===== See Also ===== | + | ===== 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. The Prompt For User Input dialog will display such variables in a password field. |
+ | |||
+ | You should set their values immediately after you are done with the password to reduce any change of erroneous access. | ||
+ | |||
+ | ===== Local Variables ===== | ||
+ | |||
+ | Variables with names that start with “Local ” (“Local ” with a space, then the rest of the variable name, eg “Local Count”) are considered local (v8+) to a specific instance 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. | ||
+ | ===== Instance Variables ===== | ||
+ | |||
+ | Variables with names that start with “Instance ” or a double-struck I (𝕀) are considered local (v8+) 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. | ||
+ | |||
+ | |||
+ | |||
+ | ===== See Also ===== | ||
=== Actions === | === Actions === | ||
Line 88: | Line 103: | ||
* [[action:Set Variable to Text|Set Variable to Text]] | * [[action:Set Variable to Text|Set Variable to Text]] | ||
* [[:Actions|See all Actions]] | * [[:Actions|See all Actions]] | ||
- | |||
- | ---- | ||
==== Forum ==== | ==== Forum ==== | ||
Line 96: | Line 109: | ||
- [[https://forum.keyboardmaestro.com/t/proper-syntax-for-array-of-arrays/4506/5|Proper Syntax for Array of Arrays?]] | - [[https://forum.keyboardmaestro.com/t/proper-syntax-for-array-of-arrays/4506/5|Proper Syntax for Array of Arrays?]] | ||
- | - [[https://www.google.fr/search?q=site:forum.keyboardmaestro.com+Keyboard+Maestro+Variables|Keyboard Maestro Forum topics about Keyboard Maestro Variables]] | + | - [[https://forum.keyboardmaestro.com/tags/variables|Keyboard Maestro Forum topics about Keyboard Maestro Variables]] |
- | array of text | + | - [[https://forum.keyboardmaestro.com/search?q=%22array%20of%20text%22|Keyboard Maestro Forum topics about Keyboard Maestro Array of Text]] |
- | - [[https://www.google.fr/search?q=site:forum.keyboardmaestro.com+array+of+text|Keyboard Maestro Forum topics about Keyboard Maestro Array of Text]] | + |