Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

(lisppad applet)

Library (lisppad applet) provides an API for Scheme programs that are invoked via the macOS and iOS Shortcuts app. An applet is a LispPad program that can be executed by the "Run Program" app intent within the iOS Shortcuts app or other apps that support Apple's App Intents framework. The library enables applets to read their input arguments, construct result values to return to the caller, manage applet attachments, and display simple interactive dialogs. With the API of (lisppad applet), it is possible to write Scheme programs that run both in the LispPad app as well as in Shortcuts workflows.

Program model

Applets are programs that receive two types of inputs, arguments and attachments, via procedures applet-arguments and applet-attachments. arguments are of type string, attachments are of type applet-attachment. applet-attachment objects represent binary data. They are either persistet and have a file URL, or they are transient. applet-attachment objects also have a filename and an optional Uniform Type Identifier (UTI) identifying the type of the binary data.

An applet returns an object of type applet-result which has the following components: result strings (representing textual results), result attachments, i.e. applet-attachment objects (representing binary data), a string representation of the value the last statement of the program evaluates to, a transcript collecting all output to standard out, and a "view" consisting of a sequence of strings and images which are displayed on demand, e.g. after an applet ran as part of a shortcut on iOS or macOS. Applets typically construct an applet-result object explicitly and return it as the result of the program.

Using applets in Shortcuts

LispPad makes the following 3 intents available in the Shortcuts app:

Run Program is used to execute an applet within Shortcuts. Get Result Attachment and Get Result Value are used to extract individual attachments and result strings from an applet result object. Other components can be accessed directly as "magic variables" from the applet result object.

All other parameters, especially the ones made available as arguments via applet-arguments and as attachements via applet-attachments can be configured in the optional section of the Run Program intent:

The remaining two intents, Get Result Attachment and Get Result Value, take an applet result as their first parameter followed by an index that identifies the concrete attachment or string to return.

Execution context

(running-as-applet?)

Returns #t if the program is currently executing as an applet using the Run Program intent within Shortcuts. Returns #f if the program is running interactively in LispPad.

Applet input

Applets receive arguments and attachments from the caller. Arguments are strings, attachments encapsulate binary data represented as applet-attachment objects. Both types of input can be accessed either directly via an index, or as a whole in form of a list.

(applet-argument index) (applet-argument index default) (applet-argument index default force-orig?)

Returns the argument string at index. If there is no argument at this index, string default is returned if provided and not set to #f, otherwise #f is returned. force-orig? determines if the argument resolution includes a potential input override (default) or if the argument is required to come from the caller.

(applet-arguments) (applet-arguments force-orig?) (applet-arguments defaults) (applet-arguments force-orig? defaults) (applet-arguments _defaults force-orig? _)

Returns a list of the string arguments passed to the applet. If defaults is provided, it is a list of default values. For each position where no string argument was supplied (or the supplied string is empty), the corresponding element from defaults is used instead. If defaults is provided and has fewer elements than the number of arguments, only the first (length defaults) arguments are returned.

If force-orig? is #f (or not provided) and an argument override has been set via applet-input-override!, the override values are used instead of the actual applet arguments. Setting force-orig? to #t forces the procedure to always return the actual applet arguments, ignoring any override. Elements for which no string was provided and no default was given are returned as #f.

(applet-attachment index) (applet-attachment index default) (applet-attachment index default force-orig?)

Returns the attachment at index. If there is no attachment at this index, applet-attachment object default is returned if provided and not set to #f, otherwise #f is returned. force-orig? determines if the attachment resolution includes a potential input override (default) or if the attachment is required to come from the caller. Attachments are always represented as applet-attachment objects.

(applet-attachments) (applet-attachments force-orig?) (applet-attachments defaults) (applet-attachments force-orig? defaults) (applet-attachments defaults force-orig?)

Returns a list of the attachments passed to the applet as applet-attachment objects. Behaves analogously to applet-arguments: defaults provides fallback values for missing attachments, and force-orig? controls whether an active argument override is applied. Elements for which no attachment was provided and no default was given are returned as #f.

