EasyYamlParser Blueprint APIリファレンス

EasyYamlParserがBlueprintとC++に公開するノード・構造体・列挙型の全体像。

このページでは、EasyYamlParserがBlueprintに公開するAPIを説明します。C++でも同じAPIを利用できます。使い方の例はユースケースを参照してください。

API全体の関係

EasyYamlParserのBlueprintノードは、すべて EasyYamlParserBlueprintLibrary の静的関数として公開されます。データは2つの構造体で扱います。

flowchart TB
  FL["EasyYamlParser ノード群<br/>(Blueprint Function Library)"] --> YO["Yaml Object 構造体<br/>(FEasyYamlObject)"]
  FL --> YV["Yaml Value 構造体<br/>(FEasyYamlValue)"]
  YO --> TXT["YAML文字列 / ファイル"]
  • Yaml Object(FEasyYamlObject): YAMLドキュメント1つ分。Load系ノードの戻り値で、Write系ノードの対象になります。
  • Yaml Value(FEasyYamlValue): ドキュメントから取り出した1つ分の値。型を判定しながら値を読み出すときに使います。

ノードはカテゴリ EasyYamlParser 配下(Load、Create、Read、Write、Array、Save、Convert、Value、Utility)に並びます。

YamlObjectの作成

Load Yaml From String

YAML文字列を解析して Yaml Object を作成します。

ピン 種類 説明
Yaml String 入力 解析するYAML文字列
Success 出力 解析に成功すると true
Error Message 出力 失敗したときのエラー内容。行番号・列番号が含まれる
Error Code 出力 失敗理由の種別(エラーコードを参照)
Return Value 出力 作成された Yaml Object。失敗時は無効なオブジェクト

Load Yaml From File

YAMLファイルを読み込んで Yaml Object を作成します。

ピン 種類 説明
File Path 入力 YAMLファイルのパス
Is Absolute 入力 オフのとき File Path はContentディレクトリ基準の相対パスとして解釈
Success 出力 読み込みと解析に成功すると true
Error Message 出力 ファイルが見つからない・読めない・解析できないときのエラー内容
Error Code 出力 失敗理由の種別
Return Value 出力 作成された Yaml Object

Create Empty Yaml Object

空の Yaml Object を作成します。ルートが空のマップの有効なオブジェクトで、Write系ノードで新しいYAMLを組み立てる起点にします。

値の読み取り

Read Int、Read Float、Read String、Read Bool の4ノードは、いずれも同じ入出力を持つ純関数(BlueprintPure)です。

ピン 種類 説明
Yaml Object 入力 読み取り元の Yaml Object
Access String 入力 読み取り先のパス(アクセス文字列)
Default Value 入力 パスが存在しない・型が違うときに返す値
Return Value 出力 読み取った値

型が異なる値を指定した場合(数値のパスに Read String を使うなど)もデフォルト値が返ります。Read Int の整数はint64(64bit)で、Read Float はdouble精度です。

Read系ノードの入出力ピンの例

Read Object

アクセス文字列が指すマップを、新しい Yaml Object として返します。取得したオブジェクトは独立したコピーで、パスの途中を省略したアクセス文字列で読み取りできます。パス先がマップでない場合は無効なオブジェクトが返ります。

Read Objects

アクセス文字列が指す、要素がマップのシーケンスを Yaml Object の配列として返します。For Each Loop と組み合わせて各要素を処理します。マップでない要素はスキップされます。

Read ObjectとRead Objectsノードの入出力ピンの例

Read Value

アクセス文字列が指すノードのスナップショットを Yaml Value として返します。パスが存在しない場合は無効な値が返ります。取得した値はValue系ノードで型を判定して読み出します。

Read Array Element / Read Array Values

  • Read Array Element は、アクセス文字列が指すシーケンスの Index 番目の要素を Yaml Value として返します。パスがシーケンスでない場合やインデックスが範囲外の場合は無効な値が返ります。
  • Read Array Values は、シーケンスの全要素を Yaml Value の配列で返します。パスがシーケンスでない場合は空の配列が返ります。

Get Array Size / Is Array

  • Get Array Size は、アクセス文字列が指すシーケンスの要素数を返します。パスがシーケンスでない場合は 0 が返ります。
  • Is Array は、パスが指すノードがシーケンスかどうかを返します。

Has Path

アクセス文字列が指すパスが存在するかを返します。値がnullのパスも「存在する」と判定されます。

Get Root Type

ドキュメントのルートノードの型(Map、Sequence など)を返します。Yaml Object が無効な場合は Null が返ります。

値の書き込み

Write Int、Write Float、Write String、Write Bool、Write Object、Write Null の6ノードは、いずれも Yaml Object ピンを参照渡し(UPARAM(ref))で受け取ります。ノードを実行すると、繋いだ Yaml Object 変数の中身が直接更新されます。

ピン 種類 説明
Yaml Object 入力 更新する Yaml Object(変数を接続します)
Access String 入力 書き込み先のパス
Value 入力 書き込む値。Write Object は別の Yaml Object を指定

アクセス文字列の途中のマップ(player.stats の stats など)が存在しない場合、パスが自動的に作成されます。Write Object で他の Yaml Object を埋め込むと、階層構造を持つYAMLを組み立てられます。Write Null は明示的にnullを書き込みます。

Write系ノードでYAMLを組み立てるBlueprintの構成例

書き込みの詳細な動作(ルートの置換、インデックスの上限など)はデータ形式と運用を参照してください。

シーケンスへの追加

Add Int To Array、Add Float To Array、Add String To Array、Add Bool To Array、Add Object To Array の5ノードは、指定したパスのシーケンスの末尾に値を追加します。Yaml Object ピンはWrite系と同じく参照渡しです。

