KM8: Local and Instance Variables

Glad my idea proved useful!

Interesting idea. I'm fairly new to Karabiner-Elements myself, and have just been using it for the hyper key functionality. If there's a way to do this in KE so it doesn't interfere with the existing ¬ and ˆ symbol creation that OPT-L and OPT-I already perform (not that I use those much, to be fair) I'd be curious to know about it as well.

I would rather use Ukelele and create a customized keyboard layout. Sounds complicated but it isn't: You just make a copy of your standard US layout, throw out 2 unnecessary glyphs and replace them with 𝕃 and 𝕀. Save the layout to ~/Library/Keyboard Layouts and finished.

You find a little tutorial and a custom layout (well, not yet with 𝕃 and 𝕀) on my blog.

Hmm. ⌘ key to launch snippets, then "ki"or "kl" plus Return. That's 4 keys.

Works fine for me also inside KM Editor.

Type 𝕃.kmmacros (1.4 KB)

Maybe a stupid question, but is it expected that local and instance variables do not work when defined in a User Prompt?



[mwe] Local and Instance variables in a prompt.kmmacros (4.2 KB)

Edit / PS:

In the meantime I found out that when I define the variables before the User Prompt, then the original values are kept. That is, the local and instance variables seem to be completely ignored in the User Prompt:

[mwe] Local and Instance variables in a prompt II.kmmacros (4.8 KB)


I think something is wrong here. (@peternlewis ?)


I only started using a hyper key recently with the KE Sierra fix, but Hyper is much more comfortable for me to use than the left hand twisting stuff I'd been using before. The worst offender was Command Control Shift 4... :grimacing:

1 Like


@peternlewis, can you confirm as a bug?

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).