Merge pull request #5531 from LakshanWeerasinghe/data.yaml-bbes

Add BBEs related to the data.yaml module

examples/anydata-to-yaml-string/anydata_to_yaml_string.bal

@@ -0,0 +1,29 @@
+import ballerina/data.yaml;
+import ballerina/io;
+
+type ServerConfig record {|
+    string host;
+    int port;
+    DatabaseConfig database;
+|};
+
+type DatabaseConfig record {|
+    string dbName;
+    string username;
+|};
+
+public function main() returns error? {
+
+    ServerConfig serverConfig = {
+        database: {
+            dbName: "userDB",
+            username: "testUser"
+        },
+        port: 3000,
+        host: "localhost"
+    };
+
+    // Serialize a Ballerina value to a string in YAML format.
+    string serverConfigYamlStr = check yaml:toYamlString(serverConfig);
+    io:println(serverConfigYamlStr);
+}

examples/anydata-to-yaml-string/anydata_to_yaml_string.md

@@ -0,0 +1,9 @@
+# Serialize a Ballerina value to a string in YAML format
+
+The `data.yaml` library provides the `toYamlString` function to serialize a value belonging to `anydata` to a string in YAML format.
+
+For more information on the underlying module, see the [`data.yaml` module](https://lib.ballerina.io/ballerina/data.yaml/latest/).
+
+::: code anydata_to_yaml_string.bal :::
+
+::: out anydata_to_yaml_string.out :::

examples/anydata-to-yaml-string/anydata_to_yaml_string.metatags

@@ -0,0 +1,2 @@
+description: This BBE demonstrates how to serialize a value belonging to `anydata` to a string in YAML format.
+keywords: ballerina, ballerina by example, BBE, yaml, yaml to string, record to yaml

examples/anydata-to-yaml-string/anydata_to_yaml_string.out

@@ -0,0 +1,6 @@
+$ bal run anydata_to_yaml_string.bal
+host: localhost
+port: 3000
+database:
+  dbName: userDB
+  username: testUser

examples/index.json

@@ -4458,6 +4458,21 @@
       }
     ]
   },
+  {
+    "title": "OS",
+    "column": 1,
+    "category": "Common libraries",
+    "samples": [
+      {
+        "name": "Environment variables",
+        "url": "environment-variables",
+        "verifyBuild": true,
+        "verifyOutput": false,
+        "disableVerificationReason": "Includes varying output",
+        "isLearnByExample": false
+      }
+    ]
+  },
   {
     "title": "File",
     "column": 2,
@@ -4551,7 +4566,7 @@
   },
   {
     "title": "UUID",
-    "column": 3,
+    "column": 2,
     "category": "Common libraries",
     "samples": [
       {
@@ -4585,21 +4600,6 @@
       }
     ]
   },
-  {
-    "title": "OS",
-    "column": 3,
-    "category": "Common libraries",
-    "samples": [
-      {
-        "name": "Environment variables",
-        "url": "environment-variables",
-        "verifyBuild": true,
-        "verifyOutput": false,
-        "disableVerificationReason": "Includes varying output",
-        "isLearnByExample": false
-      }
-    ]
-  },
   {
     "title": "XML data",
     "column": 3,
@@ -4635,6 +4635,34 @@
       }
     ]
   },
