Skip to content

Commit 014bb8f

Browse files
PeefyPeefy
authored
Merge pull request #379 from Peefy/feat-0.9-api-doc
docs: update override and multiple SDK documents in 0.9
2 parents ffe985c + a318cee commit 014bb8f

File tree

25 files changed

+438
-468
lines changed

25 files changed

+438
-468
lines changed

‎docs/reference/lang/tour.md

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3249,17 +3249,16 @@ kcl main.k -O override_spec
32493249

32503250
- `override_spec` represents a unified representation of the configuration model fields and values that need to be modified
32513251

3252-
```txt
3253-
override_spec: [[pkgpath] ":"] identifier ("=" value | "-")
3252+
```bash
3253+
override_spec: identifier (("=" | ":" | "+=") value | "-")
32543254
```
32553255

3256-
- `pkgpath`: Indicates the path of the package whose identifier needs to be modified, usually in the form of `a.b.c`. For the main package, `pkgpath` is expressed as `__main__`, which can be omitted. If omitted, it means the main package.
3257-
- `identifier`: Indicates the identifier that needs to modify the configuration, usually in the form of `a.b.c`.
3258-
- `value`: Indicates the value of the configuration that needs to be modified, which can be any legal KCL expression, such as number/string literal value, list/dict/schema expression, etc.
3259-
- `=`: means to modify the value of identifier.
3256+
- `identifier` indicates the identifier that needs to modify the configuration, usually in the form of `a.b.c` or `a["dot.key"].c`
3257+
- `value` indicates the value of the configuration that needs to be modified, which can be any legal KCL expression, such as number/string literal value, list/dict/schema expression, etc.
3258+
- `=`, `:` and `+=` denotes modifying of the value of the identifier with the corresponding attribute operator.
32603259
- When the identifier exists, modify the value of the existing identifier to value.
32613260
- When identifier does not exist, add the identifier attribute and set its value to value.
3262-
- `-`: means to delete the identifier attribute.
3261+
- `-` denotes deleting of the identifier.
32633262
- When the identifier exists, delete it directly.
32643263
- When the identifier does not exist, no modification is made to the configuration.
32653264

‎docs/reference/xlang-api/go-api.md

Lines changed: 44 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -93,50 +93,49 @@ x1 = Person {
9393
## Index
9494

9595
- [Go API](#go-api)
96-
- [Index](#index)
97-
- [Constants](#constants)
98-
- [func FormatCode](#func-formatcode)
99-
- [func FormatPath](#func-formatpath)
100-
- [func GetSchemaTypeMapping](#func-getschematypemapping)
101-
- [func InitKclvmPath](#func-initkclvmpath)
102-
- [func InitKclvmRuntime](#func-initkclvmruntime)
103-
- [func LintPath](#func-lintpath)
104-
- [func ListDepFiles](#func-listdepfiles)
105-
- [func ListDownStreamFiles](#func-listdownstreamfiles)
106-
- [func ListUpStreamFiles](#func-listupstreamfiles)
107-
- [func OverrideFile](#func-overridefile)
108-
- [func Validate](#func-validate)
109-
- [func ValidateCode](#func-validatecode)
110-
- [type KCLResult](#type-kclresult)
111-
- [type KCLResultList](#type-kclresultlist)
112-
- [func MustRun](#func-mustrun)
113-
- [func Run](#func-run)
114-
- [func RunFiles](#func-runfiles)
115-
- [type KclType](#type-kcltype)
116-
- [func GetSchemaType](#func-getschematype)
117-
- [type ListDepFilesOption](#type-listdepfilesoption)
118-
- [type ListDepsOptions](#type-listdepsoptions)
119-
- [type Option](#type-option)
120-
- [func WithCode](#func-withcode)
121-
- [func WithDisableNone](#func-withdisablenone)
122-
- [func WithExternalPkgs](#func-withexternalpkgs)
123-
- [func WithFullTypePath](#func-withfulltypepath)
124-
- [func WithIncludeSchemaTypePath](#func-withincludeschematypepath)
125-
- [func WithKFilenames](#func-withkfilenames)
126-
- [func WithLogger](#func-withlogger)
127-
- [func WithOptions](#func-withoptions)
128-
- [func WithOverrides](#func-withoverrides)
129-
- [func WithPrintOverridesAST](#func-withprintoverridesast)
130-
- [func WithSelectors](#func-withselectors)
131-
- [func WithSettings](#func-withsettings)
132-
- [func WithShowHidden](#func-withshowhidden)
133-
- [func WithSortKeys](#func-withsortkeys)
134-
- [func WithWorkDir](#func-withworkdir)
135-
- [type TestCaseInfo](#type-testcaseinfo)
136-
- [type TestOptions](#type-testoptions)
137-
- [type TestResult](#type-testresult)
138-
- [func Test](#func-test)
139-
- [type ValidateOptions](#type-validateoptions)
96+
- [Index](#index)
97+
- [Constants](#constants)
98+
- [func FormatCode](#func-formatcode)
99+
- [func FormatPath](#func-formatpath)
100+
- [func GetSchemaTypeMapping](#func-getschematypemapping)
101+
- [func InitKclvmPath](#func-initkclvmpath)
102+
- [func InitKclvmRuntime](#func-initkclvmruntime)
103+
- [func LintPath](#func-lintpath)
104+
- [func ListDepFiles](#func-listdepfiles)
105+
- [func ListDownStreamFiles](#func-listdownstreamfiles)
106+
- [func ListUpStreamFiles](#func-listupstreamfiles)
107+
- [func OverrideFile](#func-overridefile)
108+
- [func Validate](#func-validate)
109+
- [func ValidateCode](#func-validatecode)
110+
- [type KCLResult](#type-kclresult)
111+
- [type KCLResultList](#type-kclresultlist)
112+
- [func MustRun](#func-mustrun)
113+
- [func Run](#func-run)
114+
- [func RunFiles](#func-runfiles)
115+
- [type KclType](#type-kcltype)
116+
- [type ListDepFilesOption](#type-listdepfilesoption)
117+
- [type ListDepsOptions](#type-listdepsoptions)
118+
- [type Option](#type-option)
119+
- [func WithCode](#func-withcode)
120+
- [func WithDisableNone](#func-withdisablenone)
121+
- [func WithExternalPkgs](#func-withexternalpkgs)
122+
- [func WithFullTypePath](#func-withfulltypepath)
123+
- [func WithIncludeSchemaTypePath](#func-withincludeschematypepath)
124+
- [func WithKFilenames](#func-withkfilenames)
125+
- [func WithLogger](#func-withlogger)
126+
- [func WithOptions](#func-withoptions)
127+
- [func WithOverrides](#func-withoverrides)
128+
- [func WithPrintOverridesAST](#func-withprintoverridesast)
129+
- [func WithSelectors](#func-withselectors)
130+
- [func WithSettings](#func-withsettings)
131+
- [func WithShowHidden](#func-withshowhidden)
132+
- [func WithSortKeys](#func-withsortkeys)
133+
- [func WithWorkDir](#func-withworkdir)
134+
- [type TestCaseInfo](#type-testcaseinfo)
135+
- [type TestOptions](#type-testoptions)
136+
- [type TestResult](#type-testresult)
137+
- [func Test](#func-test)
138+
- [type ValidateOptions](#type-validateoptions)
140139

141140
## Constants
142141

@@ -222,7 +221,7 @@ func main() {
222221
## func [GetSchemaTypeMapping](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L237)
223222

224223
```go
225-
func GetSchemaTypeMapping(file, code, schemaName string) (map[string]*KclType, error)
224+
func GetSchemaTypeMapping(filename string, src any, schemaName string) (map[string]*KclType, error)
226225
```
227226

228227
GetSchemaTypeMapping returns a \<schemaName\>:\<schemaType\> mapping of schema types from a kcl file or code.
@@ -669,32 +668,6 @@ func main() {
669668
type KclType = kcl.KclType
670669
```
671670

