EasyYamlParser Blueprint API Reference

The full picture of the nodes, structs, and enums EasyYamlParser exposes to Blueprint and C++.

This page describes the API EasyYamlParser exposes to Blueprint. The same API is available from C++. For usage examples, see the Use Cases page.

How the API is organized

Every EasyYamlParser Blueprint node is a static function of EasyYamlParserBlueprintLibrary. Data is handled through two structs.

flowchart TB
  FL["EasyYamlParser nodes<br/>(Blueprint Function Library)"] --> YO["Yaml Object struct<br/>(FEasyYamlObject)"]
  FL --> YV["Yaml Value struct<br/>(FEasyYamlValue)"]
  YO --> TXT["YAML string / file"]
  • Yaml Object (FEasyYamlObject): one YAML document. It is the return value of the Load nodes and the target of the Write nodes.
  • Yaml Value (FEasyYamlValue): a single value taken out of a document. Use it when you need to inspect the node type before reading.

The nodes live under the category EasyYamlParser (Load, Create, Read, Write, Array, Save, Convert, Value, Utility).

Creating a Yaml Object

Load Yaml From String

Parses a YAML string into a Yaml Object.

Pin Kind Description
Yaml String input The YAML string to parse
Success output true when parsing succeeded
Error Message output The error details on failure. Includes the line and column
Error Code output The failure category (see Error codes)
Return Value output The created Yaml Object; an invalid object on failure

Load Yaml From File

Loads a YAML file into a Yaml Object.

Pin Kind Description
File Path input Path to the YAML file
Is Absolute input When off, File Path is resolved relative to the Content directory
Success output true when the file was read and parsed successfully
Error Message output Error details when the file is missing, unreadable, or fails to parse
Error Code output The failure category
Return Value output The created Yaml Object

Create Empty Yaml Object

Creates an empty Yaml Object. It is a valid object whose root is an empty map — the starting point for building new YAML with the Write nodes.

Reading values

The four nodes Read Int, Read Float, Read String, and Read Bool are pure functions (BlueprintPure) with identical inputs and outputs.

Pin Kind Description
Yaml Object input The Yaml Object to read from
Access String input The path to read (access strings)
Default Value input The value returned when the path is missing or the type differs
Return Value output The read value

When the value type differs from the node (for example, Read String on a number), the default value is returned. Read Int returns int64 (64-bit) and Read Float returns double precision.

Example input and output pins of the Read nodes

Read Object

Returns the map addressed by the access string as a new Yaml Object. The returned object is an independent copy, and you can read it with access strings relative to its root. When the addressed node is not a map, an invalid object is returned.

Read Objects

Returns the sequence of maps addressed by the access string as an array of Yaml Object. Combine it with a For Each Loop to process each element. Non-map elements are skipped.

Example input and output pins of the Read Object and Read Objects nodes

Read Value

Returns a snapshot of the node addressed by the access string as a Yaml Value. When the path is missing, an invalid value is returned. Read the value out with the Value nodes after inspecting its type.

Read Array Element / Read Array Values

  • Read Array Element returns the Index-th element of the sequence at the path as a Yaml Value. An invalid value is returned when the path is not a sequence or the index is out of range.
  • Read Array Values returns every element of the sequence at the path as an array of Yaml Value. An empty array is returned when the path is not a sequence.

Get Array Size / Is Array

  • Get Array Size returns the number of elements of the sequence at the path. It returns 0 when the path is not a sequence.
  • Is Array returns whether the node at the path is a sequence.

Has Path

Returns whether the addressed path exists. A path holding a null value also counts as existing.

Get Root Type

Returns the node type of the document root (Map, Sequence, and so on). Null is returned for an invalid Yaml Object.

Writing values

The six nodes Write Int, Write Float, Write String, Write Bool, Write Object, and Write Null all take the Yaml Object pin by reference (UPARAM(ref)). Executing the node updates the connected Yaml Object variable in place.

Pin Kind Description
Yaml Object input The Yaml Object to update (connect a variable)
Access String input The destination path
Value input The value to write. Write Object takes another Yaml Object

When an intermediate map in the access string (such as stats in player.stats) does not exist, the path is created automatically. Embedding another Yaml Object with Write Object assembles hierarchical YAML. Write Null writes an explicit null.

Example Blueprint assembling YAML with the Write nodes

For the fine print of writing (root replacement, the index limit), see Data Types and Production.

