# Yaml

### Welcome to the BoxLang YAML Module

This module provides a YAML parser and emitter for BoxLang. It is based on the [SnakeYAML](https://bitbucket.org/asomov/snakeyaml) library and provides a simple way to parse and emit YAML content in BoxLang.

```
# For Operating Systems using our Quick Installer.
install-bx-module bx-yaml

# Using CommandBox to install for web servers.
box install boxlang-yaml
```

### 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:

```java
// 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:

```java
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 } );
	}

}
```

### GitHub Repository and Reporting Issues <a href="#github-repository-and-reporting-issues" id="github-repository-and-reporting-issues"></a>

Visit the [GitHub repository](https://github.com/ortus-boxlang/bx-yaml) for release notes. You can also file a bug report or improvement suggestion via [Jira](https://ortussolutions.atlassian.net/secure/CreateIssueDetails!init.jspa?pid=13359\&components=27031\&issuetype=1).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://boxlang.ortusbooks.com/boxlang-framework/modularity/yaml.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.