Interface Util

Readonly constant

localeInfo

timeZoneInfo

base64Decode

• base64Decode(string): string

• Decode a Base-64 string and interpret the result as a UTF-8 string.

  Accepts both standard and URL-safe variants as input. Also accepts input with or without the =/== end padding. Throws an error if the input cannot be decoded as a UTF-8 string.

  Parameters

  • string: string

  Returns string

  The decoded string

base64Encode

• base64Encode(string, options?): string

• Encode a string as UTF-8 then Base-64 encode the result.

  Parameters

  • string: string

    The string to encode.
  • Optional options: {
        trimmed?: boolean;
        urlSafe?: boolean;
    }

    • Optional trimmed?: boolean

      Whether to trim the =/== padding from the string. Default is no.

    • Optional urlSafe?: boolean

      Whether to encode using the URL-safe variant, with - and _ substituted for + and /. Default is no.

  Returns string

checkSpelling

• checkSpelling(text, options): boolean

• Whether the text contains no misspellings, checked in the given language.

  The language must be a code from getSpellingLanguages; any other value throws, so intersect a saved option value with the available list before passing it — a saved language can go stale.

  Parameters

  • text: string

    The text to check.
  • options: {
        language: string;
    }

    language: the spell checker language code to check in.

    • language: string

  Returns boolean

clarify

• clarify(obscuredString): any

• Decipher a JSON object that has been lightly obscured to prevent constants such as API client identifiers appearing in plaintext in the source files.

  This function will ROT13 decipher the text, apply Base64 decoding, and parse the result as JSON.

  Parameters

  • obscuredString: string

  Returns any

getDictionaryDefinition

• getDictionaryDefinition(text): string

• The definition of this text from macOS's Dictionary Services, as plain text, or undefined if the text has no definition.

  To open the text in the Dictionary app instead of reading its definition, use popclip.openUrl with a dict:// URL.

  Parameters

  • text: string

    The text to define.

  Returns string

getPreferredSpellingLanguages

• getPreferredSpellingLanguages(): string[]

• The user's preferred languages (per macOS Language settings), filtered to those the spell checker can check.

  Returns string[]

getRandomValues

• getRandomValues(typedArray): void

• Fill the provided TypedArray with cryptographically secure random values. This aims work like crypto.getRandomValues() from Web Crypto API. Internally, it is implemented using Apple's SecRandomCopyBytes.

  Parameters

  • typedArray: Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | BigInt64Array | BigUint64Array

    The array to fill with random values. This will be modified in place.

  Returns void

  Example

  const array = new Uint8Array(16); // array of 16 bytes
  util.getRandomValues(array);      // array is now filled with random bytes
  Copy

getSpellingGuesses

• getSpellingGuesses(text, options): string[]

• Replacement guesses for a misspelled word, in the given language. Guesses are returned only when the whole text is a single misspelled word — a sentence containing a misspelling is not a candidate for replacement, so it yields an empty array, as do correctly-spelled words and misspellings or non-words that the checker has no suggestions for.

  The same language rule as checkSpelling applies.

  Parameters

  • text: string

    The text to get guesses for.
  • options: {
        language: string;
        limit?: number;
    }

    language: the spell checker language code; limit: cap the number of guesses returned (omit for all).

    • language: string

    • Optional limit?: number

  Returns string[]

getSpellingLanguages

• getSpellingLanguages(): {
      code: string;
      name: string;
  }[]

• The languages the system spell checker can check on this Mac, as objects pairing the spell checker's language code (for example "en", "de", "pt_BR") with a display name localized for the user's locale. Suitable for building a language option's values and valueLabels.

  Returns {
      code: string;
      name: string;
  }[]

hasDictionaryDefinition

• hasDictionaryDefinition(text): boolean

• Whether macOS's Dictionary Services has a definition for this text — that is, whether the text as a whole is a term in one of the dictionaries the user has enabled.

  Parameters

  • text: string

    The text to look up.

  Returns boolean

  Example

  if (util.hasDictionaryDefinition(popclip.input.text)) { ... }
  Copy

hmac

• hmac(data, key, algorithm): Uint8Array

• Generate hash-based message authentication code (HMAC) using the supplied data, key and algorithm. Implemented internally by Apple's CommonCrypto.

  Parameters

  • data: Uint8Array
  • key: Uint8Array
  • algorithm: "sha1" | "md5" | "sha256" | "sha384" | "sha512" | "sha224"

  Returns Uint8Array

localize

• localize(string): string

• Localize an English string into the current user interface language, if possible. This will work for strings which match the name of a built-in action.

  Parameters

  • string: string

    The string to localize.

  Returns string

  The localized string, or the original string if no localized version was avaiable.

  Deprecated

  This is only used by the Paste and Enter and Paste and Match Style extensions to localise their displayed action titles and is not recommended for general use.

randomUniform

• randomUniform(max): number

• Generate a random integer in range [0, max] with uniform distribution using a cryptographically secure random source.

  Parameters

  • max: number

    Maximum value to generate. Supplied value will be coerced to a 32-bit unsigned integer.

  Returns number

  Example

  const coinFlip = util.randomUniform(1); // coinFlip has value 0 or 1
  const dieRoll = util.randomUniform(5) + 1; // dieRoll has value from 1 to 6
  Copy

randomUuid

• randomUuid(): string

• Generate a RFC 4122 version 4 UUID using a cryptographically secure random number generator.

  Returns string

  UUID string such as "e621e1f8-c36c-495a-93fc-0c247a3e6e5f".