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"}