The Important Distinction Between Local and Instance Variables

Tips & Tutorials
1

Reference: Variables in the KM Wiki

==Yes, there is good reason to use both Local and Instance Variables.==

Consider this simple loop:

  • Set variable “Instance Count” to 3
  • Set variable “Instance Index” to 1
  • While calculation Instance Index <= Instance Count
    • Do stuff in an Execute a Macro action (aka Sub-Macro)
    • Set variable “Instance Index” to “Instance Index + 1”

==If that Sub-Macro changes the value of Instance Index or Instance Count, then the main macro will not behave as expected.==

Now the “Instance Index” variable used by the main macro will be unexpectedly changed within the Sub-Macro, causing the loop in the main macro to have unintended behavior.

So the use cases should be:

  • Use global variables if you want to use or change the variable across all executions, or across different macro executions, and even across a restart of your Mac.
  • Use instance variables if you want to use or change the variable between the main macro and any Sub-Macros it calls, for each execution of the main macro (specific execution instance).
  • Use local variables if you want to use or change the variable restricted to only each execution of the macro in which it is defined (specific execution instance).

Note that in all cases scripts can access the Instance or Local variables, either via the execution instance or the KMVAR environment variables.

Another Example

Imagine you have a main macro A, that uses Execute Macro to execute macro B, that uses Execute Shell Script and also uses execute macro to execute C.

Imagine that you trigger that the main macro A with a hot key and press the hot key twice.

There are two execution instances, one for each hot key trigger of the macro.

  • Use of Global Variables
    • Global variable references would be shared by all of macros and all of the execution instances - any change will be seen by all of the macros.
      .
  • Use of Instance Variables
    • There will be two sets of Instance variables.
    • One for each triggered execution instance. For each instance, all the macros A, B, and C will see the same set of instance variables - any change to any instance variable will be see by all three macros.
    • But any change to the instance variables will be seen in their respective execution instance.
    • The two running macros are like two different running programs - each one has its own instance variables.
      .
  • Use of Local Variables
    • There will be six sets of local variables.
    • Each macro in each execution instance will have its own local variables.
    • Local variables changed in macro B will not be seen in macro A or C, nor in the other execution instance of macro B.
      .
  • Use of Scripts
    • The executed shell script will be able to see the KMVAR variables available to macro B at the time of executing the script.
    • Using the KMINSTANCE environment variable, executed scripts and AppleScripts can set specific local/instance variables.

[Some edits made by @JMichaelTX.]

6 Likes
2

Thanks, Peter, that was very helpful. :+1:
I now more clearly see the distinction between Local and Instance variables.

I'm going to move your answer to a new Topic in Tips so that it is more visible to all KM users. We should also reference the topic in the KM Wiki when it becomes editable again.

3

@peternlewis, obviously I have made a few edits to further clarify and enhance the layout. Please review and confirm.

1 Like