Interface Util

A container for various utility functions and constants, available as the global util object.

interface Util {
    base64Decode(string: string): string;
    base64Encode(
        string: string,
        options?: { trimmed?: boolean; urlSafe?: boolean },
    ): string;
    buildQuery: (params: { [key: string]: string }) => string;
    checkSpelling(text: string, options: { language: string }): boolean;
    clarify(obscuredString: string): any;
    cleanHtml(html: string, options?: object): string;
    constant: {
        KEY_DELETE: 51;
        KEY_DOWNARROW: 125;
        KEY_ESCAPE: 53;
        KEY_LEFTARROW: 123;
        KEY_RETURN: 36;
        KEY_RIGHTARROW: 124;
        KEY_SPACE: 49;
        KEY_TAB: 48;
        KEY_UPARROW: 126;
        MODIFIER_COMMAND: 1048576;
        MODIFIER_CONTROL: 262144;
        MODIFIER_OPTION: 524288;
        MODIFIER_SHIFT: 131072;
    };
    getDictionaryDefinition(text: string): string | undefined;
    getPreferredSpellingLanguages(): string[];
    getRandomValues(
        typedArray:
            | Int8Array<ArrayBufferLike>
            | Uint8Array<ArrayBufferLike>
            | Uint8ClampedArray<ArrayBufferLike>
            | Int16Array<ArrayBufferLike>
            | Uint16Array<ArrayBufferLike>
            | Int32Array<ArrayBufferLike>
            | Uint32Array<ArrayBufferLike>
            | BigInt64Array<ArrayBufferLike>
            | BigUint64Array<ArrayBufferLike>,
    ): void;
    getSpellingGuesses(
        text: string,
        options: { language: string; limit?: number },
    ): string[];
    getSpellingLanguages(): { code: string; name: string }[];
    hasDictionaryDefinition(text: string): boolean;
    hmac(
        data: Uint8Array,
        key: Uint8Array,
        algorithm: "sha1" | "md5" | "sha256" | "sha384" | "sha512" | "sha224",
    ): Uint8Array;
    htmlToMarkdown(html: string, options?: object): string;
    localeInfo: {
        currencyCode: string;
        currencySymbol: string;
        decimalSeparator: string;
        groupingSeparator: string;
        languageCode: string;
        localeIdentifier: string;
        regionCode: string;
    };
    localize(string: string): string;
    parseQuery: (query: string) => any;
    randomUniform(max: number): number;
    randomUuid(): string;
    timeZoneInfo: {
        abbreviation: string;
        daylightSaving: boolean;
        identifier: string;
        secondsOffset: number;
    };
}

Properties

buildQuery

buildQuery: (params: { [key: string]: string }) => string

Builds a URL query string from an object of parameters.

`Readonly`constant

constant: {
    KEY_DELETE: 51;
    KEY_DOWNARROW: 125;
    KEY_ESCAPE: 53;
    KEY_LEFTARROW: 123;
    KEY_RETURN: 36;
    KEY_RIGHTARROW: 124;
    KEY_SPACE: 49;
    KEY_TAB: 48;
    KEY_UPARROW: 126;
    MODIFIER_COMMAND: 1048576;
    MODIFIER_CONTROL: 262144;
    MODIFIER_OPTION: 524288;
    MODIFIER_SHIFT: 131072;
}

The constant property is a container for pre-defined constants.

Type Declaration

ReadonlyKEY_DELETE: 51

Key code for the Delete (⌫) key.
ReadonlyKEY_DOWNARROW: 125

Key code for the Down Arrow key.
ReadonlyKEY_ESCAPE: 53

Key code for the Escape key.
ReadonlyKEY_LEFTARROW: 123

Key code for the Left Arrow key.
ReadonlyKEY_RETURN: 36

Key code for the Return (↵) key.
ReadonlyKEY_RIGHTARROW: 124