(applet-input-override! result)

Installs result, an applet-result object, as an override for the applet's input arguments. Subsequent calls to applet-arguments and applet-attachments (without force-orig? set to #t) will return the arguments and attachments stored in result instead of the actual applet arguments. If result is #f, any existing override is removed. Returns the previous override, or #f if there was none. This procedure is useful for testing applets interactively in the LispPad interpreter by simulating applet input.

Applet results

An applet-result object is a mutable object that collects string values and attachments to be returned to the caller when the applet finishes. The make-applet-result procedure creates a new result and the various applet-result-* procedures build it up incrementally.

(make-applet-result) (make-applet-result obj ...)

Creates and returns a new applet-result object. Each obj argument is added to the result immediately using the same rules as applet-result-append!. String arguments are added to the result's string list whereas images, PDF documents, styled text, bytevectors, and archives are added to the result's attachment list. void values are ignored. Other values are converted to their corresponding string representation and treated as a string.

(applet-result? obj)

Returns #t if obj is an applet-result object, #f otherwise.

(applet-result-append! result obj)

Appends obj to the applet-result result. Depending on the type of obj, result is muted accordingly:

  • string: appended to the result's string list.

  • bytevector: appended to the result's attachment list as a generic attachment named "Output".

  • drawing: encoded as PNG and appended to the result's attachment list as "Output.png".

  • image: encoded as JPEG and appended to the result's attachment list as "Output.jpg".

  • abstract-image: encoded as JPEG and appended to the result's attachment list as "Output.jpg".

  • pdf: appended to the result's attachment list as "Output.pdf".

  • styled-text: encoded as RTF and appended to the result's attachment list as "Output.rtf".

  • zip-archive: appended to the result's attachment list as "Output.zip".

  • tar-archive: appended to the result's attachment list as "Output.tar".

  • applet-result: all strings and attachments from obj are merged into result.

  • void: ignored.

  • All other values get converted to their string representation and appended to the string list.

(applet-result-values result)

Returns the list of strings collected in result. Entries that were appended as #f appear as #f in the returned list.

(applet-result-value-append! result str)

Appends str to the string list of applet-result result. If str is #f, a #f placeholder is appended instead. Returns the zero-based index of the newly added string.

(applet-result-attachments result)

Returns the list of attachments collected in applet-result result as applet-attachment objects. Entries that were appended as #f appear as #f in the returned list.

(applet-result-attachment-append! result attm)

Appends the applet-attachment object attm to the attachment list of applet-result result. If file is #f, a #f placeholder is appended. Returns the zero-based index of the newly added attachment.

(applet-result-view result)

Returns a list of view entries associated with an applet result object result, or #f if no view has been set. Each entry of the view is either a string (for text output) or an image object (for drawing results).

The view is an optional component of an applet result that can contain a sequence of console output entries. Drawing results are converted to native image objects when returned. The list is returned in the order entries were appended

(applet-result-view-clear! result) (applet-result-view-clear! result override)

Clears or disables the view for the applet result object result. Argument override is an optional boolean value that determines the clearing behavior: If #t or omitted: creates an empty view; if #f: disables the view entirely.

(applet-result-view-append! result obj)

Appends an object obj to the view of an applet result result. If the view has not been initialized yet, it will be set to the empty list before obj is added. obj is either a string, a drawing, an image, an abstract image, or another object that will be converted into a string.

Applet attachments

An applet-attachement wraps a binary object that is either received as an applet input argument or constructed programmatically to be included in an applet result. Applet attachments carry a filename (you can think of them as virtual files), an optional file system path, an optional Uniform Type Identifier (UTI), and their binary content.

(make-applet-attachment path) (make-applet-attachment path name) (make-applet-attachment path name type) (make-applet-attachment bytevector name) (make-applet-attachment bytevector name type)

