Util: Cinnamon Javascript Reference Manual

## Util Util — File providing certain utility functions |

## Functions

| escapeRegExp ()
| findUrls ()
| spawn ()
| spawn_async ()
| spawnCommandLine ()
| trySpawn ()
| trySpawnCommandLine ()
| spawnCommandLineAsync ()
object | spawnCommandLineAsyncIO ()
| killall ()
| queryCollection ()
any | tryFn ()
number | setTimeout ()
| clearTimeout ()
number | setInterval ()
| clearInterval ()
any | throttle ()
| unref ()
object | getGObjectPropertyValues ()
| getDesktopActionIcon ()
array | splitByGlyph ()

## Description

This file includes certain useful utility functions such as running external commands. It is generally a good idea to use the functions defined here instead of tapping into GLib directly since this adds some wrappers around the functions that make them more Cinnamon-friendly and provides helpful error messages.

## Functions

### escapeRegExp ()

    escapeRegExp (str);

Escapes a string for use within a regular expression.

#### Parameters

str | (String) a string to escape |

#### Returns

(String) the escaped string

### findUrls ()

    findUrls (str);

Searches `str` for URLs and returns an array of objects with `url` properties showing the matched URL string, and `pos` properties indicating the position within `str` where the URL was found.

#### Parameters

str | string to find URLs in |

#### Returns

the list of match objects, as described above

### spawn ()

    spawn (argv);

Runs `argv` in the background, handling any errors that occur when trying to start the program.

#### Parameters

argv | an argv array |

### spawn_async ()

    spawn_async (args,
                 callback);

Asynchronously Runs the command passed to `args`. When the command is complete, the callback will be called with the contents of stdout from the command passed as the only argument.

#### Parameters

args | an array containing all arguments of the command to be run |
callback | the callback to run when the command has completed |

### spawnCommandLine ()

    spawnCommandLine (command_line);

Runs `command_line` in the background, handling any errors that occur when trying to parse or start the program.

#### Parameters

command_line | a command line |

### trySpawn ()

    trySpawn (argv,
              doNotReap);

Runs `argv` in the background. If launching `argv` fails, this will throw an error.

#### Parameters

argv | an argv array |
doNotReap | whether to set the DO_NOT_REAP_CHILD flag |

### trySpawnCommandLine ()

    trySpawnCommandLine (command_line);

Runs `command_line` in the background. If launching `command_line` fails, this will throw an error.

#### Parameters

command_line | a command line |

### spawnCommandLineAsync ()

    spawnCommandLineAsync (           command_line,
                           function   callback,
                           function   errback);

Runs `command_line` in the background. If the process exits without error, a callback will be called, or an error callback will be called if one is provided.

#### Parameters

command_line | a command line |
callback | called on success |
errback | called on error |

### spawnCommandLineAsyncIO ()

    object
    spawnCommandLineAsyncIO (           command,
                             function   callback,
                             object     opts);

Runs `command` in the background. Callback has three arguments - stdout, stderr, and exitCode.

#### Parameters

command | a command |
callback | called on success or failure |
opts | options: argv, flags, input |

#### Returns

a Gio.Subprocess instance

### killall ()

    killall (processName);

Kills `processName`. If no process with the given name is found, this will fail silently.

#### Parameters

processName | a process name |

### queryCollection ()

    queryCollection (array     collection,
                     object    query,
                     boolean   indexOnly);

Returns (object|null): the matched object, or null if no object in the collection matches all conditions of the query.

#### Parameters

collection | an array of objects to query |
query | key-value pairs to find in the collection |
indexOnly | defaults to false, returns only the matching object's index if true. |

### tryFn ()

    any
    tryFn (function   callback,
           function   errCallback);

Try-catch can degrade performance in the function scope it is called in. By using a wrapper for try-catch, the function scope is reduced to the wrapper and not a potentially performance critical function calling the wrapper. Use of try-catch in any form will be slower than writing defensive code.

#### Parameters

callback | Function to wrap in a try-catch block. |
errCallback | The function to call on error. |

#### Returns

The output of whichever callback gets called.

### setTimeout ()

    number
    setTimeout (function   callback,
                number     ms);

Convenience wrapper for a Mainloop.timeout_add loop that returns false.

#### Parameters

callback | Function to call at the end of the timeout. |
ms | Milliseconds until the timeout expires. |

#### Returns

The ID of the loop.

### clearTimeout ()

    clearTimeout (number   id);

Convenience wrapper for Mainloop.source_remove.

#### Parameters

id | The ID of the loop to remove. |

### setInterval ()

    number
    setInterval (function   callback,
                 number     ms);

Convenience wrapper for a Mainloop.timeout_add loop that returns true.

#### Parameters

callback | Function to call on every interval. |
ms | Milliseconds between invocations. |

#### Returns

The ID of the loop.

### clearInterval ()

    clearInterval (number   id);

Convenience wrapper for Mainloop.source_remove.

#### Parameters

id | The ID of the loop to remove. |

### throttle ()

    any
    throttle (function   callback,
              number     interval,
              boolean    callFirst);

#### Parameters

callback | Function to throttle. |
interval | Milliseconds to throttle invocations to. |
callFirst | Specify invoking on the leading edge of the timeout. |

#### Returns

The output of `callback`.

### unref ()

    unref (object   object,
           array    reserved);

This will iterate `object` and assign null to every property value except for keys specified in the `reserved` array. Calling unref() in an object that has many references can make garbage collection easier for the engine. This should be used at the end of the lifecycle for classes that do not reconstruct very frequently, as GC thrashing can reduce performance.

#### Parameters

object | Object to be nullified. |
reserved | List of special keys (string) that should not be assigned null. |

### getGObjectPropertyValues ()

    object
    getGObjectPropertyValues (GObject.Object   object);

#### Parameters

object | GObject to inspect |

#### Returns

JS representation of the passed GObject

### getDesktopActionIcon ()

    getDesktopActionIcon (string   action);

Returns (string|null): Name of the icon associated with this action or null if not found

#### Parameters

action | Action name |

### splitByGlyph ()

    array
    splitByGlyph (string   str);

Converts a string, possibly containing multiple codepoint unicode characters (e.g. emoji), into an array of unicode graphemes clusters (glyphs). For example: "👩‍👩‍👧‍👧😃".length === 13, but splitByGlyph("👩‍👩‍👧‍👧😃") returns ["👩‍👩‍👧‍👧", "😃"] which is length 2.

#### Parameters

str | The string to be converted |

#### Returns

Array of unicode grapheme clusters (glyphs).