Swift ArgumentParser でバージョン番号を出力する方法

Swift swift-argument-parser

コマンドラインツールを作っているとそのツールのバージョン番号を出力したい事があります。ここでは引数で渡した文字列をそのまま標準出力に出力する myEcho というコマンドを作るというのを例にしてみます。

完成イメージはこんな感じです。

% myEcho Hello
Hello
% myEcho --version
1.0.0

引数の文字をそのまま Print し、--version フラグが立っているときはバージョン番号を出力するだけのコマンドです。

コード例その1

import ArgumentParser

struct MyEcho: ParsableCommand {

    static var configuration = CommandConfiguration(commandName: "myEcho")

    @Flag()
    var version: Bool

    @Argument()
    var text: String

    func run() throws {
        if version {
            print("1.0.0")
            return
        }

        print(text)
    }
}

MyEcho.main()

素直に今回の仕様を ArgumentParser を使って実装すると上記のような感じで書けると思います。

ヘルプを出力してみるとこんな感じ

% myEcho --help
USAGE: myEcho [--version] <text>

ARGUMENTS:
  <text>

OPTIONS:
  --version
  -h, --help              Show help information.

いけてそうです。

引数を渡してみます。

% myEcho Hello
Hello

動いてますね。バージョン番号を出力させてみます。

% myEcho --version
Error: Missing expected argument '<text>'
Usage: myEcho [--version] <text>

エラーが出ました。必須引数がないってことで怒られています。とはいえよくあるコマンドラインツールはそのツールが引数を必須としていても --version フラグが有効な場合は必須として扱いません。

直します。

コード例その2

import ArgumentParser

struct MyEcho: ParsableCommand {

    static var configuration = CommandConfiguration(commandName: "myEcho")

    @Flag()
    var version: Bool

    @Argument()
    var text: String?

    func run() throws {
        if version {
            print("1.0.0")
            return
        }

        guard let text = text else {
            throw ValidationError("need argument")
        }

        print(text)
    }
}

MyEcho.main()

@Argument() にしている text プロパティをオプショナルにして、実行時に version フラグが立っていなければ text プロパティをチェックしてエラー処理したうえで出力します。

実際動かしてみると echo 部分も --version も期待通りに動きます。引数なしで実行すると以下のような感じに怒られます。

% myEcho
Error: need argument
Usage: myEcho [--version] [<text>]

補足すると ValidateionError は ArgumentParser 側で v0.0.1 のころから定義されているエラーです。このエラーを throw するとエラーコードを履きながらエラーメッセージを表示しつつ Usage を出力してくれます。便利ですね。

とはいえ個人的には

  • func run() throws 実行時には引数関連のエラー処理は終わった状態であってほしい
  • Unwrap を後続の処理の中であまりやりたくない

という思いもありモヤモヤします。

このモヤモヤを解決するために issue で良い方法がないか聞いてみた回答が次のコードです。

完成形

import ArgumentParser

struct MyEcho: ParsableCommand {

    static var configuration = CommandConfiguration(commandName: "myEcho")

    struct Version: ParsableArguments {
        @Flag()
        var version: Bool

        func validate() throws {
            if version { throw CleanExit.message("1.0.0") }
        }
    }

    @OptionGroup()
    var version: Version

    @Argument()
    var text: String

    func run() throws {
        print(text)
    }
}

MyEcho.main()

変更点は地味に多いですが以下の通り

  • version: Bool を Version 型 に変更
  • struct Version 内で
    • Bool フラグを持たせる
    • ParsableArguments プロトコルの func validate() throws を実装
    • func validate() throws 内でフラグが立っていればバージョン番号を出力
      • 出力時には正常終了するために ArgumentParser が定義する CleanExit 型のエラーをスローする
  • text プロパティはオプショナルをやめる
  • func run() throws ではただ text プロパティを出力するのみ

これが現状のスッキリ終わらせるための Workaround です。

func validate() throws が run よりも先に実行されているので func run() throws 内では version のことは気にせずに済むようになりました。

