Skip to content

Commit

Permalink
Add examples for api documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@SasinduDilshara
SasinduDilshara committed Aug 16, 2024
1 parent 93b6f0e commit 1df7169
Show file tree
Hide file tree
Showing 6 changed files with 59 additions and 31 deletions.
42 changes: 40 additions & 2 deletions ballerina/csv_api.bal
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down
6 changes: 3 additions & 3 deletions ...-plugin-test/src/test/java/io/ballerina/lib/data/csvdata/compiler/CompilerPluginTest.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.";

Expand Down
11 changes: 6 additions & 5 deletions ...r-plugin/src/main/java/io/ballerina/lib/data/csvdata/compiler/CsvDataDiagnosticCodes.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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);

Expand Down
14 changes: 6 additions & 8 deletions native/src/main/java/io/ballerina/lib/data/csvdata/csv/CsvTraversal.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down Expand Up @@ -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();
}
Expand Down
8 changes: 4 additions & 4 deletions native/src/main/java/io/ballerina/lib/data/csvdata/utils/Constants.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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");
Expand Down Expand Up @@ -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";
Expand All @@ -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 = '/';
Expand Down
9 changes: 0 additions & 9 deletions native/src/main/java/io/ballerina/lib/data/csvdata/utils/CsvUtils.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down

0 comments on commit 1df7169

Please sign in to comment.