Types

Table of contents

  1. Value Types
    1. Text
    2. Raw Text
    3. Number
    4. Float
    5. Expression
    6. Boolean
    7. Dictionary
    8. Array
    9. Action Result
    10. Enumerations
    11. Empty
  2. Type Declaration
  3. Type Coercion
    1. Text
    2. Number
    3. Dictionary
  4. Content Item Types

Value Types

Text

@variable = "text"
@text = "text {variable} \n"

Text literals support the interpolation of variables and escape characters.

Standard escaped characters interpolated:

  • \" double quote
  • \n new line
  • \t tab
  • \\ backslash

For example:

@multi = "multi\nline\ntext"

Multiline text is also supported, however:

@multi = "multi
line
text"

Raw Text

@raw = 'i\'m text'

Raw text cancels out interpolation other than escaped single quotes. As a result, they compile much faster than standard text literals.

One caveat to raw text is that it is not allowed in Dictionaries or Arrays. This is because a dictionary or array must be a valid JSON object.

Number

@number = 42

Float

@float = 0.5

Expression

@expression = 54 + (6 * 7)

Only two operands will compile to a Math action:

@expression = 54 + 6

You can use a variable reference in an expression:

@number = 42
@expression = 54 * number + (6 * 7)

Boolean

Booleans translate to a number value of 1 for true and 0 for false.

@boolVarTrue = true
@boolVarFalse = false

Boolean variables can be used in conditionals.

@boolVarTrue = true
if boolVarTrue == true {
    /* ... */
}

Dictionary

You can declare a dictionary using valid JSON syntax.

/* Empty dictionaries */
@x: dictionary
@y = {}

@text = "text"
@dictionary = {
    "key1": "value {text}",
    "key2": 5,
    "key3": true,
    "key4": [
        "item1",
        "item 2",
        "item3"
    ]
}

You can access a dictionary value by key:

@dictionary = {}

// allows for variable references
getValue(dictionary, "key")

// must be a raw string, so no variable references are allowed.
@value = dictionary['key']

Array

An array is a variable, that has been or will be added to, to create a variable with multiple iterable values.

The contents of an array value must be valid JSON syntax.

/* Empty arrays */
@x: array
@y = []

@int = 42
@array = [5, "test", {"test":5}, "{int}"]

/* Add a value to the array variable */
@array += "another test"

You can use the for statement to iterate over the values contained in the array variable.

@items = ["Item 1","Item 2"]
for item in items {
    /* ... */
}

You can easily append to an array using the += syntax.

@x: array
@x += 5

This adds the output of the Number action with a value of 5 to the array variable x.

So x now contains 1 item with a number value of 5.

Action Result

Actions have output types. View the actions documentation to check the output type of an action, or use the --action= argument in the CLI.

@urls = url("https://apple.com","https://google.com")
@list = list("Item 1","Item 2","Item 3")
@email = emailAddress("test@test.org")
@phone = phoneNumber("(555) 555-5555")
@date = date("October 5, 2022")
@location = getCurrentLocation()

Enumerations

Some actions have arguments with the type enum, accompanied by a set of allowed values. This type only accepts specific string values.

Future release

To define enumerations for use as a type for custom actions and action definitions, use the following syntax:

enum Color {
    'Red',
    'Green',
    'Blue'
}

#define action 'com.example.app.action' myCustomAction(Color color)

myCustomAction("Purple") // throws an error

It accepts raw string comma-separated values.

Various formats are accepted:

enum Colors
{
    'Red',
    'Green',
    'Blue'
}

enum Colors {
    'Red', 'Green', 'Blue'
}

enum Colors {'Red','Green','Blue'}

Empty

You can declare a variable with no value

@empty

Or more explicitly, set the value as nil

@empty = nil

You can use nil just about anywhere to cancel out an optional value.

However, if, due to the value being optional, it has a default, it will be set to its default, not empty.

@var = getFile(nil)

if var == nil {

}

repeat i for nil {

}

for item in nil {

}

nil can skip an argument that is optional to set an argument after it.

@media = nil
setMetadata(media, nil, "Title")

nil is also faster to compile than empty text "", array, etc.

Type Declaration

You can declare a variable with a type but no initial value.

This is particularly useful for creating a variable and then appending to it, then using it with an action that expects that type of value.

Setting a variable’s value type explicitly also compiles faster than having to infer the types from empty values like "", [], or {}.

@t: text
@num: number
@list: array
@obj: dictionary
@boolean: bool
@reference: var
@real: float

@builder: text
for item in list {
    @builder += "{item}"
}

/* This would have thrown an error if `@builder` was not of type text. */
show(builder)

The following types may be used:

  • text (default: "")
  • number (default: 0)
  • bool (default: false)
  • dictionary (default: {})
  • array (default: [])
  • var (variable reference)
  • float (future release)

Type Coercion

You can currently do the following type coercions.

Text

@var = 5
@textVar = var.text

To coerce another value to text, simply reference it as an inline variable just as you would in Shortcuts.

@var = 5
@textVar = "{var}"

Or you can use…

@var = 5
@textVar = getText(var)

Number

@var = "5"
@textVar = var.number
@inlineVar = "{var.number}"
@textVar = "5"
@numVar = getNumbers(textVar)

The number() action should only coerce another value to a number, as an integer produces the same output.

@textVar = "5"
@numVar = number(textVar)

Dictionary

@var
@textVar = getDictionary(var)

Content Item Types

There is a concept of data types in Shortcuts known as a “content item”.

These are defined in Shortcuts, for example WFAppStoreAppContentItem.

In Cherri, they are shortened into singular names.

Type Content Item Type
app WFAppStoreAppContentItem
article WFArticleContentItem
contact WFContactContentItem
date WFDateContentItem
email WFEmailAddressContentItem
folder WFFolderContentItem
file WFGenericFileContentItem
image WFImageContentItem
itunes WFiTunesProductContentItem
location WFLocationContentItem
maplink WFDCMapsLinkContentItem
media WFAVAssetContentItem
pdf WFPDFContentItem
phonenumber WFPhoneNumberContentItem
richtext WFRichTextContentItem
webpage WFSafariWebPageContentItem
text WFStringContentItem

Copyright ©. Distributed under the GPL-2.0 License. Siri Shortcuts and Mac are registered trademarks of Apple Inc. Apple is not involved in this project in any way. Do not contact Apple Support unless you are having an issue with the Shortcuts app itself.