コード量は増えましたが僕が元々感じていたモヤモヤはすべて解消されています。また、バージョン番号を出力する処理が Version 型にまとまっています。今回は MyEcho.Version とネストさせて定義していますが、ネストさせる必要性は特にないのでので単体のファイルとして定義していれば使い回しもしやすいです。

まとめ

この記事を読んで気付いた方がいるかも知れませんが、ArgumentParser ではバージョン番号出力はデフォルトで提供されていません。Issue 内でも提供して欲しいと他の方がリクエストしていました。将来的には提供されるようになるかも知れませんね。

Apple のオープンソースライブラリ ArgumentParser

Swift swift-argument-parser

Swift.org - Announcing ArgumentParser

2月末に Swift.org でアナウンスされた ArgumentParser をいろいろと触ってみたので紹介的なものを書いてみようと思います。

基本的にはわかりやすい英語とサンプルコードで書かれている 本家 Documentation が一次情報なのでそちらを読んでください。リポジトリには 動作するサンプルコード もあるのでそちらを動かすのもおすすめです。

この記事の執筆時点では ver 0.0.2 がリリースされていますが僕が試したのは v0.0.1 なのでご了承ください。

はじめに

3rd Party 製の Command Line Tool 向けの Argument Parser だったりフレームワークのようなものは以前からありました。Apple 自身も Swift Package Manager 内部で使われていた ArgumentParser （名前が同じでややこしい）は存在しており、apple/swift-tools-support-core （以下 TSC）として切り出されていました。今回アナウンスされたものは TSC の ArgumentParser とも別物の単体のオープンソースライブラリとしてリリースされました。

特徴としては Swift 5.1 で追加された Property Wrapper を使ってコマンドのパラメータとプロパティの対応が宣言的に書けるようなライブラリになっています。ある種のフレームワーク的なものとしても捉えられ、仕組みに沿ってコードを書いていけば簡単にコマンドラインツールが書けるようになっています。おかげで本質的な処理部分に時間をかけられるのはうれしいところです。

Apple が作っているいくつかのオープンソースプロダクトは TSC から ArgumentParser に乗り換える方向のようです。（indexstore-db と swift-format で PR が出されていてまだマージはされていない）

今回は僕がドキュメントを読んだり少し触った範囲で気になったことを書いていきます。

僕の背景として、公開はしていませんが5個ほど TSC を使ったコマンドラインツールを個人的に書いたことがあります。他の言語だと Go と Node.js で少しコマンドラインツールを使ったことがあります。

