YAML API

YAML の解析とシリアライズのヘルパーは ptool.yaml と p.yaml に あります。

ptool.yaml.parse

v0.4.0 - Introduced.

ptool.yaml.parse(input) は YAML 文字列を Lua 値へ解析します。

• input (string, 必須): YAML テキスト。
• 戻り値: 解析された Lua 値。ルートは対応している任意の YAML 型を使えます。

型対応:

• YAML mapping -> Lua table
• YAML sequence -> Lua sequence table (1-based)
• YAML string -> Lua string
• i64 に収まる YAML integer -> Lua integer
• それ以外の YAML number -> Lua number
• YAML boolean -> Lua boolean
• YAML null -> Lua nil

エラー時の挙動:

• input が文字列でない場合はエラーになります。
• YAML 構文エラーでは、パーサー詳細を含むメッセージでエラーになります。
• 非文字列キーを持つ mapping や明示的な YAML tag など、ptool の Lua 値へ 変換できない YAML 値でもエラーになります。

例:

local data = p.yaml.parse([[
name: ptool
features:
  - yaml
  - repl
stars: 42
]])

print(data.name)
print(data.features[1])
print(data.stars)

ptool.yaml.get

v0.4.0 - Introduced.

ptool.yaml.get(input, path) は YAML テキストから指定パスの値を読み出します。

• input (string, 必須): YAML テキスト。
• path ((string|integer)[], 必須): {"spec", "template", "metadata", "name"} や {"items", 1, "name"} のような空でないパス配列。
• 戻り値: 対応する Lua 値。パスが存在しない場合は nil。

挙動:

• 文字列のパス要素は mapping key を選択します。
• 整数のパス要素は Lua の 1-based 添字で sequence 要素を選択します。

例:

local text = [[
items:
  - name: alpha
  - name: beta
]]

local first_name = p.yaml.get(text, {"items", 1, "name"})
print(first_name)

ptool.yaml.stringify

v0.4.0 - Introduced.

ptool.yaml.stringify(value) は Lua 値を YAML テキストへ変換します。

• value (YAML 互換 Lua 値, 必須): エンコードする値。
• 戻り値: エンコードされた YAML 文字列。

挙動:

• 値は ptool.json.stringify と同じ Lua 値マッピングで YAML に変換可能である 必要があります。
• Lua sequence table は YAML sequence としてエンコードされます。
• 文字列キーを持つ Lua table は YAML mapping としてエンコードされます。

例:

local text = p.yaml.stringify({
  project = "ptool",
  features = {"yaml", "lua"},
  stable = true,
})

print(text)

注意:

• 現在は単一ドキュメントの YAML のみ対応しています。
• YAML mapping のキーは文字列である必要があります。
• 明示的な YAML tag は対応していません。
• ptool.yaml.get の path 引数は、文字列および正の整数から成る空でない配列で ある必要があります。
• 整数のパス要素は Lua の配列添字に合わせて 1-based です。