From 1df716970e9109f6d5e93660f2f2819daa229953 Mon Sep 17 00:00:00 2001 From: Sasindu Alahakoon Date: Fri, 16 Aug 2024 10:13:59 +0530 Subject: [PATCH] Add examples for api documentation --- ballerina/csv_api.bal | 42 ++++++++++++++++++- .../csvdata/compiler/CompilerPluginTest.java | 6 +-- .../compiler/CsvDataDiagnosticCodes.java | 11 ++--- .../lib/data/csvdata/csv/CsvTraversal.java | 14 +++---- .../lib/data/csvdata/utils/Constants.java | 8 ++-- .../lib/data/csvdata/utils/CsvUtils.java | 9 ---- 6 files changed, 59 insertions(+), 31 deletions(-) diff --git a/ballerina/csv_api.bal b/ballerina/csv_api.bal index b4089e1..292e335 100644 --- a/ballerina/csv_api.bal +++ b/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 csvByteStream = check io:fileReadBlocksAsStream("example.csv"); +# record{int id; string name;}[] csv1 = check csv:parseStream(csvByteStream); +# stream csvByteStream2 = check io:fileReadBlocksAsStream("example.csv"); +# [int, string][] csv2 = check csv:parseStream(csvByteStream2); +# stream csvByteStream3 = check io:fileReadBlocksAsStream("example.csv"); +# record{|int id;|}[] csv3 = check csv:parseStream(csvByteStream3); +# stream 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 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 diff --git a/compiler-plugin-test/src/test/java/io/ballerina/lib/data/csvdata/compiler/CompilerPluginTest.java b/compiler-plugin-test/src/test/java/io/ballerina/lib/data/csvdata/compiler/CompilerPluginTest.java index ea9a7eb..5c73016 100644 --- a/compiler-plugin-test/src/test/java/io/ballerina/lib/data/csvdata/compiler/CompilerPluginTest.java +++ b/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."; diff --git a/compiler-plugin/src/main/java/io/ballerina/lib/data/csvdata/compiler/CsvDataDiagnosticCodes.java b/compiler-plugin/src/main/java/io/ballerina/lib/data/csvdata/compiler/CsvDataDiagnosticCodes.java index e6137e0..5104c40 100644 --- a/compiler-plugin/src/main/java/io/ballerina/lib/data/csvdata/compiler/CsvDataDiagnosticCodes.java +++ b/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); diff --git a/native/src/main/java/io/ballerina/lib/data/csvdata/csv/CsvTraversal.java b/native/src/main/java/io/ballerina/lib/data/csvdata/csv/CsvTraversal.java index c06fb7d..625ceea 100644 --- a/native/src/main/java/io/ballerina/lib/data/csvdata/csv/CsvTraversal.java +++ b/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(); } diff --git a/native/src/main/java/io/ballerina/lib/data/csvdata/utils/Constants.java b/native/src/main/java/io/ballerina/lib/data/csvdata/utils/Constants.java index 8b12602..4cd1749 100644 --- a/native/src/main/java/io/ballerina/lib/data/csvdata/utils/Constants.java +++ b/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,7 +37,7 @@ private ConfigConstants() { } } - public final class Values { + public static final class Values { public static final String NULL = "null"; public static final String BALLERINA_NULL = "()"; @@ -45,7 +45,7 @@ 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 = '/'; diff --git a/native/src/main/java/io/ballerina/lib/data/csvdata/utils/CsvUtils.java b/native/src/main/java/io/ballerina/lib/data/csvdata/utils/CsvUtils.java index 70ff154..917771f 100644 --- a/native/src/main/java/io/ballerina/lib/data/csvdata/utils/CsvUtils.java +++ b/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,