We’re thrilled to introduce the bx-yaml module for BoxLang!

This powerful new module brings seamless YAML parsing and emitting capabilities to BoxLang. You can now effortlessly serialize BoxLang native types—including structs, queries, arrays, classes, and more—into YAML. The same simplicity applies to deserialization, making it easy to work with YAML data in your BoxLang applications.

Key Features

• Serialize to YAML from native BoxLang types
• Custom serialization of BoxLang classes
• Serialize stream directly to a file
• Deserialize YAML to native BoxLang Types
• Deserialize a YAML stream from a file to BoxLang Types

Reporting Issues

If you encounter any issues or have feature requests, please report them to:

• Module Issues Repository : https://github.com/ortus-boxlang/bx-yaml

Please send us your feedback and testing!

Quick Usage

This module registers the following BIFS:

• yamlSerialize( content, [filepath], [charset=utf8] ):yaml : Serialize a BoxLang variable into a YAML string. You can also serialize to a file if you provide a file path.
• yamlDeserialize( content ):any : Deserialize a YAML string into a BoxLang variable.
• yamlDeserializeFile( filepath, [charset=utf8] ):any : Deserialize a YAML file into a BoxLang variable.

Here is a simple example:

// Serialize a BoxLang structure into a YAML string
yaml = yamlSerialize( { name="Luis", age=21, city="Orlando" } );
// Serialize a more complex structure
yaml = yamlSerialize( { name="Luis", age=21, city="Orlando", address={ street="1234", city="Orlando", state="FL" } } );

// Deserialize a YAML string into a BoxLang structure
data = yamlDeserialize( yaml );

// Deserialize a YAML file into a BoxLang structure
data = yamlDeserializeFile( "data.yml" );

BoxLang Class Serialization

BoxLang classes will be serialized as a structure according to its properties. However it must adhere to the following rules:

• The class must have a serializable = true annotation. or none at all, that is the default.
• The property must have a serializable = true annotation or none at all, that is the default.
• The property must NOT exist in the yamlExclude list in the class or the parent class.
• The property must NOT have a yamlExclude annotation.

BoxLang Class Custom Serialization

If you are serializing BoxLang classes, you can implement the toYAML() method in your classes to provide a custom serialization. Here is an example:

class {

	function init( required name="", required age=0, required city="" ){
		variables.name = arguments.name;
		variables.age = arguments.age;
		variables.city = arguments.city;
		return this;
	}

	function toYAML(){
		return { name=variables.name, city=variables.city } );
	}

}