Beak 🐦

从命令行啄入你的 Swift 文件

Beak 可以接受一个标准的 Swift 文件，然后通过命令行界面列出并运行其中的任何公共全局函数。

这对于脚本编写和用 Swift 编写的类似 make 的文件非常有用。你可以用 Swift 编写的代码替换 make 或 rake 文件！

一个 Swift 脚本示例

// This links https://github.com/kylef/PathKit as a dependency
// beak: kylef/PathKit @ 1.0.0

import PathKit // from the dependency listed above
import Foundation

/// Releases the product
/// - Parameters:
///   - version: the version to release
public func release(version: String) throws {
    // implementation here
    print("version \(version) released!")
}

/// Installs the product
public func install() throws {
    // implementation here
    print("installed")
}

$ beak list
    release: Releases the product
    install: Installs the product
$ beak run release --version 1.2.0
  version 1.2.0 released!

Beak 通过 SourceKit 分析你的 Swift 文件，并找到所有公共和全局函数。它使用关于函数和参数名称、类型和默认值的信息来构建命令行界面。它还使用标准注释文档来构建描述性帮助。

Beak 可以解析脚本顶部的特殊注释，以便通过 Swift Package Manager 拉取依赖项。

默认情况下，Beak 在当前目录中查找名为 beak.swift 的文件，否则你可以使用 --path 传递到不同 swift 文件的路径。这个仓库本身有一个 Beak 文件用于运行构建脚本。

请先确保已安装 Xcode 10.2+。

$ mint install yonaskolb/beak

$ brew tap yonaskolb/Beak https://github.com/yonaskolb/Beak.git
$ brew install Beak

这使用 Swift PM 从此仓库构建和运行 beak，然后运行也包含在此仓库中的 Beak.swift 文件内的 install 函数。真是套娃！

$ git clone https://github.com/yonaskolb/Beak.git
$ cd Beak
$ swift run beak run install

这显示了所有可以运行的函数

$ beak list

  release: Releases the product
  install: Installs the product

这将运行带有特定参数的函数。请注意，swift 文件中的任何顶层表达式也将在该函数之前运行。

$ beak run release --version 1.2.0
version 1.2.0 released

也可以只运行整个脚本，而不是特定的函数

$ beak run

这将生成并打开一个 Xcode 项目，其中链接了所有依赖项，如果您定义了任何依赖项，这将对代码完成非常有用。命令行将提示您键入 c 以将您在 Xcode 中所做的任何更改提交回原始文件

$ beak edit
generating project

您可以随时使用 --help 来获取有关命令或函数的更多信息。这将使用来自文档注释的信息。

为了使函数可访问，它们必须是全局的并声明为 public。任何非 public 函数都可以作为辅助函数，但 Beak 不会看到它们。

函数可以是 throwing 的，任何抛出的错误都将使用 CustomStringConvertible 打印出来。这使得任务失败变得容易。目前，你必须在你的脚本中包含 import Foundation 才能拥有 throwing 函数

任何没有默认值的参数都将是必需的。

Int、Bool 和 String 的参数类型是原生支持的。所有其他类型将按原样作为原始值传递，因此如果它可以编译，您可以传入任何内容，例如枚举值 --buildType .debug。

没有标签的函数参数可以与位置参数一起使用

public func release(_ version: String) { }

beak run release 1.2.0

有时，能够拉取其他 Swift 包作为依赖项以在你的脚本中使用是很有用的。这可以通过在你的文件顶部添加一些特殊注释来完成。它必须采用以下形式

// beak: {repo} {library} {library} ... @ {version}`

其中 {} 中的项目是

• repo：是 Swift 包所在的 git 仓库。这可以采用 user/repo 的简短形式或 https://github.com/user/repo.git 的扩展形式
• library：要从此包中包含的库的空格分隔列表。这默认为仓库名称，通常是你想要的。
• version：要包含的此包的版本。这可以是简单的版本字符串，也可以是 Swift Package Manager Requirement 静态成员允许的任何类型，例如
  • branch:develop 或 .branch("develop")
  • revision:ab794ebb 或 .revision("ab794ebb")
  • exact:1.2.0 或 .exact("1.2.0")
  • .upToNextMajor(from: "1.2.0")
  • .upToNextMinor(from: "1.2.3")

一些例子

// beak: JohnSundell/ShellOut @ 2.0.0
// beak: kylef/PathKit @ upToNextMajor:0.9.0
// beak: apple/swift-package-manager Utility @ branch:master

import Foundation
import Pathkit
import ShellOut
import Utility

你可以使用 beak edit 来获取这些导入的依赖项的代码完成。

如果你在你的 swift 文件顶部放置一个 beak shebang，然后对其运行 chmod a+x beak.swift 使其可执行，你将能够直接执行它，而无需调用 beak。

tasks.swift

#!/usr/bin/env beak --path

public func foo() {
    print("hello foo")
}

public func bar() {
    print("hello bar")
}

$ chmod a+x tasks.swift
$ ./tasks.swift run foo
  hello foo

如果你然后将此文件放入 usr/local/bin，你就可以从任何地方运行此文件

$ cp tasks.swift /usr/local/bin/tasks
$ tasks run bar
  hello bar

要自动插入 run 选项，你可以将你的 shebang 更改为 #!/usr/bin/env beak run --path。

• swift sh
• Marathon

Beak 在 MIT 许可证下获得许可。有关更多信息，请参阅 LICENSE。