できること

  • よくあるパターンの引数のパース処理を Property Wrapper を使って簡単に書ける
    • フラグ
      • --verbose みたいなただのフラグ・スイッチ的なオプションの指定方法
    • オプション
      • swift build --configuration debug の --configuration debug のように名前付きの引数みたいなオプションの指定方法
    • 引数
      • ls ~/ みたいに何もつかない引数
  • help もデフォで最低限は生成される
    • -h --help がデフォルトで実装される
  • エラーメッセージもデフォで最低限を返してくれる
    • 型チェックとか必須パラメータの不足など
  • ParsableCommand に準拠した型でコマンドを定義する
    • func run() throws メソッド内にコマンドの処理を書く
  • 実行自体は static メソッド main を呼ぶだけで、引数のパースや ParsableCommand の run をよしなに呼んでくれる
  • オプションのショートネームも定義できる
    • Swift で一般的な Lower camel case は自動的に Kebab case に変換されたオプション名になる
      • @Flag() var printSupportedFile: Bool は --print-supported-file
    • @Flag(name: .shortAndLong) var printSupportedFile: Bool とすれば自動的に頭文字を使ったショートネームが追加されて -p, --print-supported-file が使えるようになる
    • @Flag(name: [.customShort("s") .customLong("support-file")]) var printSupportedFile: Bool とすれば自動生成じゃなく自分で任意のパラメータ名にできる。この場合は -s, --support-file が使えるようになる
  • long オプションは基本的に -- だけど withSingleDash: true すれば - 形式にできるけど推奨はされていない
  • 独自の型もパースできる（してもらえる）
    • ExpressibleByArgument に準拠して init?(argument:) を実装する
    • enum も RawRepresentable に対応してるような奴は ExpressibleByArgument に準拠してると宣言するだけで済む。
    • transform 関数を実装していればパースできたりもする
  • フラグの反転も指定できる
    • @Flag(inversion: .prefixedNo) var index: Bool だと --index と --no-index が定義される
    • @Flag(inversion: .prefixedEnableDisable) だと --enable-hogehoge と --disable-hogehoge
  • CaseIterable と String の RawRepresentable に対応した enum を使えばフラグをまとめたりとかもできる
  • Flag オプションを Int 型に適用すると呼び出された回数が入ってくる
    • -vvvv とかしたら verbose プロパティの値は 4 になってるみたいなことができる
  • 引数のパース方法は選べるけどほとんどの場合ややこしいことになる
    • @Option(parsing: . upToNextOption) var file: [String] のケースだけはちょっと便利かもしれない。毎回 --file hoge ってしなくても連続して --file のオプションを渡せるから。
  • サブコマンドの実装ができる
    • ツリー上にパースされていく
    • コマンド名は基本的に型名が使われるが以下のように明示もできる swift static var configuration = CommandConfiguration( commandName: "stdev", abstract: "Print the standard deviation of the values.")
    • サブコマンドのサブコマンドも作れる
    • 共通のオプション（設定）は ParsableArguments に準拠した Struct とかを用意して、@OptionGroup() var options: Math.Options と書くことでまとめられる
      • ちょっとオプションの多いコマンドを作ったときにはオプションのカテゴライズをしてまとめられてコードが見やすくなるし、排他処理も書きやすくなる
  • ヘルプのカスタマイズ
    • @Flagとかの help 引数に文字列を明示的にあたえることでコメントを追加できる
    • より細かいカスタムは上記で渡していた文字列の代わりに ArgumentHelp のインスタンスを渡すことで可能
    • コマンドやサブコマンドのヘルプは static var configuration = CommandConfiguration( XXXX ) でできる
    • デフォルトの -h, --help のパラメータ名はカスタム可能。Root レベルのコマンドに対する CommandConfiguration で helpName: で指定可能
    • ヘルプに出力したくない場合には @Flag(help: .hidden) とかすれば、試験的に追加した機能とかをヘルプに出力せずにすませられる
  • バリデーション
    • ParsableCommand と ParsableArguments に validate() を実装することでバリデーションできる
    • throw すればそのメッセージが標準エラーに出力されてエラーコードで終了する
    • runメソッド内でも実行時エラーを throw できる
      • v0.0.2 では ExitCode という Error が用意されたので自前でエラーメッセージを出力して throw ExitCode.failure することで綺麗にエラーからの終了が実装できるようになった
  • マニュアルでパース
    • きっちりとコマンドラインツールとして作るのではなくスクリプトっぽく書きたいとき
      • ParsableArguments に準拠した struct にこれまど同様にオプションを書いておく
      • static method の parseOrExit() を呼べば、成功してればインスタンスが返ってくるし失敗したら終了してくれる
      • parse メソッドもあってこちらは throw されるので自分でエラーハンドリングができる。
    • コマンドやサブコマンドもマニュアルでパースできるけどややめんどくさい parseAsRoot() とかつかえばいい

できないこと(提供されてないこと)

  • コマンドラインツール的に便利なパスの処理
  • 外部のコマンドの呼び出しのサポート

これらはライブラリの名前から連想する対応範囲を超えているように思えるので別のライブラリなどを使った方が良いかもしれないです。僕は個人的にパス周りは Path.swift, パスまわりや外部のコマンド呼び出しは前述の TSC を使ったりしています。

それ以外は特別困っていません。

まとめ

コマンドラインツールはいろんな宗派があると思うので好みが分かれると思います。細かいことを言えば切りがないかも知れません。とはいえ

  • Apple 純正
  • サブコマンドも含めてコマンドラインツール作成における大枠の仕組み、パース処理が提供されている
  • 独特な実装ではなく Swift らしい素直な実装