Creates a new applet-attachment object. When given a string path, the file at that path is wrapped in the newly created attachment. When given a bytevector, the bytes are used as the attachment content. name is the filename to associate with the attachment. type is a string containing a UTI (Uniform Type Identifier) such as "public.plain-text" or "com.adobe.pdf". Returns #f if type is provided but is not a valid UTI.

(applet-attachment? obj)

Returns #t if obj is an applet attachment object, #f otherwise.

(applet-attachment-transiet? attm)

Returns #t if applet attachment attm is transient, i.e. there is no persistent underlying file backing the applet attachment. Returns #f if there is a persistent file associated with the attachment.

(applet-attachment-name attm)

Returns the filename of attm as a string.

(applet-attachment-path attm) (applet-attachment-path attm percent-encoded?)

Returns the file path of attm as a string, or #f if attm was created from in-memory data and has no associated path. If percent-encoded? is #t, the path is returned with percent-encoded characters; otherwise (the default) the path is decoded.

(applet-attachment-type attm)

Returns the UTI type identifier of applet attachment attm as a string (e.g. "public.png"), or #f if no type information is available.

(applet-attachment-data attm) (applet-attachment-data attm type)

Returns the raw content of applet attachment attm as a bytevector, or #f if the data cannot be retrieved. If type is provided (a UTI string), the data is requested in that specific content type (requires iOS 18 or later; on earlier versions the type argument is ignored).

(applet-attachment-available-types attm)

Returns a list of UTI type identifier strings representing the content types in which applet attachment attm can be provided. Returns #f on iOS versions earlier than 18.0.

(applet-attachment->object attm) (applet-attachment->object attm type)

Reads applet attachment data of attm and converts it to a native LispKit object based on its content type. If type is provided (a UTI string), it is used instead of the attachment's declared type. Returns #f if conversion is not possible or the data cannot be read.

The following conversions are supported:

  • Plain text types (public.plain-text, public.utf8-plain-text, etc.) → string

  • UTF-16 text types (public.utf16-plain-text) → string

  • Image types (public.png, public.jpeg, public.tiff, public.gif, com.microsoft.bmp) → image

  • PDF (com.adobe.pdf) → PDF document

  • RTF (public.rtf) → styled text

  • RTFD / flat RTFD → styled text

  • ZIP archive (public.zip-archive) → zip archive

  • TAR archive (public.tar-archive) → tar archive

Interaction dialogs

These procedures allow an applet to interact with the user by displaying simple dialogs. They can also be used when running interactively in the LispPad interpreter, in which case they show as in-app alert dialogs.

(applet-confirmation-dialog prompt) (applet-confirmation-dialog prompt style)

Displays a confirmation dialog with the message prompt and waits for the user to confirm or cancel. Returns #t if the user confirmed, #f if they cancelled.

style controls the presentation. When running as an applet, if style is #f the dialog is shown in the classic action-sheet style; otherwise the modern confirmation UI is used (default). When running in the LispPad interpreter, if style is a string it is used as the dialog title; otherwise "Confirm" is used as the title.

(applet-read-dialog prompt) (applet-read-dialog prompt title)

Displays a text-input dialog with the message prompt and waits for the user to enter a value. Returns the entered string, or #f if the user cancelled. title is used as the dialog title (default: "Input"). When running as an applet, the title argument is ignored.

(applet-choice-dialog prompt options) (applet-choice-dialog prompt options style)

Displays a choice dialog with the message prompt offering the user the alternatives in options. Returns the zero-based index of the chosen option, or #f if the user cancelled.

options is a list of alternatives. Each element is either a string (the title of the option) or a pair (title . style) where style controls the button appearance:

  • () (empty list) or absence of a pair: plain button (default)

  • #t: destructive button (shown in red)

  • #f: cancel button

style controls presentation style. When running as an applet, #f selects the classic action-sheet style; any other value selects the modern style (default). When running in the LispPad interpreter, a string style is used as the dialog title; otherwise "Choose" is used.

PreviousLispPad
Next(lisppad applescript)

Last updated