ScPL (Shortcuts Programming Language)

ScPL is a programming language designed for writing iOS Shortcuts in text. It provides an alternative to the standard drag-and-drop interface in the Shortcuts app, making it easier to manage large, complex shortcuts by allowing you to copy, paste, and type actions directly.

Note: ScPL has not been updated to support the new iOS 13/14+ actions. If you require support for newer iOS actions, consider using Jellycuts.

If an action requires many arguments, use an arglist (denoted by a{ ... }) to spread them across multiple lines for better readability. This is particularly useful for complex actions like getfile.

getfile a{
  service="iCloud Drive"
  showdocumentpicker=false
  filepath="/myfile.txt"
  errorifnotfound=false
}

ScPL allows you to nest actions inside text fields or other fields that accept variables using the \(action) syntax. This creates a 'magic variable' that directly references the result of that nested action without needing to explicitly name it.

Additionally, you can use actions inside the arguments of other actions to avoid disrupting the main action's input flow. This is useful for conditional logic where you want to check a value without changing the data being passed to the primary action.

// Nesting an action inside a text field
Text "My number is \(Number -2.5)"

// Using an action inside another action's argument
If Equals (Text "Goodbye")
	ShowResult "If the action input was disrupted, this would run"
Otherwise
	QuickLook
End If

Parser variables exist only during the ScPL parsing phase and are replaced with their values when the shortcut is generated. They are defined using @set and accessed using @:variableName.

Parser variables can hold:

• Simple values (strings, numbers).
• Lists (e.g., [1, 2, 3]).
• Actions or lists of actions.
• Dictionaries of other parser variables (passed via {key:value} syntax).

// Setting and using a simple variable
@set varname "value"
text "value is \(@:varname)"

// Setting a list
@set list [1, 2, 3]
list @:list

// Setting an action
@set myaction (text "hi")
@:myaction

// Setting a macro that takes input
@set test (Text @:value)
@:test{value:"Hi!"}

Aggrandizements allow you to transform or access specific properties of a variable using a specialized syntax within GetVariable.

Supported aggrandizements:

• as/coerce: Coerce the variable to a specific type (e.g., as:Dictionary).
• key/forKey: Access a key in a dictionary (e.g., key:myKey).
• get/getProperty: Access a property (partial support).

Shortcut Syntax: For dictionary access, you can use the shorthand v:VariableName:KeyName instead of the full {as:Dictionary,key:KeyName} syntax.

// Full syntax
GetVariable v:MyVariable{as:Dictionary,key:myKey}

// Shorthand syntax
GetVariable v:MyDictionary:myKey

The ^(action) syntax, known as InputArg, allows you to provide a specific value to an action that would otherwise use the previous action's output. This effectively 'disrupts' the input chain by injecting a new value into the next action.

Text "Some text"
QuickLook ^(Text "Different text")

The Nothing action (internally identified as is.workflow.actions.nothing) performs no operation and produces no output. It is primarily used for two purposes:

1. Separation: To visually or logically separate blocks of actions within a workflow.
2. Input Clearing: To ensure that no input is passed to the subsequent action in a sequence (since InputPassthrough is set to false).

You can invoke this action using the keyword Nothing or any of its associated keywords: nil, nothing, empty, discard, or clear.

You can create SetVariable actions using two different syntaxes:

1. Arrow syntax: Append -> v:VariableName to an action.
2. Assignment syntax: Use mv:VariableName = action before the action.

Both methods automatically generate the necessary logic to store the action's output into a named variable.

// Arrow syntax
Text "My Text" -> v:MyNamedVariable

// Assignment syntax
mv:WowMagic = Text "My Text"

You can restrict the number of music items returned using the limit and getItems arguments.

• limit: A switch that accepts a boolean (true or false) or a variable.
• getItems: A stepper number that accepts a number or a variable. This argument is only enabled if limit is set to true.

The WFPhoneNumber parameter (type WFPhoneNumberFieldParameter) is not yet fully implemented in ScPL.

If you need to use this parameter, you can attempt to use a raw value. A suggested workaround is to convert an existing .shortcut file to a .scpl file to extract the specific values you want to use in this parameter.