Skip to main content
Version: Next

.NET API

Installation​

dotnet add package KclLib

Quick Start​

using KclLib.API;

var api = new API();
var execArgs = new ExecProgram_Args();
var path = Path.Combine("test_data", "schema.k");
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

schema AppConfig:
    replicas: int

app: AppConfig {
    replicas: 2
}

C# Code

using KclLib.API;

var execArgs = new ExecProgram_Args();
var path = "schema.k"
execArgs.KFilenameList.Add(path);
var result = new API().ExecProgram(execArgs);

ParseFile​

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

Example

The content of schema.k is

schema AppConfig:
    replicas: int

app: AppConfig {
    replicas: 2
}

C# Code

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

schema AppConfig:
    replicas: int

app: AppConfig {
    replicas: 2
}

C# Code

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

schema AppConfig:
    replicas: int

app: AppConfig {
    replicas: 2
}

C# Code

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

schema AppConfig:
    replicas: int

app: AppConfig {
    replicas: 2
}

C# Code

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

a = option("key1")
b = option("key2", required=True)
c = {
    metadata.key = option("metadata-key")
}

C# Code

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

schema AppConfig:
    replicas: int

app: AppConfig {
    replicas: 2
}

C# Code

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 for more override spec guide.

Example

The content of main.k is

a = 1

b = {
    "a": 1
    "b": 2
}

C# Code

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

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

schema Person:
    name:   str
    age:    int

    check:
        0 <   age <   120

C# Code

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

import math

a = 1

C# Code

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

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

a = 1
b = a

C# Code

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

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

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

kcl_cli_configs:
  strict_range_check: true
kcl_options:
  - key: key
    value: value

C# Code

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

[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

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

[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

import helloworld
import flask

a = helloworld.The_first_kcl_program

C# Code

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

using KclLib.API;

var result = new API().GetVersion(new GetVersion_Args());