Swift でコマンドラインツールを書く場合、これらは利点だと思うのでぜひ皆さんも使って見たらいいと思います。

iPhone 11 Pro 予約記録

iPhone

予約日から数日経ちましたが 2019/09/13(金) の様子を記録として残しておきます。

今回は予約開始が 21:00 からというのが去年と大きく違っています。各キャリアともネット予約に関しては 21:00 から受付ですが、店舗受付に関しては店舗によっては翌日の朝からの対応という情報が流れていました。ヨドバシカメラ梅田は店舗での受け付けも 21:00 から対応してくれるということだったので現地向かいました。

当日持っていったもの

  • 寒さ対策として
  • 軽食と飲み物
  • 座る用に
    • ウレタンの座布団
    • スリーピングマットと座椅子アタッチメント

結果として終始Tシャツのままだったし、同僚とずっとしゃべっていたので座ることもなかった。とはいえ備えあれば憂いなし。

来年に向けて

  • 予約時には各キャリア前に並ぶで正解では？
  • 最近は並ぶ人も少ないので1〜2時間前でも十分かも
    • 店内カウンターで待たせてもらえる可能性大

Sketch で Symbol 新規作成時の名前入力で入力補完してくれる Plugin 「SymbolNameAutocomplete」を作ってみた

昨晩、Sketch Plugin 「SymbolNameAutocomplete」を公開しました。

できること

Symbol の新規作成時に Symbol 名を入力する時に入力補完してくれます。

より具体的には以下のような感じに振る舞います。

  • 既に存在している Local Symbol を対象とする
  • / による階層分け毎にマッチングさせていく
  • 補完決定時に下位階層がある場合には / まで補完
  • / の前後に半角スペースなどを入れている場合には <半角スペース>/<半角スペース> まで補完

/ の前後のスペースを考慮して補完するあたりはこだわりました。候補の選択にカーソルキーが使えるのは当然のこと、Ctrl+N, Ctrl+P での移動にもちゃんと対応させています。

背景

  1. 2018年2月28日 『try! macOS meet-up』で「Symbol 新規作成時の名前入力で Safari のアドレス補完っぽく入力補完したい」と @usagimaru 氏, @dy4_268 氏 に相談するも具体的な方法まで至らず
    • その筋の人達でも即答即解決とはいかず
  2. 2018年3月頃にあるデザイナーが「命名するときに入力補完されたらええのにな！」という。
    • 需要を認識
  3. 2018年7月10日 zeplin/emoji-autocomplete-sketch-plugin: Type “:” followed by the first few letters to autocomplete emojis. 🍒 zeplin が emoji の Autocomplete プラグインをおもむろにリリース
    • 大いに参考になるとコードを読んでみる
  4. 2018年9月29日 ずむ on Twitter: "WWDC 2010 Session 145 "Key Event Handling in Cocoa Applications" を見たら入力フィールドの下に出てくる候補表示の作り方があった！ 今のところ Archive のページから入手可能。 https://t.co/rhyw9DnPAE" つぶやき発見
    • そのものズバリの情報。
    • サンプルコードもある！CustomMenus
  5. 連休で暇になりトライ

まとめ

これまでも公開していないですがいくつか Sketch Plugin は書いていましたがいずれも CocoaScript で書いたものばかりでしたが、今回はじめて Objective-C で書きました。zeplin の emoji-autocomplete-sketch-plugin のおかげで割とすんなり作れました。今はまだソースコードは公開していませんが時間が取れたら公開したいと思います。

このプラグインを使うことで Symbol の命名規則のブレをある程度抑えることができると思いますので使ってみてください。

ErgoDash を作ってみた

自作キーボード

結構前に作ってたんだけどキーキャップの到着が遅かったりしてエントリ書けてなかったので書いてみます。といっても Twitter 貼り付けるだけになってます。

組み立ての感想

