osascript-tag
A JavaScript template literal tag that executes AppleScript and other OSA (Open Scripting Architecture) scripts.
Compatible with JXA (JavaScript for Automation).
## Why?
> Every time I get a script it's a matter of trying to know what I could do with it. I see colors, imagery. It has to have a smell. It's like falling in love. You can't give a reason why.
>
> — Paul Newman
## Installation
To get started, add `osascript-tag` to your project:
```
npm i --save osascript-tag
```
## Usage
### Running AppleScript
It can be used as template literal tag to asynchronously run an AppleScript within your code. It returns a promise that resolves with the output of the script, and rejects with an error if running the script was not successful.
```js
const osascript = require('osascript-tag');
async function main() {
const result = await osascript`
tell application "iTunes"
get { artist, name } of current track
end tell
`;
console.log(result); // "King Gizzard & The Lizard Wizard, This Thing"
}
```
### Running JXA (JavaScript for Automation)
To run a JXA (JavaScript for Automation) script, use the `osascript.jxa` template tag (also available as the named export: `jxa`) . Please note that `osascript.jxa` requires macOS 10.10 or greater.
```js
const osascript = require('osascript-tag');
async function main() {
await osascript.jxa`
const app = Application.currentApplication();
app.includeStandardAdditions = true;
app.displayNotification("All graphics have been converted.", {
withTitle: "My Graphic Processing Script",
subtitle: "Processing is complete.",
soundName: "Glass",
});
`;
}
```
### Parsing Values Returned from JXA Scripts
By default all calls to `osascript.jxa` will resolve with the stdout result as a string.
If your script, however, is expected to return parsable values, you can pass a `parse` option to `osascript.jxa` to return parsed values ready for consumption in your JavaScript code.
```js
const osascript = require('osascript-tag');
async function main() {
const { artist, title } = await osascript.jxa({ parse: true })`
const iTunes = Application('iTunes');
return {
artist: iTunes.currentTrack.artist(),
title: iTunes.currentTrack.name(),
}
`;
console.log(artist); // "King Gizzard & The Lizard Wizard"
console.log(title); // "This Thing"
}
```
## API
The `osascript-tag` can be used in one of the following ways:
- [`osascript`](#osascript)
- [`osascript(options: Options)`](#osascriptoptions-options)
- [`osascript.jxa`](#osascriptjxa)
- [`osascript.jxa(options: JXAOptions)`](#osascriptjxaoptions-jxaoptions)
### `osascript`
Executes the given OSA script.
##### Example
```js
const result = await osascript`
tell application "Finder"
name of every file of the desktop
end tell
`;
```
##### Arguments
1. `script: string` - A string repressing the AppleScript code to execute
2. `...replacements: any[]` - The replacements values
##### Returns
A `Promise` that resolves with the script's standard output, or rejects with an error if the scripts was not successful.
### `osascript(options: Options)`
Executes the given OSA script with custom options.
##### Example
```js
const result = await osascript({ flags: 'so' })`
tell application "Finder"
name of every file of the desktop
end tell
`;
```
##### Arguments
1. `options: Options` - An object with the following keys:
- `flags?: string` - The flags used to modify the output of the script. It is a string consisting of any of the of the modifier characters `e`, `h`, `o`, and `s`. Defaults to `"eh"`. The meanings of the modifier characters are as follows:
- `h` Return values in human-readable form (default).
- `s` Return values in recompilable source form.
- `e` Redirect script errors to stderr (default)
- `o` Redirect script errors to stdout.
- `language?: string` - The language of the OSA script to be executed. Defaults to `"AppleScript"`.
##### Returns
An instance of [`osascript`](#osascript) configured with the provided options.
### `osascript.jxa`
A convenient wrapper for `osascript` configured to run JXA.
##### Example
```js
await osascript.jxa`
const app = Application.currentApplication();
app.includeStandardAdditions = true;
app.displayAlert('This is a message');
`;
```
##### Returns
An instance of [`osascript`](#osascript) configured to run JXA.
### `osascript.jxa(options: JXAOptions)`
Executes a JXA script with custom options.
##### Example
```js
const result = await osascript.jxa({ parse: true })`
const app = Application('iTunes');
return {
artist: app.currentTrack.artist(),
title: app.currentTrack.name(),
};
`;
```
##### Arguments
1. `options: JXAOptions` - An object with the following keys:
- `flags?: string` - The flags used to modify the output of the script. It is a string consisting of any of the of the modifier characters `e`, `h`, `o`, and `s`. Defaults to `"eh"`. The meanings of the modifier characters are as follows:
- `h` Return values in human-readable form (default).
- `s` Return values in recompilable source form.
- `e` Redirect script errors to stderr (default)
- `o` Redirect script errors to stdout.
- `parse?: boolean` - A boolean indicating whether the standard output of the script is parsed for consumption in JavaScript. This uses `JSON.parse` under the hood. **Note that setting this option to true will automatically set the `flags` option to `"se"` if not set explicitly otherwise**. Defaults to `false`.
- `argv?: any[]` - An array of arguments to be passed to the script. This array will be available in the JXA script itself as a global variable `argv`. Please note that all values will be serialized to strings.
##### Returns
An instance of [`osascript`](#osascript) configured to run JXA with custom options.
## Licence
MIT