Scripts

mash.scripts · Platform

mash.scripts runs one saved script from another. Use it to share a routine between automations, to hand heavy work to a background worker, or to run a script on a file you’ve just found. The script it runs is a saved mashlet from Settings > MaSH, found by name, id or UUID.

How it works

Three ways to start a script. run runs it now and waits, and gives you what the script returns. queue starts it on a background worker and gives you a job at once, with an optional delay. import runs it now, and prints its output into yours too.

The other script is told what it’s working on. file becomes its mash.event.file, user is who it acts as, and input (a dictionary) becomes mash.event.input. The script reads them the way any event script does.

It returns a value. return in the script gives run and import their result. A job’s result holds it when the script was queued.

An error in the other script is an error in yours. If it fails, run raises an error that names the script and carries its message.

Scripts written by a user can only run their own. An automation owned by a user can look up, run and queue only the scripts that user owns. Naming someone else’s script is refused. It can act only as its own owner. Administrators have no such limit.

Common tasks

Call a shared routine and use its answer:

set tidy to mash.scripts.run("tidy-name", null, null, {name: "  ada LOVELACE "})
printline tidy

That script reads its input and returns:

set input to mash.event.input ?? {}
set name to mash.str(input["name"] ?? "").trim().title(true).toString()
return name

Run a script on a file in the background, a minute from now:

set doc to mash.event.file
set job to mash.scripts.queue("file-invoice", doc, null, {source: "inbox"}, mash.date.now().addMinutes(1))
printline "Queued job {{job.id}}"

Find scripts by wildcard:

set found to mash.scripts.get("invoice-*")
printline "{{found.count()}} scripts match"

Watch out for

• A script that queues or runs itself can loop forever. Guard against it, for example by passing a flag in input and checking it.
• queue takes a date for the delay, not a number of seconds. Build it with mash.date.now().addMinutes(1).
• get with a wildcard gives a list, and an exact name gives the script. Check which you asked for.
• Passing a file doesn’t copy it. The other script opens the same file, so it sees the same changes.
• Input is plain data. Pass names, numbers, lists and dictionaries. Pass a File as file, not inside input.

See also

Reacting to events, mash.event, and mash.queue for following a queued job.

Methods

get

scripts.get(str: int) → Mashlet

Get a mashlet by ID, name, or wildcard pattern.

import

scripts.import(script: mixed, file?: mixed, user?: mixed, input?: array)

Import and execute a mashlet, returning its result.

queue

scripts.queue(script: mixed, file?: mixed, user?: mixed, input?: mixed, delay?: Date) → Job

Queue a mashlet for background execution.

run

scripts.run(script: mixed, file?: mixed, user?: mixed, input?: array)

Run a mashlet synchronously.