Commander 0.9.2

Commander 0.9.2

×

测试已测试✗
语言语言 SwiftSwift
许可 BSD-3-Clause
发布最后发布2021年6月
SwiftSwift 版本5
SPM支持 SPM✓

由 Kyle Fuller 维护。

Commander 0.9.2

Commander

Commander

Build Status

Commander 是一个小巧的 Swift 框架，允许您以组合的方式创建美观的命令行界面。

使用

简单的 Hello World
import Commander

let main = command { (filename:String) in
  print("Reading file \(filename)...")
}

main.run()
类型安全的参数处理

传递给命令函数的闭包接受任何符合 ArgumentConvertible 协议的参数，Commander 会自动将这些参数转换为这些类型。如果无法转换，用户将收到一个友好的错误消息，通知他们的参数与期望的类型不匹配。

String、Int、Double 和 Float 已扩展以符合 ArgumentConvertible 协议，您可以轻松扩展任何其他类或结构体，使其可以作为命令的参数使用。

command { (hostname:String, port:Int) in
  print("Connecting to \(hostname) on port \(port)...")
}
命令分组

您可以一起分组一系列命令。

Group {
  $0.command("login") { (name:String) in
    print("Hello \(name)")
  }

  $0.command("logout") {
    print("Goodbye.")
  }
}

用法

$ auth
Usage:

    $ auth COMMAND

Commands:

    + login
    + logout

$ auth login Kyle
Hello Kyle
$ auth logout
Goodbye.

描述参数

您可以对命令的参数位置和选项进行描述以自动生成帮助信息。这通过传递这些参数的描述符来完成。

例如，对于带有描述的固定位置参数，您可以使用

command(
    Argument<String>("name", description: "Your name"),
    Argument<String>("surname", description: "Your surname"),
    Argument<Int>("count", description: "Number of times to print")
) { name, surname, count in
    for _ in 0..<count {
        print("Hello \(name) \(surname)")
    }
   }.run()

请注意，您需要传递 3 个必需的参数。

另一个例子，描述一个接受两个（可选）选项的命令，即 --name 和 --count，其中 name 的默认值是 world，count 的默认值是 1。

command(
  Option("name", default: "world"),
  Option("count", default: 1, description: "The number of times to print.")
) { name, count in
  for _ in 0..<count {
    print("Hello \(name)")
  }
}
$ hello --help
Usage:

    $ hello

Options:
    --name
    --count - The number of times to print.

$ hello
Hello world

$ hello --name Kyle
Hello Kyle

$ hello --name Kyle --count 4
Hello Kyle
Hello Kyle
Hello Kyle
Hello Kyle
描述符类型
  • 选项 - 带值的可选选项。
  • 选项 - 带值的选项，可以多次使用，您的命令将收到一个包含所有选项值的数组。您需要事先指定预期多少个值。例如：--myOption value1 value2 value3
  • 可变选项 - 与选项相同，但是值数量不是固定的，用户可以重复选项并用额外的值进行扩展。例如：--myOption value1 --myOption value2
  • 标志 - 布尔类型的开关。
  • 参数 - 位置参数。
  • 可变参数 - 可变参数。

注意：描述参数后要在选项和标志之后描述，以便解析器可以区分 --option value 和 --flag argument。

使用参数解析器

注意：ArgumentParser 本身是 ArgumentConvertible，因此您还可以获取原始参数解析器以执行任何自定义解析。

command { (name:String, parser:ArgumentParser) in
  if parser.hasOption("verbose") {
    print("Verbose mode enabled")
  }

  print("Hello \(name)")
}
$ tool Kyle --verbose
Verbose mode enabled
Hello Kyle

使用 Commander 的示例工具

安装

您可以通过多种方式安装 Commander，使用 SPM（Swift 包管理器），Conche，CocoaPods 或 CocoaPods-Rome。

框架和 rpath

需要注意的是，Commander（以及任何其他依赖项）的 .framework 或动态库文件必须在运行时可用，除非您正在使用 SPM。

应用程序将在其 rpath 中查找，该 rpath 包含其希望找到 .framework 的路径。

使用 Swift 脚本，您可以使用以下方式使用 -F 标志来设置框架搜索路径

#!/usr/bin/env xcrun swift -F Rome

import Commander

对于编译的 Swift 代码，您需要添加一个指向您的依赖框架的 rpath，格式如下

$ install_name_tool -add_rpath "@executable_path/../Frameworks/"  "bin/querykit"

其中相对于可执行文件的 "../Frameworks" 用于查找框架，而 "bin/querykit" 是可执行文件。

当在其他系统上安装您的可执行文件时，重要的是要复制框架和二进制文件。

架构

CommandType

CommandType 是命令背后的核心协议，它是一个包含 run 方法的对象或结构，该方法接受一个 ArgumentParser。

command 函数和 Group 都返回符合 CommandType 命令，可以轻松互换。

protocol CommandType {
  func run(parser:ArgumentParser) throws
}
ArgumentConvertible

便捷的command函数接受一个闭包作为您的命令，它接受符合ArgumentConvertible协议的参数。这使Commander能够轻松地将参数转换为您的命令所需的数据类型。

protocol ArgumentConvertible {
  init(parser: ArgumentParser) throws
}
ArgumentParser

ArgumentParser是一个对象，允许您提取选项、标志和位置参数。

许可协议

Commander遵循BSD许可协议。有关更多信息，请参阅LICENSE文件。