シーケンスが存在しないパスを指定した場合はシーケンスが自動的に作成されます。既存の要素は保持され、追加のたびに末尾へ1つずつ加わります。

Add系ノードでYAMLシーケンスに値を追加するBlueprintの構成例

保存・変換

Save Yaml To File

Yaml Object の内容をファイルに保存します。

ピン 種類 説明
Yaml Object 入力 保存する Yaml Object
File Path 入力 保存先パス。相対パスはContentディレクトリ基準
Is Absolute 入力 File Path を絶対パスとして扱うか
Success 出力 保存に成功すると true
Error Message 出力 失敗したときのエラー内容
Error Code 出力 失敗理由の種別

保存先のフォルダが存在しない場合は自動的に作成されます。

Yaml To String

Yaml Object の内容をYAML文字列に変換します。YAMLはインデントで階層を表現するため、出力は常に改行とインデント付きの整形形式です。Yaml Object が無効な場合は空文字列が返ります。

Yaml To StringノードでYAML文字列に変換する構成例

Yaml Valueの操作

Read Value、Read Array Element、Read Array Values で取得した Yaml Value から値を取り出すノード群です。

Get Int Value / Get Float Value / Get String Value / Get Bool Value

Yaml Value が保持する値を指定の型で読み取ります。Default Value ピンで、型が違うとき・無効な値のときに返す値を指定します。

  • Get Int Value はint64、Get Float Value はdouble精度です。
  • Get String Value は文字列ノードのみから読み取ります。数値や真偽値は暗黙には変換されません。

Get Node Type

Yaml Value のノード型を EEasyYamlNodeType で返します。Null、Bool、Int、Float、String、Sequence、Map のいずれかで、比較して分岐できます。

Is Yaml Value Valid

Yaml Value が有効か(パスが存在したか)を返します。null値との区別には Get Node Type を使います。

Value系ノードの構成例

ユーティリティ

Is Yaml Object Valid

Yaml Object が有効なYAMLを保持しているかを返します。Load Yaml From String の失敗時の戻り値や、未初期化の変数の判定に使用します。

Are Yaml Objects Equal

2つの Yaml Object の内容が等しいかを比較します。型、値、マップのキー順序を含めた深い比較です。2つの無効なオブジェクトは等しいと判定されます。

エラーコード

Load 系・Save 系ノードの Error Code ピンは、列挙型 EEasyYamlErrorCode です。Success のboolと組み合わせて、分岐に使えます。

値 意味
None 成功
InvalidYaml YAMLの文法エラー
FileNotFound ファイルが見つからない・読めない
InvalidArgument 引数が不正(無効なオブジェクトの保存など)
StructConversionFailed USTRUCTとの変換に失敗(C++ API)
FileWriteFailed ファイルの書き込みに失敗

Error Message には、人の読める形式のエラー内容が入ります。YAMLの文法エラーでは line X column Y の形式で位置が分かります。

C++での実装例

Blueprintと同じノードは、C++では UEasyYamlBlueprintLibrary の静的関数として呼び出せます。加えて、FEasyYamlObject(Yaml Object)のメンバー関数と、USTRUCTとの変換APIがC++専用で用意されています。

#include "EasyYamlParser/EasyYamlBlueprintLibrary.h"
#include "EasyYamlParser/EasyYamlObject.h"

// 読み込みと読み取り
bool bSuccess = false;
FString ErrorMessage;
EEasyYamlErrorCode ErrorCode;
FEasyYamlObject YamlObject = UEasyYamlBlueprintLibrary::LoadYamlFromString(YamlString, bSuccess, ErrorMessage, ErrorCode);

if (bSuccess)
{
    // 関数ライブラリ経由
    FString Name = UEasyYamlBlueprintLibrary::ReadString(YamlObject, TEXT("player.name"), TEXT("Unknown"));

    // 構造体のメンバー関数(同等の結果)
    int64 Level = YamlObject.ReadInt(TEXT("player.level"), 1);
}

// 新しいYAMLの作成と保存
FEasyYamlObject NewYaml = FEasyYamlObject::CreateEmpty();
NewYaml.WriteInt(TEXT("score"), 1000);
NewYaml.WriteString(TEXT("playerName"), TEXT("Hero"));

FEasyYamlResult Result;
NewYaml.TrySaveToFile(TEXT("SaveData/PlayerSave.yaml"), Result);

USTRUCTとの変換(C++専用)

FEasyYamlObject には、YAMLドキュメントとUSTRUCTインスタンスを相互変換する関数があります。Blueprintからは使用できません。

// YAML -> USTRUCT(ルートがマップである必要があります)
FMyConfig Config;
FEasyYamlResult Result;
if (YamlObject.TryReadStruct(Config, Result))
{
    // Configの各UPROPERTYに値が反映されています
}

// USTRUCT -> YAML
FEasyYamlObject FromConfig = FEasyYamlObject::FromStruct(Config, bSuccess);

変換のマッピングルールと注意点はデータ形式と運用を参照してください。

ライフサイクルと保持のまとめ

  • Yaml Object は構造体の値ですが、コピー同士は内部のツリーを共有します。Write系・Add系ノードで書き込んだ内容は、同じ Yaml Object からコピーしたすべての変数から見えます。
  • Read Object / Read Objects が返すオブジェクトは独立したディープコピーです。取得後に元のドキュメントを書き換えても影響しません。
  • Yaml Value はノードのスナップショットです。取得後に元のドキュメントを書き換えても、値は変わりません。
  • ガベージコレクションの管理対象にならないUSTRUCTベースの設計です。解放処理は不要で、スコープから外れたあと自動的に破棄されます。