シェルスクリプトの構文を覚えられない自分のためのZshユーティリティライブラリです。直感的に書きにくい構文を、読みやすい名前の関数で扱えるようにします。
curl -sL https://raw.githubusercontent.com/milkeclair/z/main/install.zsh | zsh
z.updateは、読み込み済みのインストール先と導入済みmodを、1つのブランチアーカイブから更新します。必要な依存modも含めます。確認は1回だけ行い、新しいファイルを準備してから置換し、現在のシェルで読み込み直します。Gitの作業ツリーはGitで更新します。
z.installは導入済みmodを保持してcoreを置換します。単一のmodを更新するにはz.install.mod <mod_name>を使います。
z.install.mod.listは、配布されているmodと導入済みmodを一覧します。緑は導入済み、オレンジは内容が異なるもの、赤は未導入です。Z_INSTALL_BRANCH(既定: main)と比較し、ローカルの編集もオレンジで表示します。
z.install.mod.allは、1回の確認後に配布対象の全modを導入または更新します。ローカルだけのmodとmod直下のファイルは保持し、配布対象のmodを選択したブランチの内容で置換して読み込み直します。
z.uninstall
z.version- 現在のバージョンを表示します。
z.version.latest- GitHubから最新バージョンを取得して表示します。
z.version.note- 現在のバージョンのリリースノートを表示します。
z.version.latest.note- GitHubから最新バージョンのリリースノートを取得して表示します。
z.helpでこのREADMEを表示します。
z.help <function_name>で関数のドキュメントを表示します。ドキュメントのコメントが見つからない場合はDocument not foundと表示します。
引数の数が2を超えているか確認するスクリプトです。
my.argument_check() {
z.arg.named max $@ default=2 && local max=$REPLY
z.arg.named.shift max $@
z.arr.count $REPLY
if z.int.is.gt $REPLY $max; then
z.io "more than $max args"
else
z.io.error "$max or less args"
fi
}テスト
z.t.describe "my.argument_check"; {
z.t.context "when more than max args"; {
z.t.it "prints 'more than max args'"; {
z.t.mock.call_original name="z.io"
z.io.null my.argument_check max=3 "1" "2" "3" "4"
z.t.mock.result
z.t.expect.reply.includes "more than 3 args"
}
}
z.t.context "when 2 or less args"; {
z.t.it "prints '2 or less args' to stderr"; {
z.t.mock name="z.int.is.gt" behavior="return 1"
z.t.mock name="z.io"
z.t.mock name="z.io.error"
z.io.null my.argument_check "1" "2" "3"
z.t.mock.result name="z.io"
z.t.expect.reply.is.null skip_unmock=true
z.t.mock.result name="z.io.error"
z.t.expect.reply.includes "2 or less args"
}
}
}よく使う処理を行うユーティリティ関数を提供します。
関数はz.、モジュールはz.<module>.の接頭辞で名前空間を分けます。
lib配下では次の規則を使います。
- analysis
- データを変更せずに解析します。
- 値を返す場合は
returnではなくREPLYへ格納します。
- operator
- 引数を判定し、trueまたはfalseを
returnします。 - 判定結果は
REPLYではなく、関数の終了コードで返します。 - if文の条件として使用できます。
- 引数を判定し、trueまたはfalseを
- process
- データを変更します。
- 値を返す場合は
returnではなくREPLYへ格納します。
返す値はREPLYへ直接代入します。文字列を変換せず、配列の要素と空文字列もそのまま保持します。
- arg
- 名前付き引数と位置引数の解析
- arr
- join、split、uniqueなど
- common
- eq、is.null、guardなど
- debug
- 対話形式のデバッグ
- dir
- make、remove、existsなど
- file
- read、write、make.with_dirなど
- fn
- list、show、editなど
- hash
- keys、values、mergeなど
- int
- is.gteq、is.lteq、is.eqなど
- io
- is.empty、oneline、indentなど
- mode
- 対話モード
- path
- dir、base、stemなど
- perm
- chmod、chown、chgrpのラッパー
- status
- 終了コードの扱いをまとめた関数
- str
- color、is.path_like、gsubなど
- t
- テストフレームワーク
- var
- exists、sets、getなど
テストを記述・実行するフレームワークを提供します。テストはZshで書き、RSpecに似た構文を使います。
全テストを実行するにはz.tを使います。次のオプションを指定できます。
z.tは現在のディレクトリからテストを探します。パスが/testで終わるディレクトリで実行してください。それ以外のディレクトリではエラーを返します。
z_mainには、テスト対象のmain.zshのパスが入ります。各テストはこのファイルをsourceして、テスト環境を読み込みます。
-l, --log- テストの詳細を表示します。
-f, --failed- 失敗したテストだけを表示します。
-c, --compact- 結果をドットで簡潔に表示します(
.: 成功、F: 失敗、*: 保留)。
- 結果をドットで簡潔に表示します(
<name|path>- 一致するテストだけを実行します。
- ディレクトリ(例:
z.t mod)なら配下のテストを再帰的に集めます。 - テストファイルのパス(例:
z.t arg/process)ならそのファイルだけを実行します。
テストはtestディレクトリに置きます。関数はz.t.、モジュールはz.t.<module>.の接頭辞で名前空間を分けます。
test配下では次の規則を使います。
- describe
- テストする関数や機能を記述します。
- xdescribe
- describeブロックをスキップします。
- context
- テストを実行する条件を記述します。
- xcontext
- contextブロックをスキップします。
- it
- 関数や機能に期待する動作を記述します。
- xit
- itブロックをスキップします。
- expect
- 関数や機能の期待する動作を検証します。
- 検証関数は
z.t.expect.の接頭辞で名前空間を分けます。
- mock
- 関数やコマンドをモックします。
- テストや検証の後にモックを自動で解除します。
- 検証時の解除を省略するには
skip_unmockを指定します。 - モックの結果は
returnではなくREPLYへ格納します。 - モード:
- 既定: 元の処理を実行せずに呼び出しを記録します。
call_original: 呼び出しを記録して元の関数を実行します。z.t.mock.call_originalも同じ動作です。
- 任意の処理:
behavior引数にコマンドを渡して処理を指定できます。
対話形式でデバッグする関数を提供します。
スクリプト内でz.debugを呼ぶとデバッグモードに入ります。実行を一時停止し、対話プロンプトを表示します。
デバッグモードを有効にするにはz.debug.enable、無効にするにはz.debug.disableを使います。
デバッグモードで使えるコマンド:
cまたはcontinue: 実行を続けます。p <var>またはprint <var>: 変数の値を表示します。hまたはhelp: ヘルプを表示します。q、quit、exit: スクリプトを終了します。
my.function() {
local var="hello"
z.debug
z.io $var
}関数の実行に接頭辞を付ける対話モードを提供します。デバッグに似ていますが、Git操作のように毎回gitと入力する手間を省くために使います。
$ z.mode git
git> status
git> add file.txt
git> commit -m "Add file.txt"
git> push origin branch
git> q
$$ z.mode z.io split="."
z.io> oneline "This.is.a.test"
z.io> line "Indented" "line" indent=2
z.io> q
$特定の作業を行うためのmodを提供します。使いたいものを個別に導入します。
z.install.mod <mod_name>
依存するmodを解決し、先に導入します。
z.uninstall.mod <mod_name>
z.reload- ホームのZsh設定を読み直します。README
z.pj- 名前付きのプロジェクトディレクトリとVS Codeの起動。README
z.git- Git操作用のmod。README
z.wtproxy- Docker Composeとworktree用のプロキシmod。README
z.job- 簡単なバックグラウンドジョブ。README
z.completion- シェルでの関数名やドキュメントの補完。README
Language Serverを提供します。
ダウンロード: https://marketplace.visualstudio.com/items?itemName=milkeclair.z-ls
- 補完
- 関数名
- Hover表示
- 名前
- 説明
- 引数
- 返り値
- 使用例
- Signature Help
- 引数の説明
- 定義への移動
- 診断
- 関数が見つからない場合の候補提示
- 空行
- ファイル先頭
- 空白だけの行
- 末尾の改行
- 未使用の関数引数
- 必須の位置引数の不足
- 必須の名前付き引数の不足
- 抑制コメント(
# zls: ignore)