Skip to content

docs: refactor multiple language documents #347

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 24, 2024
Merged

docs: refactor multiple language documents #347

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 47 additions & 1 deletion docs/reference/xlang-api/java-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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());
}
}
```
174 changes: 3 additions & 171 deletions docs/reference/xlang-api/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
17 changes: 16 additions & 1 deletion docs/reference/xlang-api/python-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
```
21 changes: 20 additions & 1 deletion docs/reference/xlang-api/rest-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down Expand Up @@ -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;

Expand Down Expand Up @@ -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 {
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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 {
Expand Down
21 changes: 20 additions & 1 deletion i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/xlang-api/java-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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();
```
Loading