Skip to content

Commit

Permalink
en: KCL tools (#125)
Browse files Browse the repository at this point in the history 
doc: translate ref/cli/kcl/* to en
  • Loading branch information
@He1pa
He1pa authored Sep 20, 2022
1 parent 45f0525 commit f935e13
Show file tree
Hide file tree
Showing 10 changed files with 498 additions and 95 deletions.
4 changes: 2 additions & 2 deletions docs/reference/cli/kcl/index.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
# KCL 语言工具
# KCL Language Tools

KCL 作为 Kusion 的配置策略语言，不仅仅提供了 kcl 命令编译和执行配置程序，还提供了 fmt、lint、test、vet、docgen 等配套的辅助工具。
As the configuration policy language of Kusion, KCL not only provides the command `kcl` to compile and execute configuration programs but also provides fmt, lint, test, vet, docgen and other supporting tools.
76 changes: 36 additions & 40 deletions docs/reference/cli/kcl/lint.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,13 @@
sidebar_position: 3
---

# Lint 检查代码风格
# Lint Check

KCL 支持通过内置的命令行工具对 KCL 代码进行检查，并支持多种输出格式。本文档展示 KCL Lint 工具的使用方式。
KCL supports checking KCL code style through built-in command line tool and supports multiple output formats. This document shows how to use the KCL Lint tool.

## 示例
## Example

### 工程结构
### Project Struct

```text
.
Expand All @@ -22,27 +22,27 @@ KCL 支持通过内置的命令行工具对 KCL 代码进行检查，并支持
└── test.k
```

其中，`.kcllint` 文件为配置参数文件，非必需项，`a.k`,`b.k`,`c.k`,`test.k` 为测试的 kcl 文件。
`.kcllint` is the configuration file of lint. It is optional. `a.k`, `b.k`, `c.k` and `test.k` are the kcl file to be checked.

命令：
Args：

```shell
kcl-lint your_config.k
```

或
or

```shell
kcl-lint your_config_path
```

lint 配置文件
lint configuration file

```shell
kcl-lint --config abspath/.kcllint your_config.k
```

输出结果示例：
Output:

```shell
/Users/../test.k:12:1: E0501 line too long (122 > 120 characters)
Expand All @@ -60,9 +60,9 @@ Check total 1 files:
KCL Lint: 2 problems
```

## KCL Lint 工具使用方式
## KCL Lint Tool

### CLI 参数
### Args

```shell
usage: kcl-lint [-h] [--config file] [file]
Expand All @@ -75,30 +75,30 @@ optional arguments:
--config file KCL lint config path
```

+ --config : lint 配置文件 `.kcllint` 的路径
+ file : 需要检查的单个 `.k` 文件路径或路径目录下的所有 `.k` 文件，支持绝对路径或当前目录的相对路径
+ --config : path of `.kcllint`
+ file: the path of a single `*.k` file or directory to be checked. Support the absolute path or relative path of the current directory.

### Lint 配置参数
### Lint Configuration

#### 优先级
#### Priority

Lint 的配置参数的优先级如下：
The priority of Lint's configuration is as follows:

1. CLI 参数中的 `--config file` 路径的 `.kcllint` 文件
2. 被检查 `.k` 文件所在目录或被检查目录下的 `.kcllint` 文件
3. 默认配置
1. the `.kcllint` set in CLI Args
2. the `.kcllint` under directory of checked `.k` file or checked directory
3. default configuration

#### .kcllint

`.kcllint` 文件以 yaml 格式书写。其内容包括：
The file `.kcllint` is written in YAML. Its contents include:

- check_list 用于选择检查的 checker，可选项为 `"import"` 和 `"misc"`
- ignore 用于选择忽略的检查项，可选项见错误代码
- max_line_length 为检查的参数，即单行代码最大长度
- output 用于选择输出流和输出格式，可选项为 `"stdout"`、`"file"`、`"sarif"`
- output_path 为可选项，当 output 选择了“file”或"sarif"，则必须设置输出文件的路径
+ check_list: kinds of checks, including `"import"` and `"misc"`
+ ignore: ignored check items. See the `Error Code` for optional items.
+ max_line_length: the parameter of check, that is, the maximum length of code
+ output: output streams and formats, including `"stdout"`、`"file"` and `"sarif"`
+ output_path: The path of output file. It is optional, but it is required when the `output` set as `"file"` or `"sarif"`

示例：
Example:

```yaml
check_list: ["import","misc"]
Expand All @@ -108,7 +108,7 @@ output: ["stdout"]
output_path:
```
#### 默认配置
Default Configuration:
```yaml
check_list: ["import", "misc"]
Expand All @@ -117,17 +117,13 @@ max_line_length: 200
output: ["stdout"]
```
### 检查项及错误代码
### Error Code
目前提供 import_checker 和 misc_checker
- import_checker
- E0401: Unable to import.
- W0401: Reimport.
- E0406: Module import itself.
- W0411: Import but unused.
- E0413: ImportStmt is not at the top of the file
- misc_checker
- E0501: Line too long
+ import_checker
+ E0401: Unable to import.
+ W0401: Reimport.
+ E0406: Module import itself.
+ W0411: Import but unused.
+ E0413: ImportStmt is not at the top of the file
+ misc_checker
+ E0501: Line too long
28 changes: 14 additions & 14 deletions docs/reference/cli/kcl/overview.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,19 +2,19 @@
sidebar_position: 1
---

# 概览
# Overview

KCL 工具链是 KCL 语言的工具集合，旨在提升 KCL 的批量迁移、编写、编译和测试的效率。
KCL toolchain is a toolset of KCL language, which aims to improve the efficiency of batch migration, writing, compiling and testing of KCL.

| 类别 | 工具名称 | 说明 |
| -------------- | --------------- | -------------------------------------------------------------------------------- |
| 主工具集 | **kcl** | kcl 命令行工具提供对基于 KCL 语言的配置编写、编译和测试。 |
| | kcl build | （未支持）kcl build 子命令提供对 KCL 代码的构建 |
| | kcl test | kcl 测试工具，对 KCL 的单元测试（未支持）及集成测试 |
| | kcl fmt | kcl-fmt 工具提供对 KCL 代码的格式化 |
| | kcl list | （目前为 kcl list-options 及 kcl list-attributes 子命令形态）kcl-list 工具解析 KCL 代码，并列表展示 option 参数/schema attributes 信息。 |
| 自动化工具集 | kcl-lint | kcl-lint 工具提供对 KCL 代码的 lint 检查和自动修复 |
| | kcl-doc | kcl-doc 工具提供对 KCL 代码的文档解析和生成 |
| | kcl-fmt | 等同于 kcl fmt 子命令 |
| ide 插件集 | IntelliJ IDEA KCL 插件 | 提供 IntelliJ IDEA 平台的 KCL 编写、编译辅助 |
| | VS Code KCL 插件 | 提供 VS Code 平台的 KCL 编写、编译辅助 |
| | Name | Description |
| ---------------- | ------------------------ | ----------------------------------------------------------------------- |
| Main Toolset | **kcl** | Provide support for KCL in coding, compiling and testing |
| | kcl build | Build KCL code(not support) |
| | kcl test | KCL test tool, provide unit test(not support) and integration test |
| | kcl fmt | Formoat KCL code |
| | kcl list | Parses the KCL code and lists the option parameter/schema attributes information. （kcl list-options and kcl list-attributes)|
|Automation Toolset| kcl-lint | Check code style for KCL code |
| | kcl-doc | Parses the KCL code and generate documents |
| | kcl-fmt | Same as `kcl fmt` |
| IDE Plugin | IntelliJ IDEA KCL plugin | Provide KCL compilation and compilation assistance for IntelliJ IDEA |
| | VS Code KCL plugin | Provide KCL compilation and compilation assistance for VS Code |
53 changes: 24 additions & 29 deletions docs/reference/cli/kcl/test.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,15 @@
sidebar_position: 5
---

# 测试工具
# Test Tool

## 简介
## Intro

KCL 支持通过内置的 `kcl-test` 命令行工具和 `testing` 包提供了简易的测试框架。每个目录下的全部 KCL 文件是一个测试整体，每个 `_test.k` 中 `Test` 开头的 schema 是一个测试案例。
KCL provides a simple testing framework through the built-in 'kcl-test' command line tool and 'testing' package. All KCL files in each directory are a set of tests, and each schema begins with 'Test' in each 'test.k' is a test case.

## 使用方式
## How to use

假设有 hello.k 文件，代码如下:
There is a KCL file `hello.k`:

```python
schema Person:
Expand All @@ -23,7 +23,7 @@ hello = Person {
}
```

构造 hello_test.k 测试文件，内容如下：
Build a test file `hello_test.k`:

```python
schema TestPerson:
Expand All @@ -40,17 +40,17 @@ schema TestPerson_ok:
assert a.age == 1
```

然后再目录下执行 `kcl-test` 命令:
Execute the following command:

```
$ kcl-test
ok /pkg/to/app [365.154142ms]
$
```

## 失败的测试
## Failed Test Case

将 hello_test.k 测试代码修改如下，构造失败的测试：
Modify `hello_test.k` to the following code to build failed test case:

```python
# Copyright 2021 The KCL Authors. All rights reserved.
Expand All @@ -71,7 +71,7 @@ schema TestPerson_ok:
assert a.age == 1
```

测试输出的错误如下：
Output:

```
$ kcl-test
Expand All @@ -91,9 +91,8 @@ FAIL /pkg/to/app [354.153775ms]
$
```

## 配置 option 参数

可以通过 testing 包指定面值类型的命令行参数：
## Option Args
Literal type command line arguments can be specified via the testing package:

```python
schema TestOptions:
Expand All @@ -116,9 +115,9 @@ schema TestOptions:
assert option("bool-false") == False
```

其中 `testing.arguments` 定义一组 key-value 参数，只有在当前的测试中有效。
`testing.arguments` defines a set of key-value arguments, valid only in the current test.

option 参数也可以从 settings.yaml 文件读取。假设有 `./settings.yaml` 文件如下：
The option arguments can also be load from the `settings.yaml`. There is a file `settings.yaml`:

```yaml
- key: app-name
Expand All @@ -129,7 +128,7 @@ option 参数也可以从 settings.yaml 文件读取。假设有 `./settings.yam
value: reg.docker.inc.com/test-image
```
然后可以通过 `testing.setting_file("./settings.yaml")` 方式配置参数。同时依然支持 `testing.arguments()` 覆盖配置文件中的参数：
Parameters can then be configured via `testing.setting_file("./settings.yaml")`. At the same time, `testing.arguments()` is still supported to override the parameters in the configuration file:

```py
schema TestOptions_setting:
Expand All @@ -140,25 +139,21 @@ schema TestOptions_setting:
assert option("file") == "settings.yaml"
```

testing.setting_file("settings.yaml") 则是从 yaml 文件加载对应的 key-value 参数。

## 测试插件

如果要测试的目录含有 `plugin.py` 和测试文件，自动切换到插件模式。那么将测试前设置 `KCL_PLUGINS_ROOT` 环境变量（不能再访问其他目录的插件）用于测试当前插件，测试完成之后恢复之前的 `KCL_PLUGINS_ROOT` 环境变量。
## Plugin Test

## 集成测试
Automatically switch to plugin mode if the directory to be tested contains `plugin.py` and test files. Then set the environment variable `KCL_PLUGINS_ROOT` before the test (plugins in other directories can no longer be accessed) to test the current plugin, and restore the previous `KCL_PLUGINS_ROOT` after the test is completed.

目录含有 `*.k` 时自动执行集成测试，如果有 `stdout.golden` 则验证输出的结果，如果有 `stderr.golden` 则验证错误。支持 `settings.yaml` 文件定义命令行参数。
## Integration Test

如果有 k 文件含有 `# kcl-test: ignore` 标注注释将忽略测试。
Automatically execute integration tests when the directory contains `*.k`. If there is `stdout.golden` then verify the output. If there is `stderr.golden` then verify the error. Supports the `settings.yaml` file to define command line arguments.

## 批量测试
## Batch Test

- `kcl-test path` 执行指定目录的测试, 当前目录可以省略该参数
- `kcl-test -run=regexp` 可以执行匹配模式的测试
- `kcl-test ./...` 递归执行子目录的单元测试
+ `kcl-test path` Execute the test of the specified directory. It can be omitted if is the current directory
+ `kcl-test -run=regexp` Execute the test which matches patterns
+ `kcl-test ./...` Execute unit tests recursively

## 命令行参数
## Args

```
$ kcl-test -h
Expand Down
20 changes: 10 additions & 10 deletions docs/reference/cli/kcl/vet.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,15 @@
sidebar_position: 4
---

# Validation 校验代码
# Validation Code

## 简介
## Intro

KCL 支持通过内置的 `kcl-vet` 命令行工具提供了基本的配置数据校验能力，可以编写 KCL schema 对输入的 JSON/YAML 格式文件进行类型以及数值的校验。
KCL supports basic configuration data verification capabilities through the built-in `kcl-vet` command line tool. You can write a KCL schema to verify the type and value of the input JSON/YAML files.

## 使用方式
## How to use

假设有 data.json 文件，代码如下:
There is a JSON format file `data.json`:

```json
{
Expand All @@ -28,7 +28,7 @@ KCL 支持通过内置的 `kcl-vet` 命令行工具提供了基本的配置数
}
```

构造 schema.k 校验文件，内容如下：
Build a validate KCL file `schema.k`:

```py
schema User:
Expand All @@ -47,22 +47,22 @@ schema Data:
value: str
```

在目录下执行如下命令
Execute the following command:

```
$ kcl-vet data.json schema.k
Validate succuss!
```

## 指定校验的 schema
## Specify the schema for validation

当教研的 KCL 文件中存在多个 schema 定义时，kcl-vet 工具会默认取第一个 schema 定义进行校验，如果需要指定校验的 schema，可以使用 `-d|--schema` 参数
When multiple schema definitions exist in the KCL file, by default, the `kcl-vet` tool will use the first schema to check. If you need to specify a schema for verification, you can use the '- d | -- schema' parameter

```
$kcl-vet data.json schema.k -d User
```

## 命令行参数
## Args

```
$ kcl-vet -h
Expand Down
3 changes: 3 additions & 0 deletions i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/cli/kcl/index.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# KCL 语言工具

KCL 作为 Kusion 的配置策略语言，不仅仅提供了 kcl 命令编译和执行配置程序，还提供了 fmt、lint、test、vet、docgen 等配套的辅助工具。
Loading

0 comments on commit f935e13

Please sign in to comment.