Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/wsmd/osascript-tag
📜 JavaScript template literal tag for executing OSA scripts (AppleScript, JavaScript, etc.)
https://github.com/wsmd/osascript-tag
apple applescript automation darwin javascript macos nodejs osascript osx
Last synced: 19 days ago
JSON representation
📜 JavaScript template literal tag for executing OSA scripts (AppleScript, JavaScript, etc.)
- Host: GitHub
- URL: https://github.com/wsmd/osascript-tag
- Owner: wsmd
- License: mit
- Created: 2019-04-30T04:39:35.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2023-01-03T21:01:20.000Z (almost 2 years ago)
- Last Synced: 2024-10-11T12:56:05.299Z (about 1 month ago)
- Topics: apple, applescript, automation, darwin, javascript, macos, nodejs, osascript, osx
- Language: TypeScript
- Homepage:
- Size: 851 KB
- Stars: 10
- Watchers: 2
- Forks: 0
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
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