+  {
+    "title": "YAML data",
+    "column": 3,
+    "category": "Common libraries",
+    "samples": [
+      {
+        "name": "YAML to anydata",
+        "url": "yaml-to-anydata",
+        "verifyBuild": true,
+        "verifyOutput": true,
+        "isLearnByExample": true
+      },
+      {
+        "name": "YAML to anydata with projection",
+        "url": "yaml-to-anydata-with-projection",
+        "verifyBuild": true,
+        "verifyOutput": true,
+        "isLearnByExample": true
+      },
+      {
+        "name": "Serialize to YAML string",
+        "url": "anydata-to-yaml-string",
+        "verifyBuild": true,
+        "verifyOutput": true,
+        "isLearnByExample": true
+      }
+    ]
+  },
   {
     "title": "Constraint",
     "column": 3,

examples/xml-from-record-conversion/xml_from_record_conversion.bal

@@ -18,7 +18,6 @@ type Invoice record {
 @xmldata:Namespace {
     uri: "http://example1.com"
 }
-
 type Item record {
     string itemCode;
     int count;

examples/yaml-to-anydata-with-projection/yaml_to_anydata_with_projection.bal

@@ -0,0 +1,33 @@
+import ballerina/data.yaml;
+import ballerina/io;
+
+type ServerConfig record {|
+    string host;
+    int port;
+    int[2] remotePorts;
+    DatabaseConfig database;
+|};
+
+type DatabaseConfig record {|
+    string dbName;
+    string username;
+|};
+
+public function main() returns error? {
+    // Similar to content read from a YAML file.
+    string yamlString = string `
+        host: "localhost"
+        port: 8080
+        remotePorts: [9000, 9001, 9002, 9003]
+        protocol: "http"
+        database:
+          dbName: "testdb"
+          username: "dbuser"
+          password: "dbpassword"`;
+
+    // Based on the expected type, this function selectively constructs the record from the YAML string.
+    ServerConfig serverConfig = check yaml:parseString(yamlString);
+    // The `password` field is excluded in the created record value.
+    // Only the first two elements from the source are used to create the `remotePorts` array.
+    io:println(serverConfig);
+}

examples/yaml-to-anydata-with-projection/yaml_to_anydata_with_projection.md

@@ -0,0 +1,11 @@
+# YAML to anydata conversion with projection
+
+The `data.yaml` library provides multiple APIs to selectively parse elements and attributes from a YAML source, in the form of a string, byte array, or byte block stream, into a Ballerina record. Using projection, users can selectively add fields to records and limit the sizes of arrays.
+
+In this example, the `password` attribute is excluded when creating the `DatabaseConfig` record, and only the first two elements from the source are used to create the `remotePorts` array.
+
+For more information on the underlying module, see the [`data.yaml` module](https://lib.ballerina.io/ballerina/data.yaml/latest/).
+
+::: code yaml_to_anydata_with_projection.bal :::
+
+::: out yaml_to_anydata_with_projection.out :::

examples/yaml-to-anydata-with-projection/yaml_to_anydata_with_projection.metatags

@@ -0,0 +1,2 @@
+description: This BBE demonstrates how to selectively convert fields from a YAML source, which can be provided as a string, byte array, or byte block stream, into a Ballerina record with projection.
+keywords: ballerina, ballerina by example, BBE, yaml, record, data projection 

examples/yaml-to-anydata-with-projection/yaml_to_anydata_with_projection.out

@@ -0,0 +1,2 @@
+$ bal run yaml_to_anydata_with_projection.bal
+{"host":"localhost","port":8080,"remotePorts":[9000,9001],"database":{"dbName":"testdb","username":"dbuser"}}

examples/yaml-to-anydata/yaml_to_anydata.bal

@@ -0,0 +1,52 @@
+import ballerina/data.yaml;
+import ballerina/io;
+
+type ServerConfig record {|
+    string host;
+    int port;
+    string protocol;
+|};
+
+final string yamlString = string
+        `
+        host: "localhost"
+        port: 8080
+        protocol: "http"`;
+
+public function main() returns error? {
+    // Parse the YAML string as a record.
+    ServerConfig serverConfig1 = check yaml:parseString(yamlString);
+    io:println(serverConfig1);
+
+    byte[] yamlByteArr = yamlString.toBytes();
+    // Parse the YAML byte array as a record.
+    ServerConfig serverConfig2 = check yaml:parseBytes(yamlByteArr);
+    io:println(serverConfig2);
+
+    stream<byte[], error?> byteBlockStream = new (new ByteBlockGenerator(yamlString));
+    // Parse the YAML byte block stream as a record.
+    ServerConfig serverConfig3 = check yaml:parseStream(byteBlockStream);
+    io:println(serverConfig3);
+}
+
+// Defines a class called `ByteBlockGenerator`, which is stream implementor with a `next()` method.
+// This `next()` method is called when iterating over a stream created with a `ByteBlockGenerator` value.
+class ByteBlockGenerator {
+    private int index = 0;
+    private final byte[] byteArr;
+    private final int arraySize;
+
+    public function init(string data) {
+        self.byteArr = data.toBytes();
+        self.arraySize = self.byteArr.length();
+    }
+
+    public isolated function next() returns record {|byte[] value;|}|error? {
+        if self.index >= self.arraySize {
+            return;
+        }
+        int startIndex = self.index;
+        self.index = startIndex + 4 > self.arraySize ? self.arraySize : startIndex + 3;
+        return {value: self.byteArr.slice(startIndex, self.index)};
+    }
+}

examples/yaml-to-anydata/yaml_to_anydata.md

@@ -0,0 +1,9 @@
+# YAML to anydata conversion
+
+The `data.yaml` library provides multiple functions to parse YAML source, in the form of a string, byte array, or byte block stream, as a value that belongs to a subtype of `anydata`.
+
+For more information on the underlying module, see the [`data.yaml` module](https://lib.ballerina.io/ballerina/data.yaml/latest/).
+
+::: code yaml_to_anydata.bal :::
+
+::: out yaml_to_anydata.out :::

examples/yaml-to-anydata/yaml_to_anydata.metatags

@@ -0,0 +1,2 @@
+description: This BBE demonstrates how to parse a YAML source, which can be provided as a string, byte array, or byte block stream, as a value that belongs to a subtype of anydata.
+keywords: ballerina, ballerina by example, BBE, yaml, record, stream, byte array

examples/yaml-to-anydata/yaml_to_anydata.out

@@ -0,0 +1,4 @@
+$ bal run yaml_to_anydata.bal
+{"host":"localhost","port":8080,"protocol":"http"}
+{"host":"localhost","port":8080,"protocol":"http"}
+{"host":"localhost","port":8080,"protocol":"http"}