How you can write Swift scripts utilizing the brand new Command API in Vapor 4?

Swift Argument Parser vs Vapor Instructions

Apple open-sourced a brand new library that may assist you a large number if you wish to construct scripts that written in Swift. The Swift Argument Parser was beforehand a part of the Swift Bundle Supervisor instruments, however now it’s even highly effective & has it is personal life (I imply repository). 😉

Alternatively Vapor already had a considerably related strategy to construct scripts, however in Vapor 4 the Command API is best than ever. Property Wrappers (accessible from Swift 5.1) are utilized in each instances to deal with arguments, flags & choices. Personally I like this strategy quite a bit.

Let me present you a easy hi there command:

import ArgumentParser

struct HelloCommand: ParsableCommand {
    @Argument(assist: "The title to say hi there")
    var title: String

    func run() throws {
        print("Hey (self.title)!")
    }
}
HelloCommand.essential()

Now I am going to present you the way to implement an analogous command utilizing Vapor:

import Vapor

closing class HelloCommand: Command {
    
    let assist = "This command will say hi there to a given title."

    struct Signature: CommandSignature {
        @Argument(title: "title", assist: "The title to say hi there")
        var title: String
    }

    func run(utilizing context: CommandContext, signature: Signature) throws {
        print("Hey (signature.title)!")
    }
}

public func configure(_ app: Software) throws {
    app.instructions.use(HelloCommand(), as: "hi there")
}

As you possibly can see they virtually appear like the identical.

In case you love scripting, it is best to positively verify swift-sh and Brisk

The Swift Argument Parser library is a light-weight answer in case you are solely in search of a easy Swift script. A very good instance is a software that manipulates recordsdata on the system or one thing related. It is only one little dependency, nevertheless it removes a lot boilerplate out of your scripts. It lets you concentrate on the script itself, as an alternative of parsing the command line inputs. You’ll find extra detailed examples and an in depth documentation contained in the GitHub repository. 🙏

Vapor’s Command API is beneficial if you wish to carry out extra difficult duties along with your scripts. Something that is a part of your Vapor software may be triggered from a command, so you possibly can simply create a backend software that reads (or writes) information from the database utilizing Fluent 4. That is the primary benefit of utilizing a Vapor command, as an alternative a stanadlone Swift script.

Arguments, choices, flags

Let’s lengthen the hi there command with a brand new choice and a flag. The primary distinction between an choice and a flag is that an choice has an related worth, however a flag is simply one thing that you just give to the command or not. Each choices and flags begin with a single - or a double sprint --, often the one dashed model makes use of a brief title for a similar factor. 🤓

Arguments are person supplied values learn so as (eg.: ./hi there joe bob john).

Now that you understand the fundamental definitions, right here is the instance:

closing class HelloCommand: Command {
        
    struct Signature: CommandSignature {

        @Argument(title: "title", assist: "The title to say hi there")
        var title: String

        @Possibility(title: "greeting", quick: "g", assist: "Greeting used")
        var greeting: String?

        @Flag(title: "capitalize", quick: "c", assist: "Capitalizes the title")
        var capitalize: Bool
    }

    let assist = "This command will say hi there to a given title."

    func run(utilizing context: CommandContext, signature: Signature) throws {
        let greeting = signature.greeting ?? "Hey"
        var title = signature.title
        if signature.capitalize {
            title = title.capitalized
        }
        print("(greeting) (title)!")
    }
}

Arguments are required by default, choices and flags are optionals. You possibly can have a customized title (quick and lengthy) for the whole lot, plus you possibly can customise the assistance message for each part.

swift run Run hi there john


swift run Run hi there john --greeting Hello


swift run Run hi there john --greeting Hello --capitalized


swift run Run hi there john -g Szia -c

You possibly can name the command utilizing a number of types. Be at liberty to select a most popular model. ⭐️

Subcommands

When command-line packages develop bigger, it may be helpful to divide them into a bunch of smaller packages, offering an interface by way of subcommands. Utilities equivalent to git and the Swift package deal supervisor are in a position to present various interfaces for every of their sub-functions by implementing subcommands equivalent to git department or swift package deal init.