今回はこれまでで1番苦戦しました。

  • ファームウェアを焼こうと思ったらそもそもリセットスイッチが反応しない
    • ジャンパのところでショートさせてた
  • 表面実装のLED取り付けに失敗しいくつか点灯しない
    • ハンダ不良なのか熱しすぎて壊したのか不明
    • あやしそうな箇所を余分に買ってたLEDにひとつ付け替えるだけで解消
  • キースイッチが1個だけ反応しない

これらのミスは今回4個目のキーボード作成だったので中途半端な慣れによるところが大半でした。LEDは難しかったですがフラックスを初導入して塗ってみるとかなり作業が図ったのは収穫でした。

今回はじめてケースのデータを遊舎工房さんに依頼して親指キーが多いケースを切ってもらいました。Illustrator を使うのも初めてでしたが元データから切り貼りするだけだったのでなんとかなりました。今は作者のかたがそのまま遊舎工房さんに投げられるようなデータをシェアしてくれているので簡単にケースはゲットできると思います。

自作キーボードで組み立てで便利だったもの

自作キーボード

最近、自作キーボード作りにハマっています。これまでに

  1. Meishi ― The micro macro keyboard kit
  2. HelixPico
  3. Mint60

と作ってきました。ハンダ付け初心者な僕がそれなりに組み立てられるようになったのには道具の力が非常に大きいです。いい大人なので力量は道具に素直に頼っています。これまでつかった便利だったもの、あって良かったものを紹介するというテイのアフィリエイトエントリです。

必須部門

温度調節ハンダゴテ

白光 ダイヤル式温度制御はんだこて FX600

白光 ダイヤル式温度制御はんだこて FX600

温度調節ができるものじゃないと Helix とかの LED のハンダ付けで部品を壊してしまうらしい。温度が体感で分かるわけがないので絶対に温度調節機能付きのハンダゴテを買いましょう。今のところハンダが原因でパーツは壊したことがないです。

白光 こて先 2C型 T18-C2

白光 こて先 2C型 T18-C2

コテ先もこのタイプの物が綺麗にハンダ付けできるようです。母材もちゃんと熱することを意識してからはハンダもちゃんと上がってくるようになった気がします。

ハンダゴテ置き

goot はんだこて台 ST-11

goot はんだこて台 ST-11

子供の頃、親父は大きい灰皿を使っていた記憶がありますが、僕はたばこを吸わないし専用品が良いに決まってるので買いました。スポンジタイプで綺麗にハンダを剥がせないので金だわしっぽいタイプが気になってます。

ハンダ

goot 電子工作用はんだ SD-63

goot 電子工作用はんだ SD-63

言うまでもないですね。初心者向けの鉛入りを買いましょう。

はんだ吸取り線

goot はんだ吸取り線 CP-3015

goot はんだ吸取り線 CP-3015

初心者なのでミスります。ミスまでいかなくても気に入らないときもあるのでハンダ吸い取り線は必須です。仕組みを考えれば当たり前ですが、ハンダと同じように線を直接持ったら激熱でした。ちゃんとケース部分を持って使いましょう。

精密プラスドライバ

ベッセル(VESSEL) 精密ドライバーセット +2本 -4本セット TD-56

ベッセル(VESSEL) 精密ドライバーセット +2本 -4本セット TD-56

たいていのケースの組み立てに +00 あたりのドライバーが必要です。間違ったサイズを使うとねじ頭をなめてしまう悲劇に見舞われるのでセット物を買っておくと安心です。100円均一のは粗悪なのでダメ絶対。

つかめるニッパー

ツノダ(Tusnoda) つかめるニッパー TH-150NC 結束バンド・極細線をキャッチ 奥行1.7×高さ16.5×幅10cm 飛散防止パット スペア2セット付き

ツノダ(Tusnoda) つかめるニッパー TH-150NC 結束バンド・極細線をキャッチ 奥行1.7×高さ16.5×幅10cm 飛散防止パット スペア2セット付き

ダイオードの足を切ったりするのでニッパーは必須。特にこれのように切り取った足が飛んでいったりしないようなガードが付いているものは部屋を散らからせないで済むのでおすすめ。

