An iOS 14 Shortcuts creator written in Swift, inspired by SwiftUI.
SwiftShortcuts is distributed using the Swift Package Manager. To install it into a project, add it as a dependency within your Package.swift
manifest:
let package = Package(
...
dependencies: [
.package(url: "https://github.com/a2/swift-shortcuts.git", from: "1.0.0")
],
...
)
Then import SwiftShortcuts in your project wherever you'd like to use it:
import SwiftShortcuts
SwiftShorcuts was inspired by SwiftUI and, just as every SwiftUI View
is made from other View
types, so too is every Shortcut
built from other Shortcut
types. The only requirement of the Shortcut
protocol is an instance property named body
whose type is another Shortcut
:
/// A type that represents a user workflow, or a part of one, in the Shortcuts app.
public protocol Shortcut {
/// The type of shortcut representing the body of this shortcut.
///
/// When you create a custom shortcut, Swift infers this type from your
/// implementation of the required `body` property.
associatedtype Body: Shortcut
/// The contents of the shortcut.
var body: Body { get }
}
To start writing your own shortcut, create a type (such as a struct
) that conforms to the Shortcut protocol. At first, return a Comment
with some "Hello, world!" text.
// main.swift
struct HelloWorldShortcut: Shortcut {
var body: some Shortcut {
Comment("Hello, world!")
}
}
To create a file that you can import into the Shortcuts app, call the build()
function on your shortcut and write the Data
to a file.
// continued from above
let shortcut = HelloWorldShortcut()
let data = try shortcut.build()
try data.write(to: URL(fileURLWithPath: "Hello World.shortcut"))
Now you can share (for example, via AirDrop) the Hello World.shortcut file to your device and it will open in the Shortcuts app. Unfortunately iOS 13 does not support opening serialized .shortcut
files.
Saves the output of BatteryLevel
shortcut to an OutputVariable
and later references that value in a ShowResult
shortcut.
// Swift 5.2
import SwiftShortcuts
struct BatteryLevelShortcut: Shortcut {
@OutputVariable var batteryLevel: Variable
var body: some Shortcut {
ShortcutGroup {
Comment("This Shortcut was generated in Swift.")
BatteryLevel()
.savingOutput(to: $batteryLevel)
If(batteryLevel < Number(20), then: {
SetLowPowerMode(true)
ShowResult("Your battery level is \(batteryLevel)%; you might want to charge soon.")
}, else: {
ShowResult("Your battery level is \(batteryLevel)%; you're probably fine for now.")
})
}
}
}
Takes advantage of the usingResult()
function to chain shortcut outputs to shortcut inputs.
// Swift 5.2
import SwiftShortcuts
struct ClapAlongShortcut: Shortcut {
var body: some Shortcut {
ShortcutGroup {
Comment("This Shortcut was generated in Swift.")
AskForInput(prompt: "WHAT π DO π YOU π WANT π TO π SAY")
.usingResult { providedInput in
ChangeCase(variable: providedInput, target: .value(.uppercase))
}
.usingResult { changedCaseText in
ReplaceText(variable: changedCaseText, target: "[\\s]", replacement: " π ", isRegularExpression: true)
}
.usingResult { updatedText in
ChooseFromMenu(items: [
MenuItem(label: "Share") {
Share(input: updatedText)
},
MenuItem(label: "Copy to Clipboard") {
CopyToClipboard(content: updatedText)
},
])
}
}
}
}
Shorten with small.cat
A more complicated example that temporarily shortens a URL or some text with the small.cat service.
// Swift 5.2
import SwiftShortcuts
struct ShortenWithSmallCatShortcut: Shortcut {
@OutputVariable var url: Variable
@OutputVariable var expiry: Variable
var body: some Shortcut {
ShortcutGroup {
GetType(input: .shortcutInput)
.usingResult { type in
If(type == "URL", then: {
Text("\(.shortcutInput)")
}, else: {
GetClipboard()
})
}
.usingResult { ifResult in
URLEncode(input: "\(ifResult)")
}
.savingOutput(to: $url)
ChooseFromMenu(prompt: "Expires in:", items: [
MenuItem(label: "10 minutes") {
Text("10")
},
MenuItem(label: "1 hour") {
Text("60")
},
MenuItem(label: "1 day") {
Text("1440")
},
MenuItem(label: "1 week") {
Text("10080")
},
])
.savingOutput(to: $expiry)
GetContentsOfURL(method: .POST, url: "https://small.cat/entries", body: .form([
"entry[duration]": "\(expiry)",
"entry[value]": "\(url)",
"utf8": "β",
])).usingResult { contents in
GetURLsFromInput(input: "\(contents)")
}.usingResult { urls in
FilterFiles(input: urls, filters: .all([
NameFilter(beginsWith: "http://small.cat/"),
NameFilter(isNot: "http://small.cat/"),
]), limit: 1)
}.usingResult { url in
ChooseFromMenu(items: [
MenuItem(label: "Copy") {
CopyToClipboard(content: url)
},
MenuItem(label: "Share") {
Share(input: url)
},
MenuItem(label: "Show") {
ShowAlert(title: "Small.cat", message: "\(url)", showsCancelButton: false)
},
])
}
}
}
}
SwiftShortcuts began as the similarly named ShortcutsSwift and was originally inspired by Shortcuts JS. Both SwiftShortcuts, and ShortcutsSwift before it, aimed to be in Swift what Shortcuts JS is for JavaScript.
The goal of this iteration of SwiftShortcuts is to make writing Shortcuts app workflows in Swift as easy as composing View
s in SwiftUI. As you can see above, even the base Shortcut
protocol is heavily inspired by SwiftUI's View
protocol.
This repository does not contain every possible Shortcuts-supported action or every possible permutation of parametres for those shortcuts. Please feel free to contribute missing shortcut types and even test cases.
SwiftShortcuts is available under the MIT license. See the LICENSE file for more info.
Inspired by the support model behind Publish.
SwiftShortcuts is developed completely in the open, and your contributions are more than welcome.
This project does not come with GitHub Issues-based support, and users are instead encouraged to become active participants in its continued development β by fixing any bugs that they encounter, or by improving the documentation wherever it's found to be lacking.
If you wish to make a change, open a Pull Request β even if it just contains a draft of the changes you're planning, or a test that reproduces an issue β and we can discuss it further from there.
Hope you'll enjoy using SwiftShortcuts!