KM8: Local and Instance Variables

Another bug report:

KM8: Bug Report - Calculation with Local Variable Fails

Difference Between "Local" and "Instance" Variables?

@peternlewis, I'm not clear on what the difference is between "Local" and "Instance" Variables.

Could you please clarify, and if you have some, provide some examples?

From the KM Wiki:

Both definitions use the term "specific instance", or similar. That is what confuses me.

Variables with names that start with “Local ” or a double-struck L (𝕃) are considered local 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.

Variables with names that start with “Instance ” or a double-struck I (𝕀) are considered local 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.


Yes, the Prompt For User Input currently can't set the local/instance variables because essentially it's running in its own instance. I can work around it I think, but it wont happen in 8.0.1.

Also, as stated elsewhere, I am going to remove the double-struct I and L (𝕀 and 𝕃). The characters cause problems because they are not even in the first unicode plane.

If people have suggestions for alternative characters, I am open to adding a different alternative.

1 Like

The difference between Local and Instance is whether the variable is strictly limited to the macro it is in (Local), or is limited to the macro execution instance it is in.

The difference becomes apparent when you call a sub-macro. The sub-macro is in the same execution instance, so it can see (and set) Instance variables. But it cannot see Local variables.

1 Like

if you can't fix it in 8.0.1, then please show some kind of error if the user enters a Local or Instance Variable in a Prompt for User Input.

Obviously, we need Local/Instance Variables to work in Prompts.

I agree. The characters initially selected were less than optimial.

Proposal for Local/Instance Characters

æ for A Local Variable Prefix
Æ for A Instance Variable Prefix

These characters/keys are easily accssible from the standard Mac keyboard as:
æ -- '
Æ -- '

I really like these choices because:

  1. They are easy to type
  2. They both use the same key with OPT, one with SHIFT
  3. I think these characters are rarely used, especially as the prefix of a word.



One more point:
I think you should also allow two underscores after the key word:

"Local__" as a local variable prefix
"Instance__" as an instance prefix

so that:

  1. The prefix does NOT show in a Prompt action
  2. The whole variable word is easily selectable by a double-click.

So, Peter, you guys, what do you think?


Limiting the range to the Basic Multilingual Plane (BMT) (plane 0), this comes to mind:

  • From the Geometric Shapes block:
    • Triangles: Instance, ▶︎ Local
    • Diamonds: Instance, Local
    • Other similar black/white pairings like circles, squares

Otherwise, chars that are in the BMP and also part of the standard US keyboard layout:

  • The quote marks: Instance, » Local
  • Simply: > Instance, >> Local (might cause parsing problems?)
  • The dagger: Instance, †† Local
  • Exclamation marks: ¡ Instance, ! Local


The doubling as well as the white/black pairing has a semantic logic, since Local is more restricted than Instance (right?). The exclamation mark can be seen as resembling to the letter "i", as well as a warning that the variable is not accessible from outside of the macro (e.g. from embedded AppleScripts).

I'm not a friend of arbitrary chars like æ and Æ, because these are actually letters (not symbols) and the letters they are are not related to the initial letters of the subject (I and L).

Furthermore the different height of the glyphs makes for an ugly, unbalanced appearance, and we have to live with this decision for a long time :wink:

The only esthetically (halfway) pleasing and semantically meaningful Letterlike on the standard layout I could find is the Pound-L: £ Instance, ££ Local

Here a visual representation:

My favorites are the exclamation marks ¡ and !, and to some degree, the Angle Quotation Marks and ».

Each of them can be typed with a single keystroke and they are somewhat meaningful, the ¡! more than the ›».

Edit: An afterthought:

The more I think about the proposed ¡! solution the better it appears to me!

Some facts:

  • Extremely easy to type: ! is Shift-1, ¡ is Option-1
  • The semantics are OK:
    • ¡ resembles perfectly an i like in "Instance"
    • !, well, with a bit of imagination you can se it as lowercase l with a dot below :wink:
    • Both characters have the semantics of a warning: ‘you can’t access the variables from a script or from the shell!’
  • The pragmatics are perfect:
    • Local variables will be used way more often than Instance variables. And the sign for the local variable (!) is even printed on the keyboard (= easiest access possible)
    • The (less used) Instance variable sign (¡) is not printed on the keyboard but it doesn’t require any more keystrokes either.
    • Both are single-figure signs, that is they don’t lengthen the variable names like the proposed double signs do.
  • The esthetics are perfect too:
    • Since KM Editor is using a proportional font, the ! as well as the ¡ are really thin, that is, non-obtrusive.