Key code for the Right Arrow key.
ReadonlyKEY_SPACE: 49

Key code for the space bar.
ReadonlyKEY_TAB: 48

Key code for the Tab (⇥) key.
ReadonlyKEY_UPARROW: 126

Key code for the Up Arrow key.
ReadonlyMODIFIER_COMMAND: 1048576

Bit mask for the Command (⌘) key.
ReadonlyMODIFIER_CONTROL: 262144

Bit mask for the Control (⌃) key.
ReadonlyMODIFIER_OPTION: 524288

Bit mask for the Option (⌥) key.
ReadonlyMODIFIER_SHIFT: 131072

Bit mask for the Shift (⇧) key.

localeInfo

localeInfo: {
    currencyCode: string;
    currencySymbol: string;
    decimalSeparator: string;
    groupingSeparator: string;
    languageCode: string;
    localeIdentifier: string;
    regionCode: string;
}

Information about the user's locale, as configured in macOS settings. Values are read afresh on each access. A value the locale does not define is the empty string.

Type Declaration

currencyCode: string

ISO 4217 currency code, e.g. "GBP".
currencySymbol: string

Currency symbol, e.g. "£".
decimalSeparator: string

Decimal separator for numbers, e.g. ".".
groupingSeparator: string

Thousands separator for numbers, e.g. ",".
languageCode: string

ISO 639 language code, e.g. "en".
localeIdentifier: string

Locale identifier, e.g. "en_GB".
regionCode: string

ISO 3166 region code, e.g. "GB".

parseQuery

parseQuery: (query: string) => any

Parses a URL query string into an object of parameters.

timeZoneInfo

timeZoneInfo: {
    abbreviation: string;
    daylightSaving: boolean;
    identifier: string;
    secondsOffset: number;
}

Information about the current time zone, as configured in macOS settings. Values are read afresh on each access.

Type Declaration

abbreviation: string

Abbreviation for the zone in its current state, e.g. "GMT" or "BST".
daylightSaving: boolean

Whether daylight saving time is currently in effect.
identifier: string

Zone identifier from the IANA database, e.g. "Europe/London".
secondsOffset: number

Current offset from GMT in seconds, including any daylight saving offset.

Methods

base64Decode

base64Decode(string: 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: string,
options?: { trimmed?: boolean; urlSafe?: boolean },
): string
Encode a string as UTF-8 then Base-64 encode the result.
Parameters
- string: string
  The string to encode.
- Optionaloptions: { trimmed?: boolean; urlSafe?: boolean }
  - Optionaltrimmed?: boolean
    
    Whether to trim the =/== padding from the string. Default is no.
  - OptionalurlSafe?: boolean
    
    Whether to encode using the URL-safe variant, with - and _ substituted for + and /. Default is no.
Returns string

checkSpelling

checkSpelling(text: string, options: { language: string }): 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.
Returns boolean

clarify

clarify(obscuredString: string): 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

cleanHtml

cleanHtml(html: string, options?: object): string
Sanitizes an HTML string, removing scripts, styles and other unsafe markup, using sanitize-html.
Parameters
- html: string
  The HTML to sanitize.
- Optionaloptions: object
  Reserved; the current implementation ignores it.
Returns string

getDictionaryDefinition

getDictionaryDefinition(text: string): string | undefined
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 | undefined

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:
        | Int8Array<ArrayBufferLike>
        | Uint8Array<ArrayBufferLike>
        | Uint8ClampedArray<ArrayBufferLike>
        | Int16Array<ArrayBufferLike>
        | Uint16Array<ArrayBufferLike>
        | Int32Array<ArrayBufferLike>
        | Uint32Array<ArrayBufferLike>
        | BigInt64Array<ArrayBufferLike>
        | BigUint64Array<ArrayBufferLike>,
): void
Fill the provided TypedArray with cryptographically secure random values. This aims to work like crypto.getRandomValues() from Web Crypto API. Internally, it is implemented using Apple's SecRandomCopyBytes.
Parameters
- typedArray:
      | Int8Array<ArrayBufferLike>
      | Uint8Array<ArrayBufferLike>
      | Uint8ClampedArray<ArrayBufferLike>
      | Int16Array<ArrayBufferLike>
      | Uint16Array<ArrayBufferLike>
      | Int32Array<ArrayBufferLike>
      | Uint32Array<ArrayBufferLike>
      | BigInt64Array<ArrayBufferLike>
      | BigUint64Array<ArrayBufferLike>
  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
