Merge pull request #28 from SasinduDilshara/refactor-gradle-files

Add examples for api documentation

ballerina/csv_api.bal

@@ -17,6 +17,15 @@
 import ballerina/jballerina.java;
 
 # Converts CSV string to subtype of `record{}[]` or `anydata[][]`.
+# ```ballerina
+# string csvString = string `id,name
+#                            1,John
+#                            3,Jane`;
+# record{int id; string name;}[] csv1 = check csv:parseString(csvString);
+# [int, string][] csv2 = check csv:parseString(csvString);
+# record{|int id;|}[] csv3 = check csv:parseString(csvString);
+# record{int id;}[] csv4 = check csv:parseString(csvString, {skipLines: [1]});
+# ```
 #
 # + csvString - Source CSV string value
 # + options - Options to be used for filtering in the projection
@@ -26,6 +35,13 @@ public isolated function parseString(string csvString, ParseOptions options = {}
      returns t|Error = @java:Method {'class: "io.ballerina.lib.data.csvdata.csv.Native"} external;
 
 # Converts byte[] to subtype of `record{}[]` or `anydata[][]`.
+# ```ballerina
+# byte[] csvBytes = check io:fileReadBytes("example.csv");
+# record{int id; string name;}[] csv1 = check csv:parseBytes(csvBytes);
+# [int, string][] csv2 = check csv:parseBytes(csvBytes);
+# record{|int id;|}[] csv3 = check csv:parseBytes(csvBytes);
+# record{int id;}[] csv4 = check csv:parseBytes(csvBytes, {skipLines: [1]});
+# ```
 #
 # + csvBytes - Source CSV byte array
 # + options - Options to be used for filtering in the projection
@@ -35,7 +51,17 @@ public isolated function parseBytes(byte[] csvBytes, ParseOptions options = {},
      returns t|Error = @java:Method {'class: "io.ballerina.lib.data.csvdata.csv.Native"} external;
 
 # Converts CSV byte-block-stream to subtype of `record{}[]` or `anydata[][]`.
-#
+# ```ballerina
+# stream<byte[], io:Error?> csvByteStream = check io:fileReadBlocksAsStream("example.csv");
+# record{int id; string name;}[] csv1 = check csv:parseStream(csvByteStream);
+# stream<byte[], io:Error?> csvByteStream2 = check io:fileReadBlocksAsStream("example.csv");
+# [int, string][] csv2 = check csv:parseStream(csvByteStream2);
+# stream<byte[], io:Error?> csvByteStream3 = check io:fileReadBlocksAsStream("example.csv");
+# record{|int id;|}[] csv3 = check csv:parseStream(csvByteStream3);
+# stream<byte[], io:Error?> csvByteStream4 = check io:fileReadBlocksAsStream("example.csv");
+# record{int id;}[] csv4 = check csv:parseStream(csvByteStream4, {skipLines: [1]});
+# ```
+# 
 # + csvByteStream - Source CSV byte-block-stream
 # + options - Options to be used for filtering in the projection
 # + t - Target type
@@ -45,6 +71,12 @@ public isolated function parseStream(stream<byte[], error?> csvByteStream,
      returns t|Error = @java:Method {'class: "io.ballerina.lib.data.csvdata.csv.Native"} external;
 
 # Convert value of type record{}[] to subtype of `record{}[]` or `anydata[][]`.
+# ```ballerina
+# record{int id; string name;}[] csvRecords = [{id: 1, name: "John"}, {id: 2, name: "Jane"}];
+# [int, string][] csv1 = check csv:transform(csvRecords);
+# record{|int id;|}[] csv2 = check csv:transform(csvRecords);
+# record{int id;}[] csv3 = check csv:transform(csvRecords, {skipLines: [1]});
+# ```
 #
 # + csvRecords - Source Ballerina record array value
 # + options - Options to be used for filtering in the projection
@@ -55,7 +87,13 @@ public isolated function transform(record{}[] csvRecords,
      returns t|Error = @java:Method {'class: "io.ballerina.lib.data.csvdata.csv.Native"} external;
 
 # Convert value of type string array of array to subtype of `record{}[]` or `anydata[][]`.
-#
+# ```ballerina
+# string[][] csvList = [["1", "John"], ["2", "Jane"]];
+# [int, string][] csv1 = check csv:parseList(csvList);
+# record{|int id;|}[] csv2 = check csv:parseList(csvList, {customHeaders: ["id", "name"]});
+# record{int id;}[] csv3 = check csv:parseList(csvList, {skipLines: [1], customHeaders: ["id", "name"]});
+# ```
+# 
 # + csvList - Source Ballerina string array of array value
 # + options - Options to be used for filtering in the projection
 # + t - Target type

compiler-plugin-test/src/test/java/io/ballerina/lib/data/csvdata/compiler/CompilerPluginTest.java

@@ -43,12 +43,12 @@ public class CompilerPluginTest {
             "are supported for fields, and other types are not allowed.";
     static final String UNSUPPORTED_TUPLE_MEMBER_TYPE = "Unsupported type in the tuple member: " +
             "Tuple members can only be basic types, other types are not supported.";
-    static final String IGNORE_OUTPUT_HEADERS_FOR_RECORD_ARRAY = "The option 'outputWithHeaders' will be ignored" +
+    static final String IGNORE_OUTPUT_HEADERS_FOR_RECORD_ARRAY = "The option 'outputWithHeaders' will be not allowed" +
             " since the expected type is a subtype record array.";
-    static final String IGNORE_HEADERS_ORDER_FOR_RECORD_ARRAY = "The option 'headersOrder' will be ignored" +
+    static final String IGNORE_HEADERS_ORDER_FOR_RECORD_ARRAY = "The option 'headersOrder' will be not allowed" +
             " since the expected type is a subtype record array.";
     static final String IGNORE_CUSTOM_HEADERS_PARAMETER_WHEN_HEADER_PRESENT = "The option " +
-            "'customHeadersIfHeadersAbsent' will be ignored since the header is present.";
+            "'customHeadersIfHeadersAbsent' will be not allowed since the header is present.";
     static final String CUSTOM_HEADERS_SHOULD_BE_PROVIDED = "customHeaders parameter should be provided since the" +
             " headerRows larger than 1.";
 

compiler-plugin/src/main/java/io/ballerina/lib/data/csvdata/compiler/CsvDataDiagnosticCodes.java

@@ -34,12 +34,13 @@ public enum CsvDataDiagnosticCodes {
                               "and other types are not allowed.", ERROR),
     UNSUPPORTED_TUPLE_MEMBER_TYPE("CSV_ERROR_4", "Unsupported type in the tuple member: Tuple members can only " +
                                           "be basic types, other types are not supported.", ERROR),
-    IGNORE_OUTPUT_HEADERS_FOR_RECORD_ARRAY("CSV_ERROR_5", "The option 'outputWithHeaders' will be ignored since the " +
-                                "expected type is a subtype record array.", ERROR),
-    IGNORE_HEADERS_ORDER_FOR_RECORD_ARRAY("CSV_ERROR_5", "The option 'headersOrder' will be ignored " +
-            "since the expected type is a subtype record array.", ERROR),
+    IGNORE_OUTPUT_HEADERS_FOR_RECORD_ARRAY("CSV_ERROR_5", "The option 'outputWithHeaders' will " +
+            "be not allowed since the expected type is a subtype record array.", ERROR),
+    IGNORE_HEADERS_ORDER_FOR_RECORD_ARRAY("CSV_ERROR_5", "The option 'headersOrder' will " +
+            "be not allowed since the expected type is a subtype record array.", ERROR),
     IGNORE_CUSTOM_HEADERS_PARAMETER_WHEN_HEADER_PRESENT("CSV_ERROR_6",
-            "The option 'customHeadersIfHeadersAbsent' will be ignored since the header is present.", ERROR),
+            "The option 'customHeadersIfHeadersAbsent' will be not " +
+                    "allowed since the header is present.", ERROR),
     CUSTOM_HEADERS_SHOULD_BE_PROVIDED("CSV_ERROR_7",
             "customHeaders parameter should be provided since the headerRows larger than 1.", ERROR);
 

native/src/main/java/io/ballerina/lib/data/csvdata/csv/CsvTraversal.java

@@ -253,8 +253,8 @@ private void traverseCsvWithExpectedType(int sourceArraySize,
                             expectedArrayElementType, isIntersection);
                     break;
                 case TypeTags.UNION_TAG:
-                    traverseCsvWithUnionExpectedType(sourceArraySize, csv,
-                            (UnionType) expectedArrayElementType, type, isIntersection);
+                    traverseCsvWithUnionExpectedType(csv,
+                            (UnionType) expectedArrayElementType, type);
                     break;
                 default:
                     throw DiagnosticLog.error(DiagnosticErrorCode.SOURCE_CANNOT_CONVERT_INTO_EXP_TYPE, type);
@@ -336,16 +336,14 @@ public void traverseCsvWithListAsExpectedType(long length, BArray csv, Type expe
             }
         }
 
-        public void traverseCsvWithUnionExpectedType(long length, BArray csv,
-                                                     UnionType expectedArrayType, Type type, boolean isIntersection) {
+        public void traverseCsvWithUnionExpectedType(BArray csv,
+                                                     UnionType expectedArrayType, Type type) {
 
             for (Type memberType: expectedArrayType.getMemberTypes()) {
                 try {
                     memberType = TypeCreator.createArrayType(TypeUtils.getReferredType(memberType));
-                    if (CsvUtils.isExpectedTypeIsMap(memberType) || CsvUtils.isExpectedTypeIsArray(memberType)) {
-                        traverseCsv(csv, config, memberType);
-                        return;
-                    }
+                    traverseCsv(csv, config, memberType);
+                    return;
                 } catch (Exception ex) {
                     resetForUnionTypes();
                 }

native/src/main/java/io/ballerina/lib/data/csvdata/utils/Constants.java

@@ -9,7 +9,7 @@
  * @since 0.1.0
  */
 public final class Constants {
-    public final class ConfigConstants {
+    public static final class ConfigConstants {
         public static final BString DELIMITER = StringUtils.fromString("delimiter");
         public static final BString TEXT_ENCLOSURE = StringUtils.fromString("textEnclosure");
         public static final BString HEADER = StringUtils.fromString("header");
@@ -37,15 +37,15 @@ private ConfigConstants() {
         }
     }
 
-    public final class Values {
+    public static final class Values {
         public static final String NULL = "null";
         public static final String BALLERINA_NULL = "()";
 
         private Values() {
         }
     }
 
-    public final class LineTerminator {
+    public static final class LineTerminator {
         public static final char LF = '\n';
         public static final char CR = '\r';
         public static final String CRLF = "\r\n";
@@ -54,7 +54,7 @@ private LineTerminator() {
         }
     }
 
-    public final class EscapeChar {
+    public static final class EscapeChar {
         public static final char DOUBLE_QUOTES_CHAR = '"';
         public static final char BACKSLASH_CHAR = '\\';
         public static final char SLASH_CHAR = '/';

native/src/main/java/io/ballerina/lib/data/csvdata/utils/CsvUtils.java

@@ -52,15 +52,6 @@ public static boolean isExpectedTypeIsArray(Type expectedType) {
         };
     }
 
-    public static boolean isExpectedTypeIsMap(Type expectedType) {
-        expectedType = TypeUtils.getReferredType(expectedType);
-
-        return switch (expectedType.getTag()) {
-            case TypeTags.MAP_TAG, TypeTags.RECORD_TYPE_TAG -> true;
-            default -> false;
-        };
-    }
-
     public static boolean isBasicType(Type type) {
         return switch (type.getTag()) {
             case TypeTags.INT_TAG, TypeTags.STRING_TAG, TypeTags.BOOLEAN_TAG, TypeTags.DECIMAL_TAG, TypeTags.FLOAT_TAG,