From e9ea71c141f7531cd207f085cc796aad3f915052 Mon Sep 17 00:00:00 2001 From: tanner0101 Date: Thu, 5 Apr 2018 15:50:48 -0400 Subject: [PATCH] add command and logger docs --- 3.0/docs/command/getting-started.md | 44 +++++++- 3.0/docs/command/overview.md | 169 +++++++++++++++++++++++++++- 3.0/docs/console/getting-started.md | 2 +- 3.0/docs/console/overview.md | 2 +- 3.0/docs/logging/getting-started.md | 44 +++++++- 3.0/docs/logging/overview.md | 18 ++- 6 files changed, 269 insertions(+), 10 deletions(-) diff --git a/3.0/docs/command/getting-started.md b/3.0/docs/command/getting-started.md index 29e518a6..da685799 100644 --- a/3.0/docs/command/getting-started.md +++ b/3.0/docs/command/getting-started.md @@ -1,3 +1,43 @@ -# Getting Started with Async +# Getting Started with Command -Coming soon. \ No newline at end of file +The Command module is provided as a part of Vapor's Console package ([vapor/console](https://github.com/vapor/console)). This module provides APIs for creating command-line interfaces (CLIs). It's what powers the [Vapor Toolbox](../getting-started/toolbox.md). + +!!! tip + For an in-depth look at all of Command's APIs, check out the [Command API docs](https://api.vapor.codes/console/latest/Command/index.html). + +## Usage + +This package is included with Vapor and exported by default. You will have access to all `Command` APIs when you import `Vapor`. + +```swift +import Vapor // implies import Command +``` + +### Standalone + +The Command module, part of the larger Vapor Console package, can also be used on its own with any Swift project. + +To include it in your package, add the following to your `Package.swift` file. + +```swift +// swift-tools-version:4.0 +import PackageDescription + +let package = Package( + name: "Project", + dependencies: [ + ... + /// 💻 APIs for creating interactive CLI tools. + .package(url: "https://github.com/vapor/console.git", from: "3.0.0"), + ], + targets: [ + .target(name: "Project", dependencies: ["Command", ... ]) + ] +) +``` + +Use `import Command` to access the APIs. + +## Overview + +Continue to [Command → Overview](overview.md) for an overview of Command's features. \ No newline at end of file diff --git a/3.0/docs/command/overview.md b/3.0/docs/command/overview.md index a92fbc66..960e572f 100644 --- a/3.0/docs/command/overview.md +++ b/3.0/docs/command/overview.md @@ -1,3 +1,168 @@ -# Async Overview +# Command Overview -Coming soon. \ No newline at end of file +This guide will introduce you to the Command module by showing you how to create your own CLI. For this example, we will implement [`cowsay`](https://en.wikipedia.org/wiki/Cowsay), a command that prints an ASCII picture of a cow with a message. + +!!! tip + You can install the real `cowsay` program using `brew install cowsay`. + +```sh +$ cowsay Hello + ----- +< Hello > + ----- + \ ^__^ + \ (oo\_______ + (__)\ )\/\ + ||----w | + || || +``` + +## Command + +The first step is to create a type that conforms to [`Command`](https://api.vapor.codes/console/latest/Command/Protocols/Command.html). + +```swift +/// Generates ASCII picture of a cow with a message. +struct CowsayCommand: Command { + ... +} +``` + +Now let's implement the required methods. + +### Arguments + +Commands can have zero or more [`CommandArgument`](https://api.vapor.codes/console/latest/Command/Structs/CommandArgument.html)s. These arguments will be required for the command to run. + +```swift +/// Generates ASCII picture of a cow with a message. +struct CowsayCommand: Command { + /// See `Command` + var arguments: [CommandArgument] { + return [.argument(name: "message")] + } + + ... +} +``` + +Here we are defining one argument, the `message` that the cow will say. This is required to run the `cowsay` command. + +### Options + +Commands can have zero or more [`CommandOption`](https://api.vapor.codes/console/latest/Command/Structs/CommandOption.html)s. These options are not required for the command to run and can be passed using `--` or `-` syntax. + +```swift +/// Generates ASCII picture of a cow with a message. +struct CowsayCommand: Command { + ... + /// See `Command` + var options: [CommandOption] { + return [ + .value(name: "eyes", short: "e", default: "oo", help: ["Change cow's eyes"]), + .value(name: "tongue", short: "t", default: " ", help: ["Change cow's tongue"]), + ] + } + ... +} +``` + +Here we are defining two options, `eyes` and `tongue`. These will let the user optionally change how the cow looks. + +### Help + +Next we can define an optional help message to display when the user passes `--help`. + +```swift +/// Generates ASCII picture of a cow with a message. +struct CowsayCommand: Command { + ... + /// See `Command` + var help: [String] { + return ["Generates ASCII picture of a cow with a message."] + } + ... +} +``` + +Let's take a look at how this will look once our command is complete: + +```sh +Usage: cowsay [--eyes,-e] [--tongue,-t] + +Generates ASCII picture of a cow with a message. + +Arguments: + message n/a + +Options: + eyes Change cow's eyes + tongue Change cow's tongue +``` + +### Run + +Finally, we need to write our implementation: + +```swift +/// Generates ASCII picture of a cow with a message. +struct CowsayCommand: Command { + ... + + /// See `Command`. + func run(using context: CommandContext) throws -> Future { + let message = try context.argument("message") + /// We can use requireOption here since both options have default values + let eyes = try context.requireOption("eyes") + let tongue = try context.requireOption("tongue") + let padding = String(repeating: "-", count: message.count) + let text: String = """ + \(padding) + < \(message) > + \(padding) + \\ ^__^ + \\ (\(eyes)\\_______ + (__)\\ )\\/\\ + \(tongue) ||----w | + || || + """ + context.console.print(text) + return .done(on: context.container) + } +} +``` + +The [`CommandContext`](https://api.vapor.codes/console/latest/Command/Structs/CommandContext.html) gives you access to everything you will need, including a `Container`. Now that we have a complete `Command`, the next step is to configure it. + +## Config + +Use the [`CommandConfig`](https://api.vapor.codes/console/latest/Command/Structs/CommandConfig.html) struct to register commands to your container. This is usually done in [`configure.swift`](../getting-started/structure.md#configureswift) + +```swift +/// Create a `CommandConfig` with default commands. +var commandConfig = CommandConfig.default() +/// Add the `CowsayCommand`. +commandConfig.use(CowsayCommand(), as: "cowsay") +/// Register this `CommandConfig` to services. +services.register(commandConfig) +``` + +Check that your command was properly configured using `--help`. + +```swift +swift run Run cowsay --help +``` + +That's it! + +```swift +$ swift run Run cowsay 'Good job!' -e ^^ -t U + --------- +< Good job! > + --------- + \ ^__^ + \ (^^\_______ + (__)\ )\/\ + U ||----w | + || || +``` \ No newline at end of file diff --git a/3.0/docs/console/getting-started.md b/3.0/docs/console/getting-started.md index 2fa986b5..1ed2b977 100644 --- a/3.0/docs/console/getting-started.md +++ b/3.0/docs/console/getting-started.md @@ -3,7 +3,7 @@ The Console module is provided as a part of Vapor's Console package ([vapor/console](https://github.com/vapor/console)). This module provides APIs for performing console I/O including things like outputting stylized text, requesting user input, and displaying activity indicators like loading bars. !!! tip - For an in-depth look at all of Console's APIs, check out the [Console API docs](https://api.vapor.codes/console/latest/Console/indext.html). + For an in-depth look at all of Console's APIs, check out the [Console API docs](https://api.vapor.codes/console/latest/Console/index.html). ## Usage diff --git a/3.0/docs/console/overview.md b/3.0/docs/console/overview.md index 163905e8..cd1b1e5a 100644 --- a/3.0/docs/console/overview.md +++ b/3.0/docs/console/overview.md @@ -35,7 +35,7 @@ You can combine as many differently styled fragments to a [`ConsoleText`](https: ```swift /// Accepts input from the terminal until the first newline. -let input = console.input(isSecure: false) +let input = console.input() console.print("You wrote: \(input)") ``` diff --git a/3.0/docs/logging/getting-started.md b/3.0/docs/logging/getting-started.md index 29e518a6..2ecb2b29 100644 --- a/3.0/docs/logging/getting-started.md +++ b/3.0/docs/logging/getting-started.md @@ -1,3 +1,43 @@ -# Getting Started with Async +# Getting Started with Logging -Coming soon. \ No newline at end of file +The Logging module is provided as a part of Vapor's Console package ([vapor/console](https://github.com/vapor/console)). This module provides convenience APIs for creating log + +!!! tip + For an in-depth look at all of Logging's APIs, check out the [Logging API docs](https://api.vapor.codes/console/latest/Logging/index.html). + +## Usage + +This package is included with Vapor and exported by default. You will have access to all `Logging` APIs when you import `Vapor`. + +```swift +import Vapor // implies import Logging +``` + +### Standalone + +The Logging module, part of the larger Vapor Console package, can also be used on its own with any Swift project. + +To include it in your package, add the following to your `Package.swift` file. + +```swift +// swift-tools-version:4.0 +import PackageDescription + +let package = Package( + name: "Project", + dependencies: [ + ... + /// 💻 APIs for creating interactive CLI tools. + .package(url: "https://github.com/vapor/console.git", from: "3.0.0"), + ], + targets: [ + .target(name: "Project", dependencies: ["Logging", ... ]) + ] +) +``` + +Use `import Logging` to access the APIs. + +## Overview + +Continue to [Logging → Overview](overview.md) for an overview of Logging's features. \ No newline at end of file diff --git a/3.0/docs/logging/overview.md b/3.0/docs/logging/overview.md index a92fbc66..df17ae9b 100644 --- a/3.0/docs/logging/overview.md +++ b/3.0/docs/logging/overview.md @@ -1,3 +1,17 @@ -# Async Overview +# Logging Overview + +The logging package provides convenience APIs for logging information while your app is running. The [`Logger`](https://api.vapor.codes/console/latest/Logging/Protocols/Logger.html) protocol declares a common interface for logging information. A default [`PrintLogger`](https://api.vapor.codes/console/latest/Logging/Classes/PrintLogger.html) is available, but you can implement custom loggers to suit your specific needs. + +## Log + +First, you will want to use a `Container` to create an instance of `Logger`. Then you can use the convenience methods to log information. + +```swift +let logger = try req.make(Logger.self) +logger.info("Logger created!") +``` + +See [`Logger`](https://api.vapor.codes/console/latest/Logging/Protocols/Logger.html) in the API docs for a list of all available methods. + +Check out [Service → Services](../service/services.md#instance) for more information on how to register a custom logger. -Coming soon. \ No newline at end of file