diff --git a/docs/reference/xlang-api/go-api.md b/docs/reference/xlang-api/go-api.md index 2a978250..cdbc09f2 100644 --- a/docs/reference/xlang-api/go-api.md +++ b/docs/reference/xlang-api/go-api.md @@ -4,6 +4,8 @@ sidebar_position: 3 # Go API + + ```go import kcl "kcl-lang.io/kcl-go" ``` @@ -12,7 +14,7 @@ import kcl "kcl-lang.io/kcl-go" ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ -│ kcl files │ │ KCL-Go-API │ │ KCLResultList │ +│ kcl files │ │ KCL-Go-API │ │ KCLResultList │ │ ┌───────────┐ │ │ │ │ │ │ │ 1.k │ │ │ │ │ │ │ └───────────┘ │ │ │ │ ┌───────────┐ │ ┌───────────────┐ @@ -40,7 +42,15 @@ import kcl "kcl-lang.io/kcl-go"

```go -{ +package main + +import ( + "fmt" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { const k_code = ` name = "kcl" age = 1 @@ -85,39 +95,50 @@ x1 = Person { ## Index - [Go API](#go-api) - - [KCL Go SDK](#kcl-go-sdk) - - [Index](#index) - - [Constants](#constants) - - [func FormatCode](#func-formatcode) - - [func FormatPath](#func-formatpath) - - [func InitKclvmPath](#func-initkclvmpath) - - [func InitKclvmRuntime](#func-initkclvmruntime) - - [func LintPath](#func-lintpath) - - [func ListDepFiles](#func-listdepfiles) - - [func ListDownStreamFiles](#func-listdownstreamfiles) - - [func ListUpStreamFiles](#func-listupstreamfiles) - - [func OverrideFile](#func-overridefile) - - [func ValidateCode](#func-validatecode) - - [type KCLResult](#type-kclresult) - - [type KCLResultList](#type-kclresultlist) - - [func MustRun](#func-mustrun) - - [func Run](#func-run) - - [func RunFiles](#func-runfiles) - - [type KclType](#type-kcltype) - - [func GetSchemaType](#func-getschematype) - - [type ListDepFilesOption](#type-listdepfilesoption) - - [type ListDepsOptions](#type-listdepsoptions) - - [type Option](#type-option) - - [func WithCode](#func-withcode) - - [func WithDisableNone](#func-withdisablenone) - - [func WithKFilenames](#func-withkfilenames) - - [func WithOptions](#func-withoptions) - - [func WithOverrides](#func-withoverrides) - - [func WithPrintOverridesAST](#func-withprintoverridesast) - - [func WithSettings](#func-withsettings) - - [func WithSortKeys](#func-withsortkeys) - - [func WithWorkDir](#func-withworkdir) - - [type ValidateOptions](#type-validateoptions) + - [KCL Go SDK](#kcl-go-sdk) + - [Index](#index) + - [Constants](#constants) + - [func FormatCode](#func-formatcode) + - [func FormatPath](#func-formatpath) + - [func GetSchemaTypeMapping](#func-getschematypemapping) + - [func InitKclvmPath](#func-initkclvmpath) + - [func InitKclvmRuntime](#func-initkclvmruntime) + - [func LintPath](#func-lintpath) + - [func ListDepFiles](#func-listdepfiles) + - [func ListDownStreamFiles](#func-listdownstreamfiles) + - [func ListUpStreamFiles](#func-listupstreamfiles) + - [func OverrideFile](#func-overridefile) + - [func Validate](#func-validate) + - [func ValidateCode](#func-validatecode) + - [type KCLResult](#type-kclresult) + - [type KCLResultList](#type-kclresultlist) + - [func MustRun](#func-mustrun) + - [func Run](#func-run) + - [func RunFiles](#func-runfiles) + - [type KclType](#type-kcltype) + - [func GetSchemaType](#func-getschematype) + - [type ListDepFilesOption](#type-listdepfilesoption) + - [type ListDepsOptions](#type-listdepsoptions) + - [type Option](#type-option) + - [func WithCode](#func-withcode) + - [func WithDisableNone](#func-withdisablenone) + - [func WithExternalPkgs](#func-withexternalpkgs) + - [func WithIncludeSchemaTypePath](#func-withincludeschematypepath) + - [func WithKFilenames](#func-withkfilenames) + - [func WithLogger](#func-withlogger) + - [func WithOptions](#func-withoptions) + - [func WithOverrides](#func-withoverrides) + - [func WithPrintOverridesAST](#func-withprintoverridesast) + - [func WithSelectors](#func-withselectors) + - [func WithSettings](#func-withsettings) + - [func WithSortKeys](#func-withsortkeys) + - [func WithWorkDir](#func-withworkdir) + - [type TestCaseInfo](#type-testcaseinfo) + - [type TestOptions](#type-testoptions) + - [type TestResult](#type-testresult) + - [func Test](#func-test) + - [type ValidateOptions](#type-validateoptions) + ## Constants @@ -127,7 +148,7 @@ KclvmAbiVersion is the current kclvm ABI version. const KclvmAbiVersion = scripts.KclvmAbiVersion ``` -## func [FormatCode](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L110) +## func [FormatCode]() ```go func FormatCode(code interface{}) ([]byte, error) @@ -138,8 +159,19 @@ FormatCode returns the formatted code.

Example

+ + ```go -{ +package main + +import ( + "fmt" + "log" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { out, err := kcl.FormatCode(`a = 1+2`) if err != nil { log.Fatal(err) @@ -149,6 +181,8 @@ FormatCode returns the formatted code. } ``` + + ``` a = 1 + 2 ``` @@ -156,7 +190,7 @@ a = 1 + 2

-## func [FormatPath](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L122) +## func [FormatPath]() ```go func FormatPath(path string) (changedPaths []string, err error) @@ -169,8 +203,19 @@ the returned changedPaths are the changed file paths \(relative path\)
Example

+ + ```go -{ +package main + +import ( + "fmt" + "log" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { changedPaths, err := kcl.FormatPath("testdata/fmt") if err != nil { log.Fatal(err) @@ -182,7 +227,33 @@ the returned changedPaths are the changed file paths \(relative path\)

-## func [InitKclvmPath](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L54) +## func [GetSchemaTypeMapping]() + +```go +func GetSchemaTypeMapping(file, code, schemaName string) (map[string]*KclType, error) +``` + +GetSchemaTypeMapping returns a \:\ mapping of schema types from a kcl file or code. + +file: string + +``` +The kcl filename +``` + +code: string + +``` +The kcl code string +``` + +schema\_name: string + +``` +The schema name got, when the schema name is empty, all schemas are returned. +``` + +## func [InitKclvmPath]() ```go func InitKclvmPath(kclvmRoot string) @@ -190,7 +261,7 @@ func InitKclvmPath(kclvmRoot string) InitKclvmPath init kclvm path. -## func [InitKclvmRuntime](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L59) +## func [InitKclvmRuntime]() ```go func InitKclvmRuntime(n int) @@ -198,7 +269,7 @@ func InitKclvmRuntime(n int) InitKclvmRuntime init kclvm process. -## func [LintPath](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L142) +## func [LintPath]() ```go func LintPath(paths []string) (results []string, err error) @@ -210,7 +281,18 @@ LintPath lint files from the given path

```go -{ +package main + +import ( + "fmt" + "log" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { + // import a + // import a # reimport results, err := kcl.LintPath([]string{"testdata/lint/import.k"}) if err != nil { @@ -226,12 +308,13 @@ LintPath lint files from the given path ``` Module 'a' is reimported multiple times Module 'a' imported but unused +Module 'a' imported but unused ```

-## func [ListDepFiles](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L127) +## func [ListDepFiles]() ```go func ListDepFiles(workDir string, opt *ListDepFilesOption) (files []string, err error) @@ -239,7 +322,7 @@ func ListDepFiles(workDir string, opt *ListDepFilesOption) (files []string, err ListDepFiles return the depend files from the given path -## func [ListDownStreamFiles](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L137) +## func [ListDownStreamFiles]() ```go func ListDownStreamFiles(workDir string, opt *ListDepsOptions) ([]string, error) @@ -247,7 +330,7 @@ func ListDownStreamFiles(workDir string, opt *ListDepsOptions) ([]string, error) ListDownStreamFiles return a list of downstream depend files from the given changed path list. -## func [ListUpStreamFiles](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L132) +## func [ListUpStreamFiles]() ```go func ListUpStreamFiles(workDir string, opt *ListDepsOptions) (deps []string, err error) @@ -255,7 +338,7 @@ func ListUpStreamFiles(workDir string, opt *ListDepsOptions) (deps []string, err ListUpStreamFiles return a list of upstream depend files from the given path list -## func [OverrideFile](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L154) +## func [OverrideFile]() ```go func OverrideFile(file string, specs, importPaths []string) (bool, error) @@ -270,15 +353,24 @@ When the pkgpath is '__main__', it can be omitted. importPaths. List of import statements that need to be added -## func [ValidateCode](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L159) +## func [Validate]() ```go -func ValidateCode(data, code string, opt *ValidateOptions) (ok bool, err error) +func Validate(dataFile, schemaFile string, opts *ValidateOptions) (ok bool, err error) ``` -ValidateCode validate data match code +Validate validates the given data file against the specified schema file with the provided options. + +## func [ValidateCode]() + +```go +func ValidateCode(data, code string, opts *ValidateOptions) (ok bool, err error) +``` + +ValidateCode validate data string match code string + +## type [KCLResult]() -## type [KCLResult](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L47) ```go type KCLResult = kcl.KCLResult @@ -288,13 +380,21 @@ type KCLResult = kcl.KCLResult

```go -{ +package main + +import ( + "fmt" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { const k_code = ` name = "kcl" age = 1 - + two = 2 - + schema Person: name: str = "kcl" age: int = 1 @@ -323,7 +423,15 @@ x1.age: 101

```go -{ +package main + +import ( + "fmt" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { const k_code = ` schema Person: name: str = "kcl" @@ -356,13 +464,13 @@ person: {Name:kcl Age:101}

-## type [KCLResultList](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L48) +## type [KCLResultList]() ```go type KCLResultList = kcl.KCLResultList ``` -### func [MustRun](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L64) +### func [MustRun]() ```go func MustRun(path string, opts ...Option) *KCLResultList @@ -374,7 +482,15 @@ MustRun is like Run but panics if return any error.

```go -{ +package main + +import ( + "fmt" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { yaml := kcl.MustRun("testdata/main.k", kcl.WithCode(`name = "kcl"`)).First().YAMLString() fmt.Println(yaml) @@ -392,7 +508,15 @@ name: kcl

```go -{ +package main + +import ( + "fmt" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { const code = ` b = 1 a = 2 @@ -420,7 +544,15 @@ b: 1

```go -{ +package main + +import ( + "fmt" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { const code = ` schema Person: name: str = "" @@ -447,8 +579,18 @@ x = Person()

Example (Settings)

+ + ```go -{ +package main + +import ( + "fmt" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { yaml := kcl.MustRun("./testdata/app0/kcl.yaml").First().YAMLString() fmt.Println(yaml) } @@ -457,7 +599,7 @@ x = Person()

-### func [Run](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L69) +### func [Run]() ```go func Run(path string, opts ...Option) (*KCLResultList, error) @@ -468,12 +610,31 @@ Run evaluates the KCL program with path and opts, then returns the object list.
Example (Get Field)

+ + ```go -{ +package main + +import ( + "fmt" + "log" + + kcl "kcl-lang.io/kcl-go" +) + +func assert(v bool, a ...interface{}) { + if !v { + a = append([]interface{}{"assert failed"}, a...) + log.Panic(a...) + } +} +func main() { + // run kcl.yaml x, err := kcl.Run("./testdata/app0/kcl.yaml") assert(err == nil, err) + // print deploy_topology[1].zone fmt.Println(x.First().Get("deploy_topology.1.zone")) } @@ -486,7 +647,7 @@ R000A

-### func [RunFiles](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L74) +### func [RunFiles]() ```go func RunFiles(paths []string, opts ...Option) (*KCLResultList, error) @@ -498,7 +659,15 @@ RunFiles evaluates the KCL program with multi file path and opts, then returns t

```go -{ +package main + +import ( + "fmt" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { result, _ := kcl.RunFiles([]string{"./testdata/app0/kcl.yaml"}) fmt.Println(result.First().YAMLString()) } @@ -507,13 +676,13 @@ RunFiles evaluates the KCL program with multi file path and opts, then returns t

-## type [KclType](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L50) +## type [KclType]() ```go type KclType = kcl.KclType ``` -### func [GetSchemaType](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L176) +### func [GetSchemaType]() ```go func GetSchemaType(file, code, schemaName string) ([]*KclType, error) @@ -533,31 +702,31 @@ code: string The kcl code string ``` -schema_name: string +schema\_name: string ``` The schema name got, when the schema name is empty, all schemas are returned. ``` -## type [ListDepFilesOption](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L45) +## type [ListDepFilesOption]() ```go type ListDepFilesOption = list.Option ``` -## type [ListDepsOptions](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L44) +## type [ListDepsOptions]() ```go type ListDepsOptions = list.DepOptions ``` -## type [Option](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L43) +## type [Option]() ```go type Option = kcl.Option ``` -### func [WithCode](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L79) +### func [WithCode]() ```go func WithCode(codes ...string) Option @@ -565,7 +734,7 @@ func WithCode(codes ...string) Option WithCode returns a Option which hold a kcl source code list. -### func [WithDisableNone](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L97) +### func [WithDisableNone]() ```go func WithDisableNone(disableNone bool) Option @@ -573,7 +742,23 @@ func WithDisableNone(disableNone bool) Option WithDisableNone returns a Option which hold a disable none switch. -### func [WithKFilenames](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L82) +### func [WithExternalPkgs]() + +```go +func WithExternalPkgs(externalPkgs ...string) Option +``` + +WithExternalPkgs returns a Option which hold a external package list. + +### func [WithIncludeSchemaTypePath]() + +```go +func WithIncludeSchemaTypePath(includeSchemaTypePath bool) Option +``` + +WithIncludeSchemaTypePath returns a Option which hold a include schema type path switch. + +### func [WithKFilenames]() ```go func WithKFilenames(filenames ...string) Option @@ -581,7 +766,15 @@ func WithKFilenames(filenames ...string) Option WithKFilenames returns a Option which hold a filenames list. -### func [WithOptions](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L85) +### func [WithLogger]() + +```go +func WithLogger(l io.Writer) Option +``` + +WithLogger returns a Option which hold a logger. + +### func [WithOptions]() ```go func WithOptions(key_value_list ...string) Option @@ -592,8 +785,19 @@ WithOptions returns a Option which hold a key=value pair list for option functio
Example

+ + ```go -{ +package main + +import ( + "fmt" + "log" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { const code = ` name = option("name") age = option("age") @@ -618,7 +822,7 @@ name: kcl

-### func [WithOverrides](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L88) +### func [WithOverrides]() ```go func WithOverrides(override_list ...string) Option @@ -626,7 +830,7 @@ func WithOverrides(override_list ...string) Option WithOverrides returns a Option which hold a override list. -### func [WithPrintOverridesAST](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L100) +### func [WithPrintOverridesAST]() ```go func WithPrintOverridesAST(printOverridesAST bool) Option @@ -634,7 +838,15 @@ func WithPrintOverridesAST(printOverridesAST bool) Option WithPrintOverridesAST returns a Option which hold a printOverridesAST switch. -### func [WithSettings](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L91) +### func [WithSelectors]() + +```go +func WithSelectors(selectors ...string) Option +``` + +WithSelectors returns a Option which hold a path selector list. + +### func [WithSettings]() ```go func WithSettings(filename string) Option @@ -642,7 +854,7 @@ func WithSettings(filename string) Option WithSettings returns a Option which hold a settings file. -### func [WithSortKeys](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L105) +### func [WithSortKeys]() ```go func WithSortKeys(sortKeys bool) Option @@ -650,7 +862,7 @@ func WithSortKeys(sortKeys bool) Option WithSortKeys returns a Option which hold a sortKeys switch. -### func [WithWorkDir](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L94) +### func [WithWorkDir]() ```go func WithWorkDir(workDir string) Option @@ -658,7 +870,39 @@ func WithWorkDir(workDir string) Option WithWorkDir returns a Option which hold a work dir. -## type [ValidateOptions](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L46) +## type [TestCaseInfo]() + +```go +type TestCaseInfo = testing.TestCaseInfo +``` + +## type [TestOptions]() + + + +```go +type TestOptions = testing.TestOptions +``` + +## type [TestResult]() + + + +```go +type TestResult = testing.TestResult +``` + +### func [Test]() + +```go +func Test(testOpts *TestOptions, opts ...Option) (TestResult, error) +``` + +Test calls the test tool to run uni tests in packages. + +## type [ValidateOptions]() + + ```go type ValidateOptions = validate.ValidateOptions diff --git a/docs/reference/xlang-api/rest-api.md b/docs/reference/xlang-api/rest-api.md index d15101ff..17966c5a 100644 --- a/docs/reference/xlang-api/rest-api.md +++ b/docs/reference/xlang-api/rest-api.md @@ -117,7 +117,6 @@ Cross-language APIs defined via Protobuf([https://github.com/kcl-lang/kcl-go/blo // Copyright 2023 The KCL Authors. All rights reserved. // // This file defines the request parameters and return structure of the KCL RPC server. -// We can use the following command to start a KCL RPC server. syntax = "proto3"; @@ -128,6 +127,12 @@ import "google/protobuf/descriptor.proto"; // ---------------------------------------------------------------------------- +// kcl main.k -E pkg_name=pkg_path +message CmdExternalPkgSpec { + string pkg_name = 1; + string pkg_path = 2; +} + // kcl main.k -D name=value message CmdArgSpec { string name = 1; @@ -169,7 +174,7 @@ message KclErrorInfo { } // ---------------------------------------------------------------------------- -// service request/response +// service requset/response // ---------------------------------------------------------------------------- // gpyrpc.BuiltinService @@ -190,11 +195,17 @@ service KclvmService { rpc OverrideFile(OverrideFile_Args) returns (OverrideFile_Result); rpc GetSchemaType(GetSchemaType_Args) returns(GetSchemaType_Result); + rpc GetFullSchemaType(GetFullSchemaType_Args) returns(GetSchemaType_Result); rpc GetSchemaTypeMapping(GetSchemaTypeMapping_Args) returns(GetSchemaTypeMapping_Result); rpc ValidateCode(ValidateCode_Args) returns(ValidateCode_Result); rpc ListDepFiles(ListDepFiles_Args) returns(ListDepFiles_Result); rpc LoadSettingsFiles(LoadSettingsFiles_Args) returns(LoadSettingsFiles_Result); + + rpc Rename(Rename_Args) returns(Rename_Result); + rpc RenameCode(RenameCode_Args) returns(RenameCode_Result); + + rpc Test(Test_Args) returns (Test_Result); } message Ping_Args { @@ -233,7 +244,7 @@ message ExecProgram_Args { repeated string k_filename_list = 2; repeated string k_code_list = 3; - + repeated CmdArgSpec args = 4; repeated CmdOverrideSpec overrides = 5; @@ -254,14 +265,28 @@ message ExecProgram_Args { // yaml/json: sort keys bool sort_keys = 12; - // include schema type path in JSON/YAML result - bool include_schema_type_path = 13; + + // -E --external : external packages path + repeated CmdExternalPkgSpec external_pkgs = 13; + + // Whether including schema type in JSON/YAML result + bool include_schema_type_path = 14; + + // Whether only compiling the program + bool compile_only = 15; + + // Compile the dir recursively + bool recursive = 16; + + // -S --path_selector + repeated string path_selector = 17; } + message ExecProgram_Result { string json_result = 1; string yaml_result = 2; - - string escaped_time = 101; + string log_message = 3; + string err_message = 4; } message ResetPlugin_Args { @@ -305,19 +330,9 @@ message OverrideFile_Result { bool result = 1; } -message EvalCode_Args { - string code = 1; -} -message EvalCode_Result { - string json_result = 2; -} - -message ResolveCode_Args { - string code = 1; -} - -message ResolveCode_Result { - bool success = 1; +message GetFullSchemaType_Args { + ExecProgram_Args exec_args = 1; + string schema_name = 2; } message GetSchemaType_Args { @@ -394,6 +409,8 @@ message CliConfig { bool disable_none = 6; int64 verbose = 7; bool debug = 8; + bool sort_keys = 9; + bool include_schema_type_path = 10; } message KeyValuePair { @@ -401,8 +418,61 @@ message KeyValuePair { string value = 2; } +// --------------------------------------------------------------------------------- +// Rename API +// find all the occurrences of the target symbol and rename them. This API will rewrite files if they contain symbols to be renamed. +// --------------------------------------------------------------------------------- + +message Rename_Args { + string symbol_path = 1; // the path to the target symbol to be renamed. The symbol path should conform to format: `:` When the pkgpath is '__main__', `:` can be omitted. + repeated string file_paths = 2; // the paths to the source code files + string new_name = 3; // the new name of the symbol +} + +message Rename_Result { + repeated string changed_files = 1; // the file paths got changed +} + +// --------------------------------------------------------------------------------- +// RenameCode API +// find all the occurrences of the target symbol and rename them. This API won't rewrite files but return the modified code if any code has been changed. +// --------------------------------------------------------------------------------- + +message RenameCode_Args { + string symbol_path = 1; // the path to the target symbol to be renamed. The symbol path should conform to format: `:` When the pkgpath is '__main__', `:` can be omitted. + map source_codes = 2; // the source code. a : map + string new_name = 3; // the new name of the symbol +} + +message RenameCode_Result { + map changed_codes = 1; // the changed code. a : map +} + +// --------------------------------------------------------------------------------- +// Test API +// Test KCL packages with test arguments +// --------------------------------------------------------------------------------- + +message Test_Args { + ExecProgram_Args exec_args = 1; // This field stores the execution program arguments. + repeated string pkg_list = 2; // The package path list to be tested e.g., "./...", "/path/to/package/", "/path/to/package/..." + string run_regexp = 3; // This field stores a regular expression for filtering tests to run. + bool fail_fast = 4; // This field determines whether the test run should stop on the first failure. +} + +message Test_Result { + repeated TestCaseInfo info = 2; +} + +message TestCaseInfo { + string name = 1; // Test case name + string error = 2; + uint64 duration = 3; // Number of whole microseconds in the duration. + string log_message = 4; +} + // ---------------------------------------------------------------------------- -// JSON Schema Lit +// KCL Type Structure // ---------------------------------------------------------------------------- message KclType { @@ -421,6 +491,11 @@ message KclType { int32 line = 10; repeated Decorator decorators = 11; // schema decorators + + string filename = 12; // `filename` represents the absolute path of the file name where the attribute is located. + string pkg_path = 13; // `pkg_path` represents the path name of the package where the attribute is located. + string description = 14; // `description` represents the document of the attribute. + map examples = 15; // A map object to hold examples, the key is the example name. } message Decorator { @@ -429,6 +504,12 @@ message Decorator { map keywords = 3; } +message Example { + string summary = 1; // Short description for the example. + string description = 2; // Long description for the example. + string value = 3; // Embedded literal example. +} + // ---------------------------------------------------------------------------- // END // ---------------------------------------------------------------------------- diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/xlang-api/go-api.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/xlang-api/go-api.md index 2a978250..cdbc09f2 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/xlang-api/go-api.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/xlang-api/go-api.md @@ -4,6 +4,8 @@ sidebar_position: 3 # Go API + + ```go import kcl "kcl-lang.io/kcl-go" ``` @@ -12,7 +14,7 @@ import kcl "kcl-lang.io/kcl-go" ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ -│ kcl files │ │ KCL-Go-API │ │ KCLResultList │ +│ kcl files │ │ KCL-Go-API │ │ KCLResultList │ │ ┌───────────┐ │ │ │ │ │ │ │ 1.k │ │ │ │ │ │ │ └───────────┘ │ │ │ │ ┌───────────┐ │ ┌───────────────┐ @@ -40,7 +42,15 @@ import kcl "kcl-lang.io/kcl-go"

```go -{ +package main + +import ( + "fmt" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { const k_code = ` name = "kcl" age = 1 @@ -85,39 +95,50 @@ x1 = Person { ## Index - [Go API](#go-api) - - [KCL Go SDK](#kcl-go-sdk) - - [Index](#index) - - [Constants](#constants) - - [func FormatCode](#func-formatcode) - - [func FormatPath](#func-formatpath) - - [func InitKclvmPath](#func-initkclvmpath) - - [func InitKclvmRuntime](#func-initkclvmruntime) - - [func LintPath](#func-lintpath) - - [func ListDepFiles](#func-listdepfiles) - - [func ListDownStreamFiles](#func-listdownstreamfiles) - - [func ListUpStreamFiles](#func-listupstreamfiles) - - [func OverrideFile](#func-overridefile) - - [func ValidateCode](#func-validatecode) - - [type KCLResult](#type-kclresult) - - [type KCLResultList](#type-kclresultlist) - - [func MustRun](#func-mustrun) - - [func Run](#func-run) - - [func RunFiles](#func-runfiles) - - [type KclType](#type-kcltype) - - [func GetSchemaType](#func-getschematype) - - [type ListDepFilesOption](#type-listdepfilesoption) - - [type ListDepsOptions](#type-listdepsoptions) - - [type Option](#type-option) - - [func WithCode](#func-withcode) - - [func WithDisableNone](#func-withdisablenone) - - [func WithKFilenames](#func-withkfilenames) - - [func WithOptions](#func-withoptions) - - [func WithOverrides](#func-withoverrides) - - [func WithPrintOverridesAST](#func-withprintoverridesast) - - [func WithSettings](#func-withsettings) - - [func WithSortKeys](#func-withsortkeys) - - [func WithWorkDir](#func-withworkdir) - - [type ValidateOptions](#type-validateoptions) + - [KCL Go SDK](#kcl-go-sdk) + - [Index](#index) + - [Constants](#constants) + - [func FormatCode](#func-formatcode) + - [func FormatPath](#func-formatpath) + - [func GetSchemaTypeMapping](#func-getschematypemapping) + - [func InitKclvmPath](#func-initkclvmpath) + - [func InitKclvmRuntime](#func-initkclvmruntime) + - [func LintPath](#func-lintpath) + - [func ListDepFiles](#func-listdepfiles) + - [func ListDownStreamFiles](#func-listdownstreamfiles) + - [func ListUpStreamFiles](#func-listupstreamfiles) + - [func OverrideFile](#func-overridefile) + - [func Validate](#func-validate) + - [func ValidateCode](#func-validatecode) + - [type KCLResult](#type-kclresult) + - [type KCLResultList](#type-kclresultlist) + - [func MustRun](#func-mustrun) + - [func Run](#func-run) + - [func RunFiles](#func-runfiles) + - [type KclType](#type-kcltype) + - [func GetSchemaType](#func-getschematype) + - [type ListDepFilesOption](#type-listdepfilesoption) + - [type ListDepsOptions](#type-listdepsoptions) + - [type Option](#type-option) + - [func WithCode](#func-withcode) + - [func WithDisableNone](#func-withdisablenone) + - [func WithExternalPkgs](#func-withexternalpkgs) + - [func WithIncludeSchemaTypePath](#func-withincludeschematypepath) + - [func WithKFilenames](#func-withkfilenames) + - [func WithLogger](#func-withlogger) + - [func WithOptions](#func-withoptions) + - [func WithOverrides](#func-withoverrides) + - [func WithPrintOverridesAST](#func-withprintoverridesast) + - [func WithSelectors](#func-withselectors) + - [func WithSettings](#func-withsettings) + - [func WithSortKeys](#func-withsortkeys) + - [func WithWorkDir](#func-withworkdir) + - [type TestCaseInfo](#type-testcaseinfo) + - [type TestOptions](#type-testoptions) + - [type TestResult](#type-testresult) + - [func Test](#func-test) + - [type ValidateOptions](#type-validateoptions) + ## Constants @@ -127,7 +148,7 @@ KclvmAbiVersion is the current kclvm ABI version. const KclvmAbiVersion = scripts.KclvmAbiVersion ``` -## func [FormatCode](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L110) +## func [FormatCode]() ```go func FormatCode(code interface{}) ([]byte, error) @@ -138,8 +159,19 @@ FormatCode returns the formatted code.

Example

+ + ```go -{ +package main + +import ( + "fmt" + "log" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { out, err := kcl.FormatCode(`a = 1+2`) if err != nil { log.Fatal(err) @@ -149,6 +181,8 @@ FormatCode returns the formatted code. } ``` + + ``` a = 1 + 2 ``` @@ -156,7 +190,7 @@ a = 1 + 2

-## func [FormatPath](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L122) +## func [FormatPath]() ```go func FormatPath(path string) (changedPaths []string, err error) @@ -169,8 +203,19 @@ the returned changedPaths are the changed file paths \(relative path\)
Example

+ + ```go -{ +package main + +import ( + "fmt" + "log" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { changedPaths, err := kcl.FormatPath("testdata/fmt") if err != nil { log.Fatal(err) @@ -182,7 +227,33 @@ the returned changedPaths are the changed file paths \(relative path\)

-## func [InitKclvmPath](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L54) +## func [GetSchemaTypeMapping]() + +```go +func GetSchemaTypeMapping(file, code, schemaName string) (map[string]*KclType, error) +``` + +GetSchemaTypeMapping returns a \:\ mapping of schema types from a kcl file or code. + +file: string + +``` +The kcl filename +``` + +code: string + +``` +The kcl code string +``` + +schema\_name: string + +``` +The schema name got, when the schema name is empty, all schemas are returned. +``` + +## func [InitKclvmPath]() ```go func InitKclvmPath(kclvmRoot string) @@ -190,7 +261,7 @@ func InitKclvmPath(kclvmRoot string) InitKclvmPath init kclvm path. -## func [InitKclvmRuntime](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L59) +## func [InitKclvmRuntime]() ```go func InitKclvmRuntime(n int) @@ -198,7 +269,7 @@ func InitKclvmRuntime(n int) InitKclvmRuntime init kclvm process. -## func [LintPath](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L142) +## func [LintPath]() ```go func LintPath(paths []string) (results []string, err error) @@ -210,7 +281,18 @@ LintPath lint files from the given path

```go -{ +package main + +import ( + "fmt" + "log" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { + // import a + // import a # reimport results, err := kcl.LintPath([]string{"testdata/lint/import.k"}) if err != nil { @@ -226,12 +308,13 @@ LintPath lint files from the given path ``` Module 'a' is reimported multiple times Module 'a' imported but unused +Module 'a' imported but unused ```

-## func [ListDepFiles](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L127) +## func [ListDepFiles]() ```go func ListDepFiles(workDir string, opt *ListDepFilesOption) (files []string, err error) @@ -239,7 +322,7 @@ func ListDepFiles(workDir string, opt *ListDepFilesOption) (files []string, err ListDepFiles return the depend files from the given path -## func [ListDownStreamFiles](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L137) +## func [ListDownStreamFiles]() ```go func ListDownStreamFiles(workDir string, opt *ListDepsOptions) ([]string, error) @@ -247,7 +330,7 @@ func ListDownStreamFiles(workDir string, opt *ListDepsOptions) ([]string, error) ListDownStreamFiles return a list of downstream depend files from the given changed path list. -## func [ListUpStreamFiles](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L132) +## func [ListUpStreamFiles]() ```go func ListUpStreamFiles(workDir string, opt *ListDepsOptions) (deps []string, err error) @@ -255,7 +338,7 @@ func ListUpStreamFiles(workDir string, opt *ListDepsOptions) (deps []string, err ListUpStreamFiles return a list of upstream depend files from the given path list -## func [OverrideFile](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L154) +## func [OverrideFile]() ```go func OverrideFile(file string, specs, importPaths []string) (bool, error) @@ -270,15 +353,24 @@ When the pkgpath is '__main__', it can be omitted. importPaths. List of import statements that need to be added -## func [ValidateCode](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L159) +## func [Validate]() ```go -func ValidateCode(data, code string, opt *ValidateOptions) (ok bool, err error) +func Validate(dataFile, schemaFile string, opts *ValidateOptions) (ok bool, err error) ``` -ValidateCode validate data match code +Validate validates the given data file against the specified schema file with the provided options. + +## func [ValidateCode]() + +```go +func ValidateCode(data, code string, opts *ValidateOptions) (ok bool, err error) +``` + +ValidateCode validate data string match code string + +## type [KCLResult]() -## type [KCLResult](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L47) ```go type KCLResult = kcl.KCLResult @@ -288,13 +380,21 @@ type KCLResult = kcl.KCLResult

```go -{ +package main + +import ( + "fmt" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { const k_code = ` name = "kcl" age = 1 - + two = 2 - + schema Person: name: str = "kcl" age: int = 1 @@ -323,7 +423,15 @@ x1.age: 101

```go -{ +package main + +import ( + "fmt" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { const k_code = ` schema Person: name: str = "kcl" @@ -356,13 +464,13 @@ person: {Name:kcl Age:101}

-## type [KCLResultList](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L48) +## type [KCLResultList]() ```go type KCLResultList = kcl.KCLResultList ``` -### func [MustRun](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L64) +### func [MustRun]() ```go func MustRun(path string, opts ...Option) *KCLResultList @@ -374,7 +482,15 @@ MustRun is like Run but panics if return any error.

```go -{ +package main + +import ( + "fmt" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { yaml := kcl.MustRun("testdata/main.k", kcl.WithCode(`name = "kcl"`)).First().YAMLString() fmt.Println(yaml) @@ -392,7 +508,15 @@ name: kcl

```go -{ +package main + +import ( + "fmt" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { const code = ` b = 1 a = 2 @@ -420,7 +544,15 @@ b: 1

```go -{ +package main + +import ( + "fmt" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { const code = ` schema Person: name: str = "" @@ -447,8 +579,18 @@ x = Person()

Example (Settings)

+ + ```go -{ +package main + +import ( + "fmt" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { yaml := kcl.MustRun("./testdata/app0/kcl.yaml").First().YAMLString() fmt.Println(yaml) } @@ -457,7 +599,7 @@ x = Person()

-### func [Run](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L69) +### func [Run]() ```go func Run(path string, opts ...Option) (*KCLResultList, error) @@ -468,12 +610,31 @@ Run evaluates the KCL program with path and opts, then returns the object list.
Example (Get Field)

+ + ```go -{ +package main + +import ( + "fmt" + "log" + + kcl "kcl-lang.io/kcl-go" +) + +func assert(v bool, a ...interface{}) { + if !v { + a = append([]interface{}{"assert failed"}, a...) + log.Panic(a...) + } +} +func main() { + // run kcl.yaml x, err := kcl.Run("./testdata/app0/kcl.yaml") assert(err == nil, err) + // print deploy_topology[1].zone fmt.Println(x.First().Get("deploy_topology.1.zone")) } @@ -486,7 +647,7 @@ R000A

-### func [RunFiles](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L74) +### func [RunFiles]() ```go func RunFiles(paths []string, opts ...Option) (*KCLResultList, error) @@ -498,7 +659,15 @@ RunFiles evaluates the KCL program with multi file path and opts, then returns t

```go -{ +package main + +import ( + "fmt" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { result, _ := kcl.RunFiles([]string{"./testdata/app0/kcl.yaml"}) fmt.Println(result.First().YAMLString()) } @@ -507,13 +676,13 @@ RunFiles evaluates the KCL program with multi file path and opts, then returns t

-## type [KclType](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L50) +## type [KclType]() ```go type KclType = kcl.KclType ``` -### func [GetSchemaType](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L176) +### func [GetSchemaType]() ```go func GetSchemaType(file, code, schemaName string) ([]*KclType, error) @@ -533,31 +702,31 @@ code: string The kcl code string ``` -schema_name: string +schema\_name: string ``` The schema name got, when the schema name is empty, all schemas are returned. ``` -## type [ListDepFilesOption](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L45) +## type [ListDepFilesOption]() ```go type ListDepFilesOption = list.Option ``` -## type [ListDepsOptions](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L44) +## type [ListDepsOptions]() ```go type ListDepsOptions = list.DepOptions ``` -## type [Option](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L43) +## type [Option]() ```go type Option = kcl.Option ``` -### func [WithCode](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L79) +### func [WithCode]() ```go func WithCode(codes ...string) Option @@ -565,7 +734,7 @@ func WithCode(codes ...string) Option WithCode returns a Option which hold a kcl source code list. -### func [WithDisableNone](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L97) +### func [WithDisableNone]() ```go func WithDisableNone(disableNone bool) Option @@ -573,7 +742,23 @@ func WithDisableNone(disableNone bool) Option WithDisableNone returns a Option which hold a disable none switch. -### func [WithKFilenames](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L82) +### func [WithExternalPkgs]() + +```go +func WithExternalPkgs(externalPkgs ...string) Option +``` + +WithExternalPkgs returns a Option which hold a external package list. + +### func [WithIncludeSchemaTypePath]() + +```go +func WithIncludeSchemaTypePath(includeSchemaTypePath bool) Option +``` + +WithIncludeSchemaTypePath returns a Option which hold a include schema type path switch. + +### func [WithKFilenames]() ```go func WithKFilenames(filenames ...string) Option @@ -581,7 +766,15 @@ func WithKFilenames(filenames ...string) Option WithKFilenames returns a Option which hold a filenames list. -### func [WithOptions](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L85) +### func [WithLogger]() + +```go +func WithLogger(l io.Writer) Option +``` + +WithLogger returns a Option which hold a logger. + +### func [WithOptions]() ```go func WithOptions(key_value_list ...string) Option @@ -592,8 +785,19 @@ WithOptions returns a Option which hold a key=value pair list for option functio
Example

+ + ```go -{ +package main + +import ( + "fmt" + "log" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { const code = ` name = option("name") age = option("age") @@ -618,7 +822,7 @@ name: kcl

-### func [WithOverrides](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L88) +### func [WithOverrides]() ```go func WithOverrides(override_list ...string) Option @@ -626,7 +830,7 @@ func WithOverrides(override_list ...string) Option WithOverrides returns a Option which hold a override list. -### func [WithPrintOverridesAST](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L100) +### func [WithPrintOverridesAST]() ```go func WithPrintOverridesAST(printOverridesAST bool) Option @@ -634,7 +838,15 @@ func WithPrintOverridesAST(printOverridesAST bool) Option WithPrintOverridesAST returns a Option which hold a printOverridesAST switch. -### func [WithSettings](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L91) +### func [WithSelectors]() + +```go +func WithSelectors(selectors ...string) Option +``` + +WithSelectors returns a Option which hold a path selector list. + +### func [WithSettings]() ```go func WithSettings(filename string) Option @@ -642,7 +854,7 @@ func WithSettings(filename string) Option WithSettings returns a Option which hold a settings file. -### func [WithSortKeys](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L105) +### func [WithSortKeys]() ```go func WithSortKeys(sortKeys bool) Option @@ -650,7 +862,7 @@ func WithSortKeys(sortKeys bool) Option WithSortKeys returns a Option which hold a sortKeys switch. -### func [WithWorkDir](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L94) +### func [WithWorkDir]() ```go func WithWorkDir(workDir string) Option @@ -658,7 +870,39 @@ func WithWorkDir(workDir string) Option WithWorkDir returns a Option which hold a work dir. -## type [ValidateOptions](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L46) +## type [TestCaseInfo]() + +```go +type TestCaseInfo = testing.TestCaseInfo +``` + +## type [TestOptions]() + + + +```go +type TestOptions = testing.TestOptions +``` + +## type [TestResult]() + + + +```go +type TestResult = testing.TestResult +``` + +### func [Test]() + +```go +func Test(testOpts *TestOptions, opts ...Option) (TestResult, error) +``` + +Test calls the test tool to run uni tests in packages. + +## type [ValidateOptions]() + + ```go type ValidateOptions = validate.ValidateOptions diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/xlang-api/rest-api.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/xlang-api/rest-api.md index 446263b4..6330e497 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/xlang-api/rest-api.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/xlang-api/rest-api.md @@ -129,7 +129,6 @@ curl -X POST \ // Copyright 2023 The KCL Authors. All rights reserved. // // This file defines the request parameters and return structure of the KCL RPC server. -// We can use the following command to start a KCL RPC server. syntax = "proto3"; @@ -140,6 +139,12 @@ import "google/protobuf/descriptor.proto"; // ---------------------------------------------------------------------------- +// kcl main.k -E pkg_name=pkg_path +message CmdExternalPkgSpec { + string pkg_name = 1; + string pkg_path = 2; +} + // kcl main.k -D name=value message CmdArgSpec { string name = 1; @@ -202,11 +207,17 @@ service KclvmService { rpc OverrideFile(OverrideFile_Args) returns (OverrideFile_Result); rpc GetSchemaType(GetSchemaType_Args) returns(GetSchemaType_Result); + rpc GetFullSchemaType(GetFullSchemaType_Args) returns(GetSchemaType_Result); rpc GetSchemaTypeMapping(GetSchemaTypeMapping_Args) returns(GetSchemaTypeMapping_Result); rpc ValidateCode(ValidateCode_Args) returns(ValidateCode_Result); rpc ListDepFiles(ListDepFiles_Args) returns(ListDepFiles_Result); rpc LoadSettingsFiles(LoadSettingsFiles_Args) returns(LoadSettingsFiles_Result); + + rpc Rename(Rename_Args) returns(Rename_Result); + rpc RenameCode(RenameCode_Args) returns(RenameCode_Result); + + rpc Test(Test_Args) returns (Test_Result); } message Ping_Args { @@ -245,7 +256,7 @@ message ExecProgram_Args { repeated string k_filename_list = 2; repeated string k_code_list = 3; - + repeated CmdArgSpec args = 4; repeated CmdOverrideSpec overrides = 5; @@ -266,14 +277,28 @@ message ExecProgram_Args { // yaml/json: sort keys bool sort_keys = 12; - // include schema type path in JSON/YAML result - bool include_schema_type_path = 13; + + // -E --external : external packages path + repeated CmdExternalPkgSpec external_pkgs = 13; + + // Whether including schema type in JSON/YAML result + bool include_schema_type_path = 14; + + // Whether only compiling the program + bool compile_only = 15; + + // Compile the dir recursively + bool recursive = 16; + + // -S --path_selector + repeated string path_selector = 17; } + message ExecProgram_Result { string json_result = 1; string yaml_result = 2; - - string escaped_time = 101; + string log_message = 3; + string err_message = 4; } message ResetPlugin_Args { @@ -317,19 +342,9 @@ message OverrideFile_Result { bool result = 1; } -message EvalCode_Args { - string code = 1; -} -message EvalCode_Result { - string json_result = 2; -} - -message ResolveCode_Args { - string code = 1; -} - -message ResolveCode_Result { - bool success = 1; +message GetFullSchemaType_Args { + ExecProgram_Args exec_args = 1; + string schema_name = 2; } message GetSchemaType_Args { @@ -406,6 +421,8 @@ message CliConfig { bool disable_none = 6; int64 verbose = 7; bool debug = 8; + bool sort_keys = 9; + bool include_schema_type_path = 10; } message KeyValuePair { @@ -413,8 +430,61 @@ message KeyValuePair { string value = 2; } +// --------------------------------------------------------------------------------- +// Rename API +// find all the occurrences of the target symbol and rename them. This API will rewrite files if they contain symbols to be renamed. +// --------------------------------------------------------------------------------- + +message Rename_Args { + string symbol_path = 1; // the path to the target symbol to be renamed. The symbol path should conform to format: `:` When the pkgpath is '__main__', `:` can be omitted. + repeated string file_paths = 2; // the paths to the source code files + string new_name = 3; // the new name of the symbol +} + +message Rename_Result { + repeated string changed_files = 1; // the file paths got changed +} + +// --------------------------------------------------------------------------------- +// RenameCode API +// find all the occurrences of the target symbol and rename them. This API won't rewrite files but return the modified code if any code has been changed. +// --------------------------------------------------------------------------------- + +message RenameCode_Args { + string symbol_path = 1; // the path to the target symbol to be renamed. The symbol path should conform to format: `:` When the pkgpath is '__main__', `:` can be omitted. + map source_codes = 2; // the source code. a : map + string new_name = 3; // the new name of the symbol +} + +message RenameCode_Result { + map changed_codes = 1; // the changed code. a : map +} + +// --------------------------------------------------------------------------------- +// Test API +// Test KCL packages with test arguments +// --------------------------------------------------------------------------------- + +message Test_Args { + ExecProgram_Args exec_args = 1; // This field stores the execution program arguments. + repeated string pkg_list = 2; // The package path list to be tested e.g., "./...", "/path/to/package/", "/path/to/package/..." + string run_regexp = 3; // This field stores a regular expression for filtering tests to run. + bool fail_fast = 4; // This field determines whether the test run should stop on the first failure. +} + +message Test_Result { + repeated TestCaseInfo info = 2; +} + +message TestCaseInfo { + string name = 1; // Test case name + string error = 2; + uint64 duration = 3; // Number of whole microseconds in the duration. + string log_message = 4; +} + // ---------------------------------------------------------------------------- -// JSON Schema Lit +// KCL Type Structure // ---------------------------------------------------------------------------- message KclType { @@ -433,6 +503,11 @@ message KclType { int32 line = 10; repeated Decorator decorators = 11; // schema decorators + + string filename = 12; // `filename` represents the absolute path of the file name where the attribute is located. + string pkg_path = 13; // `pkg_path` represents the path name of the package where the attribute is located. + string description = 14; // `description` represents the document of the attribute. + map examples = 15; // A map object to hold examples, the key is the example name. } message Decorator { @@ -441,6 +516,12 @@ message Decorator { map keywords = 3; } +message Example { + string summary = 1; // Short description for the example. + string description = 2; // Long description for the example. + string value = 3; // Embedded literal example. +} + // ---------------------------------------------------------------------------- // END // ---------------------------------------------------------------------------- diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.7.0/reference/xlang-api/go-api.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.7.0/reference/xlang-api/go-api.md index 2a978250..cdbc09f2 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.7.0/reference/xlang-api/go-api.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.7.0/reference/xlang-api/go-api.md @@ -4,6 +4,8 @@ sidebar_position: 3 # Go API + + ```go import kcl "kcl-lang.io/kcl-go" ``` @@ -12,7 +14,7 @@ import kcl "kcl-lang.io/kcl-go" ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ -│ kcl files │ │ KCL-Go-API │ │ KCLResultList │ +│ kcl files │ │ KCL-Go-API │ │ KCLResultList │ │ ┌───────────┐ │ │ │ │ │ │ │ 1.k │ │ │ │ │ │ │ └───────────┘ │ │ │ │ ┌───────────┐ │ ┌───────────────┐ @@ -40,7 +42,15 @@ import kcl "kcl-lang.io/kcl-go"

```go -{ +package main + +import ( + "fmt" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { const k_code = ` name = "kcl" age = 1 @@ -85,39 +95,50 @@ x1 = Person { ## Index - [Go API](#go-api) - - [KCL Go SDK](#kcl-go-sdk) - - [Index](#index) - - [Constants](#constants) - - [func FormatCode](#func-formatcode) - - [func FormatPath](#func-formatpath) - - [func InitKclvmPath](#func-initkclvmpath) - - [func InitKclvmRuntime](#func-initkclvmruntime) - - [func LintPath](#func-lintpath) - - [func ListDepFiles](#func-listdepfiles) - - [func ListDownStreamFiles](#func-listdownstreamfiles) - - [func ListUpStreamFiles](#func-listupstreamfiles) - - [func OverrideFile](#func-overridefile) - - [func ValidateCode](#func-validatecode) - - [type KCLResult](#type-kclresult) - - [type KCLResultList](#type-kclresultlist) - - [func MustRun](#func-mustrun) - - [func Run](#func-run) - - [func RunFiles](#func-runfiles) - - [type KclType](#type-kcltype) - - [func GetSchemaType](#func-getschematype) - - [type ListDepFilesOption](#type-listdepfilesoption) - - [type ListDepsOptions](#type-listdepsoptions) - - [type Option](#type-option) - - [func WithCode](#func-withcode) - - [func WithDisableNone](#func-withdisablenone) - - [func WithKFilenames](#func-withkfilenames) - - [func WithOptions](#func-withoptions) - - [func WithOverrides](#func-withoverrides) - - [func WithPrintOverridesAST](#func-withprintoverridesast) - - [func WithSettings](#func-withsettings) - - [func WithSortKeys](#func-withsortkeys) - - [func WithWorkDir](#func-withworkdir) - - [type ValidateOptions](#type-validateoptions) + - [KCL Go SDK](#kcl-go-sdk) + - [Index](#index) + - [Constants](#constants) + - [func FormatCode](#func-formatcode) + - [func FormatPath](#func-formatpath) + - [func GetSchemaTypeMapping](#func-getschematypemapping) + - [func InitKclvmPath](#func-initkclvmpath) + - [func InitKclvmRuntime](#func-initkclvmruntime) + - [func LintPath](#func-lintpath) + - [func ListDepFiles](#func-listdepfiles) + - [func ListDownStreamFiles](#func-listdownstreamfiles) + - [func ListUpStreamFiles](#func-listupstreamfiles) + - [func OverrideFile](#func-overridefile) + - [func Validate](#func-validate) + - [func ValidateCode](#func-validatecode) + - [type KCLResult](#type-kclresult) + - [type KCLResultList](#type-kclresultlist) + - [func MustRun](#func-mustrun) + - [func Run](#func-run) + - [func RunFiles](#func-runfiles) + - [type KclType](#type-kcltype) + - [func GetSchemaType](#func-getschematype) + - [type ListDepFilesOption](#type-listdepfilesoption) + - [type ListDepsOptions](#type-listdepsoptions) + - [type Option](#type-option) + - [func WithCode](#func-withcode) + - [func WithDisableNone](#func-withdisablenone) + - [func WithExternalPkgs](#func-withexternalpkgs) + - [func WithIncludeSchemaTypePath](#func-withincludeschematypepath) + - [func WithKFilenames](#func-withkfilenames) + - [func WithLogger](#func-withlogger) + - [func WithOptions](#func-withoptions) + - [func WithOverrides](#func-withoverrides) + - [func WithPrintOverridesAST](#func-withprintoverridesast) + - [func WithSelectors](#func-withselectors) + - [func WithSettings](#func-withsettings) + - [func WithSortKeys](#func-withsortkeys) + - [func WithWorkDir](#func-withworkdir) + - [type TestCaseInfo](#type-testcaseinfo) + - [type TestOptions](#type-testoptions) + - [type TestResult](#type-testresult) + - [func Test](#func-test) + - [type ValidateOptions](#type-validateoptions) + ## Constants @@ -127,7 +148,7 @@ KclvmAbiVersion is the current kclvm ABI version. const KclvmAbiVersion = scripts.KclvmAbiVersion ``` -## func [FormatCode](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L110) +## func [FormatCode]() ```go func FormatCode(code interface{}) ([]byte, error) @@ -138,8 +159,19 @@ FormatCode returns the formatted code.

Example

+ + ```go -{ +package main + +import ( + "fmt" + "log" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { out, err := kcl.FormatCode(`a = 1+2`) if err != nil { log.Fatal(err) @@ -149,6 +181,8 @@ FormatCode returns the formatted code. } ``` + + ``` a = 1 + 2 ``` @@ -156,7 +190,7 @@ a = 1 + 2

-## func [FormatPath](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L122) +## func [FormatPath]() ```go func FormatPath(path string) (changedPaths []string, err error) @@ -169,8 +203,19 @@ the returned changedPaths are the changed file paths \(relative path\)
Example

+ + ```go -{ +package main + +import ( + "fmt" + "log" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { changedPaths, err := kcl.FormatPath("testdata/fmt") if err != nil { log.Fatal(err) @@ -182,7 +227,33 @@ the returned changedPaths are the changed file paths \(relative path\)

-## func [InitKclvmPath](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L54) +## func [GetSchemaTypeMapping]() + +```go +func GetSchemaTypeMapping(file, code, schemaName string) (map[string]*KclType, error) +``` + +GetSchemaTypeMapping returns a \:\ mapping of schema types from a kcl file or code. + +file: string + +``` +The kcl filename +``` + +code: string + +``` +The kcl code string +``` + +schema\_name: string + +``` +The schema name got, when the schema name is empty, all schemas are returned. +``` + +## func [InitKclvmPath]() ```go func InitKclvmPath(kclvmRoot string) @@ -190,7 +261,7 @@ func InitKclvmPath(kclvmRoot string) InitKclvmPath init kclvm path. -## func [InitKclvmRuntime](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L59) +## func [InitKclvmRuntime]() ```go func InitKclvmRuntime(n int) @@ -198,7 +269,7 @@ func InitKclvmRuntime(n int) InitKclvmRuntime init kclvm process. -## func [LintPath](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L142) +## func [LintPath]() ```go func LintPath(paths []string) (results []string, err error) @@ -210,7 +281,18 @@ LintPath lint files from the given path

```go -{ +package main + +import ( + "fmt" + "log" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { + // import a + // import a # reimport results, err := kcl.LintPath([]string{"testdata/lint/import.k"}) if err != nil { @@ -226,12 +308,13 @@ LintPath lint files from the given path ``` Module 'a' is reimported multiple times Module 'a' imported but unused +Module 'a' imported but unused ```

-## func [ListDepFiles](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L127) +## func [ListDepFiles]() ```go func ListDepFiles(workDir string, opt *ListDepFilesOption) (files []string, err error) @@ -239,7 +322,7 @@ func ListDepFiles(workDir string, opt *ListDepFilesOption) (files []string, err ListDepFiles return the depend files from the given path -## func [ListDownStreamFiles](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L137) +## func [ListDownStreamFiles]() ```go func ListDownStreamFiles(workDir string, opt *ListDepsOptions) ([]string, error) @@ -247,7 +330,7 @@ func ListDownStreamFiles(workDir string, opt *ListDepsOptions) ([]string, error) ListDownStreamFiles return a list of downstream depend files from the given changed path list. -## func [ListUpStreamFiles](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L132) +## func [ListUpStreamFiles]() ```go func ListUpStreamFiles(workDir string, opt *ListDepsOptions) (deps []string, err error) @@ -255,7 +338,7 @@ func ListUpStreamFiles(workDir string, opt *ListDepsOptions) (deps []string, err ListUpStreamFiles return a list of upstream depend files from the given path list -## func [OverrideFile](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L154) +## func [OverrideFile]() ```go func OverrideFile(file string, specs, importPaths []string) (bool, error) @@ -270,15 +353,24 @@ When the pkgpath is '__main__', it can be omitted. importPaths. List of import statements that need to be added -## func [ValidateCode](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L159) +## func [Validate]() ```go -func ValidateCode(data, code string, opt *ValidateOptions) (ok bool, err error) +func Validate(dataFile, schemaFile string, opts *ValidateOptions) (ok bool, err error) ``` -ValidateCode validate data match code +Validate validates the given data file against the specified schema file with the provided options. + +## func [ValidateCode]() + +```go +func ValidateCode(data, code string, opts *ValidateOptions) (ok bool, err error) +``` + +ValidateCode validate data string match code string + +## type [KCLResult]() -## type [KCLResult](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L47) ```go type KCLResult = kcl.KCLResult @@ -288,13 +380,21 @@ type KCLResult = kcl.KCLResult

```go -{ +package main + +import ( + "fmt" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { const k_code = ` name = "kcl" age = 1 - + two = 2 - + schema Person: name: str = "kcl" age: int = 1 @@ -323,7 +423,15 @@ x1.age: 101

```go -{ +package main + +import ( + "fmt" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { const k_code = ` schema Person: name: str = "kcl" @@ -356,13 +464,13 @@ person: {Name:kcl Age:101}

-## type [KCLResultList](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L48) +## type [KCLResultList]() ```go type KCLResultList = kcl.KCLResultList ``` -### func [MustRun](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L64) +### func [MustRun]() ```go func MustRun(path string, opts ...Option) *KCLResultList @@ -374,7 +482,15 @@ MustRun is like Run but panics if return any error.

```go -{ +package main + +import ( + "fmt" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { yaml := kcl.MustRun("testdata/main.k", kcl.WithCode(`name = "kcl"`)).First().YAMLString() fmt.Println(yaml) @@ -392,7 +508,15 @@ name: kcl

```go -{ +package main + +import ( + "fmt" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { const code = ` b = 1 a = 2 @@ -420,7 +544,15 @@ b: 1

```go -{ +package main + +import ( + "fmt" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { const code = ` schema Person: name: str = "" @@ -447,8 +579,18 @@ x = Person()

Example (Settings)

+ + ```go -{ +package main + +import ( + "fmt" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { yaml := kcl.MustRun("./testdata/app0/kcl.yaml").First().YAMLString() fmt.Println(yaml) } @@ -457,7 +599,7 @@ x = Person()

-### func [Run](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L69) +### func [Run]() ```go func Run(path string, opts ...Option) (*KCLResultList, error) @@ -468,12 +610,31 @@ Run evaluates the KCL program with path and opts, then returns the object list.
Example (Get Field)

+ + ```go -{ +package main + +import ( + "fmt" + "log" + + kcl "kcl-lang.io/kcl-go" +) + +func assert(v bool, a ...interface{}) { + if !v { + a = append([]interface{}{"assert failed"}, a...) + log.Panic(a...) + } +} +func main() { + // run kcl.yaml x, err := kcl.Run("./testdata/app0/kcl.yaml") assert(err == nil, err) + // print deploy_topology[1].zone fmt.Println(x.First().Get("deploy_topology.1.zone")) } @@ -486,7 +647,7 @@ R000A

-### func [RunFiles](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L74) +### func [RunFiles]() ```go func RunFiles(paths []string, opts ...Option) (*KCLResultList, error) @@ -498,7 +659,15 @@ RunFiles evaluates the KCL program with multi file path and opts, then returns t

```go -{ +package main + +import ( + "fmt" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { result, _ := kcl.RunFiles([]string{"./testdata/app0/kcl.yaml"}) fmt.Println(result.First().YAMLString()) } @@ -507,13 +676,13 @@ RunFiles evaluates the KCL program with multi file path and opts, then returns t

-## type [KclType](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L50) +## type [KclType]() ```go type KclType = kcl.KclType ``` -### func [GetSchemaType](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L176) +### func [GetSchemaType]() ```go func GetSchemaType(file, code, schemaName string) ([]*KclType, error) @@ -533,31 +702,31 @@ code: string The kcl code string ``` -schema_name: string +schema\_name: string ``` The schema name got, when the schema name is empty, all schemas are returned. ``` -## type [ListDepFilesOption](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L45) +## type [ListDepFilesOption]() ```go type ListDepFilesOption = list.Option ``` -## type [ListDepsOptions](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L44) +## type [ListDepsOptions]() ```go type ListDepsOptions = list.DepOptions ``` -## type [Option](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L43) +## type [Option]() ```go type Option = kcl.Option ``` -### func [WithCode](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L79) +### func [WithCode]() ```go func WithCode(codes ...string) Option @@ -565,7 +734,7 @@ func WithCode(codes ...string) Option WithCode returns a Option which hold a kcl source code list. -### func [WithDisableNone](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L97) +### func [WithDisableNone]() ```go func WithDisableNone(disableNone bool) Option @@ -573,7 +742,23 @@ func WithDisableNone(disableNone bool) Option WithDisableNone returns a Option which hold a disable none switch. -### func [WithKFilenames](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L82) +### func [WithExternalPkgs]() + +```go +func WithExternalPkgs(externalPkgs ...string) Option +``` + +WithExternalPkgs returns a Option which hold a external package list. + +### func [WithIncludeSchemaTypePath]() + +```go +func WithIncludeSchemaTypePath(includeSchemaTypePath bool) Option +``` + +WithIncludeSchemaTypePath returns a Option which hold a include schema type path switch. + +### func [WithKFilenames]() ```go func WithKFilenames(filenames ...string) Option @@ -581,7 +766,15 @@ func WithKFilenames(filenames ...string) Option WithKFilenames returns a Option which hold a filenames list. -### func [WithOptions](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L85) +### func [WithLogger]() + +```go +func WithLogger(l io.Writer) Option +``` + +WithLogger returns a Option which hold a logger. + +### func [WithOptions]() ```go func WithOptions(key_value_list ...string) Option @@ -592,8 +785,19 @@ WithOptions returns a Option which hold a key=value pair list for option functio
Example

+ + ```go -{ +package main + +import ( + "fmt" + "log" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { const code = ` name = option("name") age = option("age") @@ -618,7 +822,7 @@ name: kcl

-### func [WithOverrides](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L88) +### func [WithOverrides]() ```go func WithOverrides(override_list ...string) Option @@ -626,7 +830,7 @@ func WithOverrides(override_list ...string) Option WithOverrides returns a Option which hold a override list. -### func [WithPrintOverridesAST](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L100) +### func [WithPrintOverridesAST]() ```go func WithPrintOverridesAST(printOverridesAST bool) Option @@ -634,7 +838,15 @@ func WithPrintOverridesAST(printOverridesAST bool) Option WithPrintOverridesAST returns a Option which hold a printOverridesAST switch. -### func [WithSettings](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L91) +### func [WithSelectors]() + +```go +func WithSelectors(selectors ...string) Option +``` + +WithSelectors returns a Option which hold a path selector list. + +### func [WithSettings]() ```go func WithSettings(filename string) Option @@ -642,7 +854,7 @@ func WithSettings(filename string) Option WithSettings returns a Option which hold a settings file. -### func [WithSortKeys](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L105) +### func [WithSortKeys]() ```go func WithSortKeys(sortKeys bool) Option @@ -650,7 +862,7 @@ func WithSortKeys(sortKeys bool) Option WithSortKeys returns a Option which hold a sortKeys switch. -### func [WithWorkDir](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L94) +### func [WithWorkDir]() ```go func WithWorkDir(workDir string) Option @@ -658,7 +870,39 @@ func WithWorkDir(workDir string) Option WithWorkDir returns a Option which hold a work dir. -## type [ValidateOptions](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L46) +## type [TestCaseInfo]() + +```go +type TestCaseInfo = testing.TestCaseInfo +``` + +## type [TestOptions]() + + + +```go +type TestOptions = testing.TestOptions +``` + +## type [TestResult]() + + + +```go +type TestResult = testing.TestResult +``` + +### func [Test]() + +```go +func Test(testOpts *TestOptions, opts ...Option) (TestResult, error) +``` + +Test calls the test tool to run uni tests in packages. + +## type [ValidateOptions]() + + ```go type ValidateOptions = validate.ValidateOptions diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.7.0/reference/xlang-api/rest-api.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.7.0/reference/xlang-api/rest-api.md index 446263b4..6330e497 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.7.0/reference/xlang-api/rest-api.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.7.0/reference/xlang-api/rest-api.md @@ -129,7 +129,6 @@ curl -X POST \ // Copyright 2023 The KCL Authors. All rights reserved. // // This file defines the request parameters and return structure of the KCL RPC server. -// We can use the following command to start a KCL RPC server. syntax = "proto3"; @@ -140,6 +139,12 @@ import "google/protobuf/descriptor.proto"; // ---------------------------------------------------------------------------- +// kcl main.k -E pkg_name=pkg_path +message CmdExternalPkgSpec { + string pkg_name = 1; + string pkg_path = 2; +} + // kcl main.k -D name=value message CmdArgSpec { string name = 1; @@ -202,11 +207,17 @@ service KclvmService { rpc OverrideFile(OverrideFile_Args) returns (OverrideFile_Result); rpc GetSchemaType(GetSchemaType_Args) returns(GetSchemaType_Result); + rpc GetFullSchemaType(GetFullSchemaType_Args) returns(GetSchemaType_Result); rpc GetSchemaTypeMapping(GetSchemaTypeMapping_Args) returns(GetSchemaTypeMapping_Result); rpc ValidateCode(ValidateCode_Args) returns(ValidateCode_Result); rpc ListDepFiles(ListDepFiles_Args) returns(ListDepFiles_Result); rpc LoadSettingsFiles(LoadSettingsFiles_Args) returns(LoadSettingsFiles_Result); + + rpc Rename(Rename_Args) returns(Rename_Result); + rpc RenameCode(RenameCode_Args) returns(RenameCode_Result); + + rpc Test(Test_Args) returns (Test_Result); } message Ping_Args { @@ -245,7 +256,7 @@ message ExecProgram_Args { repeated string k_filename_list = 2; repeated string k_code_list = 3; - + repeated CmdArgSpec args = 4; repeated CmdOverrideSpec overrides = 5; @@ -266,14 +277,28 @@ message ExecProgram_Args { // yaml/json: sort keys bool sort_keys = 12; - // include schema type path in JSON/YAML result - bool include_schema_type_path = 13; + + // -E --external : external packages path + repeated CmdExternalPkgSpec external_pkgs = 13; + + // Whether including schema type in JSON/YAML result + bool include_schema_type_path = 14; + + // Whether only compiling the program + bool compile_only = 15; + + // Compile the dir recursively + bool recursive = 16; + + // -S --path_selector + repeated string path_selector = 17; } + message ExecProgram_Result { string json_result = 1; string yaml_result = 2; - - string escaped_time = 101; + string log_message = 3; + string err_message = 4; } message ResetPlugin_Args { @@ -317,19 +342,9 @@ message OverrideFile_Result { bool result = 1; } -message EvalCode_Args { - string code = 1; -} -message EvalCode_Result { - string json_result = 2; -} - -message ResolveCode_Args { - string code = 1; -} - -message ResolveCode_Result { - bool success = 1; +message GetFullSchemaType_Args { + ExecProgram_Args exec_args = 1; + string schema_name = 2; } message GetSchemaType_Args { @@ -406,6 +421,8 @@ message CliConfig { bool disable_none = 6; int64 verbose = 7; bool debug = 8; + bool sort_keys = 9; + bool include_schema_type_path = 10; } message KeyValuePair { @@ -413,8 +430,61 @@ message KeyValuePair { string value = 2; } +// --------------------------------------------------------------------------------- +// Rename API +// find all the occurrences of the target symbol and rename them. This API will rewrite files if they contain symbols to be renamed. +// --------------------------------------------------------------------------------- + +message Rename_Args { + string symbol_path = 1; // the path to the target symbol to be renamed. The symbol path should conform to format: `:` When the pkgpath is '__main__', `:` can be omitted. + repeated string file_paths = 2; // the paths to the source code files + string new_name = 3; // the new name of the symbol +} + +message Rename_Result { + repeated string changed_files = 1; // the file paths got changed +} + +// --------------------------------------------------------------------------------- +// RenameCode API +// find all the occurrences of the target symbol and rename them. This API won't rewrite files but return the modified code if any code has been changed. +// --------------------------------------------------------------------------------- + +message RenameCode_Args { + string symbol_path = 1; // the path to the target symbol to be renamed. The symbol path should conform to format: `:` When the pkgpath is '__main__', `:` can be omitted. + map source_codes = 2; // the source code. a : map + string new_name = 3; // the new name of the symbol +} + +message RenameCode_Result { + map changed_codes = 1; // the changed code. a : map +} + +// --------------------------------------------------------------------------------- +// Test API +// Test KCL packages with test arguments +// --------------------------------------------------------------------------------- + +message Test_Args { + ExecProgram_Args exec_args = 1; // This field stores the execution program arguments. + repeated string pkg_list = 2; // The package path list to be tested e.g., "./...", "/path/to/package/", "/path/to/package/..." + string run_regexp = 3; // This field stores a regular expression for filtering tests to run. + bool fail_fast = 4; // This field determines whether the test run should stop on the first failure. +} + +message Test_Result { + repeated TestCaseInfo info = 2; +} + +message TestCaseInfo { + string name = 1; // Test case name + string error = 2; + uint64 duration = 3; // Number of whole microseconds in the duration. + string log_message = 4; +} + // ---------------------------------------------------------------------------- -// JSON Schema Lit +// KCL Type Structure // ---------------------------------------------------------------------------- message KclType { @@ -433,6 +503,11 @@ message KclType { int32 line = 10; repeated Decorator decorators = 11; // schema decorators + + string filename = 12; // `filename` represents the absolute path of the file name where the attribute is located. + string pkg_path = 13; // `pkg_path` represents the path name of the package where the attribute is located. + string description = 14; // `description` represents the document of the attribute. + map examples = 15; // A map object to hold examples, the key is the example name. } message Decorator { @@ -441,6 +516,12 @@ message Decorator { map keywords = 3; } +message Example { + string summary = 1; // Short description for the example. + string description = 2; // Long description for the example. + string value = 3; // Embedded literal example. +} + // ---------------------------------------------------------------------------- // END // ---------------------------------------------------------------------------- diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.7.0/user_docs/getting-started/install.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.7.0/user_docs/getting-started/install.md index 9ce194eb..e26180c1 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.7.0/user_docs/getting-started/install.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.7.0/user_docs/getting-started/install.md @@ -50,7 +50,7 @@ wget -q https://kcl-lang.io/script/install-cli.sh -O - | /bin/bash powershell -Command "iwr -useb https://kcl-lang.io/script/install-cli.ps1 | iex" ``` -### Homebrew (MacOS) +#### Homebrew (MacOS) - 安装最新版本 @@ -74,7 +74,7 @@ brew upgrade kcl-lang/tap/kcl brew uninstall kcl-lang/tap/kcl ``` -### Scoop (Windows) +#### Scoop (Windows) 首先安装 [Scoop](https://scoop.sh/), 然后通过如下命令安装 `kcl`: @@ -147,7 +147,7 @@ wget -q https://kcl-lang.io/script/install-kcl-lsp.sh -O - | /bin/bash powershell -Command "iwr -useb https://kcl-lang.io/script/install-kcl-lsp.ps1 | iex" ``` -#### Homebrew (MacOS) +### Homebrew (MacOS) - 安装最新版本 @@ -171,7 +171,7 @@ brew upgrade kcl-lang/tap/kcl-lsp brew uninstall kcl-lang/tap/kcl-lsp ``` -#### Scoop (Windows) +### Scoop (Windows) 首先安装 [Scoop](https://scoop.sh/), 然后通过如下命令安装 `kcl-language-server` 二进制: diff --git a/versioned_docs/version-0.7.0/reference/xlang-api/go-api.md b/versioned_docs/version-0.7.0/reference/xlang-api/go-api.md index 2a978250..cdbc09f2 100644 --- a/versioned_docs/version-0.7.0/reference/xlang-api/go-api.md +++ b/versioned_docs/version-0.7.0/reference/xlang-api/go-api.md @@ -4,6 +4,8 @@ sidebar_position: 3 # Go API + + ```go import kcl "kcl-lang.io/kcl-go" ``` @@ -12,7 +14,7 @@ import kcl "kcl-lang.io/kcl-go" ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ -│ kcl files │ │ KCL-Go-API │ │ KCLResultList │ +│ kcl files │ │ KCL-Go-API │ │ KCLResultList │ │ ┌───────────┐ │ │ │ │ │ │ │ 1.k │ │ │ │ │ │ │ └───────────┘ │ │ │ │ ┌───────────┐ │ ┌───────────────┐ @@ -40,7 +42,15 @@ import kcl "kcl-lang.io/kcl-go"

```go -{ +package main + +import ( + "fmt" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { const k_code = ` name = "kcl" age = 1 @@ -85,39 +95,50 @@ x1 = Person { ## Index - [Go API](#go-api) - - [KCL Go SDK](#kcl-go-sdk) - - [Index](#index) - - [Constants](#constants) - - [func FormatCode](#func-formatcode) - - [func FormatPath](#func-formatpath) - - [func InitKclvmPath](#func-initkclvmpath) - - [func InitKclvmRuntime](#func-initkclvmruntime) - - [func LintPath](#func-lintpath) - - [func ListDepFiles](#func-listdepfiles) - - [func ListDownStreamFiles](#func-listdownstreamfiles) - - [func ListUpStreamFiles](#func-listupstreamfiles) - - [func OverrideFile](#func-overridefile) - - [func ValidateCode](#func-validatecode) - - [type KCLResult](#type-kclresult) - - [type KCLResultList](#type-kclresultlist) - - [func MustRun](#func-mustrun) - - [func Run](#func-run) - - [func RunFiles](#func-runfiles) - - [type KclType](#type-kcltype) - - [func GetSchemaType](#func-getschematype) - - [type ListDepFilesOption](#type-listdepfilesoption) - - [type ListDepsOptions](#type-listdepsoptions) - - [type Option](#type-option) - - [func WithCode](#func-withcode) - - [func WithDisableNone](#func-withdisablenone) - - [func WithKFilenames](#func-withkfilenames) - - [func WithOptions](#func-withoptions) - - [func WithOverrides](#func-withoverrides) - - [func WithPrintOverridesAST](#func-withprintoverridesast) - - [func WithSettings](#func-withsettings) - - [func WithSortKeys](#func-withsortkeys) - - [func WithWorkDir](#func-withworkdir) - - [type ValidateOptions](#type-validateoptions) + - [KCL Go SDK](#kcl-go-sdk) + - [Index](#index) + - [Constants](#constants) + - [func FormatCode](#func-formatcode) + - [func FormatPath](#func-formatpath) + - [func GetSchemaTypeMapping](#func-getschematypemapping) + - [func InitKclvmPath](#func-initkclvmpath) + - [func InitKclvmRuntime](#func-initkclvmruntime) + - [func LintPath](#func-lintpath) + - [func ListDepFiles](#func-listdepfiles) + - [func ListDownStreamFiles](#func-listdownstreamfiles) + - [func ListUpStreamFiles](#func-listupstreamfiles) + - [func OverrideFile](#func-overridefile) + - [func Validate](#func-validate) + - [func ValidateCode](#func-validatecode) + - [type KCLResult](#type-kclresult) + - [type KCLResultList](#type-kclresultlist) + - [func MustRun](#func-mustrun) + - [func Run](#func-run) + - [func RunFiles](#func-runfiles) + - [type KclType](#type-kcltype) + - [func GetSchemaType](#func-getschematype) + - [type ListDepFilesOption](#type-listdepfilesoption) + - [type ListDepsOptions](#type-listdepsoptions) + - [type Option](#type-option) + - [func WithCode](#func-withcode) + - [func WithDisableNone](#func-withdisablenone) + - [func WithExternalPkgs](#func-withexternalpkgs) + - [func WithIncludeSchemaTypePath](#func-withincludeschematypepath) + - [func WithKFilenames](#func-withkfilenames) + - [func WithLogger](#func-withlogger) + - [func WithOptions](#func-withoptions) + - [func WithOverrides](#func-withoverrides) + - [func WithPrintOverridesAST](#func-withprintoverridesast) + - [func WithSelectors](#func-withselectors) + - [func WithSettings](#func-withsettings) + - [func WithSortKeys](#func-withsortkeys) + - [func WithWorkDir](#func-withworkdir) + - [type TestCaseInfo](#type-testcaseinfo) + - [type TestOptions](#type-testoptions) + - [type TestResult](#type-testresult) + - [func Test](#func-test) + - [type ValidateOptions](#type-validateoptions) + ## Constants @@ -127,7 +148,7 @@ KclvmAbiVersion is the current kclvm ABI version. const KclvmAbiVersion = scripts.KclvmAbiVersion ``` -## func [FormatCode](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L110) +## func [FormatCode]() ```go func FormatCode(code interface{}) ([]byte, error) @@ -138,8 +159,19 @@ FormatCode returns the formatted code.

Example

+ + ```go -{ +package main + +import ( + "fmt" + "log" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { out, err := kcl.FormatCode(`a = 1+2`) if err != nil { log.Fatal(err) @@ -149,6 +181,8 @@ FormatCode returns the formatted code. } ``` + + ``` a = 1 + 2 ``` @@ -156,7 +190,7 @@ a = 1 + 2

-## func [FormatPath](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L122) +## func [FormatPath]() ```go func FormatPath(path string) (changedPaths []string, err error) @@ -169,8 +203,19 @@ the returned changedPaths are the changed file paths \(relative path\)
Example

+ + ```go -{ +package main + +import ( + "fmt" + "log" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { changedPaths, err := kcl.FormatPath("testdata/fmt") if err != nil { log.Fatal(err) @@ -182,7 +227,33 @@ the returned changedPaths are the changed file paths \(relative path\)

-## func [InitKclvmPath](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L54) +## func [GetSchemaTypeMapping]() + +```go +func GetSchemaTypeMapping(file, code, schemaName string) (map[string]*KclType, error) +``` + +GetSchemaTypeMapping returns a \:\ mapping of schema types from a kcl file or code. + +file: string + +``` +The kcl filename +``` + +code: string + +``` +The kcl code string +``` + +schema\_name: string + +``` +The schema name got, when the schema name is empty, all schemas are returned. +``` + +## func [InitKclvmPath]() ```go func InitKclvmPath(kclvmRoot string) @@ -190,7 +261,7 @@ func InitKclvmPath(kclvmRoot string) InitKclvmPath init kclvm path. -## func [InitKclvmRuntime](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L59) +## func [InitKclvmRuntime]() ```go func InitKclvmRuntime(n int) @@ -198,7 +269,7 @@ func InitKclvmRuntime(n int) InitKclvmRuntime init kclvm process. -## func [LintPath](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L142) +## func [LintPath]() ```go func LintPath(paths []string) (results []string, err error) @@ -210,7 +281,18 @@ LintPath lint files from the given path

```go -{ +package main + +import ( + "fmt" + "log" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { + // import a + // import a # reimport results, err := kcl.LintPath([]string{"testdata/lint/import.k"}) if err != nil { @@ -226,12 +308,13 @@ LintPath lint files from the given path ``` Module 'a' is reimported multiple times Module 'a' imported but unused +Module 'a' imported but unused ```

-## func [ListDepFiles](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L127) +## func [ListDepFiles]() ```go func ListDepFiles(workDir string, opt *ListDepFilesOption) (files []string, err error) @@ -239,7 +322,7 @@ func ListDepFiles(workDir string, opt *ListDepFilesOption) (files []string, err ListDepFiles return the depend files from the given path -## func [ListDownStreamFiles](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L137) +## func [ListDownStreamFiles]() ```go func ListDownStreamFiles(workDir string, opt *ListDepsOptions) ([]string, error) @@ -247,7 +330,7 @@ func ListDownStreamFiles(workDir string, opt *ListDepsOptions) ([]string, error) ListDownStreamFiles return a list of downstream depend files from the given changed path list. -## func [ListUpStreamFiles](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L132) +## func [ListUpStreamFiles]() ```go func ListUpStreamFiles(workDir string, opt *ListDepsOptions) (deps []string, err error) @@ -255,7 +338,7 @@ func ListUpStreamFiles(workDir string, opt *ListDepsOptions) (deps []string, err ListUpStreamFiles return a list of upstream depend files from the given path list -## func [OverrideFile](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L154) +## func [OverrideFile]() ```go func OverrideFile(file string, specs, importPaths []string) (bool, error) @@ -270,15 +353,24 @@ When the pkgpath is '__main__', it can be omitted. importPaths. List of import statements that need to be added -## func [ValidateCode](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L159) +## func [Validate]() ```go -func ValidateCode(data, code string, opt *ValidateOptions) (ok bool, err error) +func Validate(dataFile, schemaFile string, opts *ValidateOptions) (ok bool, err error) ``` -ValidateCode validate data match code +Validate validates the given data file against the specified schema file with the provided options. + +## func [ValidateCode]() + +```go +func ValidateCode(data, code string, opts *ValidateOptions) (ok bool, err error) +``` + +ValidateCode validate data string match code string + +## type [KCLResult]() -## type [KCLResult](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L47) ```go type KCLResult = kcl.KCLResult @@ -288,13 +380,21 @@ type KCLResult = kcl.KCLResult

```go -{ +package main + +import ( + "fmt" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { const k_code = ` name = "kcl" age = 1 - + two = 2 - + schema Person: name: str = "kcl" age: int = 1 @@ -323,7 +423,15 @@ x1.age: 101

```go -{ +package main + +import ( + "fmt" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { const k_code = ` schema Person: name: str = "kcl" @@ -356,13 +464,13 @@ person: {Name:kcl Age:101}

-## type [KCLResultList](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L48) +## type [KCLResultList]() ```go type KCLResultList = kcl.KCLResultList ``` -### func [MustRun](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L64) +### func [MustRun]() ```go func MustRun(path string, opts ...Option) *KCLResultList @@ -374,7 +482,15 @@ MustRun is like Run but panics if return any error.

```go -{ +package main + +import ( + "fmt" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { yaml := kcl.MustRun("testdata/main.k", kcl.WithCode(`name = "kcl"`)).First().YAMLString() fmt.Println(yaml) @@ -392,7 +508,15 @@ name: kcl

```go -{ +package main + +import ( + "fmt" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { const code = ` b = 1 a = 2 @@ -420,7 +544,15 @@ b: 1

```go -{ +package main + +import ( + "fmt" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { const code = ` schema Person: name: str = "" @@ -447,8 +579,18 @@ x = Person()

Example (Settings)

+ + ```go -{ +package main + +import ( + "fmt" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { yaml := kcl.MustRun("./testdata/app0/kcl.yaml").First().YAMLString() fmt.Println(yaml) } @@ -457,7 +599,7 @@ x = Person()

-### func [Run](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L69) +### func [Run]() ```go func Run(path string, opts ...Option) (*KCLResultList, error) @@ -468,12 +610,31 @@ Run evaluates the KCL program with path and opts, then returns the object list.
Example (Get Field)

+ + ```go -{ +package main + +import ( + "fmt" + "log" + + kcl "kcl-lang.io/kcl-go" +) + +func assert(v bool, a ...interface{}) { + if !v { + a = append([]interface{}{"assert failed"}, a...) + log.Panic(a...) + } +} +func main() { + // run kcl.yaml x, err := kcl.Run("./testdata/app0/kcl.yaml") assert(err == nil, err) + // print deploy_topology[1].zone fmt.Println(x.First().Get("deploy_topology.1.zone")) } @@ -486,7 +647,7 @@ R000A

-### func [RunFiles](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L74) +### func [RunFiles]() ```go func RunFiles(paths []string, opts ...Option) (*KCLResultList, error) @@ -498,7 +659,15 @@ RunFiles evaluates the KCL program with multi file path and opts, then returns t

```go -{ +package main + +import ( + "fmt" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { result, _ := kcl.RunFiles([]string{"./testdata/app0/kcl.yaml"}) fmt.Println(result.First().YAMLString()) } @@ -507,13 +676,13 @@ RunFiles evaluates the KCL program with multi file path and opts, then returns t

-## type [KclType](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L50) +## type [KclType]() ```go type KclType = kcl.KclType ``` -### func [GetSchemaType](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L176) +### func [GetSchemaType]() ```go func GetSchemaType(file, code, schemaName string) ([]*KclType, error) @@ -533,31 +702,31 @@ code: string The kcl code string ``` -schema_name: string +schema\_name: string ``` The schema name got, when the schema name is empty, all schemas are returned. ``` -## type [ListDepFilesOption](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L45) +## type [ListDepFilesOption]() ```go type ListDepFilesOption = list.Option ``` -## type [ListDepsOptions](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L44) +## type [ListDepsOptions]() ```go type ListDepsOptions = list.DepOptions ``` -## type [Option](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L43) +## type [Option]() ```go type Option = kcl.Option ``` -### func [WithCode](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L79) +### func [WithCode]() ```go func WithCode(codes ...string) Option @@ -565,7 +734,7 @@ func WithCode(codes ...string) Option WithCode returns a Option which hold a kcl source code list. -### func [WithDisableNone](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L97) +### func [WithDisableNone]() ```go func WithDisableNone(disableNone bool) Option @@ -573,7 +742,23 @@ func WithDisableNone(disableNone bool) Option WithDisableNone returns a Option which hold a disable none switch. -### func [WithKFilenames](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L82) +### func [WithExternalPkgs]() + +```go +func WithExternalPkgs(externalPkgs ...string) Option +``` + +WithExternalPkgs returns a Option which hold a external package list. + +### func [WithIncludeSchemaTypePath]() + +```go +func WithIncludeSchemaTypePath(includeSchemaTypePath bool) Option +``` + +WithIncludeSchemaTypePath returns a Option which hold a include schema type path switch. + +### func [WithKFilenames]() ```go func WithKFilenames(filenames ...string) Option @@ -581,7 +766,15 @@ func WithKFilenames(filenames ...string) Option WithKFilenames returns a Option which hold a filenames list. -### func [WithOptions](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L85) +### func [WithLogger]() + +```go +func WithLogger(l io.Writer) Option +``` + +WithLogger returns a Option which hold a logger. + +### func [WithOptions]() ```go func WithOptions(key_value_list ...string) Option @@ -592,8 +785,19 @@ WithOptions returns a Option which hold a key=value pair list for option functio
Example

+ + ```go -{ +package main + +import ( + "fmt" + "log" + + kcl "kcl-lang.io/kcl-go" +) + +func main() { const code = ` name = option("name") age = option("age") @@ -618,7 +822,7 @@ name: kcl

-### func [WithOverrides](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L88) +### func [WithOverrides]() ```go func WithOverrides(override_list ...string) Option @@ -626,7 +830,7 @@ func WithOverrides(override_list ...string) Option WithOverrides returns a Option which hold a override list. -### func [WithPrintOverridesAST](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L100) +### func [WithPrintOverridesAST]() ```go func WithPrintOverridesAST(printOverridesAST bool) Option @@ -634,7 +838,15 @@ func WithPrintOverridesAST(printOverridesAST bool) Option WithPrintOverridesAST returns a Option which hold a printOverridesAST switch. -### func [WithSettings](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L91) +### func [WithSelectors]() + +```go +func WithSelectors(selectors ...string) Option +``` + +WithSelectors returns a Option which hold a path selector list. + +### func [WithSettings]() ```go func WithSettings(filename string) Option @@ -642,7 +854,7 @@ func WithSettings(filename string) Option WithSettings returns a Option which hold a settings file. -### func [WithSortKeys](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L105) +### func [WithSortKeys]() ```go func WithSortKeys(sortKeys bool) Option @@ -650,7 +862,7 @@ func WithSortKeys(sortKeys bool) Option WithSortKeys returns a Option which hold a sortKeys switch. -### func [WithWorkDir](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L94) +### func [WithWorkDir]() ```go func WithWorkDir(workDir string) Option @@ -658,7 +870,39 @@ func WithWorkDir(workDir string) Option WithWorkDir returns a Option which hold a work dir. -## type [ValidateOptions](https://github.com/kcl-lang/kcl-go/blob/main/kclvm.go#L46) +## type [TestCaseInfo]() + +```go +type TestCaseInfo = testing.TestCaseInfo +``` + +## type [TestOptions]() + + + +```go +type TestOptions = testing.TestOptions +``` + +## type [TestResult]() + + + +```go +type TestResult = testing.TestResult +``` + +### func [Test]() + +```go +func Test(testOpts *TestOptions, opts ...Option) (TestResult, error) +``` + +Test calls the test tool to run uni tests in packages. + +## type [ValidateOptions]() + + ```go type ValidateOptions = validate.ValidateOptions diff --git a/versioned_docs/version-0.7.0/reference/xlang-api/rest-api.md b/versioned_docs/version-0.7.0/reference/xlang-api/rest-api.md index d15101ff..17966c5a 100644 --- a/versioned_docs/version-0.7.0/reference/xlang-api/rest-api.md +++ b/versioned_docs/version-0.7.0/reference/xlang-api/rest-api.md @@ -117,7 +117,6 @@ Cross-language APIs defined via Protobuf([https://github.com/kcl-lang/kcl-go/blo // Copyright 2023 The KCL Authors. All rights reserved. // // This file defines the request parameters and return structure of the KCL RPC server. -// We can use the following command to start a KCL RPC server. syntax = "proto3"; @@ -128,6 +127,12 @@ import "google/protobuf/descriptor.proto"; // ---------------------------------------------------------------------------- +// kcl main.k -E pkg_name=pkg_path +message CmdExternalPkgSpec { + string pkg_name = 1; + string pkg_path = 2; +} + // kcl main.k -D name=value message CmdArgSpec { string name = 1; @@ -169,7 +174,7 @@ message KclErrorInfo { } // ---------------------------------------------------------------------------- -// service request/response +// service requset/response // ---------------------------------------------------------------------------- // gpyrpc.BuiltinService @@ -190,11 +195,17 @@ service KclvmService { rpc OverrideFile(OverrideFile_Args) returns (OverrideFile_Result); rpc GetSchemaType(GetSchemaType_Args) returns(GetSchemaType_Result); + rpc GetFullSchemaType(GetFullSchemaType_Args) returns(GetSchemaType_Result); rpc GetSchemaTypeMapping(GetSchemaTypeMapping_Args) returns(GetSchemaTypeMapping_Result); rpc ValidateCode(ValidateCode_Args) returns(ValidateCode_Result); rpc ListDepFiles(ListDepFiles_Args) returns(ListDepFiles_Result); rpc LoadSettingsFiles(LoadSettingsFiles_Args) returns(LoadSettingsFiles_Result); + + rpc Rename(Rename_Args) returns(Rename_Result); + rpc RenameCode(RenameCode_Args) returns(RenameCode_Result); + + rpc Test(Test_Args) returns (Test_Result); } message Ping_Args { @@ -233,7 +244,7 @@ message ExecProgram_Args { repeated string k_filename_list = 2; repeated string k_code_list = 3; - + repeated CmdArgSpec args = 4; repeated CmdOverrideSpec overrides = 5; @@ -254,14 +265,28 @@ message ExecProgram_Args { // yaml/json: sort keys bool sort_keys = 12; - // include schema type path in JSON/YAML result - bool include_schema_type_path = 13; + + // -E --external : external packages path + repeated CmdExternalPkgSpec external_pkgs = 13; + + // Whether including schema type in JSON/YAML result + bool include_schema_type_path = 14; + + // Whether only compiling the program + bool compile_only = 15; + + // Compile the dir recursively + bool recursive = 16; + + // -S --path_selector + repeated string path_selector = 17; } + message ExecProgram_Result { string json_result = 1; string yaml_result = 2; - - string escaped_time = 101; + string log_message = 3; + string err_message = 4; } message ResetPlugin_Args { @@ -305,19 +330,9 @@ message OverrideFile_Result { bool result = 1; } -message EvalCode_Args { - string code = 1; -} -message EvalCode_Result { - string json_result = 2; -} - -message ResolveCode_Args { - string code = 1; -} - -message ResolveCode_Result { - bool success = 1; +message GetFullSchemaType_Args { + ExecProgram_Args exec_args = 1; + string schema_name = 2; } message GetSchemaType_Args { @@ -394,6 +409,8 @@ message CliConfig { bool disable_none = 6; int64 verbose = 7; bool debug = 8; + bool sort_keys = 9; + bool include_schema_type_path = 10; } message KeyValuePair { @@ -401,8 +418,61 @@ message KeyValuePair { string value = 2; } +// --------------------------------------------------------------------------------- +// Rename API +// find all the occurrences of the target symbol and rename them. This API will rewrite files if they contain symbols to be renamed. +// --------------------------------------------------------------------------------- + +message Rename_Args { + string symbol_path = 1; // the path to the target symbol to be renamed. The symbol path should conform to format: `:` When the pkgpath is '__main__', `:` can be omitted. + repeated string file_paths = 2; // the paths to the source code files + string new_name = 3; // the new name of the symbol +} + +message Rename_Result { + repeated string changed_files = 1; // the file paths got changed +} + +// --------------------------------------------------------------------------------- +// RenameCode API +// find all the occurrences of the target symbol and rename them. This API won't rewrite files but return the modified code if any code has been changed. +// --------------------------------------------------------------------------------- + +message RenameCode_Args { + string symbol_path = 1; // the path to the target symbol to be renamed. The symbol path should conform to format: `:` When the pkgpath is '__main__', `:` can be omitted. + map source_codes = 2; // the source code. a : map + string new_name = 3; // the new name of the symbol +} + +message RenameCode_Result { + map changed_codes = 1; // the changed code. a : map +} + +// --------------------------------------------------------------------------------- +// Test API +// Test KCL packages with test arguments +// --------------------------------------------------------------------------------- + +message Test_Args { + ExecProgram_Args exec_args = 1; // This field stores the execution program arguments. + repeated string pkg_list = 2; // The package path list to be tested e.g., "./...", "/path/to/package/", "/path/to/package/..." + string run_regexp = 3; // This field stores a regular expression for filtering tests to run. + bool fail_fast = 4; // This field determines whether the test run should stop on the first failure. +} + +message Test_Result { + repeated TestCaseInfo info = 2; +} + +message TestCaseInfo { + string name = 1; // Test case name + string error = 2; + uint64 duration = 3; // Number of whole microseconds in the duration. + string log_message = 4; +} + // ---------------------------------------------------------------------------- -// JSON Schema Lit +// KCL Type Structure // ---------------------------------------------------------------------------- message KclType { @@ -421,6 +491,11 @@ message KclType { int32 line = 10; repeated Decorator decorators = 11; // schema decorators + + string filename = 12; // `filename` represents the absolute path of the file name where the attribute is located. + string pkg_path = 13; // `pkg_path` represents the path name of the package where the attribute is located. + string description = 14; // `description` represents the document of the attribute. + map examples = 15; // A map object to hold examples, the key is the example name. } message Decorator { @@ -429,6 +504,12 @@ message Decorator { map keywords = 3; } +message Example { + string summary = 1; // Short description for the example. + string description = 2; // Long description for the example. + string value = 3; // Embedded literal example. +} + // ---------------------------------------------------------------------------- // END // ----------------------------------------------------------------------------