In fact, the ¡! solution seems so good to me, that I’m almost sure that there is something in the way that prevented Peter from choosing it right from the start (referring to the KM8 update). Maybe a parsing problem in the context of calculations?

BTW, I wouldn’t care about the contradiction to the usual semantics of the ! as ‘not’. It is clear in the context that this is not an operator but just a Sigil.

The underplaying problem of all that is that KM’s variables are global and persistent by default.

KM variables should have been always, IMO, macro-local by default, with an option to create global/persistent variables when needed. But, as far as I know, Peter is not the original author of the program, and, of course changing this now would break a considerable part of all existing macros. So we have to live with that.

In future macros (if handled correctly by the author) the majority of variables will be local, and that’s why I think it is really important to find a decent, non-obtrusive solution.


What about compatibility of shell use i.e. “$KMVAR_!Myvariable” and relate other languages?

Without thinking too much, I don’t see any reason why this should cause problems. The currently used 𝕃 and 𝕀 would be “worse”, no?

¡ and ! are ASCII chars, after all.

And, by the way, you can’t use local variables in shell or AppleScripts, since they are limited to the macro. (They are not in the ENV, unless I’m missing something.)

Since locality is restricted to KM (if I understand well :wink: ) scripting using these local variable is impossible?

I also was unsure, but I tried it in my first KM8 macro, and accessing local variables from the contained AppleScript didn’t work. (getvariable)

I didn’t try it with shell scripts though.

And it seems logic, since they are stored nowhere (“local”). However, it would be indeed great if we were able to access those variables from scripts that are launched by the macro itself (i.e. embedded AppleScripts or shell scripts). But I guess this would be a really major complication.

1 Like

Nope. Try this:

[test] Local Vars.kmmacros (2.5 KB)

The same with 𝕀.

1 Like

:+1: => local variables more useful.

Is instance variables are transient (exist only for the current run and are dropped at exit) and with (local) scripting access?

For scripting access there seems to be no difference. None of them are accessible. Have you tried the above test macro with 𝕀?

According to what I understood, Instance variables are accessible to macros that launch the other macro (or viceversa).

I have not yet tested KM8 :blush:… but I hope quite soon
Thanks for your tests… and more :grinning:

I have added an Afterthought to my above post. Maybe worth reading.

Thanks for the clarification, Peter.

So, since using a Execute Macro is in the same execution instance, shouldn't Execute Script be as well, and thus, instance variables should be available to scripts?

@Tom, thanks for your thoughtful and comprehensive discussion.

I am good with your preference of ! and ¡.
The logic is good, keyboard access is good, and the memory association of ! with l for local, and ¡ with i for instance, works for me.

The only drawback is that using these does NOT allow you to quickly select the entire variable name by double-clicking -- it does NOT include the exclamation marks. I need to do this a lot. For example, setting a variable in one action, and then using it in the next, or later, action.

Since you tried two characters, I have done the same, just for comparision:




Visually, I still prefer the exclamation marks.

So, @peternlewis, I can support @Tom's suggestion of exclamation marks.

@peternlewis, some other thoughts on this:

  • Using "Local " and "Instance " as indicators might conflict with existing macros that use those terms.
  • As I suggested above, I think using "Local__" and "Instance__" is better, and maybe you should eliminate the other indicators.
1 Like

Now that understand "local" vs "instance" variables, it seems to me (per my post to Peter above) that instance variables should be accessible to scripts.

But instance variables are NOT available to scripts, at least not to AppleScript. Here my test macro/script:

Example Results

Macro: Instance Variable Test KM8 @TEST

Instance Variable Test KM8 @TEST.kmmacros (2.0 KB)

1 Like

This is a good point I hadn't considered.

The escape from double-clicking because they are punctuation (they are word-breaking). Of course the same is true for ›» and also for £. 𝕀 and 𝕃 are working fine in that respect.

However, as you also have stated, I don't think that this is game breaker. But, maybe somebody comes up with a better solution.

As a sidenote, I was quite content with @peternlewis' initial choice (𝕀 and 𝕃). OK, you might need a snippet expander to insert them, but, since we all have KM this shouldn't be a problem. But I'm interested to know why he thinks that the fact that those chars are not on Unicode Plane 0 (BMT) poses a problem.

1 Like