diff --git a/docs/reference/xlang-api/dotnet-api.md b/docs/reference/xlang-api/dotnet-api.md index 3de5fb4e..12387547 100644 --- a/docs/reference/xlang-api/dotnet-api.md +++ b/docs/reference/xlang-api/dotnet-api.md @@ -22,3 +22,625 @@ execArgs.KFilenameList.Add(path); var result = api.ExecProgram(execArgs); Console.WriteLine(result.YamlResult); ``` + +## API Reference + +### ExecProgram + +Execute KCL file with arguments and return the JSON/YAML result. + +
Example +

+ +The content of `schema.k` is + +```python +schema AppConfig: + replicas: int + +app: AppConfig { + replicas: 2 +} +``` + +C# Code + +```csharp +using KclLib.API; + +var execArgs = new ExecProgram_Args(); +var path = "schema.k" +execArgs.KFilenameList.Add(path); +var result = new API().ExecProgram(execArgs); +``` + +

+
+ +### ParseProgram + +Parse KCL program with entry files and return the AST JSON string. + +
Example +

+ +The content of `schema.k` is + +```python +schema AppConfig: + replicas: int + +app: AppConfig { + replicas: 2 +} +``` + +C# Code + +```csharp +using KclLib.API; + +var path = "schema.k" +var args = new ParseProgram_Args(); +args.Paths.Add(path); +var result = new API().ParseProgram(args); +``` + +

+
+ +### ParseFile + +Parse KCL single file to Module AST JSON string with import dependencies and parse errors. + +
Example +

+ +The content of `schema.k` is + +```python +schema AppConfig: + replicas: int + +app: AppConfig { + replicas: 2 +} +``` + +C# Code + +```csharp +using KclLib.API; + +var path = "schema.k" +var args = new ParseFile_Args { Path = path }; +var result = new API().ParseFile(args); +``` + +

+
+ +### ParseProgram + +Parse KCL program with entry files and return the AST JSON string. + +
Example +

+ +The content of `schema.k` is + +```python +schema AppConfig: + replicas: int + +app: AppConfig { + replicas: 2 +} +``` + +C# Code + +```csharp +using KclLib.API; + +var path = "schema.k"; +var args = new ParseProgram_Args(); +args.Paths.Add(path); +var result = new API().ListOptions(args); +``` + +

+
+ +### LoadPackage + +LoadPackage provides users with the ability to parse KCL program and semantic model information including symbols, types, definitions, etc. + +
Example +

+ +The content of `schema.k` is + +```python +schema AppConfig: + replicas: int + +app: AppConfig { + replicas: 2 +} +``` + +C# Code + +```csharp +using KclLib.API; + +var path = "schema.k"; +var args = new LoadPackage_Args(); +args.ResolveAst = true; +args.ParseArgs = new ParseProgram_Args(); +args.ParseArgs.Paths.Add(path); +var result = new API().LoadPackage(args); +``` + +

+
+ +### ListVariables + +ListVariables provides users with the ability to parse KCL program and get all variables by specs. + +
Example +

+ +The content of `schema.k` is + +```python +schema AppConfig: + replicas: int + +app: AppConfig { + replicas: 2 +} +``` + +C# Code + +```csharp +using KclLib.API; + +var api = new API(); +var args = new ListVariables_Args(); +var path = "schema.k"; +args.Files.Add(path); +var result = api.ListVariables(args); +``` + +

+
+ +### ListOptions + +ListOptions provides users with the ability to parse KCL program and get all option information. + +
Example +

+ +The content of `options.k` is + +```python +a = option("key1") +b = option("key2", required=True) +c = { + metadata.key = option("metadata-key") +} +``` + +C# Code + +```csharp +using KclLib.API; + +var path = "options.k"; +var args = new ParseProgram_Args(); +args.Paths.Add(path); +var result = new API().ListOptions(args); +``` + +

+
+ +### GetSchemaTypeMapping + +Get schema type mapping defined in the program. + +
Example +

+ +The content of `schema.k` is + +```python +schema AppConfig: + replicas: int + +app: AppConfig { + replicas: 2 +} +``` + +C# Code + +```csharp +using KclLib.API; + +var path = "schema.k"; +var execArgs = new ExecProgram_Args(); +execArgs.KFilenameList.Add(path); +var args = new GetSchemaTypeMapping_Args(); +args.ExecArgs = execArgs; +var result = new API().GetSchemaTypeMapping(args); +``` + +

+
+ +### OverrideFile + +Override KCL file with arguments. See [https://www.kcl-lang.io/docs/user_docs/guides/automation](https://www.kcl-lang.io/docs/user_docs/guides/automation) for more override spec guide. + +
Example +

+ +The content of `main.k` is + +```python +a = 1 + +b = { + "a": 1 + "b": 2 +} +``` + +C# Code + +```csharp +using KclLib.API; + +var args = new OverrideFile_Args +{ + File = "main.k", +}; +args.Specs.Add("b.a=2"); +var result = new API().OverrideFile(args); +``` + +

+
+ +### FormatCode + +Format the code source. + +
Example +

+ +C# Code + +```csharp +using KclLib.API; + +string sourceCode = "schema Person:\n" + " name: str\n" + " age: int\n" + " check:\n" + + " 0 < age < 120\n"; +string expectedFormattedCode = "schema Person:\n" + " name: str\n" + " age: int\n\n" + " check:\n" + + " 0 < age < 120\n\n"; +var api = new API(); +var args = new FormatCode_Args(); +args.Source = sourceCode; +var result = api.FormatCode(args); +``` + +

+
+ +### FormatPath + +Format KCL file or directory path contains KCL files and returns the changed file paths. + +
Example +

+ +The content of `format_path.k` is + +```python +schema Person: + name: str + age: int + + check: + 0 < age < 120 +``` + +C# Code + +```csharp +using KclLib.API; + +var api = new API(); +var args = new FormatPath_Args(); +var path = "format_path.k"; +args.Path = path; +var result = api.FormatPath(args); +``` + +

+
+ +### LintPath + +Lint files and return error messages including errors and warnings. + +
Example +

+ +The content of `lint_path.k` is + +```python +import math + +a = 1 +``` + +C# Code + +```csharp +using KclLib.API; + +var path = "lint_path.k" +var args = new LintPath_Args(); +args.Paths.Add(path); +var result = new API().LintPath(args); +bool foundWarning = result.Results.Any(warning => warning.Contains("Module 'math' imported but unused")); +``` + +

+
+ +### ValidateCode + +Validate code using schema and JSON/YAML data strings. + +
Example +

+ +C# Code + +```csharp +using KclLib.API; + +string code = @" +schema Person: + name: str + age: int + check: + 0 < age < 120 +"; +string data = "{\"name\": \"Alice\", \"age\": 10}"; +var args = new ValidateCode_Args +{ + Code = code, + Data = data, + Format = "json" +}; +var result = new API().ValidateCode(args); +``` + +

+
+ +### Rename + +Rename all the occurrences of the target symbol in the files. This API will rewrite files if they contain symbols to be renamed. Return the file paths that got changed. + +
Example +

+ +The content of `main.k` is + +```python +a = 1 +b = a +``` + +C# Code + +```csharp +using KclLib.API; + +Rename_Args args = Rename_Args.newBuilder().setPackageRoot(".").setSymbolPath("a") + .addFilePaths("main.k").setNewName("a2").build(); +API apiInstance = new API(); +Rename_Result result = apiInstance.rename(args); +``` + +

+
+ +### RenameCode + +Rename all the occurrences of the target symbol and return the modified code if any code has been changed. This API won't rewrite files but return the changed code. + +
Example +

+ +C# Code + +```csharp +using KclLib.API; + +var args = new RenameCode_Args +{ + PackageRoot = "/mock/path", + SymbolPath = "a", + SourceCodes = { { "/mock/path/main.k", "a = 1\nb = a" } }, + NewName = "a2" +}; +var result = new API().RenameCode(args); +``` + +

+
+ +### Test + +Test KCL packages with test arguments. + +
Example +

+ +C# Code + +```csharp +using KclLib.API; + +var pkg = Path.Combine(parentDirectory, "test_data", "testing"); +var args = new Test_Args(); +args.PkgList.Add(pkg + "/..."); +var result = new API().Test(args); +``` + +

+
+ +### LoadSettingsFiles + +Load the setting file config defined in `kcl.yaml` + +
Example +

+ +The content of `kcl.yaml` is + +```yaml +kcl_cli_configs: + strict_range_check: true +kcl_options: + - key: key + value: value +``` + +C# Code + +```csharp +using KclLib.API; + +var workDir = "."; +var settingsFile = "kcl.yaml"; +var args = new LoadSettingsFiles_Args +{ + WorkDir = workDir, +}; +args.Files.Add(settingsFile); +var result = new API().LoadSettingsFiles(args); +``` + +

+
+ +### UpdateDependencies + +Download and update dependencies defined in the `kcl.mod` file and return the external package name and location list. + +
Example +

+ +The content of `module/kcl.mod` is + +```yaml +[package] +name = "mod_update" +edition = "0.0.1" +version = "0.0.1" + +[dependencies] +helloworld = { oci = "oci://ghcr.io/kcl-lang/helloworld", tag = "0.1.0" } +flask = { git = "https://github.com/kcl-lang/flask-demo-kcl-manifests", commit = "ade147b" } +``` + +C# Code + +```csharp +using KclLib.API; + +var manifestPath = "module"; +var args = new UpdateDependencies_Args { ManifestPath = manifestPath }; +var result = new API().UpdateDependencies(args); +``` + +

+
+ +Call `ExecProgram` with external dependencies + +
Example +

+ +The content of `module/kcl.mod` is + +```yaml +[package] +name = "mod_update" +edition = "0.0.1" +version = "0.0.1" + +[dependencies] +helloworld = { oci = "oci://ghcr.io/kcl-lang/helloworld", tag = "0.1.0" } +flask = { git = "https://github.com/kcl-lang/flask-demo-kcl-manifests", commit = "ade147b" } +``` + +The content of `module/main.k` is + +```python +import helloworld +import flask + +a = helloworld.The_first_kcl_program +``` + +C# Code + +```csharp +using KclLib.API; + +API api = new API(); + +var manifestPath = "module"; +var testFile = Path.Combine(manifestPath, "main.k"); +var updateArgs = new UpdateDependencies_Args { ManifestPath = manifestPath }; +var depResult = new API().UpdateDependencies(updateArgs); +var execArgs = new ExecProgram_Args(); +execArgs.KFilenameList.Add(testFile); +execArgs.ExternalPkgs.AddRange(depResult.ExternalPkgs); +var execResult = new API().ExecProgram(execArgs); +``` + +

+
+ +### GetVersion + +Return the KCL service version information. + +
Example +

+ +C# Code + +```csharp +using KclLib.API; + +var result = new API().GetVersion(new GetVersion_Args()); +``` + +

+
diff --git a/docs/reference/xlang-api/java-api.md b/docs/reference/xlang-api/java-api.md index c025dd90..fee90323 100644 --- a/docs/reference/xlang-api/java-api.md +++ b/docs/reference/xlang-api/java-api.md @@ -207,15 +207,13 @@ app: AppConfig { Java Code -```python -import kcl_lib.api as api - -args = api.LoadPackage_Args( - parse_args=api.ParseProgram_Args(paths=["schema.k"]), resolve_ast=True -) -api = api.API() -result = api.load_package(args) -assert list(result.symbols.values())[0].ty.schema_name == "AppConfig" +```java +import com.kcl.api.*; + +API api = new API(); +LoadPackage_Result result = api.loadPackage(LoadPackage_Args.newBuilder().setResolveAst(true) + .setWithAstIndex(true) + .setParseArgs(ParseProgram_Args.newBuilder().addPaths("schema.k").build()).build()); ```

diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/xlang-api/dotnet-api.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/xlang-api/dotnet-api.md index bfabfedb..6dea5eed 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/xlang-api/dotnet-api.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/xlang-api/dotnet-api.md @@ -22,3 +22,625 @@ execArgs.KFilenameList.Add(path); var result = api.ExecProgram(execArgs); Console.WriteLine(result.YamlResult); ``` + +## API 参考 + +### ExecProgram + +Execute KCL file with arguments and return the JSON/YAML result. + +
Example +

+ +The content of `schema.k` is + +```python +schema AppConfig: + replicas: int + +app: AppConfig { + replicas: 2 +} +``` + +C# Code + +```csharp +using KclLib.API; + +var execArgs = new ExecProgram_Args(); +var path = "schema.k" +execArgs.KFilenameList.Add(path); +var result = new API().ExecProgram(execArgs); +``` + +

+
+ +### ParseProgram + +Parse KCL program with entry files and return the AST JSON string. + +
Example +

+ +The content of `schema.k` is + +```python +schema AppConfig: + replicas: int + +app: AppConfig { + replicas: 2 +} +``` + +C# Code + +```csharp +using KclLib.API; + +var path = "schema.k" +var args = new ParseProgram_Args(); +args.Paths.Add(path); +var result = new API().ParseProgram(args); +``` + +

+
+ +### ParseFile + +Parse KCL single file to Module AST JSON string with import dependencies and parse errors. + +
Example +

+ +The content of `schema.k` is + +```python +schema AppConfig: + replicas: int + +app: AppConfig { + replicas: 2 +} +``` + +C# Code + +```csharp +using KclLib.API; + +var path = "schema.k" +var args = new ParseFile_Args { Path = path }; +var result = new API().ParseFile(args); +``` + +

+
+ +### ParseProgram + +Parse KCL program with entry files and return the AST JSON string. + +
Example +

+ +The content of `schema.k` is + +```python +schema AppConfig: + replicas: int + +app: AppConfig { + replicas: 2 +} +``` + +C# Code + +```csharp +using KclLib.API; + +var path = "schema.k"; +var args = new ParseProgram_Args(); +args.Paths.Add(path); +var result = new API().ListOptions(args); +``` + +

+
+ +### LoadPackage + +LoadPackage provides users with the ability to parse KCL program and semantic model information including symbols, types, definitions, etc. + +
Example +

+ +The content of `schema.k` is + +```python +schema AppConfig: + replicas: int + +app: AppConfig { + replicas: 2 +} +``` + +C# Code + +```csharp +using KclLib.API; + +var path = "schema.k"; +var args = new LoadPackage_Args(); +args.ResolveAst = true; +args.ParseArgs = new ParseProgram_Args(); +args.ParseArgs.Paths.Add(path); +var result = new API().LoadPackage(args); +``` + +

+
+ +### ListVariables + +ListVariables provides users with the ability to parse KCL program and get all variables by specs. + +
Example +

+ +The content of `schema.k` is + +```python +schema AppConfig: + replicas: int + +app: AppConfig { + replicas: 2 +} +``` + +C# Code + +```csharp +using KclLib.API; + +var api = new API(); +var args = new ListVariables_Args(); +var path = "schema.k"; +args.Files.Add(path); +var result = api.ListVariables(args); +``` + +

+
+ +### ListOptions + +ListOptions provides users with the ability to parse KCL program and get all option information. + +
Example +

+ +The content of `options.k` is + +```python +a = option("key1") +b = option("key2", required=True) +c = { + metadata.key = option("metadata-key") +} +``` + +C# Code + +```csharp +using KclLib.API; + +var path = "options.k"; +var args = new ParseProgram_Args(); +args.Paths.Add(path); +var result = new API().ListOptions(args); +``` + +

+
+ +### GetSchemaTypeMapping + +Get schema type mapping defined in the program. + +
Example +

+ +The content of `schema.k` is + +```python +schema AppConfig: + replicas: int + +app: AppConfig { + replicas: 2 +} +``` + +C# Code + +```csharp +using KclLib.API; + +var path = "schema.k"; +var execArgs = new ExecProgram_Args(); +execArgs.KFilenameList.Add(path); +var args = new GetSchemaTypeMapping_Args(); +args.ExecArgs = execArgs; +var result = new API().GetSchemaTypeMapping(args); +``` + +

+
+ +### OverrideFile + +Override KCL file with arguments. See [https://www.kcl-lang.io/docs/user_docs/guides/automation](https://www.kcl-lang.io/docs/user_docs/guides/automation) for more override spec guide. + +
Example +

+ +The content of `main.k` is + +```python +a = 1 + +b = { + "a": 1 + "b": 2 +} +``` + +C# Code + +```csharp +using KclLib.API; + +var args = new OverrideFile_Args +{ + File = "main.k", +}; +args.Specs.Add("b.a=2"); +var result = new API().OverrideFile(args); +``` + +

+
+ +### FormatCode + +Format the code source. + +
Example +

+ +C# Code + +```csharp +using KclLib.API; + +string sourceCode = "schema Person:\n" + " name: str\n" + " age: int\n" + " check:\n" + + " 0 < age < 120\n"; +string expectedFormattedCode = "schema Person:\n" + " name: str\n" + " age: int\n\n" + " check:\n" + + " 0 < age < 120\n\n"; +var api = new API(); +var args = new FormatCode_Args(); +args.Source = sourceCode; +var result = api.FormatCode(args); +``` + +

+
+ +### FormatPath + +Format KCL file or directory path contains KCL files and returns the changed file paths. + +
Example +

+ +The content of `format_path.k` is + +```python +schema Person: + name: str + age: int + + check: + 0 < age < 120 +``` + +C# Code + +```csharp +using KclLib.API; + +var api = new API(); +var args = new FormatPath_Args(); +var path = "format_path.k"; +args.Path = path; +var result = api.FormatPath(args); +``` + +

+
+ +### LintPath + +Lint files and return error messages including errors and warnings. + +
Example +

+ +The content of `lint_path.k` is + +```python +import math + +a = 1 +``` + +C# Code + +```csharp +using KclLib.API; + +var path = "lint_path.k" +var args = new LintPath_Args(); +args.Paths.Add(path); +var result = new API().LintPath(args); +bool foundWarning = result.Results.Any(warning => warning.Contains("Module 'math' imported but unused")); +``` + +

+
+ +### ValidateCode + +Validate code using schema and JSON/YAML data strings. + +
Example +

+ +C# Code + +```csharp +using KclLib.API; + +string code = @" +schema Person: + name: str + age: int + check: + 0 < age < 120 +"; +string data = "{\"name\": \"Alice\", \"age\": 10}"; +var args = new ValidateCode_Args +{ + Code = code, + Data = data, + Format = "json" +}; +var result = new API().ValidateCode(args); +``` + +

+
+ +### Rename + +Rename all the occurrences of the target symbol in the files. This API will rewrite files if they contain symbols to be renamed. Return the file paths that got changed. + +
Example +

+ +The content of `main.k` is + +```python +a = 1 +b = a +``` + +C# Code + +```csharp +using KclLib.API; + +Rename_Args args = Rename_Args.newBuilder().setPackageRoot(".").setSymbolPath("a") + .addFilePaths("main.k").setNewName("a2").build(); +API apiInstance = new API(); +Rename_Result result = apiInstance.rename(args); +``` + +

+
+ +### RenameCode + +Rename all the occurrences of the target symbol and return the modified code if any code has been changed. This API won't rewrite files but return the changed code. + +
Example +

+ +C# Code + +```csharp +using KclLib.API; + +var args = new RenameCode_Args +{ + PackageRoot = "/mock/path", + SymbolPath = "a", + SourceCodes = { { "/mock/path/main.k", "a = 1\nb = a" } }, + NewName = "a2" +}; +var result = new API().RenameCode(args); +``` + +

+
+ +### Test + +Test KCL packages with test arguments. + +
Example +

+ +C# Code + +```csharp +using KclLib.API; + +var pkg = Path.Combine(parentDirectory, "test_data", "testing"); +var args = new Test_Args(); +args.PkgList.Add(pkg + "/..."); +var result = new API().Test(args); +``` + +

+
+ +### LoadSettingsFiles + +Load the setting file config defined in `kcl.yaml` + +
Example +

+ +The content of `kcl.yaml` is + +```yaml +kcl_cli_configs: + strict_range_check: true +kcl_options: + - key: key + value: value +``` + +C# Code + +```csharp +using KclLib.API; + +var workDir = "."; +var settingsFile = "kcl.yaml"; +var args = new LoadSettingsFiles_Args +{ + WorkDir = workDir, +}; +args.Files.Add(settingsFile); +var result = new API().LoadSettingsFiles(args); +``` + +

+
+ +### UpdateDependencies + +Download and update dependencies defined in the `kcl.mod` file and return the external package name and location list. + +
Example +

+ +The content of `module/kcl.mod` is + +```yaml +[package] +name = "mod_update" +edition = "0.0.1" +version = "0.0.1" + +[dependencies] +helloworld = { oci = "oci://ghcr.io/kcl-lang/helloworld", tag = "0.1.0" } +flask = { git = "https://github.com/kcl-lang/flask-demo-kcl-manifests", commit = "ade147b" } +``` + +C# Code + +```csharp +using KclLib.API; + +var manifestPath = "module"; +var args = new UpdateDependencies_Args { ManifestPath = manifestPath }; +var result = new API().UpdateDependencies(args); +``` + +

+
+ +Call `ExecProgram` with external dependencies + +
Example +

+ +The content of `module/kcl.mod` is + +```yaml +[package] +name = "mod_update" +edition = "0.0.1" +version = "0.0.1" + +[dependencies] +helloworld = { oci = "oci://ghcr.io/kcl-lang/helloworld", tag = "0.1.0" } +flask = { git = "https://github.com/kcl-lang/flask-demo-kcl-manifests", commit = "ade147b" } +``` + +The content of `module/main.k` is + +```python +import helloworld +import flask + +a = helloworld.The_first_kcl_program +``` + +C# Code + +```csharp +using KclLib.API; + +API api = new API(); + +var manifestPath = "module"; +var testFile = Path.Combine(manifestPath, "main.k"); +var updateArgs = new UpdateDependencies_Args { ManifestPath = manifestPath }; +var depResult = new API().UpdateDependencies(updateArgs); +var execArgs = new ExecProgram_Args(); +execArgs.KFilenameList.Add(testFile); +execArgs.ExternalPkgs.AddRange(depResult.ExternalPkgs); +var execResult = new API().ExecProgram(execArgs); +``` + +

+
+ +### GetVersion + +Return the KCL service version information. + +
Example +

+ +C# Code + +```csharp +using KclLib.API; + +var result = new API().GetVersion(new GetVersion_Args()); +``` + +

+
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/xlang-api/java-api.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/xlang-api/java-api.md index 2ecea072..c8df505e 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/xlang-api/java-api.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/xlang-api/java-api.md @@ -206,15 +206,13 @@ app: AppConfig { Java Code -```python -import kcl_lib.api as api - -args = api.LoadPackage_Args( - parse_args=api.ParseProgram_Args(paths=["schema.k"]), resolve_ast=True -) -api = api.API() -result = api.load_package(args) -assert list(result.symbols.values())[0].ty.schema_name == "AppConfig" +```java +import com.kcl.api.*; + +API api = new API(); +LoadPackage_Result result = api.loadPackage(LoadPackage_Args.newBuilder().setResolveAst(true) + .setWithAstIndex(true) + .setParseArgs(ParseProgram_Args.newBuilder().addPaths("schema.k").build()).build()); ```

diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.9/reference/xlang-api/dotnet-api.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.9/reference/xlang-api/dotnet-api.md index bfabfedb..6dea5eed 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.9/reference/xlang-api/dotnet-api.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.9/reference/xlang-api/dotnet-api.md @@ -22,3 +22,625 @@ execArgs.KFilenameList.Add(path); var result = api.ExecProgram(execArgs); Console.WriteLine(result.YamlResult); ``` + +## API 参考 + +### ExecProgram + +Execute KCL file with arguments and return the JSON/YAML result. + +
Example +

+ +The content of `schema.k` is + +```python +schema AppConfig: + replicas: int + +app: AppConfig { + replicas: 2 +} +``` + +C# Code + +```csharp +using KclLib.API; + +var execArgs = new ExecProgram_Args(); +var path = "schema.k" +execArgs.KFilenameList.Add(path); +var result = new API().ExecProgram(execArgs); +``` + +

+
+ +### ParseProgram + +Parse KCL program with entry files and return the AST JSON string. + +
Example +

+ +The content of `schema.k` is + +```python +schema AppConfig: + replicas: int + +app: AppConfig { + replicas: 2 +} +``` + +C# Code + +```csharp +using KclLib.API; + +var path = "schema.k" +var args = new ParseProgram_Args(); +args.Paths.Add(path); +var result = new API().ParseProgram(args); +``` + +

+
+ +### ParseFile + +Parse KCL single file to Module AST JSON string with import dependencies and parse errors. + +
Example +

+ +The content of `schema.k` is + +```python +schema AppConfig: + replicas: int + +app: AppConfig { + replicas: 2 +} +``` + +C# Code + +```csharp +using KclLib.API; + +var path = "schema.k" +var args = new ParseFile_Args { Path = path }; +var result = new API().ParseFile(args); +``` + +

+
+ +### ParseProgram + +Parse KCL program with entry files and return the AST JSON string. + +
Example +

+ +The content of `schema.k` is + +```python +schema AppConfig: + replicas: int + +app: AppConfig { + replicas: 2 +} +``` + +C# Code + +```csharp +using KclLib.API; + +var path = "schema.k"; +var args = new ParseProgram_Args(); +args.Paths.Add(path); +var result = new API().ListOptions(args); +``` + +

+
+ +### LoadPackage + +LoadPackage provides users with the ability to parse KCL program and semantic model information including symbols, types, definitions, etc. + +
Example +

+ +The content of `schema.k` is + +```python +schema AppConfig: + replicas: int + +app: AppConfig { + replicas: 2 +} +``` + +C# Code + +```csharp +using KclLib.API; + +var path = "schema.k"; +var args = new LoadPackage_Args(); +args.ResolveAst = true; +args.ParseArgs = new ParseProgram_Args(); +args.ParseArgs.Paths.Add(path); +var result = new API().LoadPackage(args); +``` + +

+
+ +### ListVariables + +ListVariables provides users with the ability to parse KCL program and get all variables by specs. + +
Example +

+ +The content of `schema.k` is + +```python +schema AppConfig: + replicas: int + +app: AppConfig { + replicas: 2 +} +``` + +C# Code + +```csharp +using KclLib.API; + +var api = new API(); +var args = new ListVariables_Args(); +var path = "schema.k"; +args.Files.Add(path); +var result = api.ListVariables(args); +``` + +

+
+ +### ListOptions + +ListOptions provides users with the ability to parse KCL program and get all option information. + +
Example +

+ +The content of `options.k` is + +```python +a = option("key1") +b = option("key2", required=True) +c = { + metadata.key = option("metadata-key") +} +``` + +C# Code + +```csharp +using KclLib.API; + +var path = "options.k"; +var args = new ParseProgram_Args(); +args.Paths.Add(path); +var result = new API().ListOptions(args); +``` + +

+
+ +### GetSchemaTypeMapping + +Get schema type mapping defined in the program. + +
Example +

+ +The content of `schema.k` is + +```python +schema AppConfig: + replicas: int + +app: AppConfig { + replicas: 2 +} +``` + +C# Code + +```csharp +using KclLib.API; + +var path = "schema.k"; +var execArgs = new ExecProgram_Args(); +execArgs.KFilenameList.Add(path); +var args = new GetSchemaTypeMapping_Args(); +args.ExecArgs = execArgs; +var result = new API().GetSchemaTypeMapping(args); +``` + +

+
+ +### OverrideFile + +Override KCL file with arguments. See [https://www.kcl-lang.io/docs/user_docs/guides/automation](https://www.kcl-lang.io/docs/user_docs/guides/automation) for more override spec guide. + +
Example +

+ +The content of `main.k` is + +```python +a = 1 + +b = { + "a": 1 + "b": 2 +} +``` + +C# Code + +```csharp +using KclLib.API; + +var args = new OverrideFile_Args +{ + File = "main.k", +}; +args.Specs.Add("b.a=2"); +var result = new API().OverrideFile(args); +``` + +

+
+ +### FormatCode + +Format the code source. + +
Example +

+ +C# Code + +```csharp +using KclLib.API; + +string sourceCode = "schema Person:\n" + " name: str\n" + " age: int\n" + " check:\n" + + " 0 < age < 120\n"; +string expectedFormattedCode = "schema Person:\n" + " name: str\n" + " age: int\n\n" + " check:\n" + + " 0 < age < 120\n\n"; +var api = new API(); +var args = new FormatCode_Args(); +args.Source = sourceCode; +var result = api.FormatCode(args); +``` + +

+
+ +### FormatPath + +Format KCL file or directory path contains KCL files and returns the changed file paths. + +
Example +

+ +The content of `format_path.k` is + +```python +schema Person: + name: str + age: int + + check: + 0 < age < 120 +``` + +C# Code + +```csharp +using KclLib.API; + +var api = new API(); +var args = new FormatPath_Args(); +var path = "format_path.k"; +args.Path = path; +var result = api.FormatPath(args); +``` + +

+
+ +### LintPath + +Lint files and return error messages including errors and warnings. + +
Example +

+ +The content of `lint_path.k` is + +```python +import math + +a = 1 +``` + +C# Code + +```csharp +using KclLib.API; + +var path = "lint_path.k" +var args = new LintPath_Args(); +args.Paths.Add(path); +var result = new API().LintPath(args); +bool foundWarning = result.Results.Any(warning => warning.Contains("Module 'math' imported but unused")); +``` + +

+
+ +### ValidateCode + +Validate code using schema and JSON/YAML data strings. + +
Example +

+ +C# Code + +```csharp +using KclLib.API; + +string code = @" +schema Person: + name: str + age: int + check: + 0 < age < 120 +"; +string data = "{\"name\": \"Alice\", \"age\": 10}"; +var args = new ValidateCode_Args +{ + Code = code, + Data = data, + Format = "json" +}; +var result = new API().ValidateCode(args); +``` + +

+
+ +### Rename + +Rename all the occurrences of the target symbol in the files. This API will rewrite files if they contain symbols to be renamed. Return the file paths that got changed. + +
Example +

+ +The content of `main.k` is + +```python +a = 1 +b = a +``` + +C# Code + +```csharp +using KclLib.API; + +Rename_Args args = Rename_Args.newBuilder().setPackageRoot(".").setSymbolPath("a") + .addFilePaths("main.k").setNewName("a2").build(); +API apiInstance = new API(); +Rename_Result result = apiInstance.rename(args); +``` + +

+
+ +### RenameCode + +Rename all the occurrences of the target symbol and return the modified code if any code has been changed. This API won't rewrite files but return the changed code. + +
Example +

+ +C# Code + +```csharp +using KclLib.API; + +var args = new RenameCode_Args +{ + PackageRoot = "/mock/path", + SymbolPath = "a", + SourceCodes = { { "/mock/path/main.k", "a = 1\nb = a" } }, + NewName = "a2" +}; +var result = new API().RenameCode(args); +``` + +

+
+ +### Test + +Test KCL packages with test arguments. + +
Example +

+ +C# Code + +```csharp +using KclLib.API; + +var pkg = Path.Combine(parentDirectory, "test_data", "testing"); +var args = new Test_Args(); +args.PkgList.Add(pkg + "/..."); +var result = new API().Test(args); +``` + +

+
+ +### LoadSettingsFiles + +Load the setting file config defined in `kcl.yaml` + +
Example +

+ +The content of `kcl.yaml` is + +```yaml +kcl_cli_configs: + strict_range_check: true +kcl_options: + - key: key + value: value +``` + +C# Code + +```csharp +using KclLib.API; + +var workDir = "."; +var settingsFile = "kcl.yaml"; +var args = new LoadSettingsFiles_Args +{ + WorkDir = workDir, +}; +args.Files.Add(settingsFile); +var result = new API().LoadSettingsFiles(args); +``` + +

+
+ +### UpdateDependencies + +Download and update dependencies defined in the `kcl.mod` file and return the external package name and location list. + +
Example +

+ +The content of `module/kcl.mod` is + +```yaml +[package] +name = "mod_update" +edition = "0.0.1" +version = "0.0.1" + +[dependencies] +helloworld = { oci = "oci://ghcr.io/kcl-lang/helloworld", tag = "0.1.0" } +flask = { git = "https://github.com/kcl-lang/flask-demo-kcl-manifests", commit = "ade147b" } +``` + +C# Code + +```csharp +using KclLib.API; + +var manifestPath = "module"; +var args = new UpdateDependencies_Args { ManifestPath = manifestPath }; +var result = new API().UpdateDependencies(args); +``` + +

+
+ +Call `ExecProgram` with external dependencies + +
Example +

+ +The content of `module/kcl.mod` is + +```yaml +[package] +name = "mod_update" +edition = "0.0.1" +version = "0.0.1" + +[dependencies] +helloworld = { oci = "oci://ghcr.io/kcl-lang/helloworld", tag = "0.1.0" } +flask = { git = "https://github.com/kcl-lang/flask-demo-kcl-manifests", commit = "ade147b" } +``` + +The content of `module/main.k` is + +```python +import helloworld +import flask + +a = helloworld.The_first_kcl_program +``` + +C# Code + +```csharp +using KclLib.API; + +API api = new API(); + +var manifestPath = "module"; +var testFile = Path.Combine(manifestPath, "main.k"); +var updateArgs = new UpdateDependencies_Args { ManifestPath = manifestPath }; +var depResult = new API().UpdateDependencies(updateArgs); +var execArgs = new ExecProgram_Args(); +execArgs.KFilenameList.Add(testFile); +execArgs.ExternalPkgs.AddRange(depResult.ExternalPkgs); +var execResult = new API().ExecProgram(execArgs); +``` + +

+
+ +### GetVersion + +Return the KCL service version information. + +
Example +

+ +C# Code + +```csharp +using KclLib.API; + +var result = new API().GetVersion(new GetVersion_Args()); +``` + +

+
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.9/reference/xlang-api/java-api.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.9/reference/xlang-api/java-api.md index 2ecea072..c8df505e 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.9/reference/xlang-api/java-api.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.9/reference/xlang-api/java-api.md @@ -206,15 +206,13 @@ app: AppConfig { Java Code -```python -import kcl_lib.api as api - -args = api.LoadPackage_Args( - parse_args=api.ParseProgram_Args(paths=["schema.k"]), resolve_ast=True -) -api = api.API() -result = api.load_package(args) -assert list(result.symbols.values())[0].ty.schema_name == "AppConfig" +```java +import com.kcl.api.*; + +API api = new API(); +LoadPackage_Result result = api.loadPackage(LoadPackage_Args.newBuilder().setResolveAst(true) + .setWithAstIndex(true) + .setParseArgs(ParseProgram_Args.newBuilder().addPaths("schema.k").build()).build()); ```

