Merge pull request #29 from ballerina-platform/doc-update

Update documentation
ballerina-platform · Feb 13, 2024 · 49896c4 · 49896c4
2 parents 0c9da68 + 3c80fe8
commit 49896c4
Show file tree

Hide file tree

Showing 18 changed files with 639 additions and 330 deletions.
diff --git a/README.md b/README.md
diff --git a/changelog.md b/changelog.md
@@ -0,0 +1,16 @@
+# Changelog
+This file contains all the notable changes done to the Ballerina EDI Module through the releases.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- [Add support for Ballerina Swan Lake Update 8.](https://github.com/ballerina-platform/ballerina-library/issues/5900)
+- [Add support for field length constraints (min/max).](https://github.com/ballerina-platform/ballerina-library/issues/5896)
+- Add support for EDIFACT to Ballerina schema conversion.
+
+### Changed
+- Documentation improvements on tool and CLI commands.
+- Set the default value of `required` to `true` for the field `code` in schema definitions.
diff --git a/docs/proposals/edi.md b/docs/proposals/edi.md
@@ -1,6 +1,6 @@
 # Proposal: EDI
 
-_Owners_: @chathurace @ruks  
+_Authors_: @chathurace @ruks  
 _Reviewers_:     
 _Created_: 2023/03/31  
 _Updated_:   

diff --git a/edi-tools-cli/src/main/java/io/ballerina/edi/cmd/CodegenCmd.java b/edi-tools-cli/src/main/java/io/ballerina/edi/cmd/CodegenCmd.java
@@ -21,26 +21,27 @@
 import io.ballerina.cli.BLauncherCmd;
 import picocli.CommandLine;
 
+import java.io.BufferedReader;
+import java.io.IOException;
 import java.io.InputStream;
+import java.io.InputStreamReader;
 import java.io.PrintStream;
+import java.nio.charset.StandardCharsets;
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.nio.file.StandardCopyOption;
 
-@CommandLine.Command(
-        name = "codegen",
-        description = "Generated code for a given EDI schema."
-)
+@CommandLine.Command(name = "codegen", description = "Generates Ballerina records and parser functions for a given EDI schema.")
 public class CodegenCmd implements BLauncherCmd {
     private static final String EDI_TOOL = "editools.jar";
     private static final String CMD_NAME = "codegen";
 
     private final PrintStream printStream;
 
-    @CommandLine.Option(names = {"-s", "--schema"}, description = "EDI schema path")
+    @CommandLine.Option(names = { "-s", "--schema" }, description = "EDI schema path")
     private String schemaPath;
 
-    @CommandLine.Option(names = {"-o", "--output"}, description = "Output path")
+    @CommandLine.Option(names = { "-o", "--output" }, description = "Output path")
     private String outputPath;
 
     public CodegenCmd() {
@@ -70,7 +71,7 @@ public void execute() {
             process.waitFor();
             java.io.InputStream is = process.getInputStream();
             byte b[] = new byte[is.available()];
-            is.read(b,0,b.length);
+            is.read(b, 0, b.length);
             printStream.println(new String(b));
         } catch (Exception e) {
             printStream.println("Error in generating code. " + e.getMessage());
@@ -85,17 +86,28 @@ public String getName() {
 
     @Override
     public void printLongDesc(StringBuilder stringBuilder) {
-
+        Class<?> clazz = EdiCmd.class;
+        ClassLoader classLoader = clazz.getClassLoader();
+        InputStream inputStream = classLoader.getResourceAsStream("cli-docs/codegen.help");
+        if (inputStream != null) {
+            try (InputStreamReader inputStreamREader = new InputStreamReader(inputStream, StandardCharsets.UTF_8);
+                    BufferedReader br = new BufferedReader(inputStreamREader)) {
+                String content = br.readLine();
+                printStream.append(content);
+                while ((content = br.readLine()) != null) {
+                    printStream.append('\n').append(content);
+                }
+            } catch (IOException e) {
+                printStream.println("Helper text is not available.");
+            }
+        }
     }
 
     @Override
     public void printUsage(StringBuilder stringBuilder) {
-        stringBuilder.append("Ballerina EDI tools - Code generation\n");
-        stringBuilder.append("Ballerina code generation for edi schema: bal edi codegen -s <schema json path> -o <output bal file path>\n");
     }
 
     @Override
     public void setParentCmdParser(CommandLine commandLine) {
-
     }
 }
diff --git a/edi-tools-cli/src/main/java/io/ballerina/edi/cmd/ConvertEdifactCmd.java b/edi-tools-cli/src/main/java/io/ballerina/edi/cmd/ConvertEdifactCmd.java
@@ -1,5 +1,5 @@
 /*
- *  Copyright (c) 2024, WSO2 LLC (http://www.wso2.org) All Rights Reserved.
+ *  Copyright (c) 2023, WSO2 Inc. (http://www.wso2.org) All Rights Reserved.
  *
  *  WSO2 Inc. licenses this file to you under the Apache License,
  *  Version 2.0 (the "License"); you may not use this file except
@@ -21,28 +21,29 @@
 import io.ballerina.cli.BLauncherCmd;
 import picocli.CommandLine;
 
+import java.io.BufferedReader;
+import java.io.IOException;
 import java.io.InputStream;
+import java.io.InputStreamReader;
 import java.io.PrintStream;
 import java.net.URL;
+import java.nio.charset.StandardCharsets;
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.nio.file.StandardCopyOption;
 
-@CommandLine.Command(
-        name = "convertEdifactSchema",
-        description = "Converts EDIFACT schema to EDI schema."
-)
+@CommandLine.Command(name = "convertEdifactSchema", description = "Converts EDIFACT schema to EDI schema.")
 public class ConvertEdifactCmd implements BLauncherCmd {
     private static final String CMD_NAME = "convertEdifactSchema";
     private final PrintStream printStream;
 
-    @CommandLine.Option(names = {"-v", "--version"}, description = "EDIFACT version")
+    @CommandLine.Option(names = { "-v", "--version" }, description = "EDIFACT version")
     private String version;
 
-    @CommandLine.Option(names = {"-t", "--type"}, description = "EDIFACT message type")
+    @CommandLine.Option(names = { "-t", "--type" }, description = "EDIFACT message type")
     private String type;
 
-    @CommandLine.Option(names = {"-o", "--output"}, description = "EDIFACT schema directory path")
+    @CommandLine.Option(names = { "-o", "--output" }, description = "EDIFACT schema directory path")
     private String dir;
 
     public ConvertEdifactCmd() {
@@ -65,7 +66,8 @@ public void execute() {
                 Files.copy(in, tempFile, StandardCopyOption.REPLACE_EXISTING);
             }
             ProcessBuilder processBuilder = new ProcessBuilder(
-                    "java", "-jar", tempFile.toAbsolutePath().toString(), CMD_NAME, version, type == null ? "" : type, dir);
+                    "java", "-jar", tempFile.toAbsolutePath().toString(), CMD_NAME, version, type == null ? "" : type,
+                    dir);
             processBuilder.inheritIO();
             Process process = processBuilder.start();
             process.waitFor();
@@ -86,17 +88,28 @@ public String getName() {
 
     @Override
     public void printLongDesc(StringBuilder stringBuilder) {
-
+        Class<?> clazz = EdiCmd.class;
+        ClassLoader classLoader = clazz.getClassLoader();
+        InputStream inputStream = classLoader.getResourceAsStream("cli-docs/convertEDIfact.help");
+        if (inputStream != null) {
+            try (InputStreamReader inputStreamREader = new InputStreamReader(inputStream, StandardCharsets.UTF_8);
+                    BufferedReader br = new BufferedReader(inputStreamREader)) {
+                String content = br.readLine();
+                printStream.append(content);
+                while ((content = br.readLine()) != null) {
+                    printStream.append('\n').append(content);
+                }
+            } catch (IOException e) {
+                printStream.println("Helper text is not available.");
+            }
+        }
     }
 
     @Override
     public void printUsage(StringBuilder stringBuilder) {
-        stringBuilder.append("Ballerina EDI tools - EDIFACT to Ballerina EDI schema conversion\n");
-        stringBuilder.append("bal edi convertEdifactSchema -v <EDIFACT version> -t <EDIFACT message type> -o <output folder>\n");
     }
 
     @Override
     public void setParentCmdParser(CommandLine commandLine) {
-
     }
 }
diff --git a/edi-tools-cli/src/main/java/io/ballerina/edi/cmd/ConvertX12Cmd.java b/edi-tools-cli/src/main/java/io/ballerina/edi/cmd/ConvertX12Cmd.java
@@ -1,5 +1,5 @@
 /*
- *  Copyright (c) 2023, WSO2 LLC (http://www.wso2.org) All Rights Reserved.
+ *  Copyright (c) 2023, WSO2 Inc. (http://www.wso2.org) All Rights Reserved.
  *
  *  WSO2 Inc. licenses this file to you under the Apache License,
  *  Version 2.0 (the "License"); you may not use this file except
@@ -15,45 +15,45 @@
  *  specific language governing permissions and limitations
  *  under the License.
  */
+
 package io.ballerina.edi.cmd;
 
 import io.ballerina.cli.BLauncherCmd;
 import picocli.CommandLine;
 
+import java.io.BufferedReader;
 import java.io.IOException;
 import java.io.InputStream;
+import java.io.InputStreamReader;
 import java.io.PrintStream;
-import java.net.URL;
+import java.nio.charset.StandardCharsets;
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.nio.file.StandardCopyOption;
 import java.util.ArrayList;
 import java.util.List;
 
-@CommandLine.Command(
-        name = "convertX12Schema",
-        description = "Converts X12 schema to JSON schema."
-)
+@CommandLine.Command(name = "convertX12Schema", description = "Converts X12 schema to JSON schema.")
 public class ConvertX12Cmd implements BLauncherCmd {
 
     private static final String CMD_NAME = "convertX12Schema";
     private static final String EDI_TOOL = "editools.jar";
 
     private final PrintStream printStream;
 
-    @CommandLine.Option(names = {"-H", "--headers"}, description = {"Include headers in the input"})
+    @CommandLine.Option(names = { "-H", "--headers" }, description = { "Include headers in the input" })
     private boolean headersIncluded;
 
-    @CommandLine.Option(names = {"-c", "--collection"}, description = {"Switch to collection mode"})
+    @CommandLine.Option(names = { "-c", "--collection" }, description = { "Switch to collection mode" })
     private boolean collectionMode;
 
-    @CommandLine.Option(names = {"-i", "--input"}, description = {"X12 schema path"})
+    @CommandLine.Option(names = { "-i", "--input" }, description = { "X12 schema path" })
     private String inputPath;
 
-    @CommandLine.Option(names = {"-o", "--output"}, description = {"Output path"})
+    @CommandLine.Option(names = { "-o", "--output" }, description = { "Output path" })
     private String outputPath;
 
-    @CommandLine.Option(names = {"-d", "--segdet"}, description = {"Segment details path"})
+    @CommandLine.Option(names = { "-d", "--segdet" }, description = { "Segment details path" })
     private String segdetPath;
 
     public ConvertX12Cmd() {
@@ -69,10 +69,10 @@ public void execute() {
             return;
         }
         StringBuilder stringBuilder = new StringBuilder("Converting schema ");
-        if(collectionMode){
+        if (collectionMode) {
             stringBuilder.append("in collection ");
         }
-        if(headersIncluded){
+        if (headersIncluded) {
             stringBuilder.append("with headers ");
         }
         stringBuilder.append(inputPath).append("...");
@@ -89,23 +89,23 @@ public void execute() {
             argsList.add("-jar");
             argsList.add(tempFile.toAbsolutePath().toString());
             argsList.add(CMD_NAME);
-            if(headersIncluded){
+            if (headersIncluded) {
                 argsList.add("H");
             }
-            if(collectionMode){
+            if (collectionMode) {
                 argsList.add("c");
             }
             argsList.add(inputPath);
             argsList.add(outputPath);
-            if(segdetPath != null){
+            if (segdetPath != null) {
                 argsList.add(segdetPath);
             }
             ProcessBuilder processBuilder = new ProcessBuilder(argsList);
             Process process = processBuilder.start();
             process.waitFor();
             java.io.InputStream is = process.getInputStream();
             byte[] b = new byte[is.available()];
-            is.read(b,0,b.length);
+            is.read(b, 0, b.length);
             printStream.println(new String(b));
 
         } catch (IOException | InterruptedException e) {
@@ -121,23 +121,28 @@ public String getName() {
 
     @Override
     public void printLongDesc(StringBuilder stringBuilder) {
-        // Not implemented
+        Class<?> clazz = EdiCmd.class;
+        ClassLoader classLoader = clazz.getClassLoader();
+        InputStream inputStream = classLoader.getResourceAsStream("cli-docs/convertX12.help");
+        if (inputStream != null) {
+            try (InputStreamReader inputStreamREader = new InputStreamReader(inputStream, StandardCharsets.UTF_8);
+                    BufferedReader br = new BufferedReader(inputStreamREader)) {
+                String content = br.readLine();
+                printStream.append(content);
+                while ((content = br.readLine()) != null) {
+                    printStream.append('\n').append(content);
+                }
+            } catch (IOException e) {
+                printStream.println("Helper text is not available.");
+            }
+        }
     }
 
     @Override
     public void printUsage(StringBuilder stringBuilder) {
-        stringBuilder.append("Ballerina EDI tools - X12 Schema Conversion\n");
-        stringBuilder.append("Ballerina X12 schema conversion: bal edi ").append(CMD_NAME).append(" [-H] [-c] -i <schema input path> -o <output json file/folder path> [-d] <segment details path>\n");
-        stringBuilder.append("Options:\n");
-        stringBuilder.append("  -H, --headers       Enable headers mode (Input should be a directory and should contain header schemas)\n");
-        stringBuilder.append("  -c, --collection    Enable collection mode (Input should be a directory)\n");
-        stringBuilder.append("  -i, --input string  Input path\n");
-        stringBuilder.append("  -o, --output string Output path\n");
-        stringBuilder.append("  -d, --segdet string Segment details path\n");
     }
 
     @Override
     public void setParentCmdParser(CommandLine commandLine) {
-        // Not implemented
     }
 }