Implement data.yaml module

README.md

@@ -1,8 +1,78 @@
-Ballerina YAML Data Library
-===================
+# Ballerina YAML Data Library
+
+[![Build](https://github.com/ballerina-platform/module-ballerina-data.yaml/actions/workflows/build-timestamped-master.yml/badge.svg)](https://github.com/ballerina-platform/module-ballerina-data.yaml/actions/workflows/build-timestamped-master.yml)
+[![codecov](https://codecov.io/gh/ballerina-platform/module-ballerina-data.yaml/branch/main/graph/badge.svg)](https://codecov.io/gh/ballerina-platform/module-ballerina-data.yaml)
+[![Trivy](https://github.com/ballerina-platform/module-ballerina-data.yaml/actions/workflows/trivy-scan.yml/badge.svg)](https://github.com/ballerina-platform/module-ballerina-data.yaml/actions/workflows/trivy-scan.yml)
+[![GraalVM Check](https://github.com/ballerina-platform/module-ballerina-data.yaml/actions/workflows/build-with-bal-test-graalvm.yml/badge.svg)](https://github.com/ballerina-platform/module-ballerina-data.yaml/actions/workflows/build-with-bal-test-graalvm.yml)
+[![GitHub Last Commit](https://img.shields.io/github/last-commit/ballerina-platform/module-ballerina-data.yaml.svg)](https://github.com/ballerina-platform/module-ballerina-data.yaml/commits/master)
+[![Github issues](https://img.shields.io/github/issues/ballerina-platform/ballerina-standard-library/module/data.yaml.svg?label=Open%20Issues)](https://github.com/ballerina-platform/ballerina-standard-library/labels/module%2Fdata.yaml)
+
+The Ballerina data.yaml library provides robust and flexible functionalities for working with YAML data within
+Ballerina applications.
+This library enables developers to seamlessly integrate YAML processing capabilities,
+ensuring smooth data interchange and configuration management.
+
+## Key Features
+
+- **Versatile Input Handling**: Convert YAML input provided as strings, byte arrays, or streams of byte arrays into
+  Ballerina's anydata sub-types, facilitating flexible data processing.
+- **Data Projection**: Efficiently project data from YAML documents and YAML streams,
+  allowing for precise data extraction and manipulation.
+- **Ordered Data Representation**: Employ tuples to preserve the order of elements when dealing with
+  YAML document streams of unknown order, ensuring the integrity of data sequences.
+- **Serialization**: Serialize Ballerina values into YAML-formatted strings, enabling easy generation of YAML content
+  from Ballerina applications for configuration files, data storage, or data exchange purposes.
+
+## Usage
+
+### Converting external YAML document to a record value
+
+For transforming YAML content from an external source into a record value,
+the `parseString`, `parseBytes`, `parseStream` functions can be used.
+This external source can be in the form of a string or a byte array/byte-block-stream that houses the YAML data.
+This is commonly extracted from files or network sockets. The example below demonstrates the conversion of an
+YAML value from an external source into a record value.
+
+```ballerina
+import ballerina/data.yaml;
+import ballerina/io;
+
+type Book record {|
+    string name;
+    string author;
+    int year;
+|};
+
+public function main() returns error? {
+    string yamlContent = check io:fileReadString("path/to/file.yaml");
+    Book book = check yaml:parseString(yamlContent);
+    io:println(book);
+}
+```
+
+Make sure to handle possible errors that may arise during the file reading or YAML to anydata conversion process.
+The `check` keyword is utilized to handle these errors,
+but more sophisticated error handling can be implemented as per your requirements.
+
+## Serialize anydata value to YAML
+
+The serialization of anydata value into YAML-formatted strings can be done in the below way.
+
+```ballerina
+import ballerina/data.yaml;
+import ballerina/io;
+
+public function main() returns error? {
+    json content = {
+        name: "Clean Code",
+        author: "Robert C. Martin",
+        year: 2008
+    };
+    string yamlString = check yaml:toYamlString(content);
+    io:println(yamlString);
+}
+```
 
-The Ballerina YAML Data Library is a comprehensive toolkit designed to facilitate the handling and manipulation of 
-YAML data within Ballerina applications.
 
 ## Issues and projects
 

ballerina/Ballerina.toml

@@ -6,13 +6,20 @@ authors = ["Ballerina"]
 keywords = ["yaml"]
 repository = "https://github.com/ballerina-platform/module-ballerina-data.yaml"
 license = ["Apache-2.0"]
-distribution = "2201.8.1"
+distribution = "2201.10.0"
 
 [platform.java17]
 graalvmCompatible = true
 
 [[platform.java17.dependency]]
-groupId = "io.ballerina.stdlib"
+groupId = "io.ballerina.lib"
 artifactId = "yaml-native"
 version = "0.1.0"
 path = "../native/build/libs/data.yaml-native-0.1.0-SNAPSHOT.jar"
+
+
+[[platform.java17.dependency]]
+groupId = "io.ballerina.stdlib"
+artifactId = "constraint-native"
+version = "1.5.0"
+path = "./lib/constraint-native-1.5.0.jar"

ballerina/CompilerPlugin.toml

@@ -0,0 +1,6 @@
+[plugin]
+id = "constraint-compiler-plugin"
+class = "io.ballerina.lib.data.yaml.compiler.YamlDataCompilerPlugin"
+
+[[dependency]]
+path = "../compiler-plugin/build/libs/data.yaml-compiler-plugin-0.1.0-SNAPSHOT.jar"

ballerina/Dependencies.toml

@@ -5,19 +5,48 @@
 
 [ballerina]
 dependencies-toml-version = "2"
-distribution-version = "2201.9.0"
+distribution-version = "2201.10.0-20240722-112100-1b113f29"
+
+[[package]]
+org = "ballerina"
+name = "constraint"
+version = "1.5.0"
+scope = "testOnly"
+dependencies = [
+	{org = "ballerina", name = "jballerina.java"}
+]
+modules = [
+	{org = "ballerina", packageName = "constraint", moduleName = "constraint"}
+]
 
 [[package]]
 org = "ballerina"
 name = "data.yaml"
 version = "0.1.0"
 dependencies = [
-	{org = "ballerina", name = "jballerina.java"}
+	{org = "ballerina", name = "constraint"},
+	{org = "ballerina", name = "io"},
+	{org = "ballerina", name = "jballerina.java"},
+	{org = "ballerina", name = "test"},
+	{org = "ballerina", name = "time"}
 ]
 modules = [
 	{org = "ballerina", packageName = "data.yaml", moduleName = "data.yaml"}
 ]
 
+[[package]]
+org = "ballerina"
+name = "io"
+version = "1.6.0"
+scope = "testOnly"
+dependencies = [
+	{org = "ballerina", name = "jballerina.java"},
+	{org = "ballerina", name = "lang.value"}
+]
+modules = [
+	{org = "ballerina", packageName = "io", moduleName = "io"}
+]
+
 [[package]]
 org = "ballerina"
 name = "jballerina.java"
@@ -26,3 +55,73 @@ modules = [
 	{org = "ballerina", packageName = "jballerina.java", moduleName = "jballerina.java"}
 ]
 
+[[package]]
+org = "ballerina"
+name = "lang.__internal"
+version = "0.0.0"
+scope = "testOnly"
+dependencies = [
+	{org = "ballerina", name = "jballerina.java"},
+	{org = "ballerina", name = "lang.object"}
+]
+
+[[package]]
+org = "ballerina"
+name = "lang.array"
+version = "0.0.0"
+scope = "testOnly"
+dependencies = [
+	{org = "ballerina", name = "jballerina.java"},
+	{org = "ballerina", name = "lang.__internal"}
+]
+
+[[package]]
+org = "ballerina"
+name = "lang.error"
+version = "0.0.0"
+scope = "testOnly"
+dependencies = [
+	{org = "ballerina", name = "jballerina.java"}
+]
+
+[[package]]
+org = "ballerina"
+name = "lang.object"
+version = "0.0.0"
+scope = "testOnly"
+
+[[package]]
+org = "ballerina"
+name = "lang.value"
+version = "0.0.0"
+scope = "testOnly"
+dependencies = [
+	{org = "ballerina", name = "jballerina.java"}
+]
+
+[[package]]
+org = "ballerina"
+name = "test"
+version = "0.0.0"
+scope = "testOnly"
+dependencies = [
+	{org = "ballerina", name = "jballerina.java"},
+	{org = "ballerina", name = "lang.array"},
+	{org = "ballerina", name = "lang.error"}
+]
+modules = [
+	{org = "ballerina", packageName = "test", moduleName = "test"}
+]
+
+[[package]]
+org = "ballerina"
+name = "time"
+version = "2.4.0"
+scope = "testOnly"
+dependencies = [
+	{org = "ballerina", name = "jballerina.java"}
+]
+modules = [
+	{org = "ballerina", packageName = "time", moduleName = "time"}
+]
+

ballerina/Module.md

@@ -0,0 +1,67 @@
+# Ballerina YAML Data Library
+
+The Ballerina data.yaml library provides robust and flexible functionalities for working with YAML data within
+Ballerina applications.
+This library enables developers to seamlessly integrate YAML processing capabilities,
+ensuring smooth data interchange and configuration management.
+
+## Key Features
+
+- **Versatile Input Handling**: Convert YAML input provided as strings, byte arrays, or streams of byte arrays into
+  Ballerina's anydata sub-types, facilitating flexible data processing.
+- **Data Projection**: Efficiently project data from YAML documents and YAML streams,
+  allowing for precise data extraction and manipulation.
+- **Ordered Data Representation**: Employ tuples to preserve the order of elements when dealing with
+  YAML document streams of unknown order, ensuring the integrity of data sequences.
+- **Serialization**: Serialize Ballerina values into YAML-formatted strings, enabling easy generation of YAML content
+  from Ballerina applications for configuration files, data storage, or data exchange purposes.
+
+## Usage
+
+### Converting external YAML document to a record value
+
+For transforming YAML content from an external source into a record value,
+the `parseString`, `parseBytes`, `parseStream` functions can be used.
+This external source can be in the form of a string or a byte array/byte-block-stream that houses the YAML data.
+This is commonly extracted from files or network sockets. The example below demonstrates the conversion of an
+YAML value from an external source into a record value.
+
+```ballerina
+import ballerina/data.yaml;
+import ballerina/io;
+
+type Book record {|
+    string name;
+    string author;
+    int year;
+|};
+
+public function main() returns error? {
+    string yamlContent = check io:fileReadString("path/to/<file-name>.yaml");
+    Book book = check yaml:parseString(yamlContent);
+    io:println(book);
+}
+```
+
+Make sure to handle possible errors that may arise during the file reading or YAML to anydata conversion process.
+The `check` keyword is utilized to handle these errors,
+but more sophisticated error handling can be implemented as per your requirements.
+
+## Serialize anydata value to YAML
+
+The serialization of anydata value into YAML-formatted strings can be done in the below way.
+
+```ballerina
+import ballerina/data.yaml;
+import ballerina/io;
+
+public function main() returns error? {
+    json content = {
+        name: "Clean Code",
+        author: "Robert C. Martin",
+        year: 2008
+    };
+    string yamlString = check yaml:toYamlString(content);
+    io:println(yamlString);
+}
+```

ballerina/Package.md

@@ -1,5 +1,67 @@
-# module-ballerina-data.yaml
-The Ballerina YAML Data Library is a comprehensive toolkit designed to facilitate the handling and manipulation of 
-YAML data within Ballerina applications. 
-It streamlines the process of converting YAML data to native Ballerina data types, 
-enabling developers to work with YAML content seamlessly and efficiently.
+# Ballerina YAML Data Library
+
+The Ballerina data.yaml library provides robust and flexible functionalities for working with YAML data within 
+Ballerina applications. 
+This library enables developers to seamlessly integrate YAML processing capabilities, 
+ensuring smooth data interchange and configuration management.
+
+## Key Features
+
+- **Versatile Input Handling**: Convert YAML input provided as strings, byte arrays, or streams of byte arrays into 
+ Ballerina's anydata sub-types, facilitating flexible data processing.
+- **Data Projection**: Efficiently project data from YAML documents and YAML streams, 
+ allowing for precise data extraction and manipulation.
+- **Ordered Data Representation**: Employ tuples to preserve the order of elements when dealing with 
+ YAML document streams of unknown order, ensuring the integrity of data sequences.
+- **Serialization**: Serialize Ballerina values into YAML-formatted strings, enabling easy generation of YAML content 
+ from Ballerina applications for configuration files, data storage, or data exchange purposes.
+
+## Usage
+
+### Converting external YAML document to a record value
+
+For transforming YAML content from an external source into a record value, 
+the `parseString`, `parseBytes`, `parseStream` functions can be used. 
+This external source can be in the form of a string or a byte array/byte-block-stream that houses the YAML data.
+This is commonly extracted from files or network sockets. The example below demonstrates the conversion of an 
+YAML value from an external source into a record value.
+
+```ballerina
+import ballerina/data.yaml;
+import ballerina/io;
+
+type Book record {|
+    string name;
+    string author;
+    int year;
+|};
+
+public function main() returns error? {
+    string yamlContent = check io:fileReadString("path/to/<file-name>.yaml");
+    Book book = check yaml:parseString(yamlContent);
+    io:println(book);
+}
+```
+
+Make sure to handle possible errors that may arise during the file reading or YAML to anydata conversion process. 
+The `check` keyword is utilized to handle these errors, 
+but more sophisticated error handling can be implemented as per your requirements.
+
+## Serialize anydata value to YAML
+
+The serialization of anydata value into YAML-formatted strings can be done in the below way.
+
+```ballerina
+import ballerina/data.yaml;
+import ballerina/io;
+
+public function main() returns error? {
+    json content = {
+        name: "Clean Code",
+        author: "Robert C. Martin",
+        year: 2008
+    };
+    string yamlString = check yaml:toYamlString(content);
+    io:println(yamlString);
+}
+```