```

getSpellingGuesses

getSpellingGuesses(
text: string,
options: { language: string; limit?: number },
): 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).
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: string): 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)) { ... }
```

hmac

hmac(
    data: Uint8Array,
    key: Uint8Array,
    algorithm: "sha1" | "md5" | "sha256" | "sha384" | "sha512" | "sha224",
): 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

htmlToMarkdown

htmlToMarkdown(html: string, options?: object): string
Converts an HTML string to Markdown, using Turndown.
Parameters
- html: string
  The HTML to convert.
- Optionaloptions: object
  Turndown options. Defaults to { headingStyle: "atx" }.
Returns string

localize

localize(string: 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 available.

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): 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
```

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

Interface Util

Index

Properties

Methods

Properties

buildQuery

Readonlyconstant

Type Declaration

ReadonlyKEY_DELETE: 51

ReadonlyKEY_DOWNARROW: 125

ReadonlyKEY_ESCAPE: 53

ReadonlyKEY_LEFTARROW: 123

ReadonlyKEY_RETURN: 36

ReadonlyKEY_RIGHTARROW: 124

ReadonlyKEY_SPACE: 49

ReadonlyKEY_TAB: 48

ReadonlyKEY_UPARROW: 126

ReadonlyMODIFIER_COMMAND: 1048576

ReadonlyMODIFIER_CONTROL: 262144

ReadonlyMODIFIER_OPTION: 524288

ReadonlyMODIFIER_SHIFT: 131072

localeInfo

Type Declaration

currencyCode: string

currencySymbol: string

decimalSeparator: string

groupingSeparator: string

languageCode: string

localeIdentifier: string

regionCode: string

parseQuery

timeZoneInfo

Type Declaration

abbreviation: string

daylightSaving: boolean

identifier: string

secondsOffset: number

Methods

base64Decode

Parameters

Returns string

base64Encode

Parameters

Optionaltrimmed?: boolean

OptionalurlSafe?: boolean

Returns string

checkSpelling

Parameters

Returns boolean

clarify

Parameters

Returns any

cleanHtml

Parameters

Returns string

getDictionaryDefinition

Parameters

Returns string | undefined

getPreferredSpellingLanguages

Returns string[]

getRandomValues

Parameters

Returns void

Example

getSpellingGuesses

Parameters

Returns string[]

getSpellingLanguages

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

hasDictionaryDefinition

Parameters

Returns boolean

Example

hmac

Parameters

Returns Uint8Array

htmlToMarkdown

Parameters

Returns string

localize

`Readonly`constant

`Readonly`KEY_DELETE: 51

`Readonly`KEY_DOWNARROW: 125

`Readonly`KEY_ESCAPE: 53

`Readonly`KEY_LEFTARROW: 123

`Readonly`KEY_RETURN: 36

`Readonly`KEY_RIGHTARROW: 124

`Readonly`KEY_SPACE: 49

`Readonly`KEY_TAB: 48

`Readonly`KEY_UPARROW: 126

`Readonly`MODIFIER_COMMAND: 1048576

`Readonly`MODIFIER_CONTROL: 262144

`Readonly`MODIFIER_OPTION: 524288

`Readonly`MODIFIER_SHIFT: 131072

`Optional`trimmed?: boolean

`Optional`urlSafe?: boolean