コマンドのマニュアル・サンプルで使う記法について
よくコマンドの実行例で以下のような記法を見ることがあると思う。
$ git add <file>...
これは man で使ってる記法を元にしてることが多い。ただ「コマンドのサンプル(マニュアル)はこう書け」という厳密な構文が存在するわけではなく、MicrosoftやIBM始め、ある程度の共通項持った様々な亜種を定義している。
表現記法
ぱっと目に着くものを試しに書き下してみると、
| 用途 | 記法 | その他備考 |
|---|---|---|
foo は変数 |
foo or <foo> or foo or FOO |
斜体にならず、_foo_ と表示される端末もある(ミスなのかは知らない) |
foo は literal |
foo |
これは太字 |
foo または bar |
foo|bar |
|
foo が optional |
[foo] |
|
-f foo と -b をグルーピング(1つも選ばなくてもよい) |
[-f foo|-b] |
任意用の角括弧はグルーピングにも使える |
-f foo と -b をグルーピング(最低でも1つ選ぶ必要がある) |
(-f foo|-b) or {-f foo|-b} |
|
foo を繰り返し指定できる |
foo... |
|
最低でも1つの foo が必要 |
foo foo... |
|
| 複数の変数を指定する | foo bar baz |
上記繰り返しでは表現できない場合のみ |
空白を含めた foo bar を1つの引数とする |
"foo bar" |
シェルのオプションパース仕様に依存しているところが強い |
これらの表現は合成・入れ子が可能とはいえ、1行で書くには限界がある。そういう場合は複数行に分けることが多い。例えば下記のコマンドのような表記の場合、
$ foo bar ([-a] <baz> | -b)
2行に分解し、排他であることを明確に示す。
$ foo bar [-a] <baz> $ foo bar -b
共通表現
厳密な構文が存在しないとは言っても、広く用いられている共通の表現がある。
| 用途 | 記法 |
|---|---|
foo は変数 |
foo or <foo> or foo or FOO |
foo または bar |
foo|bar |
foo が optional |
[foo] |
-f foo と -b をグルーピング(1つも選ばなくてもよい) |
[-f foo|-b] |
-f foo と -b をグルーピング(最低でも1つ選ぶ必要がある) |
(-f foo|-b) or {-f foo|-b} |
foo を繰り返し指定できる |
foo... |
<foo> を optional の意味で使ったり、[foo] を変数の意味でとして使ったり、そういうことをしている明記されたルールは見たことがない。*1
正直ここらへんの規則すら破ってるサンプル表記は本当にやめて欲しいな、と思ったりする。*2
$ foo [bar]
で、実は bar が必須とか。それでいて bar は実は変数だとか。普通に実行出来る気がしない。*3
語弊が少なそうだなって思う記法の組み合わせ
僕の思う最強の(ry みたいな。
| 用途 | 記法 |
|---|---|
foo は変数 |
FOO or <foo> |
foo は literal |
foo |
foo または bar |
foo|bar |
foo が optional |
[foo] |
-f foo と -b をグルーピング(1つも選ばなくてもよい) |
[-f foo|-b] |
-f foo と -b をグルーピング(最低でも1つ選ぶ必要がある) |
(-f foo|-b) |
foo を繰り返し指定できる |
foo... |
RFCとかで制定されて欲しい今日この頃。
