日本語 man コマンド類 (ja-man-1.1j_5) と日本語 man ドキュメント (ja-man-doc-5.4 (5.4-RELEASE 用) など) をインストールすると、以下のような man コマンド閲覧、キーワード検索が コンソールからできるようになります。
4.11-RELEASE-K, 5.4-RELEASE-K, 5.5-RELEASE-K, 6.0-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.4-RELEASE-K, 8.0-RELEASE-K から 8.4-RELEASE-K, 9.0-RELEASE-K から 9.3-RELEASE-K, 10.0-RELEASE-K から 10.3-RELEASE-K, 11.0-RELEASE-K から 11.4-RELEASE-K, 12.0-RELEASE-K, 12.1-RELEASE-K は、 プライベート版 (小金丸が編集してまとめたもの) ですが、 より多くの翻訳したファイルが含まれています。 (5.4-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.4-RELEASE-K, 8.0-RELEASE-K から 8.4-RELEASE-K, 9.0-RELEASE-K から 9.3-RELEASE-K, 10.0-RELEASE-K から 10.3-RELEASE-K, 11.0-RELEASE-K から 11.4-RELEASE-K, 12.0-RELEASE-K から 12.3-RELEASE-K, 13.0-RELEASE-K から 13.2-RELEASE-K は、全翻訳済み)
13.3-STABLE-K, 15.0-CURRENT-K は現在、作成中で日々更新されています。
Table of Contents
LIBXO(3) FreeBSD ライブラリ関数マニュアル LIBXO(3)
名称
xo_format -- xo_emit のための書式記述子の内容
解説
libxo は、テキスト, XML, JSON と HTML を含む様々な出力スタイルにデータの
レンダリングを制御するために書式文字列を使用します。各書式文字列は、独立
したデータフィールドを記述している、1 組の 0 以上の ``フィールド記述'' を
含んでいます。各フィールド記述は、1 組の ``修飾子'', ``内容文字列'' と
0、1 つまたは 2 つの ``書式記述子'' を含んでいます。修飾子は、何のフィー
ルドか、とそれを扱う方法を libxo に伝えますが、書式記述子は、フィールドを
書式化する方法を libxo に伝えて、printf(3) スタイルの書式文字列を使用する
書式設定の指示です。フィールド記述は、修飾子の後のコロン (`:') と各書式記
述子の前のスラッシュ (`/') とともに、1 組の大括弧の内部に置かれます。テキ
ストは、書式文字列内のフィールド記述と混ぜられます。
フィールド記述は、次のように与えられます:
'{' [ role | modifier ]* [',' long-names ]* ':' [ content ]
[ '/' field-format [ '/' encoding-format ]] '}'
ロール (役割) は、フィールドの機能を記述しますが、修飾子は、オプションの
振る舞いを有効にします。内容、フィールド形式とエンコード形式は、ロールに
基づいて、さまざまな方法で使用されます。これらは、次のセクションに記述さ
れています。
大括弧は、printf(3) の "%%" と同様に、2 つの大括弧を使用することによって
エスケープすることができます。書式文字列 "{{braces}}" は、"{braces}" を出
力します。
次の例において、3 つのフィールド記述子が現われます。最初は、パディングの
3 つの空白を含んでいるパディングのフィールドで、2 番目は、ラベル ("In
stock") で、3 番目は、値フィールド ("in-stock") です。in-stock フィールド
には、符号なし整数として xo_emit(3) 関数に渡された次の引数を解析する "%u"
形式があります。
xo_emit("{P: }{Lwc:In stock}{:in-stock/%u}\n", 65);
このコードの単一の行は、テキスト ("In stock: 65\n")、XML
("<in-stock>65</in-stock>")、JSON ('"in-stock": 65') または HTML (ここで
リストされるには長すぎる) を生成することができます。
ロールと修飾子が通常、簡潔さのための単一の文字を使用する間に、より冗長な
書式文字列を許可するそれぞれに代替の名前があります。これらの名前は、コン
マが先行し、あらゆる単一文字の値が続かなければなりません。
xo_emit("{L,white,colon:In stock}{,key:in-stock/%u}\n", 65);
フィールドのロール
フィールドのロールは、オプションで、ロールと内容の形式を示します。ロール
は、下記にリストされます。1 つのロールだけが許可されます:
M 名前 説明
C color フィールドは, カラーまたは効果です
D decoration フィールドは, 非テキストです (例えば, コロン, コンマ)
E error フィールドは, エラーメッセージです
L label フィールドは, 値の前に付けるテキストです
N note フィールドは, 値に続くテキストです
P padding フィールドは, 垂直の整列のために必要とされる空白です
T title フィールドは, 表題のためのタイトル値です
U units フィールドは, 前の値フィールドのための単位です
V value フィールドは, フィールドの名前です (デフォルト)
W warning フィールドは, 警告メッセージです
[ start-anchor 固定された可変幅のテキストのセクションを始めます
] stop-anchor 固定された可変幅のテキストのセクションを終了します
EXAMPLE:
xo_emit("{L:Free}{D::}{P: }{:free/%u} {U:Blocks}\n",
free_blocks);
ロールが提供されないとき、"値" ロールは、デフォルトとして使用されます。
また、ロールと修飾子は、コンマが先導されるとき、より冗長な名前を使用する
ことができます:
EXAMPLE:
xo_emit("{,label:Free}{,decoration::}{,padding: }"
"{,value:free/%u} {,units:Blocks}\n",
free_blocks);
カラーのロール ({C:})
カラーと効果は、どのようにテキスト値が表示されるかを制御します。それら
は、表示スタイルのために使用されます (TEXT と HTML)。
xo_emit("{C:bold}{:value}{C:no-bold}\n", value);
カラーと効果は、他の "C" ロールフィールドによって修正されるまで、実際に、
残ります。
xo_emit("{C:bold}{C:inverse}both{C:no-bold}only inverse\n");
内容が空であるなら、"リセット" アクションが実行されます。
xo_emit("{C:both,underline}{:value}{C:}\n", value);
内容は、0 以上のカラーまたは表示効果のコンマで区切られたされたリストであ
るべきです。
xo_emit("{C:bold,underline,inverse}All three{C:no-bold,no-inverse}\n");
カラー内容は、いずれも静的であり、フィールド記述子内に直接置かれるとき、
またはスラッシュ ("/") が先行するなら、printf スタイルの書式記述子を使用
することができます。
xo_emit("{C:/%s%s}{:value}{C:}", need_bold ? "bold" : "",
need_underline ? "underline" : "", value);
カラーの名前は、それぞれ、フォアグラウンドカラーとバックグラウンドカラー
を変更するために、"fg-" または "bg-" のいずれかが前に付けられます。
xo_emit("{C:/fg-%s,bg-%s}{Lwc:Cost}{:cost/%u}{C:reset}\n",
fg_color, bg_color, cost);
次のテーブルは、サポートされた効果をリストしています:
名前 説明
bg-xxxxx バックグラウンドカラーを変更します
bold ボールドのテキスト効果を開始します
fg-xxxxx フォアグラウンドカラーを変更します
inverse 逆のテキスト効果を開始します
no-bold ボールドのテキスト効果を停止します
no-inverse 逆のテキスト効果を停止します
no-underline 下線のテキスト効果を停止します
normal 効果 (のみ) をリセットします
reset カラーと効果をリセットします (デフォルトを復元します)
underline 下線のテキスト効果を開始します
次のカラーの名前がサポートされます:
名前
black
blue
cyan
default
green
magenta
red
white
yellow
デコレーションロール ({D:})
デコレーションは、一般的にコロン、セミコロンとテキストをデコレートするた
めに使用されるコンマのような句読点で、人間の読み手のためにより単純にしま
した。これらをはっきりとマークすることによって、HTML の使用法のシナリオ
は、それらの表示パラメータを指図するために CSS を使用することができます。
xo_emit("{D:((}{:name}{D:))}\n", name);
gettext のロール ({G:})
libxo は、gettext(3) のその使用を通して国際化 (i18n) をサポートしていま
す。gettext() を使用してい処理される、"{G:}" フィールドに続いて、書式文字
列の残りの部分を要求する "{G:}" ロールを使用します。gettext() は、メッ
セージカタログにキーとして文字列を使用するので、libxo は、高価な変換プロ
セスに影響を与えることからマイナな形式の変更を停止して、重要でないフィー
ルド形式と修飾子を削除する、書式文字列の簡素化されたバージョンを使用しま
す。"/%06d" を "/%08d" に変更するような開発者の変更は、すべての .po ファ
イルの手動の検査を強制するべきではありません。
簡素化されたバージョンは、"xopo -s <text>" コマンドを使用して単一のメッ
セージのために、生成することができるか、または、全体の .pot は、"xopo -f
<input> -o <output>" コマンドを使用して変換することができます。
xo_emit("{G:}Invalid token\n");
{G:} ロールは、ドメイン名が設定されることを許可します。gettext() 呼び出し
は、それ自体のカタログを使用して文字列を出力するライブラリ関数を有効にし
て、現在の書式文字列の処理が完全されるまで、そのドメイン名を使用し続けま
す。ドメイン名は、フィールドの内容として静的であるか、または引数からドメ
イン名を取得するために、書式を使用することができます。
xo_emit("{G:libc}Service unavailable in restricted mode\n");
ラベルロール ({L:})
ラベルは、値の前に現われるテキストです。
xo_emit("{Lwc:Cost}{:cost/%u}\n", cost);
ノートロール ({N:})
ノートは、値の後に現われるテキストです。
xo_emit("{:cost/%u} {N:per year}\n", cost);
詰め物ロール ({P:})
詰め物は、フィールドの前と間で使用される空白類を表わします。詰め物の内容
は、フィールド記述子内に直接置かれるとき、静的であるか、またはラッシュ
("/") によって先導されるなら、printf スタイルの書式記述子を使用することが
でるかのいずれかを指定することができます。
xo_emit("{P: }{Lwc:Cost}{:cost/%u}\n", cost);
xo_emit("{P:/30s}{Lwc:Cost}{:cost/%u}\n", "", cost);
タイトルロール ({T:})
タイトルは、ユーザに表示されることを意図する見出しまたはカラムヘッダで
す。タイトルは、フィールド記述子内に直接置かれるとき、静的であるか、また
はラッシュ ("/") によって先導されるなら、printf スタイルの書式記述子を使
用することがでるかのいずれかを指定することができます。
xo_emit("{T:Interface Statistics}\n");
xo_emit("{T:/%20.20s}{T:/%6.6s}\n", "Item Name", "Cost");
ユニットロール ({U:})
ユニットは、等級、マイル、バイトとデシベルのような、値が測定される次元で
す。ユニットフィールドは、前の値フィールドに対してこの情報を伝えます。
xo_emit("{Lwc:Distance}{:distance/%u}{Uw:miles}\n", miles);
'w' 修飾子の意味は、ユニットで逆にされることに注意してください。空白は、
その後にではなく内容の前に追加されます。
XOF_UNITS フラグが設定されるとき、ユニットは、``units'' 属性として XML で
示されます:
<distance units="miles">50</distance>
また、ユニットは、"data-units" 属性として HTML で示すことができます:
<div class="data" data-tag="distance" data-units="miles"
data-xpath="/top/data/distance">50</div>
値ロール ({V:} と {:})
値ロールは、非表示の出力スタイル (XML と JSON) のために興味深いデータ値を
表現するために使用されます、値は、デフォルトのロールです。他のロール指示
が与えられないなら、フィールドは、値です。フィールド名は、1 つまたは 2 つ
の書式記述子が続く、フィールド記述子内に現われなければなりません。最初の
書式記述子は、表示形式 (TEXT と HTML) のために使用されますが、一方、2 番
目のものは、エンコードスタイル (XML と JSON) のために使用されます。2 番目
の形式が与えられないなら、エンコード形式は、削除されたあらゆる最小の幅が
ある最初の形式をデフォルトとします。最初の形式が与えられないなら、両方の
書式記述子は、"%s" をデフォルトとします。
xo_emit("{:length/%02u}x{:width/%02u}x{:height/%02u}\n",
length, width, height);
xo_emit("{:author} wrote
author, poem, year);
アンカのロール ({[:} と {]:})
アンカロール (anchor role) は、グループとして詰め物をされることによって、
1 組の文字列を許可しますが、別個のフィールドとして xo_emit(3) にまだ見え
ます。開始または停止のいずれかのアンカは、フィールドの幅を与えることがで
き、記述子で直接か、または引数として渡されるかのいずれかを指定することが
できます。開始と停止のアンカの間のあらゆるフィールドは、与えられた最小の
幅に満たされるように詰め物がされます。
幅を直接与えるために、アンカタグ (anchor tag) の内容としてそれをエンコー
ドします:
xo_emit("({[:10}{:min/%d}/{:max/%d}{]:})\n", min, max);
引数として幅を渡すために、"/" の後に現われなければならない、形式として
"%d" を使用します。"%d" だけが幅のためにサポートされることに注意してくだ
さい。他の値を使用することは、利用者の日を台無しにすることができました。
xo_emit("({[:/%d}{:min/%d}/{:max/%d}{]:})\n", width, min, max);
幅が負であるなら、詰め物は、左寄せに適している、右に追加されます。そうで
なければ、詰め物は、右寄せに適している、開始と停止のアンカの間のフィール
ドの左に追加されます。幅が 0 であるなら、何も起こりません。開始と停止のア
ンカ間の出力のカラムの数が、与えられた幅の絶対値未満であるなら、何も起こ
りません。
8k を越える幅は、確率誤差と見なされ、サポートされません。XOF_WARN が設定
されるなら、警告が生成されます。
フールド修飾子
フィールド修飾子は、特定の出力スタイルのために出力される方法の内容を修正
するフラグです:
M 名前 説明
a argument 内容は, "const char *" 引数として現れます
c colon コロン (":") は, ラベルの後に追加されます
d display 表示スタイル (text/HTML) のためのフィールドのみを発行し
ます
e encoding エンコードのスタイル (XML/JSON) のためだけに発行します
h humanize (hn) 人間に読み込み可能なスタイルで大きい数を書式化します
hn-space 人間化: 数とユニットの間に空白を置きます
hn-decimal 人間化: 数 < 10 なら, 10 進数を追加します
hn-1000 人間化: 1024 の代わりの除数として 1000 を使用します
k key フィールドは, XPath 述語に適しているキーです
l leaf-list フィールドは, リーフリスト, リーフ値のリストです
n no-quotes JSON スタイルを使用するとき, フィールドをクォートしません
q quotes JSON スタイルを使用するとき, フィールドをクォートします
t trim 先導して, 後続する空白類を取り除きます
w white space 空白 (" ") は, ラベルの後に追加されます
例えば、修飾子の文字列 "Lwc" は、フィールドには、ラベルロール (次のフィー
ルドを記述するテキスト) があり、コロン ('c') と空白 ('w') が続くべきであ
ることを意味します。修飾子の文字列 "Vkq" は、フィールドには、現在のインス
タンスのためのキーである、値ロールがあり、JSON のためにエンコードされると
き、値がクォートされるべきであることを意味します。
また、ロールと修飾子は、コンマが先行するとき、より冗長な名前を使用するこ
とができます。例えば、修飾子文字列 "Lwc" (または "L,white,colon") は、
フィールドにラベルのロール (次のフィールドを記述するテキスト) があり、コ
ロン ('c') と空白 ('w') が続くべきであることを意味します。修飾子文字列
"Vkq" (または ":key,quote") は、フィールドに値のロール (デフォルトのロー
ル) があり、それは、現在のインスタンスのためのキーであり、値は、JSON のた
めにエンコードされるとき、引用されるべきであることを意味します。
引数修飾子 ({a:})
引数修飾子は、フィールド記述子の内容が xo_emit パラメータ内の UTF-8 文字
列 (const char *) 引数として置かれることを示します。
EXAMPLE:
xo_emit("{La:} {a:}\n", "Label text", "label", "value");
TEXT:
Label text value
JSON:
"label": "value"
XML:
<label>value</label>
引数修飾子は、snprintf(1) を使用してフィールド記述子を構築する必要を避け
て、スタックで渡される値フィールドのためのフィールド名を許可します。多く
のフィールドの役割のために、引数修飾子は、それらの役割に "{C:fg-%s}" のよ
うな引数のための特有のメカニズムがあるので、必要ではありません。
コロン修飾子 ({c:})
コロン修飾子は、データ値に単一のコロンを追加します:
EXAMPLE:
xo_emit("{Lc:Name}{:name}\n", "phil");
TEXT:
Name:phil
コロン修飾子は、TEXT と HTML 出力スタイルのためだけに使用されます。それ
は、空白修飾子 ('{w:}') と共通に組み合わされます。それは、純粋に便利な機
能です。
表示修飾子 ({d:})
表示修飾子は、フィールドが表示出力スタイル、TEXT と HTML のために単に生成
されるべきであることを示します。
EXAMPLE:
xo_emit("{Lcw:Name}{d:name} {:id/%d}\n", "phil", 1);
TEXT:
Name: phil 1
XML:
<id>1</id>
表示修飾子は、エンコード修飾子の反対で、それらは、基本適なデータの別個の
見方に与えるためにしばしば使用されます。
エンコード修飾子 ({e:})
エンコード修飾子は、フィールドが、JSON と XML のような、エンコード出力ス
タイルのためだけに生成されるべきであることを示します。
EXAMPLE:
xo_emit("{Lcw:Name}{:name} {e:id/%d}\n", "phil", 1);
TEXT:
Name: phil
XML:
<name>phil</name><id>1</id>
エンコード修飾子は、表示修飾子の反対で、それらは、基本適なデータの別個の
見方に与えるためにしばしば使用されます。
人間化修飾子 ({h:})
人間化修飾子は、大きい数を人間に読み込み可能なな形式で表現するために使用
されます。"44470272" のような数がコンピュータと学者に完全に読み込み可能で
すが、人は、一般的により意味がある "44M" を見つけます。
"hn" は、"人間化" のためのエイリアスとして使用することができます。
人間化修飾子は、表示スタイル (TEXT と HMTL) に影響するだけです。
"no-humanize" オプションは、人間化修飾子の機能を防ぎます。
人間化の詳細に影響する多くの修飾子があります。これらは、単一の文字ではな
く、フルネームとしてのみ利用可能です。"hn-space" 修飾子は、"M" または "K"
(ex: "44 K") のような、数とあらゆる乗数シンボルの間に空白を置きます。
"hn-decimal" 修飾子は、数が 10 未満 (ex: "4.4K") であるとき、小数点と単一
の 10 分の 1 の位を追加します。"hn-1000" 修飾子は、より自然なバイナリの 2
のべき乗の習慣の代わりに JEDEC 標準に従って、1024 の代わりに除数として
1000 を使用します。
EXAMPLE:
xo_emit("{h:input/%u}, {h,hn-space:output/%u}, "
"{h,hn-decimal:errors/%u}, {h,hn-1000:capacity/%u}, "
"{h,hn-decimal:remaining/%u}\n",
input, output, errors, capacity, remaining);
TEXT:
21, 57 K, 96M, 44M, 1.2G
HTML スタイルで、オリジナルの数値は、<div> 要素の "data-number" 属性で表
現されます:
<div class="data" data-tag="errors"
data-number="100663296">96M</div>
gettext 修飾子 ({g:})
gettext 修飾子は、gettext ドメイン (通常、"{G:}" ロールを使用して設定され
る) と現在の言語設定を使用して個別のフィールドを変換するために使用されま
す。いったん、libxo が、フィールド値を表現すると、それは、自国の言語の変
換を見つけるために、キーとして使用されるところで、gettext(3) に渡されま
す。
次の例において、文字列 "State" と "full" は、ロケールベースの変換された文
字列を見つけるために、gettext() に渡されます。
xo_emit("{Lgwc:State}{g:state}\n", "full");
キー修飾子 ({k:})
キー修飾子は、特別のフィールドがリストデータのインスタンスをユニークに識
別することをサポートすることを示すために使用されます。
EXAMPLE:
xo_open_list("user");
for (i = 0; i < num_users; i++) {
xo_open_instance("user");
xo_emit("User {k:name} has {:count} tickets\n",
user[i].u_name, user[i].u_tickets);
xo_close_instance("user");
}
xo_close_list("user");
現在、キー修飾子は、XOF_XPATH が設定されるとき、HTML 出力スタイルのための
XPath 値を生成するときのみ、使用されますが、他のものは、いずれ近いうち
に、あり得ます。
リーフリスト修飾子 ({l:})
リーフリスト修飾子は、各インスタンスが単一の値だけからなるところで、リス
トを区別するために使用されます。XML において、これらは、JSON が、配列とし
てそれらを表現するところで、単一の要素として表現されます。
EXAMPLE:
xo_open_list("user");
for (i = 0; i < num_users; i++) {
xo_emit("Member {l:name}\n", user[i].u_name);
}
xo_close_list("user");
XML:
<user>phil</user>
<user>pallavi</user>
JSON:
"user": [ "phil", "pallavi" ]
クォートがない修飾子 ({n:})
クォートがない修飾子 (とその対の、'quotes' 修飾子) は、JSON 出力スタイル
の値のクォートに影響します。JSON は、文字列値のためにクォートを使用します
が、数値、ブール値、と無効のデータのためにクォートを使用しません。
xo_emit(3) は、クォートが必要かどうか判断するために単純なヒューリスティッ
クを適用しますが、しばしば、これは、呼び出し側によって制御される必要があ
ります。
EXAMPLE:
const char *bool = is_true ? "true" : "false";
xo_emit("{n:fancy/%s}", bool);
JSON:
"fancy": true
複数の修飾子 ({p:})
複数の修飾子は、出力された最も最近の数と現在の言語設定に基づいて表現の適
切な複数形を選択します。フィールドの内容は、コンマによって区切られる、単
数と複数の英語値であるべきです。
xo_emit("{:bytes} {Ngp:byte,bytes}\n", bytes);
複数の修飾子は、gettext 修飾子 ({g:}) で動作しますが、独立して動作するこ
とができることを意味します。
gettext 修飾子なしで使用されるとき、またはメッセージがメッセージカタログ
に現れないとき、最初のトークンは、最後の数の値が 1 と等しいとき、選択され
ます。そうでなければ、2 番目の値は、英語の簡単な複数形化された規則を模擬
して使用されます。
gettext 修飾子で使用されるとき、ngettext(3) 関数は、単数形と複数形を自国
の言語に変換するために、メッセージカタログを使用して、力仕事を処理するた
めに、呼び出されます。
クォート修飾子 ({q:})
クォート修飾子 (とその対の、'no-quotes' 修飾子) は、JSON 出力スタイルの値
のクォートに影響します。JSON は、文字列値のためにクォートを使用しますが、
数値、ブール値、と無効のデータのためのクォートを使用しません。xo_emit(3)
は、クォートが必要かどうか判断するために単純なヒューリスティックを適用し
ますが、しばしば、これは、呼び出し側によって制御される必要があります。
EXAMPLE:
xo_emit("{q:time/%d}", 2014);
JSON:
"year": "2014"
空白類修飾子 ({w:})
空白類修飾子は、データ値に単一の空白を追加します:
EXAMPLE:
xo_emit("{Lw:Name}{:name}\n", "phil");
TEXT:
Name phil
空白類修飾子は、TEXT と HTML 出力スタイルのためだけに使用されます。それ
は、コロン修飾子 ('{c:}') と共通に組み合わされます。それは、純粋に便利な
機能です。
'w' 修飾子の意味は、ユニットロール ({Uw:}) で逆にされることに注意してくだ
さい。空白は、その後にではなく内容の前に追加されます。
フィールドの書式化
フィールド書式は、printf(3) のための書式文字列に似ています。それは、
フィールドのロールに基づいて異なって使用されますが、フィールドの内容を書
式化るために一般的に使用されます。
書式文字列が値フィールドのために提供されないなら、それは、"%s" をデフォル
トとします。
フィールド定義は、'%' で始まり、次の文字の 1 つで終わるシーケンスである、
0 以上の printf スタイルの ``指示'' を含むことができることに注意してくだ
さい: "diouxXDOUeEfFgGaAcCsSp"。各指示は、xo_emit(3) 関数へのより多くの引
数の 1 つによって一致します。
書式文字列には、次の形式があります:
'%' format-modifier * format-character
書式 - 修飾子は、次を指定ですることがきます:
• '#' 文字、出力値を示すことは、一般的に、16 進数の値を示すために "0x"
を前に付けられるべきです。
• マイナス記号 ('-')、出力値を示すことは、左の代わりに右に詰め物がされ
るべきです。
• 先導するゼロ ('0')、出力値を示すことは、空白 (' ') の代わりに 0 で左
に詰め物がされるべきです。
• 引数の最小の幅を示す 1 つ以上の数字 ('0' - '9')。出力値のカラムの幅が
最小幅より少ないなら、値は、最小に達するため詰め物がされます。
• 文字列の引数のために検査されるバイトの最大数を示す 1 つ以上の数値が後
続するピリオド、または非文字列引数のための最大幅。ASCII 文字列を扱う
とき、これは、マルチバイト文字を除いて、フィールドの幅とする関数です
が、単一文字は、複数のバイトから成ります。xo_emit(3) は、バイトの与え
られた数を越えてメモリを決して修飾参照 (dereference) しません。
• 文字列の引数のための最大幅を示す 1 つ以上の数値が後続する 2 番目のピ
リオド。この修飾子は、文字列でない引数に対して与えることができませ
ん。
• より短い入力データを示す 1 つ以上の 'h' 文字。
• より長い入力データを示す 1 つ以上の 'l' 文字。
• 'size_t' 引数を示す 'z' 文字。
• 'ptrdiff_t' 引数を示す 't' 文字。
• 正の数値の前に発行されるされるべきである空白を示す ' ' 文字。
• あらゆる数値の前に発行されるべきである符号を示す '+' 文字。
'q'、'D'、'O' と 'U' は、非推奨とみなされ、最終的に削除されることに注意し
てください。
書式文字は、次のテーブルに記述されています:
C 引数タイプ 形式
d int base 10 (10 進数)
i int base 10 (10 進数)
o int base 8 (8 進数)
u unsigned base 10 (10 進数)
x unsigned base 16 (16 進数)
X unsigned long base 16 (16 進数)
D long base 10 (10 進数)
O unsigned long base 8 (8 進数)
U unsigned long base 10 (10 進数)
e double [-]d.ddde+-dd
E double [-]d.dddE+-dd
f double [-]ddd.ddd
F double [-]ddd.ddd
g double as 'e' or 'f'
G double as 'E' or 'F'
a double [-]0xh.hhhp[+-]d
A double [-]0Xh.hhhp[+-]d
c unsigned char 文字
C wint_t 文字
s char * UTF-8 文字列
S wchar_t * unicode/WCS 文字列
p void * '%#lx'
'h' と 'l' 修飾子は、引数のサイズと処理に影響します:
Mod d, i o, u, x, X
hh signed char unsigned char
h short unsigned short
l long unsigned long
ll long long unsigned long long
j intmax_t uintmax_t
t ptrdiff_t ptrdiff_t
z size_t size_t
q quad_t u_quad_t
UTF-8 とロケール文字列
すべての libxo のための文字列は、UTF-8 でなければなりません。libxo は、そ
れらをユーザに表示するためのロケールに基づいた文字列に変換して扱います。
文字列について、'h' と 'l' 修飾子は、引数を指しているバイトの解釈に影響し
ます。デフォルトの '%s' 文字列は、UTF-8 としてエンコードされる文字列への
'char *' ポインタです。UTF-8 が ASCII データと互換性があるので、通常の 7
ビットの ASCII 文字列を使用することができます。"%ls" は、32 ビットの Uni
code の値としてエンコードされるワイド文字列への "wchar_t *" ポインタを予
期します。"%hs" は、LC_CTYPE, LANG または LC_ALL 環境変数によって与えられ
るように、現在のロケールでエンコードされたマルチバイト文字列への 'char *'
ポインタを予期します。最初のこのリストの変数は、使用され、変数が設定され
ていないなら、ロケールは、UTF-8 をデフォルトとします。
libxo は、(XML、JSON と HTML スタイルのための) UTF-8 またはテキストスタイ
ルの表示のためのロケールに基づいた文字列のいずれかを必要とするようにこれ
らの引数をを変換します。
xo_emit("All strings are utf-8 content {:tag/%ls}",
L"except for wide strings");
"%S" は、"%ls" と同等です。
例えば、関数は、ロケールベースの名前、hat サイズと時間の値を渡されます。
hat サイズは、UTF-8 (ASCII) 文字列で書式化され、時間の値は、wchar_t 文字
列に書式化されます。
void print_order (const char *name, int size,
struct tm *timep) {
char buf[32];
const char *size_val = "unknown";
if (size > 0)
snprintf(buf, sizeof(buf), "%d", size);
size_val = buf;
}
wchar_t when[32];
wcsftime(when, sizeof(when), L"%d%b%y", timep);
xo_emit("The hat for {:name/%hs} is {:size/%s}.\n",
name, size_val);
xo_emit("It was ordered on {:order-time/%ls}.\n",
when);
}
xo_emit(3) が適切な出力を行うために必要とされる変換を実行することに注意す
ることは重要です。テキストスタイルの出力は、(上に記述されるように) 現在の
ロケールを使用しますが、一方 XML、JSON と HTML は、UTF-8 を使用します。
UTF-8 とロケールのエンコードされた文字列は、データを 1 カラムをエンコード
するために複数のバイトを使用することができます。"%s" printf 書式のための
従来の "precision'" (別名 "max-width") 値は、安全に参照さすることができる
バイトの数と発行するカラムの最大数の両方を指定するので、オーバロードとな
ります。xo_emit(3) は、前者として正確に使用し、カラムの最大数の指定のため
の 3 番目の値を追加します。
この例において、名前フィールドは、最低 3 カラムと最大 6 までで印刷 (表示)
されます。10 バイトまでは、それらのカラムを満たすことに使用されます。
xo_emit("{:name/%3.10.6s}", name);
フィールド定義の文字の外側
フィールド定義の一部ではない書式文字列の文字は、TEXT スタイルのための出力
にコピーされ、JSON と XML のスタイルのために無視されます。HTML について、
これらの文字は、クラス "text" がある <div> に置かれます。
EXAMPLE:
xo_emit("The hat is {:size/%s}.\n", size_val);
TEXT:
The hat is extra small.
XML:
<size>extra small</size>
JSON:
"size": "extra small"
HTML:
<div class="text">The hat is </div>
<div class="data" data-tag="size">extra small</div>
<div class="text">.</div>
'%n' は、サポートされません
libxo は、'%n' 指示をサポートしません。それは、悪い考えで、それをまったく
行いません。
エンコード形式 (eformat)
"eformat" 文字列は、JSON と XML のためのフィールドをエンコードするとき、
使用される書式文字列です。提供されないなら、それは、デフォルトで削除され
るあらゆる最小の幅があるプライマリ書式をデフォルトとします。プライマリが
与えられないなら、両方は、"%s" をデフォルトとします。
使用例
この例において、ストックの項目の数のための値は、発行されます:
xo_emit("{P: }{Lwc:In stock}{:in-stock/%u}\n",
instock);
この呼び出しは、次の出力を生成します:
TEXT:
In stock: 144
XML:
<in-stock>144</in-stock>
JSON:
"in-stock": 144,
HTML:
<div class="line">
<div class="padding"> </div>
<div class="label">In stock</div>
<div class="decoration">:</div>
<div class="padding"> </div>
<div class="data" data-tag="in-stock">144</div>
</div>
明らかに、HTML は、多弁賞を受賞し、この出力は、最後から 2 番目の行を次の
ように拡張する、XOF_XPATH または XOF_INFO のデータを含んでいません:
<div class="data" data-tag="in-stock"
data-xpath="/top/data/item/in-stock"
data-type="number"
data-help="Number of items in stock">144</div>
よいフィールド名は、何ですか?
役に立ち、一貫したフィールド名、次のこれらのガイドラインを行うために:
TLA のためでさえ、小文字を使用します
小文字は、より洗練されます。TLA でさえ "XPath" と "Xpath" の間の差が利用
者のユーザの気を狂わせるところで、シナリオを回避するのに、小文字であるべ
きです。"xpath" の使用は、より単純でよりよいです。
下線ではなくハイフンを使用する
ハイフンの使用は、XML において伝統的で、XOF_UNDERSCORES フラグは、望まれ
るなら、JSON で下線を生成するために使用することができます。しかし、生の
フィールド名は、ハイフンを使用するべきです。
完全な単語を使用する
特に省略が明白でないか、または、広く使用されないとき、短縮しないでくださ
い。"dsz" または "dsize" ではなく "data-size" を使用します。"ifname"、
"if-name"、"iface"、"if" または "intf" の代わりに "interface" を使用しま
す。
<verb>-<units> を使用する
形式 <verb>-<units> または <verb>-<classifier>-<units> を使用することは、
1 つのアプリが "sent-packet" と別の "packets-sent" と別の "pack
ets-we-have-sent" を使用する状況を回避して、一貫して有用な名前の作成を手
助けします。分類で単語を明白にできるように、それが明白なとき、<units> を
落とすことができます。"received-packets-of-data-after-window" の代わりに
"receive-after-window-packets" を使用します。
既存のフィールド名を再利用する
次のような書く表現より悪いことはありません:
if ($src1/process[pid == $pid]/name ==
$src2/proc-table/proc/p[process-id == $pid]/proc-name) {
...
}
同様のデータを示している誰か他の人を見つけ、それらのフィールドと階層に従
います。クォートは、``Consistency is the hobgoblin of little minds'' (一
貫性は、狭い心が化けた物である) ではなく、``A foolish consistency is the
hobgoblin of little minds'' (愚かな首尾一貫性は、狭い心が化けた物である)
であることを思い出してください。
利用者のユーザに関して考える
クリアで有用なデータを含んでいるクリアで有用なフィールドを選んで、利用者
のユーザのための共感がありあす。データを有用にするために xo_attr(3) 呼び
出しまたは "{e:}" フィールドがある表示内容を増加する必要があるかもしれま
せん。
任意の数の接尾辞を使用しない
"errors2" の意味は、何ですか? 誰も知りません。"errors-after-restart"
は、よりよい選択になります。利用者のユーザの考え、と将来について考え。利
用者が "errors2" となるなら、次の者は、幸福に "errors3" となり、利用者が
それを知る前に、誰かが errors37 と errors63 の間の差は何かを問い合わせま
す。
一貫して、一様で、驚くほどではなく、予測可能とする
API としてフィールドの語彙の利用者の考え。利用者は、役に立つ、表現して、
意味があり、直接で、明白であることを望みます。利用者は、クライアントのア
プリケーションのプログラマが、フィールドがどのように指定されるかの様々な
見解を理解する必要のない間に移動することを望みます。それらは、猫の袋では
なく、単一のまとなりのある全体としてシステムを参照するべきです。
フィールド名は、クライアントのプログラマが我々のシステムと対話する手段を
構成します。今、賢明な名前を選ぶことによって、それらの生活をよりよくして
います。
利用者のフィールド記述子のエラーを見つけるために xolint(1) を使用した後
に、利用者のフィールド名のスペルをチェックするために、同じデータの異なる
名前を検出するために ``xolint -V'' を使用します。``dropped-short'' と
``dropped-too-short'' は、両方とも合理的な名前ですが、それら両方を使用す
ることは、ユーザに 2 つのフィールド間の違いを問い合わせるようにします。違
いがないなら、フィールド名の 1 つのみを使用します。違いがあるなら、その違
いをより明白にするために名前を変更します。
関連項目
libxo(3), xolint(1), xo_emit(3)
歴史
libxo ライブラリは、FreeBSD 11.0 ではじめて登場しました。
作者
libxo は、Phil Shafer <phil@freebsd.org> によって書かれました。
FreeBSD 11.2 December 4, 2014 FreeBSD 11.2