あってよかった部門

ラジオペンチ

フジ矢 マイクロラジオペンチ 細かい作業に最適な先細仕様 (バネ付) 150mm MP6-150

フジ矢 マイクロラジオペンチ 細かい作業に最適な先細仕様 (バネ付) 150mm MP6-150

コテ先の交換にも使いました。ダイオードの足を曲げるなど用途は多彩。

ダイオード曲げるやつ

サンハヤト リードベンダー RB-5 リード線、部品の簡易折り曲げ器

サンハヤト リードベンダー RB-5 リード線、部品の簡易折り曲げ器

どうせ組み立てるなら綺麗に組み立てたいのが親御心。ダイオードは適当に曲げることもできますが、このリードベンダーがあると綺麗に曲げられます。使い方を間違わないように下の動画で使い方を把握してから使いましょう。


サンハヤト　リードベンダー「RB-5」

iPhone 分解工具キットのプラスチック

Zacro 15 in 1携帯修理ツール 開腹/分解/修理/交換用ツールキット スマホ用工具

Zacro 15 in 1携帯修理ツール 開腹/分解/修理/交換用ツールキット スマホ用工具

このツールをなんで持ってるのかあまり記憶がないですが、このツールキットに入ってるピンセットやプラスチックの棒やピックなんかはパーツを傷つけずに何かできるので便利です。特にピンセットは小さなビスを取って穴にはめるのに重宝しました。

ブレッドボード

サンハヤト SAD-101 ニューブレッドボード

サンハヤト SAD-101 ニューブレッドボード

ProMicro をハンダ付けするときの固定に使いました。今後電子工作するときにも使えるしあると便利です。

エポキシ系接着剤

セメダイン 5分硬化型エポキシ系接着剤 ハイスーパー5 15gセット箱 CA-184

セメダイン 5分硬化型エポキシ系接着剤 ハイスーパー5 15gセット箱 CA-184

界隈では有名らしい「Moge Micro」対策で USB 端子周りに盛って補強します。硬化の時間もあるのでキーボード作りを始める最初もしくは前日にあらかじめやった方が良いと思います。盛るときは最終的に Pro Micro がどのようにケースに収まるのか確認し厚みに気を付けましょう。僕は盛りすぎて何度もカッターで余分な量を削り落としました。当然ながら盛りすぎて USB ケーブルが刺せないようにならないように各所に空いている穴に盛りすぎないようにしましょう。

無印良品のコインケース

キットに入っているパーツの管理・整理やビスなどの細かいパーツの整理に便利です。無印良品だけにおしゃれでいいです。

欲しいもの

絶縁テープ

Mint60 を作る時にやらかしたのですが、キットによってはうっかりショートさせてしまうくらいスペースを切り詰めている物があります。あらかじめビルドログには足を短めに切っておきましょうとありますが、このような絶縁テープをさらに貼っておくとより安心なのではと思いました。

耐熱マット

断熱ワーキングマット耐熱300℃高温 絶縁パッド作業用マット無毒35 x 25 cm 25cm目盛り付く 電子製品/モバイル/パーソコン分解修理用ツール (ブルー)

断熱ワーキングマット耐熱300℃高温 絶縁パッド作業用マット無毒35 x 25 cm 25cm目盛り付く 電子製品/モバイル/パーソコン分解修理用ツール (ブルー)

今は OLFA のカッターマットを作業マット代わりに使っているのですが、ハンダがメインなので耐熱マットの方が良いかなと思ってきました。このマットには細かいパーツを整理するためのくぼみもあり1番小さいくぼみにはナンバリングもされているので Helix のように SMD のダイオードを使う場合なんかで便利に使えそうです。

まとめ

このエントリを書きながらもうすでに他のキーボードを作りたくなってきました。次に気になってるのは Helix か ErgoDash です。11月くらいに在庫が復活してたら検討したいですね。

話がそれましたが、今回挙げた道具達のおかげで結構順調に自作キーボード作りが捗っています。是非皆さんも道具を揃えてキーボードを作ってみましょう！