Vapor can deal with command teams in a very cool means. I am going to add an additional static property to call our instructions, since I do not prefer to repeat myself or bloat the code with pointless strings:

closing class HelloCommand: Command {
    
    static var title = "hi there"
        
    
}

struct WelcomeCommandGroup: CommandGroup {
    
    static var title = "welcome"

    let assist: String
    let instructions: [String: AnyCommand]
    
    var defaultCommand: AnyCommand? {
        self.instructions[HelloCommand.name]
    }

    init() {
        self.assist = "search engine optimization command group assist"

        self.instructions = [
            HelloCommand.name: HelloCommand(),
        ]
    }
}

public func configure(_ app: Software) throws {

    app.instructions.use(WelcomeCommandGroup(), as: WelcomeCommandGroup.title)
}

That is it, we simply moved our hi there command below the welcome namespace.

swift run Run welcome hi there john --greeting "Hello" --capitalize

In case you learn the Swift Argument Parser docs, you possibly can obtain the very same conduct by way of a customized CommandConfiguration. Personally, I favor Vapor’s strategy right here… 🤷‍♂️

Ready for async duties

Vapor builds on prime of SwiftNIO together with EventLoops, Futures & Guarantees. Many of the API is asynchronous, however within the CLI world you need to anticipate the async operations to complete.

closing class TodoCommand: Command {
    
    static let title = "todo"

    struct Signature: CommandSignature { }
        
    let assist = "This command will create a dummy Todo merchandise"

    func run(utilizing context: CommandContext, signature: Signature) throws {
        let app = context.software
        app.logger.discover("Creating todos...")
        
        let todo = Todo(title: "Look ahead to async duties...")
        attempt todo.create(on: app.db).wait()
        
        app.logger.discover("Todo is prepared.")
    }
}

There’s a throwing wait() technique which you can make the most of to “keep within the loop” till the whole lot is completed. It’s also possible to get a pointer for the applying object through the use of the present context. The app has the database connection, so you possibly can inform Fluent to create a brand new mannequin. Additionally you should use the built-in logger to print data to the console whereas the person waits. ⏳

Utilizing ConsoleKit with out Vapor

Let’s discuss overheads. Vapor comes with this neat instructions API, but in addition bundles plenty of different core issues. What if I simply need the goodies for my Swift scripts? No drawback. You should use the underlying ConsoleKit by including it as a dependency.

import PackageDescription

let package deal = Bundle(
    title: "myProject",
    platforms: [
       .macOS(.v10_15)
    ],
    dependencies: [
        .package(url: "https://github.com/vapor/console-kit", from: "4.1.0"),
    ],
    targets: [
        .target(name: "myProject", dependencies: [
            .product(name: "ConsoleKit", package: "console-kit"),
        ])
    ]
)

You continue to need to do some further work in your essential.swift file, however nothing severe:

import ConsoleKit
import Basis

let console: Console = Terminal()
var enter = CommandInput(arguments: CommandLine.arguments)
var context = CommandContext(console: console, enter: enter)

var instructions = Instructions(enableAutocomplete: true)
instructions.use(HelloCommand(), as: HelloCommand.title, isDefault: false)

do {
    let group = instructions.group(assist: "Utilizing ConsoleKit with out Vapor.")
    attempt console.run(group, enter: enter)
}
catch {
    console.error("(error)")
    exit(1)
}

This manner you possibly can do away with a lot of the community associated core packages (which might be included by default should you use Vapor). This strategy solely fetches swift-log as a 3rd celebration dependency. 😍

Abstract

ConsoleKit in Vapor is an effective way to write down CLI instruments and small scripts. The brand new Swift Argument Parser is a extra light-weight answer for a similar drawback. In case your plan is to keep up databases by way of scripts otherwise you carry out plenty of networking or asynchronous operations it could be higher to go together with Vapor, since you possibly can at all times develop by importing a brand new part from the ecosystem.