KMET: Edit KM Objects as Text (Search & Replace)

KMET: Edit KM Objects as Text (Search & Replace)

image

KMET Edit as Text.v1.0.kmmacros (205.5 KB)

ABOUT THE VERSION NUMBER:

I'm calling this version 1.0, but I've actually been using it for around 4 years. I did clean up some things before I posted it here, so it's always possible I messed something up, but I doubt it (famous last words).

My point is, this set of macros has stood the test of time, recent cleanups notwithstanding.

PURPOSE:

This is a set of macros that allows you to copy Keyboard Maestro "objects" (actions, macros, or groups) to the clipboard in text format (JSON or XML), edit them in a text editor, and paste the results back into KM.

This allows you to do things like search & replace variable names:

image

or re-order fields in a Prompt:

TEXT EDITORS:

The default text editor is BBEdit, but you can change it to use other text editors. See the macro [KMET Sub-Macro] Open Editor to Edit Object Text for more information.

USAGE:

  1. In the KM editor, select one or more actions, macros, or groups.

  2. Run the macro [KMET] Edit Selected Objects as JSON Text (or [KMET] Edit Selected Objects as XML Text).

  3. Make your changes in the text editor.

  4. Copy the modified text to the clipboard.

  5. Back in the KM editor, use [KMET] Paste Objects into KM to paste it back into KM.

  6. Most of the time you'll delete the original objects first, so you don't end up with duplicates, but that's up to you.

BUT WHAT IF I RUIN MY MACROS?

First of all, you're not modifying the actual source code of your macros. You're working on a copy of a small part of the source, which you paste back into KM when you're done, so if you mess something up, chances are it won't even paste back into the KM editor.

You can always "undo" your changes in the KM editor. And you can work on a copy of your macro, which makes it even less likely you'll mess things up.

As I mentioned earlier, I've been using these macros for around 4 years, and I've never come across anything that couldn't be fixed easily with "undo".

JSON? XML? WTF?

JSON and XML are ways to represent computer data in a text format. JSON is a newer standard, and much easier to read. XML is the native format KM uses for importing and exporting macros.

Which format should I use?

Use JSON, because it's more compact and easier to read.

So why did I bother to include XML? As I said, XML is the native format KM uses, so it's remotely possible that converting it to JSON could introduce some translation errors, although I think I handle any possible problems. Still, if a translation problem arises, you can use XML.

What are the "rules" for editing JSON or XML?

When you look at the object text, it should be pretty obvious it follows a specific pattern. Just don't deviate from that pattern.

What am I allowed to change?

Only change what you could change in the KM editor. For example, consider these actions:

image

Below, I've highlighted in yellow the only things you should change in the JSON. Compare it to the image above, and it should start to make sense.

image

So be careful, for example, if you wanted to replace a string like "Variable".

"ESCAPING" TEXT

There are certain characters in JSON that need to be "escaped". In the example above, notice the double-quotes in this action's description:

image

This is what it looks like in JSON:

image

Notice the "backslash" before each double-quote. That's called "escaping" the quote. The one at the end might be confusing - just remember that the entire string is enclosed in double-quotes, so there will always be a double-quote at the start, and one at the end.

To make it easier for you to escape strings, check out the various [KMET] Utility - Encode macros.

JSON ARRAYS:

One thing to be aware of in JSON is the use of commas in arrays:

image

In the above image, the red arrows point to a set of square brackets, which define an array. This array has 2 items in it - the one highlighted in yellow, and the one highlighted in green.

If you look at the white arrows, you'll see that there's a comma after the first item, but not after the last.

You always need a comma between each item in an array. But you don't need one at the end.

So one common problem arises when you copy the last item from an array, and paste it in somewhere, and forget the comma. Or you paste an item after the last item, and forget to add the comma before it.

OTHER USES

You can generate your own JSON or XML, and paste it into KM. In fact, that's what I do in my macro KMFAM: Favorite Actions and Macros.

You can use some of the KMET actions to help:

  • [KMET] Utility - Encode Text for JSON (Sub-Macro) (or the XML version)
  • [µKMET Sub-Macro] Set Clipboard to Objects Text
  • [KMET] Paste Objects into KM

TROUBLESHOOTING:

If nothing happens when you try to paste the objects back into KM, here's some possibilities:

  • Did you remember to copy the entire text from your text editor?

  • Did you select where to paste the objects into KM? It's just like when you copy and paste things in KM - it needs to know where you want to paste them.

  • Did you mess up the JSON or XML somehow? If in doubt, use a text comparison program and compare the original text with your modified text, and see if something looks obviously wrong. BBEdit has "Find Differences" under the "Search" menu that should be able to help. You can use the macro [KMET] Utility - Copy Selected Objects as JSON Text to get the original text from KM.

Have Fun!

6 Likes

Nice! And you mentioned BBEdit so double nice. :slight_smile:

My use case would probably be to clone a macro and point it at other files / directories.

I could also see use cases where I glean info from the XML and turn it into documents (like I do in sd2html).

Finally, for now, using BBEdit's diff function might also prove handy.

1 Like