672-
### func [GetSchemaType](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L220)
673-
674-
```go
675-
func GetSchemaType(file, code, schemaName string) ([]*KclType, error)
676-
```
677-
678-
GetSchemaType returns schema types from a kcl file or code.
679-
680-
file: string
681-
682-
```
683-
The kcl filename
684-
```
685-
686-
code: string
687-
688-
```
689-
The kcl code string
690-
```
691-
692-
schema_name: string
693-
694-
```
695-
The schema name got, when the schema name is empty, all schemas are returned.
696-
```
697-
698671
## type [ListDepFilesOption](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L49)
699672

700673
```go

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ This way you'll be able to import the above dependency to use the SDK.
3030
<dependency>
3131
<groupId>com.kcl</groupId>
3232
<artifactId>kcl-lib</artifactId>
33-
<version>0.8.6</version>
33+
<version>0.9.0-SNAPSHOT</version>
3434
</dependency>
3535
```
3636

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

Lines changed: 37 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -123,25 +123,17 @@ syntax = "proto3";
123123
package gpyrpc;
124124
125125
// kcl main.k -E pkg_name=pkg_path
126-
message CmdExternalPkgSpec {
126+
message ExternalPkg {
127127
string pkg_name = 1;
128128
string pkg_path = 2;
129129
}
130130
131131
// kcl main.k -D name=value
132-
message CmdArgSpec {
132+
message Argument {
133133
string name = 1;
134134
string value = 2;
135135
}
136136
137-
// kcl main.k -O pkgpath:path.to.field=field_value
138-
message CmdOverrideSpec {
139-
string pkgpath = 1;
140-
string field_path = 2;
141-
string field_value = 3;
142-
string action = 4;
143-
}
144-
145137
// ----------------------------------------------------------------------------
146138
// Error types
147139
// ----------------------------------------------------------------------------
@@ -186,8 +178,6 @@ service KclvmService {
186178
rpc LintPath(LintPath_Args) returns(LintPath_Result);
187179
rpc OverrideFile(OverrideFile_Args) returns (OverrideFile_Result);
188180
189-
rpc GetSchemaType(GetSchemaType_Args) returns(GetSchemaType_Result);
190-
rpc GetFullSchemaType(GetFullSchemaType_Args) returns(GetSchemaType_Result);
191181
rpc GetSchemaTypeMapping(GetSchemaTypeMapping_Args) returns(GetSchemaTypeMapping_Result);
192182
rpc ValidateCode(ValidateCode_Args) returns(ValidateCode_Result);
193183
@@ -198,6 +188,8 @@ service KclvmService {
198188
rpc RenameCode(RenameCode_Args) returns(RenameCode_Result);
199189
200190
rpc Test(Test_Args) returns (Test_Result);
191+
192+
rpc UpdateDependencies(UpdateDependencies_Args) returns (UpdateDependencies_Result);
201193
}
202194
203195
message Ping_Args {
@@ -217,7 +209,7 @@ message ListMethod_Result {
217209
message ParseFile_Args {
218210
string path = 1;
219211
string source = 2;
220-
repeated CmdExternalPkgSpec external_pkgs = 3; // External packages path
212+
repeated ExternalPkg external_pkgs = 3; // External packages path
221213
}
222214
223215
message ParseFile_Result {
@@ -229,7 +221,7 @@ message ParseFile_Result {
229221
message ParseProgram_Args {
230222
repeated string paths = 1;
231223
repeated string sources = 2;
232-
repeated CmdExternalPkgSpec external_pkgs = 3; // External packages path
224+
repeated ExternalPkg external_pkgs = 3; // External packages path
233225
}
234226
235227
message ParseProgram_Result {
@@ -304,9 +296,9 @@ message ExecProgram_Args {
304296
305297
repeated string k_filename_list = 2;
306298
repeated string k_code_list = 3;
307-
308-
repeated CmdArgSpec args = 4;
309-
repeated CmdOverrideSpec overrides = 5;
299+
300+
repeated Argument args = 4;
301+
repeated string overrides = 5;
310302
311303
bool disable_yaml_result = 6;
312304
@@ -327,7 +319,7 @@ message ExecProgram_Args {
327319
bool sort_keys = 12;
328320
329321
// -E --external : external packages path
330-
repeated CmdExternalPkgSpec external_pkgs = 13;
322+
repeated ExternalPkg external_pkgs = 13;
331323
332324
// Whether including schema type in JSON/YAML result
333325
bool include_schema_type_path = 14;
@@ -405,6 +397,7 @@ message OverrideFile_Args {
405397
406398
message OverrideFile_Result {
407399
bool result = 1;
400+
repeated Error parse_errors = 2;
408401
}
409402
410403
message ListVariables_Args {
@@ -414,31 +407,26 @@ message ListVariables_Args {
414407
415408
message ListVariables_Result {
416409
map<string, Variable> variables = 1;
417-
repeated string unsupported_codes = 2;
410+
repeated string unsupported_codes = 2;
411+
repeated Error parse_errors = 3;
418412
}
419413
420414
message Variable {
421415
string value = 1;
416+
string type_name = 2;
417+
string op_sym = 3;
418+
repeated Variable list_items = 4;
419+
repeated MapEntry dict_entries = 5;
422420
}
423421
424-
message GetFullSchemaType_Args {
425-
ExecProgram_Args exec_args = 1;
426-
string schema_name = 2;
427-
}
428-
429-
message GetSchemaType_Args {
430-
string file = 1;
431-
string code = 2;
432-
string schema_name = 3;
433-
}
434-
message GetSchemaType_Result {
435-
repeated KclType schema_type_list = 1;
422+
message MapEntry {
423+
string key = 1;
424+
Variable value = 2;
436425
}
437426
438427
message GetSchemaTypeMapping_Args {
439-
string file = 1;
440-
string code = 2;
441-
string schema_name = 3;
428+
ExecProgram_Args exec_args = 1;
429+
string schema_name = 2;
442430
}
443431
message GetSchemaTypeMapping_Result {
444432
map<string, KclType> schema_type_mapping = 1;
@@ -568,6 +556,20 @@ message TestCaseInfo {
568556
string log_message = 4;
569557
}
570558
559+
// ---------------------------------------------------------------------------------
560+
// UpdateDependencies API
561+
// Download and update dependencies defined in the kcl.mod file
562+
// ---------------------------------------------------------------------------------
563+
564+
message UpdateDependencies_Args {
565+
string manifest_path = 1;
566+
bool vendor = 2;
567+
}
568+
569+
message UpdateDependencies_Result {
570+
repeated ExternalPkg external_pkgs = 3;
571+
}
572+
571573
// ----------------------------------------------------------------------------
572574
// KCL Type Structure
573575
// ----------------------------------------------------------------------------
@@ -593,6 +595,7 @@ message KclType {
593595
string pkg_path = 13; // `pkg_path` represents the path name of the package where the attribute is located.
594596
string description = 14; // `description` represents the document of the attribute.
595597
map<string, Example> examples = 15; // A map object to hold examples, the key is the example name.
598+
KclType base_schema = 16; // contains referenced by info for schema
596599
}
597600
598601
message Decorator {

‎docs/reference/xlang-api/rust-api.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,3 +28,10 @@ fn main() -> Result<()> {
2828
Ok(())
2929
}
3030
```
31+
32+
More Rust APIs can be found [here](https://github.com/kcl-lang/kcl). If you want to use the sub crate of KCL Rust core, you can run the following command.
33+
34+
```shell
35+
# Take the kclvm-runtime as an example.
36+
cargo add --git https://github.com/kcl-lang/kcl kclvm-runtime
37+
```

‎docs/user_docs/guides/automation.md

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -78,14 +78,17 @@ kcl main.k -O override_spec
7878
- `override_spec` represents a unified representation of the configuration model fields and values that need to be modified
7979

8080
```bash
81-
override_spec: [[pkgpath] ":"] identifier ("=" value | "-")
81+
override_spec: identifier (("=" | ":" | "+=") value | "-")
8282
```
8383

84-
- `pkgpath`: indicates the package path where the identifier needs to be modified, usually in the form of `a.b.c`. For the main package,`pkgpath` is represented as `__ main__`. When omitted or not written, it indicates the main package
8584
- `identifier` indicates the identifier that needs to modify the configuration, usually in the form of `a.b.c` or `a["dot.key"].c`
8685
- `value` indicates the value of the configuration that needs to be modified, which can be any legal KCL expression, such as number/string literal value, list/dict/schema expression, etc.
87-
- `=` denotes modifying of the value of the identifier.
86+
- `=`, `:` and `+=` denotes modifying of the value of the identifier with the corresponding attribute operator.
87+
- When the identifier exists, modify the value of the existing identifier to value.
88+
- When identifier does not exist, add the identifier attribute and set its value to value.
8889
- `-` denotes deleting of the identifier.
90+
- When the identifier exists, delete it directly.
91+
- When the identifier does not exist, no modification is made to the configuration.
8992

9093
#### Override Configuration
9194

‎i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/lang/tour.md

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3182,14 +3182,13 @@ kcl main.k -O override_spec
31823182

31833183
- `override_spec`: 表示需要修改的配置模型字段和值的统一表示
31843184

3185-
```txt
3186-
override_spec: [[pkgpath] ":"] identifier ("=" value | "-")
3185+
```bash
3186+
override_spec: identifier (("=" | ":" | "+=") value | "-")
31873187
```
31883188

3189-
- `pkgpath`: 表示需要修改标识符的包路径，通常为 `a.b.c` 的形式，对于 main 包，`pkgpath` 表示为 `__main__`, 可省略，省略不写时表示 main 包
3190-
- `identifier`: 表示需要修改配置的标识符，通常为 `a.b.c` 的形式
3189+
- `identifier`: 表示需要修改配置的标识符，通常为 `a.b.c` 或者 `a["dot.key"].c` 的形式
31913190
- `value`: 表示需要修改配置的值，可以是任意合法的 KCL 表达式，比如数字/字符串字面值，list/dict/schema 表达式等
3192-
- `=`: 表示修改identifier的值
3191+
- `=`, `-` 和 `+=`: 表示用对应的属性运算符修改 identifier 的值
31933192
- 当 identifier 存在时，修改已有 identifier的值为 value
31943193
- 当 identifier 不存在时，添加 identifier属性，并将其值设置为 value
31953194
- `-`: 表示删除 identifier属性

0 commit comments

Comments
 (0)