このページでは、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 Object
アクセス文字列が指すマップを、新しい Yaml Object として返します。取得したオブジェクトは独立したコピーで、パスの途中を省略したアクセス文字列で読み取りできます。パス先がマップでない場合は無効なオブジェクトが返ります。
Read Objects
アクセス文字列が指す、要素がマップのシーケンスを Yaml Object の配列として返します。For Each Loop と組み合わせて各要素を処理します。マップでない要素はスキップされます。
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を書き込みます。
書き込みの詳細な動作(ルートの置換、インデックスの上限など)はデータ形式と運用を参照してください。
シーケンスへの追加
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つずつ加わります。
保存・変換
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 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 を使います。
ユーティリティ
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ベースの設計です。解放処理は不要で、スコープから外れたあと自動的に破棄されます。
