mirror
/
vapor-docs
mirror of https://github.com/vapor/docs.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

add command and logger docs

This commit is contained in:
tanner0101 2018-04-05 15:50:48 -04:00
parent b2fbe046c4
commit e9ea71c141
6 changed files with 269 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
3.0/docs/command/getting-started.md
View File

@ -1,3 +1,43 @@
# Getting Started with Async
# Getting Started with Command
Coming soon.
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.

169
3.0/docs/command/overview.md
View File

@ -1,3 +1,168 @@
# Async Overview
# Command Overview
Coming soon.
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: <executable> cowsay <message> [--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 |
|| ||
```

2
3.0/docs/console/getting-started.md
View File

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

2
3.0/docs/console/overview.md
View File

@ -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)")
```

44
3.0/docs/logging/getting-started.md
View File

@ -1,3 +1,43 @@
# Getting Started with Async
# Getting Started with Logging
Coming soon.
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.

18
3.0/docs/logging/overview.md
View File

@ -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 &rarr; Services](../service/services.md#instance) for more information on how to register a custom logger.
Coming soon.