Expand ObjectScript's ability to process YAML

The ObjectScript language has incredible JSON support through classes like %DynamicObject and %JSON.Adaptor. This support is due to the JSON format's immense popularity over the previous dominance of XML. JSON brought less verbosity to data representation and increased readability for humans who needed to interpret JSON content. To further reduce verbosity and increase readability, the YAML format was created. The very easy-to-read YAML format quickly became the most popular format for representing configurations and parameterizations, due to its readability and minimal verbosity. While XML is rarely used for parameterization and configuration, with YAML, JSON is gradually becoming limited to being a data exchange format rather than for configurations, parameterizations, and metadata representations. Now, all of this is done with YAML. Therefore, the primary language of InterSystems technologies needs broad support for YAML processing, at the same level as it does for JSON and XML. For this reason, I've released a new package to make ObjectScript a powerful YAML processor. The package name is yaml-adaptor.

Let's start by installing the package

1. If you using IPM, open the IRIS Terminal and call:

USER>zpm “install yaml-adaptor”

2. If you using Docker, Clone/git pull the yaml-adaptor repo into any local directory:

$ git clone https://github.com/yurimarx/yaml-adaptor.git

3. Open the terminal in this directory and run:

$ docker-compose build

4. Run the IRIS container with your project:

$ docker-compose up -d

Why use this package?

With this package, you'll be able to easily interoperate, read, write, and transform YAML to DynamicObjects, JSON, and XML bidirectionally. This package allows you to read and generate data, configurations, and parameterizations in the most popular market formats dynamically, with little code, high performance, and in real time.

The package in action!

It is very simple use this package. The features are:

1. Convert from YAML string to JSON string

ClassMethod TestYamlToJson() As %Status
{
    Set sc = $$$OK
    
    set yamlContent = ""_$CHAR(10)_
        "user:"_$CHAR(10)_
        "    name: 'Jane Doe'"_$CHAR(10)_
        "    age: 30"_$CHAR(10)_
        "    roles:"_$CHAR(10)_
        "    - 'admin'"_$CHAR(10)_
        "    - 'editor'"_$CHAR(10)_
        "database:"_$CHAR(10)_
        "    host: 'localhost'"_$CHAR(10)_
        "    port: 5432"_$CHAR(10)_
        ""

    Do ##class(dc.yamladapter.YamlUtil).yamlToJson(yamlContent, .jsonContent)
    Set jsonObj = {}.%FromJSON(jsonContent)
    Write jsonObj.%ToJSON()

    Return sc
}

2. Generate YAML file from a JSON file

ClassMethod TestYamlFileToJsonFile() As %Status
{

    Set sc = $$$OK

    Set yamlFile = "/tmp/samples/sample.yaml"
    Set jsonFile = "/tmp/samples/sample_result.json"

    Write ##class(dc.yamladapter.YamlUtil).yamlFileToJsonFile(yamlFile,jsonFile)
    

    Return sc
}

3. Convert from JSON string to YAML string

ClassMethod TestJsonToYaml() As %Status
{
    Set sc = $$$OK
    
    set jsonContent = "{""user"":{""name"":""Jane Doe"",""age"":30,""roles"":[""admin"",""editor""]},""database"":{""host"":""localhost"",""port"":5432}}"

    Do ##class(dc.yamladapter.YamlUtil).jsonToYaml(jsonContent, .yamlContent)
    Write yamlContent

    Return sc
}

4. Generate JSON file from YAML file

ClassMethod TestJsonFileToYamlFile() As %Status
{

    Set sc = $$$OK

    Set jsonFile = "/tmp/samples/sample.json"
    Set yamlFile = "/tmp/samples/sample_result.yaml"

    Write ##class(dc.yamladapter.YamlUtil).jsonFileToYamlFile(jsonFile, yamlFile)
    

    Return sc
}

5. Load a dynamic object from YAML string or YAML files

ClassMethod TestYamlFileToDynamicObject() As %Status
{
    Set sc = $$$OK

    Set yamlFile = "/tmp/samples/sample.yaml"
    
    Set dynamicYaml = ##class(YamlAdaptor).CreateFromFile(yamlFile)

    Write "Title: "_dynamicYaml.title, !
    Write "Version: "_dynamicYaml.version, !

    Return sc
}

Generate YAML from Dynamic Objects

ClassMethod TestDynamicObjectToYaml() As %Status
{
    Set sc = $$$OK

    Set dynaObj = {}
    Set dynaObj.project = "Project A"
    Set dynaObj.version = "1.0"
    
    Set yamlContent = ##class(YamlAdaptor).CreateYamlFromDynamicObject(dynaObj)

    Write yamlContent

    Return sc
}

Generate XML file from YAML file

ClassMethod TestXmlFileToYamlFile() As %Status
{

    Set sc = $$$OK

    Set xmlFile = "/tmp/samples/sample.xml"
    Set yamlFile = "/tmp/samples/sample_xml_result.yaml"

    Write ##class(dc.yamladapter.YamlUtil).xmlFileToYamlFile(xmlFile, yamlFile)
    

    Return sc
}

Generate YAML file from XML File

ClassMethod TestYamlFileToXmlFile() As %Status
{

    Set sc = $$$OK

    Set yamlFile = "/tmp/samples/sample.yaml"
    Set xmlFile = "/tmp/samples/sample_result.xml"

    Write ##class(dc.yamladapter.YamlUtil).yamlFileToXmlFile(yamlFile, "sample", xmlFile)
    

    Return sc
}