Appending to sequences

The five nodes Add Int To Array, Add Float To Array, Add String To Array, Add Bool To Array, and Add Object To Array append a value to the end of the sequence at the given path. The Yaml Object pin is passed by reference, like the Write nodes.

When the sequence does not exist at the path, it is created automatically. Existing elements are kept, and each execution appends one element to the end.

Example Blueprint appending values to a YAML sequence with the Add nodes

Saving and converting

Save Yaml To File

Saves the content of a Yaml Object to a file.

Pin Kind Description
Yaml Object input The Yaml Object to save
File Path input Destination path. Relative paths resolve against Content
Is Absolute input Whether to treat File Path as an absolute path
Success output true when saving succeeded
Error Message output Error details on failure
Error Code output The failure category

Missing output directories are created automatically.

Yaml To String

Converts the content of a Yaml Object to a YAML string. Because YAML expresses hierarchy with indentation, the output is always formatted with line breaks and indentation. An invalid Yaml Object yields an empty string.

Example configuration converting YAML to a string with Yaml To String

Operating on a Yaml Value

These nodes read values out of the Yaml Value obtained from Read Value, Read Array Element, and Read Array Values.

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

Read the value held by a Yaml Value as the given type. The Default Value pin specifies what to return when the type differs or the value is invalid.

  • Get Int Value returns int64 and Get Float Value returns double precision.
  • Get String Value reads string nodes only. Numbers and booleans are not converted implicitly.

Get Node Type

Returns the node type of a Yaml Value as EEasyYamlNodeType — one of Null, Bool, Int, Float, String, Sequence, Map — for comparison and branching.

Is Yaml Value Valid

Returns whether the Yaml Value is valid (whether the path existed). Use Get Node Type to distinguish a null value from a missing one.

Example configuration of the Value nodes

Utility

Is Yaml Object Valid

Returns whether a Yaml Object holds a valid YAML document. Use it to check the return value of Load Yaml From String on failure or an uninitialized variable.

Are Yaml Objects Equal

Compares two Yaml Object values for deep equality — types, values, and the map key order. Two invalid objects compare as equal.

Error codes

The Error Code pin of the Load and Save nodes is the EEasyYamlErrorCode enum. Combine it with the Success boolean for branching.

Value Meaning
None Success
InvalidYaml A YAML syntax error
FileNotFound The file was not found or could not be read
InvalidArgument An invalid argument (such as saving an invalid object)
StructConversionFailed A USTRUCT conversion failed (C++ API)
FileWriteFailed Writing the file failed

The Error Message carries a human-readable reason. YAML syntax errors include the position in the line X column Y form.

C++ examples

The same nodes are available from C++ as static functions of UEasyYamlBlueprintLibrary. In addition, FEasyYamlObject (Yaml Object) offers member functions and the USTRUCT conversion API that are C++-only.

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

// Loading and reading
bool bSuccess = false;
FString ErrorMessage;
EEasyYamlErrorCode ErrorCode;
FEasyYamlObject YamlObject = UEasyYamlBlueprintLibrary::LoadYamlFromString(YamlString, bSuccess, ErrorMessage, ErrorCode);

if (bSuccess)
{
    // Through the function library
    FString Name = UEasyYamlBlueprintLibrary::ReadString(YamlObject, TEXT("player.name"), TEXT("Unknown"));

    // Through the struct member functions (equivalent)
    int64 Level = YamlObject.ReadInt(TEXT("player.level"), 1);
}

// Creating and saving new 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 conversion (C++ only)

FEasyYamlObject provides functions to convert between a YAML document and a USTRUCT instance. They are not available from Blueprint.

// YAML -> USTRUCT (the root must be a map)
FMyConfig Config;
FEasyYamlResult Result;
if (YamlObject.TryReadStruct(Config, Result))
{
    // Every UPROPERTY of Config has been filled in
}

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

See Data Types and Production for the mapping rules and caveats.

Lifecycle and ownership summary

  • A Yaml Object is a struct value, but copies share the internal tree. Writes made through one copy are visible from every copy of the same Yaml Object.
  • The objects returned by Read Object / Read Objects are independent deep copies. Later writes to the source document never affect them.
  • A Yaml Value is a snapshot of a node. Later writes to the source document never change it.
  • The design is USTRUCT-based and never becomes a garbage collection target. No cleanup is required; values are destroyed automatically when they go out of scope.