Types

Table of contents

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

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

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 line 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

Expression

@expression = 54 + (6 * 7)

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 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

@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()

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 you need 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 be used to 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 type and read the empty value such as "", [], or {}. The last two in particular have a JSON parser read their empty values.

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

@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
  • var (variable reference)

Type Coercion

You can currently do the following type coercions.

Text

@var = 5
@textVar = var.text

There exists no text() action, as text literals create a text action. To coerce another value to text, simply reference it as an inline variable just as you would in Shortcuts.

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

If for some reason that doesn’t work, use the getText() action.

@var = 5
@textVar = getText(var)

Number

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

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

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

Dictionary

@var
@textVar = getDictionary(var)