diff --git a/versioned_docs/version-0.9/reference/xlang-api/dotnet-api.md b/versioned_docs/version-0.9/reference/xlang-api/dotnet-api.md index 3de5fb4e..12387547 100644 --- a/versioned_docs/version-0.9/reference/xlang-api/dotnet-api.md +++ b/versioned_docs/version-0.9/reference/xlang-api/dotnet-api.md @@ -22,3 +22,625 @@ execArgs.KFilenameList.Add(path); var result = api.ExecProgram(execArgs); Console.WriteLine(result.YamlResult); ``` + +## API Reference + +### ExecProgram + +Execute KCL file with arguments and return the JSON/YAML result. + +
Example +

+ +The content of `schema.k` is + +```python +schema AppConfig: + replicas: int + +app: AppConfig { + replicas: 2 +} +``` + +C# Code + +```csharp +using KclLib.API; + +var execArgs = new ExecProgram_Args(); +var path = "schema.k" +execArgs.KFilenameList.Add(path); +var result = new API().ExecProgram(execArgs); +``` + +

+
+ +### ParseProgram + +Parse KCL program with entry files and return the AST JSON string. + +
Example +

+ +The content of `schema.k` is + +```python +schema AppConfig: + replicas: int + +app: AppConfig { + replicas: 2 +} +``` + +C# Code + +```csharp +using KclLib.API; + +var path = "schema.k" +var args = new ParseProgram_Args(); +args.Paths.Add(path); +var result = new API().ParseProgram(args); +``` + +

+
+ +### ParseFile + +Parse KCL single file to Module AST JSON string with import dependencies and parse errors. + +
Example +

+ +The content of `schema.k` is + +```python +schema AppConfig: + replicas: int + +app: AppConfig { + replicas: 2 +} +``` + +C# Code + +```csharp +using KclLib.API; + +var path = "schema.k" +var args = new ParseFile_Args { Path = path }; +var result = new API().ParseFile(args); +``` + +

+
+ +### ParseProgram + +Parse KCL program with entry files and return the AST JSON string. + +
Example +

+ +The content of `schema.k` is + +```python +schema AppConfig: + replicas: int + +app: AppConfig { + replicas: 2 +} +``` + +C# Code + +```csharp +using KclLib.API; + +var path = "schema.k"; +var args = new ParseProgram_Args(); +args.Paths.Add(path); +var result = new API().ListOptions(args); +``` + +

+
+ +### LoadPackage + +LoadPackage provides users with the ability to parse KCL program and semantic model information including symbols, types, definitions, etc. + +
Example +

+ +The content of `schema.k` is + +```python +schema AppConfig: + replicas: int + +app: AppConfig { + replicas: 2 +} +``` + +C# Code + +```csharp +using KclLib.API; + +var path = "schema.k"; +var args = new LoadPackage_Args(); +args.ResolveAst = true; +args.ParseArgs = new ParseProgram_Args(); +args.ParseArgs.Paths.Add(path); +var result = new API().LoadPackage(args); +``` + +

+
+ +### ListVariables + +ListVariables provides users with the ability to parse KCL program and get all variables by specs. + +
Example +

+ +The content of `schema.k` is + +```python +schema AppConfig: + replicas: int + +app: AppConfig { + replicas: 2 +} +``` + +C# Code + +```csharp +using KclLib.API; + +var api = new API(); +var args = new ListVariables_Args(); +var path = "schema.k"; +args.Files.Add(path); +var result = api.ListVariables(args); +``` + +

+
+ +### ListOptions + +ListOptions provides users with the ability to parse KCL program and get all option information. + +
Example +

+ +The content of `options.k` is + +```python +a = option("key1") +b = option("key2", required=True) +c = { + metadata.key = option("metadata-key") +} +``` + +C# Code + +```csharp +using KclLib.API; + +var path = "options.k"; +var args = new ParseProgram_Args(); +args.Paths.Add(path); +var result = new API().ListOptions(args); +``` + +

+
+ +### GetSchemaTypeMapping + +Get schema type mapping defined in the program. + +
Example +

+ +The content of `schema.k` is + +```python +schema AppConfig: + replicas: int + +app: AppConfig { + replicas: 2 +} +``` + +C# Code + +```csharp +using KclLib.API; + +var path = "schema.k"; +var execArgs = new ExecProgram_Args(); +execArgs.KFilenameList.Add(path); +var args = new GetSchemaTypeMapping_Args(); +args.ExecArgs = execArgs; +var result = new API().GetSchemaTypeMapping(args); +``` + +

+
+ +### OverrideFile + +Override KCL file with arguments. See [https://www.kcl-lang.io/docs/user_docs/guides/automation](https://www.kcl-lang.io/docs/user_docs/guides/automation) for more override spec guide. + +
Example +

+ +The content of `main.k` is + +```python +a = 1 + +b = { + "a": 1 + "b": 2 +} +``` + +C# Code + +```csharp +using KclLib.API; + +var args = new OverrideFile_Args +{ + File = "main.k", +}; +args.Specs.Add("b.a=2"); +var result = new API().OverrideFile(args); +``` + +

+
+ +### FormatCode + +Format the code source. + +
Example +

+ +C# Code + +```csharp +using KclLib.API; + +string sourceCode = "schema Person:\n" + " name: str\n" + " age: int\n" + " check:\n" + + " 0 < age < 120\n"; +string expectedFormattedCode = "schema Person:\n" + " name: str\n" + " age: int\n\n" + " check:\n" + + " 0 < age < 120\n\n"; +var api = new API(); +var args = new FormatCode_Args(); +args.Source = sourceCode; +var result = api.FormatCode(args); +``` + +

+
+ +### FormatPath + +Format KCL file or directory path contains KCL files and returns the changed file paths. + +
Example +

+ +The content of `format_path.k` is + +```python +schema Person: + name: str + age: int + + check: + 0 < age < 120 +``` + +C# Code + +```csharp +using KclLib.API; + +var api = new API(); +var args = new FormatPath_Args(); +var path = "format_path.k"; +args.Path = path; +var result = api.FormatPath(args); +``` + +

+
+ +### LintPath + +Lint files and return error messages including errors and warnings. + +
Example +

+ +The content of `lint_path.k` is + +```python +import math + +a = 1 +``` + +C# Code + +```csharp +using KclLib.API; + +var path = "lint_path.k" +var args = new LintPath_Args(); +args.Paths.Add(path); +var result = new API().LintPath(args); +bool foundWarning = result.Results.Any(warning => warning.Contains("Module 'math' imported but unused")); +``` + +

+
+ +### ValidateCode + +Validate code using schema and JSON/YAML data strings. + +
Example +

+ +C# Code + +```csharp +using KclLib.API; + +string code = @" +schema Person: + name: str + age: int + check: + 0 < age < 120 +"; +string data = "{\"name\": \"Alice\", \"age\": 10}"; +var args = new ValidateCode_Args +{ + Code = code, + Data = data, + Format = "json" +}; +var result = new API().ValidateCode(args); +``` + +

+
+ +### Rename + +Rename all the occurrences of the target symbol in the files. This API will rewrite files if they contain symbols to be renamed. Return the file paths that got changed. + +
Example +

+ +The content of `main.k` is + +```python +a = 1 +b = a +``` + +C# Code + +```csharp +using KclLib.API; + +Rename_Args args = Rename_Args.newBuilder().setPackageRoot(".").setSymbolPath("a") + .addFilePaths("main.k").setNewName("a2").build(); +API apiInstance = new API(); +Rename_Result result = apiInstance.rename(args); +``` + +

+
+ +### RenameCode + +Rename all the occurrences of the target symbol and return the modified code if any code has been changed. This API won't rewrite files but return the changed code. + +
Example +

+ +C# Code + +```csharp +using KclLib.API; + +var args = new RenameCode_Args +{ + PackageRoot = "/mock/path", + SymbolPath = "a", + SourceCodes = { { "/mock/path/main.k", "a = 1\nb = a" } }, + NewName = "a2" +}; +var result = new API().RenameCode(args); +``` + +

+
+ +### Test + +Test KCL packages with test arguments. + +
Example +

+ +C# Code + +```csharp +using KclLib.API; + +var pkg = Path.Combine(parentDirectory, "test_data", "testing"); +var args = new Test_Args(); +args.PkgList.Add(pkg + "/..."); +var result = new API().Test(args); +``` + +

+
+ +### LoadSettingsFiles + +Load the setting file config defined in `kcl.yaml` + +
Example +

+ +The content of `kcl.yaml` is + +```yaml +kcl_cli_configs: + strict_range_check: true +kcl_options: + - key: key + value: value +``` + +C# Code + +```csharp +using KclLib.API; + +var workDir = "."; +var settingsFile = "kcl.yaml"; +var args = new LoadSettingsFiles_Args +{ + WorkDir = workDir, +}; +args.Files.Add(settingsFile); +var result = new API().LoadSettingsFiles(args); +``` + +

+
+ +### UpdateDependencies + +Download and update dependencies defined in the `kcl.mod` file and return the external package name and location list. + +
Example +

+ +The content of `module/kcl.mod` is + +```yaml +[package] +name = "mod_update" +edition = "0.0.1" +version = "0.0.1" + +[dependencies] +helloworld = { oci = "oci://ghcr.io/kcl-lang/helloworld", tag = "0.1.0" } +flask = { git = "https://github.com/kcl-lang/flask-demo-kcl-manifests", commit = "ade147b" } +``` + +C# Code + +```csharp +using KclLib.API; + +var manifestPath = "module"; +var args = new UpdateDependencies_Args { ManifestPath = manifestPath }; +var result = new API().UpdateDependencies(args); +``` + +

+
+ +Call `ExecProgram` with external dependencies + +
Example +

+ +The content of `module/kcl.mod` is + +```yaml +[package] +name = "mod_update" +edition = "0.0.1" +version = "0.0.1" + +[dependencies] +helloworld = { oci = "oci://ghcr.io/kcl-lang/helloworld", tag = "0.1.0" } +flask = { git = "https://github.com/kcl-lang/flask-demo-kcl-manifests", commit = "ade147b" } +``` + +The content of `module/main.k` is + +```python +import helloworld +import flask + +a = helloworld.The_first_kcl_program +``` + +C# Code + +```csharp +using KclLib.API; + +API api = new API(); + +var manifestPath = "module"; +var testFile = Path.Combine(manifestPath, "main.k"); +var updateArgs = new UpdateDependencies_Args { ManifestPath = manifestPath }; +var depResult = new API().UpdateDependencies(updateArgs); +var execArgs = new ExecProgram_Args(); +execArgs.KFilenameList.Add(testFile); +execArgs.ExternalPkgs.AddRange(depResult.ExternalPkgs); +var execResult = new API().ExecProgram(execArgs); +``` + +

+
+ +### GetVersion + +Return the KCL service version information. + +
Example +

+ +C# Code + +```csharp +using KclLib.API; + +var result = new API().GetVersion(new GetVersion_Args()); +``` + +

+
diff --git a/versioned_docs/version-0.9/reference/xlang-api/java-api.md b/versioned_docs/version-0.9/reference/xlang-api/java-api.md index c025dd90..fee90323 100644 --- a/versioned_docs/version-0.9/reference/xlang-api/java-api.md +++ b/versioned_docs/version-0.9/reference/xlang-api/java-api.md @@ -207,15 +207,13 @@ app: AppConfig { Java Code -```python -import kcl_lib.api as api - -args = api.LoadPackage_Args( - parse_args=api.ParseProgram_Args(paths=["schema.k"]), resolve_ast=True -) -api = api.API() -result = api.load_package(args) -assert list(result.symbols.values())[0].ty.schema_name == "AppConfig" +```java +import com.kcl.api.*; + +API api = new API(); +LoadPackage_Result result = api.loadPackage(LoadPackage_Args.newBuilder().setResolveAst(true) + .setWithAstIndex(true) + .setParseArgs(ParseProgram_Args.newBuilder().addPaths("schema.k").build()).build()); ```