How one 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). 😉

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

Let me present you a easy good day command:

import ArgumentParser

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

    func run() throws {
        print("Whats up (self.title)!")
    }
}
HelloCommand.foremost()

Now I am going to present you how you can implement the same command utilizing Vapor:

import Vapor

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

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

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

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

As you may see they virtually appear like the identical.

When you love scripting, it’s best to undoubtedly examine swift-sh and Brisk

The Swift Argument Parser library is a light-weight resolution in case you are solely on the lookout for a easy Swift script. A superb instance is a instrument that manipulates information on the system or one thing comparable. It is only one little dependency, but it surely removes a lot boilerplate out of your scripts. It means that you can concentrate on the script itself, as a substitute of parsing the command line inputs. You will discover 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 might be triggered from a command, so you may simply create a backend instrument that reads (or writes) data from the database utilizing Fluent 4. That is the principle benefit of utilizing a Vapor command, as a substitute a stanadlone Swift script.

Arguments, choices, flags

Let’s prolong the good day command with a brand new possibility and a flag. The principle distinction between an possibility and a flag is that an possibility 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 --, normally the only dashed model makes use of a brief title for a similar factor. 🤓

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

Now that you realize the essential definitions, right here is the instance:

closing class HelloCommand: Command {
        
    struct Signature: CommandSignature {

        @Argument(title: "title", assist: "The title to say good day")
        var title: String

        @Choice(title: "greeting", brief: "g", assist: "Greeting used")
        var greeting: String?

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

    let assist = "This command will say good day to a given title."

    func run(utilizing context: CommandContext, signature: Signature) throws {
        let greeting = signature.greeting ?? "Whats up"
        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 (brief and lengthy) for all the pieces, plus you may customise the assistance message for each part.

swift run Run good day john


swift run Run good day john --greeting Hello


swift run Run good day john --greeting Hello --capitalized


swift run Run good day 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 via subcommands. Utilities akin to git and the Swift bundle supervisor are in a position to present various interfaces for every of their sub-functions by implementing subcommands akin to git department or swift bundle init.

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

closing class HelloCommand: Command {
    
    static var title = "good day"
        
    
}

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 optimisation 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 good day command below the welcome namespace.

swift run Run welcome good day john --greeting "Hello" --capitalize

When you learn the Swift Argument Parser docs, you may obtain the very same conduct via a customized CommandConfiguration. Personally, I choose Vapor’s method 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 it’s a must 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: "Anticipate async duties...")
        strive todo.create(on: app.db).wait()
        
        app.logger.discover("Todo is prepared.")
    }
}

There’s a throwing wait() technique you can make the most of to “keep within the loop” till all the pieces is completed. You may as well get a pointer for the applying object through the use of the present context. The app has the database connection, so you may inform Fluent to create a brand new mannequin. Additionally you should utilize the built-in logger to print information to the console whereas the person waits. ⏳

Utilizing ConsoleKit with out Vapor

Let’s speak about overheads. Vapor comes with this neat instructions API, but additionally bundles a number of different core issues. What if I simply need the goodies for my Swift scripts? No downside. You need to use the underlying ConsoleKit by including it as a dependency.

import PackageDescription

let bundle = 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 must do some further work in your foremost.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.")
    strive console.run(group, enter: enter)
}
catch {
    console.error("(error)")
    exit(1)
}

This fashion you may eliminate many of the community associated core packages (which might be included by default in case you use Vapor). This method solely fetches swift-log as a 3rd social gathering dependency. 😍

Abstract

ConsoleKit in Vapor is a good way to put in writing CLI instruments and small scripts. The brand new Swift Argument Parser is a extra light-weight resolution for a similar downside. In case your plan is to keep up databases via scripts otherwise you carry out a number of networking or asynchronous operations it is perhaps higher to go along with Vapor, since you may at all times develop by importing a brand new part from the ecosystem.