Merge pull request #347 from Peefy/refactor-multiple-language-docs

docs: refactor multiple language documents

Author: Peefy

docs/reference/xlang-api/java-api.md

@@ -4,4 +4,50 @@ sidebar_position: 5
 
 # Java API
 
-At present, the KCL Java SDK is still in the early preview version. The KCL team will continue to update and provide more functions in the future. For more information, see [https://github.com/kcl-lang/kcl-java](https://github.com/kcl-lang/kcl-java)
+## Installation
+
+Refer to [this](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry#authenticating-to-github-packages
+) to configure your Maven; set up your GitHub account and Token in the `settings.xml`.
+
+### Maven
+
+In your project's pom.xml, configure our repository as follows:
+
+```xml
+<repositories>
+    <repository>
+        <id>github</id>
+        <url>https://maven.pkg.github.com/kcl-lang/*</url>
+        <snapshots>
+            <enabled>true</enabled>
+        </snapshots>
+    </repository>
+</repositories>
+```
+
+This way you'll be able to import the above dependency to use the SDK.
+
+```xml
+<dependency>
+    <groupId>com.kcl</groupId>
+    <artifactId>kcl-lib</artifactId>
+    <version>0.8.5</version>
+</dependency>
+```
+
+## Quick Start
+
+```java
+import com.kcl.api.API;
+import com.kcl.api.Spec.ExecProgram_Args;
+import com.kcl.api.Spec.ExecProgram_Result;
+
+public class ExecProgramTest {
+    public static void main(String[] args) throws Exception {
+        API api = new API();
+        ExecProgram_Result result = api
+                .execProgram(ExecProgram_Args.newBuilder().addKFilenameList("path/to/kcl.k").build());
+        System.out.println(result.getYamlResult());
+    }
+}
+```

docs/reference/xlang-api/overview.md

@@ -4,179 +4,11 @@ sidebar_position: 1
 
 # Introduction
 
-The KCL language provides general programming language interfaces such as C/Rust/Go/Python/Java, and the related languages are under development.
+The KCL language provides general programming language APIs.
 
-## C/Rust API
+## C/Rust APIs
 
-The core of KCL is developed in Rust, and the C language API is exported externally for packaging and integration in high-level languages such as Go/Python/Java.
-
-## Go API
-
-Go API is a C-API provided by CGO wrapping KCL, while providing deeper customization features to meet the needs of upper-level tools.
-
-### Abstract Model
-
-The abstract model of the KCL Go API is as follows:
-
-```
-┌─────────────────┐         ┌─────────────────┐           ┌─────────────────┐
-│     kcl files   │         │   KCL-Go-API    │           │  KCLResultList  │
-│  ┌───────────┐  │         │                 │           │                 │
-│  │    1.k    │  │         │                 │           │                 │
-│  └───────────┘  │         │                 │           │  ┌───────────┐  │         ┌───────────────┐
-│  ┌───────────┐  │         │  ┌───────────┐  │           │  │ KCLResult │──┼────────▶│x.Get("a.b.c") │
-│  │    2.k    │  │         │  │ Run(path) │  │           │  └───────────┘  │         └───────────────┘
-│  └───────────┘  │────┐    │  └───────────┘  │           │                 │
-│  ┌───────────┐  │    │    │                 │           │  ┌───────────┐  │         ┌───────────────┐
-│  │    3.k    │  │    │    │                 │           │  │ KCLResult │──┼────────▶│x.Get("k", &v) │
-│  └───────────┘  │    │    │                 │           │  └───────────┘  │         └───────────────┘
-│  ┌───────────┐  │    ├───▶│  ┌───────────┐  │──────────▶│                 │
-│  │setting.yml│  │    │    │  │RunFiles() │  │           │  ┌───────────┐  │         ┌───────────────┐
-│  └───────────┘  │    │    │  └───────────┘  │           │  │ KCLResult │──┼────────▶│x.JSONString() │
-└─────────────────┘    │    │                 │           │  └───────────┘  │         └───────────────┘
-                       │    │                 │           │                 │
-┌─────────────────┐    │    │                 │           │  ┌───────────┐  │         ┌───────────────┐
-│     Options     │    │    │  ┌───────────┐  │           │  │ KCLResult │──┼────────▶│x.YAMLString() │
-│WithOptions      │    │    │  │MustRun()  │  │           │  └───────────┘  │         └───────────────┘
-│WithOverrides    │────┘    │  └───────────┘  │           │                 │
-│WithWorkDir      │         │                 │           │                 │
-│WithDisableNone  │         │                 │           │                 │
-└─────────────────┘         └─────────────────┘           └─────────────────┘
-```
-
-The input file contains the KCL file and the `setting.yml` configuration file, and `Options` can be used to specify additional parameters and information such as working directory. The "KCL-Go-API" part is the provided KCL execution function. The execution function executes the KCL program according to the input file and additional parameters, and finally outputs the result of `KCLResultList`. `KCLResultList` is a list of `KCLResult`, each `KCLResult` corresponding to a generated configuration file or `map[string]interface{}`.
-
-### Example
-
-```go
-package main
-
-import (
-	"fmt"
-
-	kcl "kcl-lang.io/kcl-go"
-)
-
-
-func main() {
-	const k_code = `
-name = "kcl"
-age = 1
-
-schema Person:
-    name: str = "kcl"
-    age: int = 1
-
-x0 = Person{}
-x1 = Person{age:101}
-`
-
-	result := kcl.MustRun("hello.k", kcl.WithCode(k_code)).First()
-	fmt.Println(result.GetRawYAMLString())
-
-	fmt.Println("----")
-	fmt.Println("x0.name:", result.Get("x0.name"))
-	fmt.Println("x1.age:", result.Get("x1.age"))
-
-	fmt.Println("----")
-
-	var person struct {
-		Name string
-		Age  int
-	}
-	fmt.Printf("person: %+v\n", result.Get("x1", &person))
-}
-```
-
-Output result:
-
-```yaml
-age: 1
-name: kcl
-x0:
-    age: 1
-    name: kcl
-x1:
-    age: 101
-    name: kcl
-
-----
-x0.name: kcl
-x1.age: 101
-----
-person: &{Name:kcl Age:101}
-```
-
-## Python API
-
-Using the Python SDK requires that you have a local Python version higher than 3.7.3 and a local pip package management tool. You can use the following command to install and obtain helpful information.
-
-```bash
-python3 -m pip install kclvm --user && python3 -m kclvm --help
-```
-
-### Command Line Tool
-
-Prepare a KCL file named `main.k`
-
-```python
-name = "kcl"
-age = 1
-
-schema Person:
-    name: str = "kcl"
-    age: int = 1
-
-x0 = Person {}
-x1 = Person {
-    age = 101
-}
-```
-
-Execute the following command and get the output:
-
-```shell
-$ python3 -m kclvm hello.k
-name: kcl
-age: 1
-x0:
-  name: kcl
-  age: 1
-x1:
-  name: kcl
-  age: 101
-```
-
-### API
-
-In addition, we can also execute KCL files through Python code.
-
-Prepare a KCL file named `main.py`
-
-```python
-import kclvm.program.exec as kclvm_exec
-import kclvm.vm.planner as planner
-
-print(planner.plan(kclvm_exec.Run(["hello.k"]).filter_by_path_selector()))
-```
-
-Execute the following command and get the output:
-
-```shell
-$ python3 main.py
-name: kcl
-age: 1
-x0:
-  name: kcl
-  age: 1
-x1:
-  name: kcl
-  age: 101
-```
-
-You can see that the same output can be obtained through command line tools and APIs.
-
-At present, the KCL Python SDK is still in the early preview version. The KCL team will continue to update and provide more functions in the future. For more information, see [https://github.com/kcl-lang/kcl-py](https://github.com/kcl-lang/kcl-py)
+The core of KCL is developed in Rust, and the C language API is exported externally for packaging and integration in other high-level languages such as Go, Python, etc.
 
 ## REST-API
 

docs/reference/xlang-api/python-api.md

@@ -4,4 +4,19 @@ sidebar_position: 4
 
 # Python API
 
-At present, the KCL Python SDK is still in the early preview version. The KCL team will continue to update and provide more functions in the future. For more information, see [https://github.com/kcl-lang/kcl-py](https://github.com/kcl-lang/kcl-py)
+## Installation
+
+```shell
+python3 -m pip install kcl-lib
+```
+
+## Quick Start
+
+```typescript
+import kcl_lib.api as api
+
+args = api.ExecProgram_Args(k_filename_list=["path/to/kcl.k"])
+api = api.API()
+result = api.exec_program(args)
+print(result.yaml_result)
+```

docs/reference/xlang-api/rest-api.md

@@ -179,6 +179,7 @@ service KclvmService {
 	rpc ParseProgram(ParseProgram_Args) returns(ParseProgram_Result);
 	rpc LoadPackage(LoadPackage_Args) returns(LoadPackage_Result);
 	rpc ListOptions(ParseProgram_Args) returns(ListOptions_Result);
+	rpc ListVariables(ListVariables_Args) returns(ListVariables_Result);
 
 	rpc FormatCode(FormatCode_Args) returns(FormatCode_Result);
 	rpc FormatPath(FormatPath_Args) returns(FormatPath_Result);
@@ -303,7 +304,7 @@ message ExecProgram_Args {
 
 	repeated string k_filename_list = 2;
 	repeated string k_code_list = 3;
-
+	
 	repeated CmdArgSpec args = 4;
 	repeated CmdOverrideSpec overrides = 5;
 
@@ -339,6 +340,9 @@ message ExecProgram_Args {
 
 	// -S --path_selector
 	repeated string path_selector = 17;
+
+	// -K --fast_eval
+	bool fast_eval = 18;
 }
 
 message ExecProgram_Result {
@@ -403,6 +407,20 @@ message OverrideFile_Result {
 	bool result = 1;
 }
 
+message ListVariables_Args {
+	string file = 1;
+	repeated string specs = 2;
+}
+
+message ListVariables_Result {
+	map<string, Variable> variables = 1;
+	repeated string unsupported_codes = 2; 
+}
+
+message Variable {
+	string value = 1;
+}
+
 message GetFullSchemaType_Args {
 	ExecProgram_Args exec_args = 1;
 	string schema_name = 2;
@@ -487,6 +505,7 @@ message CliConfig {
 	bool sort_keys = 9;
 	bool show_hidden = 10;
 	bool include_schema_type_path = 11;
+	bool fast_eval = 12;
 }
 
 message KeyValuePair {

i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/xlang-api/java-api.md

@@ -4,4 +4,23 @@ sidebar_position: 5
 
 # Java API
 
-目前 KCL Java SDK 还处于早期预览版本，后续 KCL 团队会持续更新并提供更丰富的功能，更多信息请参阅：[https://github.com/kcl-lang/kcl-java](https://github.com/kcl-lang/kcl-java)。
+## 添加依赖
+
+```shell
+npm install kcl-lib
+```
+
+### Maven
+
+## 快速开始
+
+```typescript
+import { execProgram, ExecProgramArgs } from "kcl-lib";
+
+function main() {
+  const result = execProgram(new ExecProgramArgs(["path/to/kcl.k"]));
+  console.log(result.yamlResult);
+}
+
+main();
+```