Browse the docs

Transform text

Applies one text filter (case, quoting, encoding, paths, URLs, counts, substring, calculation and more) and returns the result.

Transform text with op

Keyboard Maestro: FilterVariable, FilterClipboard, Substring

Details #

One step for what Keyboard Maestro's Filter actions do to text. Pick the filter with op, give it text, and read the result from into. The result is also the step's output. The text can use variables and expressions, as in any step.

The filters, by group:

  • Case: uppercase, lowercase, capitalize, uppercaseFirst, lowercaseFirst, titleCase, sentence.

  • Whitespace and lines: trim, reverse, shuffle (reorders the lines), unwrap, wrap (uses width), unixLineEndings, macLineEndings, windowsLineEndings, bulletControlCharacters, zapControlCharacters.

  • Counts (numbers): characterCount, lineCount, wordCount.

  • Pieces: substring (uses start, length, kind).

  • Quotes: dumbQuotes, smartQuotes, frenchQuotes.

  • Quoting for code: quoteShell, quoteAppleScript, quoteJavaScript, quoteSwift, quoteJSON, quoteProcessTokens, regexEscape.

  • Encoding: base64Encode, base64Decode, urlEncode, urlDecode, htmlEncode, htmlEncodeNonASCII, htmlEncodeNumeric, htmlDecode, htmlList, md5.

  • JSON: jsonPretty, jsonCompact.

  • Paths: abbreviateTilde, expandTilde, standardizePath, resolveSymlinks, baseName, lastPathComponent, deleteLastPathComponent, pathExtension, deletePathExtension, displayName.

  • URL parts: urlScheme, urlHost, urlUser, urlPassword, urlPort, urlPath, urlQuery, urlFragment. A part that is missing gives empty text.

  • Evaluate: calculate (evaluates the text as an expression and returns the result as text), processTokens (expands Keyboard Maestro %Variable%name% tokens and {{ }} templates using the run's variables).

  • Lookups: namedVariable (the value of the variable called name, or of the text if name is not given), namedClipboard (the text of the named clipboard in clipboard history).

  • Clipboard actions: cleanURL (strips tracking parameters such as utm_*, fbclid, gclid, mc_* and ref from a link; other text comes back unchanged), markdownLink ([host](url)), colorFormat (a color as hex, rgb, hsl, swiftui, nscolor or uicolor, with format), sortLines (A to Z, or Z to A with order: desc), uniqueLines (drops repeated lines), collapseSpaces (trims and squeezes runs of spaces) and fenceCode (wraps in a ``` fence, with an optional language). They are what the clipboard actions are made of.

  • Paste as: htmlToMarkdown (rich text as Markdown; text is {{clipboard.rich}} and fallback the plain text to use when nothing rich was copied), markdownToHTML (Markdown as an HTML fragment), toJSON (CSV, TSV, YAML, key: value or key=value lines as pretty JSON) and jsonToCSV (an array of objects as CSV). They are what the rows of Paste as are made of.

  • Rich text: attributedTextToRTF, rtfToText, removeStyles (text in, text out; styling is not kept), and identity (returns the text unchanged).

An unknown op fails with "unknown text.transform op" and a "did you mean" hint when only the capitalisation is off. (action is another spelling of op, and value another spelling of text.)

Parameters #

ParameterTypeRequiredValuesWhat it does
texttextYesThe input text. Required by the schema; may be empty. (value is another spelling.)
actionone ofabbreviateTilde attributedTextToRTF base64Decode base64Encode baseName bulletControlCharacters calculate capitalize characterCount deleteLastPathComponent deletePathExtension displayName dumbQuotes expandTilde frenchQuotes htmlDecode htmlEncode htmlEncodeNonASCII htmlEncodeNumeric htmlList identity jsonCompact jsonPretty lastPathComponent lineCount lowercase lowercaseFirst macLineEndings md5 namedClipboard namedVariable pathExtension processTokens quoteAppleScript quoteJSON quoteJavaScript quoteProcessTokens quoteShell quoteSwift regexEscape removeStyles resolveSymlinks reverse rtfToText sentence shuffle smartQuotes standardizePath substring titleCase trim unixLineEndings unwrap uppercase uppercaseFirst urlDecode urlEncode urlFragment urlHost urlPassword urlPath urlPort urlQuery urlScheme urlUser windowsLineEndings wordCount wrap zapControlCharactersAnother spelling of op.
fallbacktextFor htmlToMarkdown: the text to convert when text is empty.
formattextFor colorFormat: hex, rgb, hsl, swiftui, nscolor or uicolor.
intotextThe variable that receives the result.
kindtextFor substring: FromStart (the first length characters), FromEnd (the last length) or Range (the default; anything else is treated as a range).
languagetextFor fenceCode: the language written after the opening fence.
lengthany valueFor substring: how many characters. The default is all of them.
nametextFor namedVariable and namedClipboard: the name to look up.
opone ofabbreviateTilde attributedTextToRTF base64Decode base64Encode baseName bulletControlCharacters calculate capitalize characterCount cleanURL collapseSpaces colorFormat deleteLastPathComponent deletePathExtension displayName dumbQuotes expandTilde fenceCode frenchQuotes htmlDecode htmlEncode htmlEncodeNonASCII htmlEncodeNumeric htmlList htmlToMarkdown identity jsonCompact jsonPretty jsonToCSV lastPathComponent lineCount lowercase lowercaseFirst macLineEndings markdownLink markdownToHTML md5 namedClipboard namedVariable pathExtension processTokens quoteAppleScript quoteJSON quoteJavaScript quoteProcessTokens quoteShell quoteSwift regexEscape removeStyles resolveSymlinks reverse rtfToText sentence shuffle smartQuotes sortLines standardizePath substring titleCase toJSON trim uniqueLines unixLineEndings unwrap uppercase uppercaseFirst urlDecode urlEncode urlFragment urlHost urlPassword urlPath urlPort urlQuery urlScheme urlUser windowsLineEndings wordCount wrap zapControlCharactersThe filter to apply. Required (or action). See the groups above.
orderone ofasc descFor sortLines: asc (the default) or desc.
startany valueFor substring with kind Range: the first character, counting from 1. The default is 1.
valuetextAnother spelling of text.
widthnumberFor wrap: the line width in characters. The default is 72 and the smallest is 8.

Every step also accepts label, onFailure, timeout and dryRunSafe.

Examples #

This only works on text, so it is safe:

Tidy a title and count its words
Do
  1. Transform “the lord of the rings” with trim
  2. Transform “{{clean}}” with title case
  3. Transform “{{title}}” with word count
  4. Show “{{title}} ({{words}} words)” for 3 s
Open in Switchboard to try it

Take the last three characters:

Last three characters
Do
  1. Transform “Switchboard” with substring
  2. Show “{{tail}}”
Open in Switchboard to try it

Gotchas #

  • It is safe in a dry run: it runs for real, since it only changes text and touches nothing else.

  • base64Decode fails with "that text isn't Base64"; jsonPretty and jsonCompact fail with "that text isn't valid JSON".

  • calculate fails with "nothing to calculate" on empty text and "couldn't calculate" when the expression is wrong. Use Variables and expressions for the expression language.

  • namedClipboard fails with "no clipboard is named" when there is no such clipboard, and "clipboard history isn't running in this process" if history is off.

  • urlEncode leaves only letters, digits and -._~ as they are. urlDecode turns + into a space.

  • md5 is for checksums and matching, not for security.

  • shuffle gives a different order each run.

See also #

Set variable, Clipboard, Set field value, upper, urlEncode