Skip to main content
Version: Next

Go API

import kcl "kcl-lang.io/kcl-go"
┌─────────────────┐         ┌─────────────────┐           ┌─────────────────┐
│     kcl files   │         │    KCL-Go-API   │           │  KCLResultList  │
│  ┌───────────┐  │         │                 │           │                 │
│  │    1.k    │  │         │                 │           │                 │
│  └───────────┘  │         │                 │           │  ┌───────────┐  │         ┌───────────────┐
│  ┌───────────┐  │         │  ┌───────────┐  │           │  │ KCLResult │──┼────────▶│x.Get("a.b.c") │
│  │    2.k    │  │         │  │ Run(path) │  │           │  └───────────┘  │         └───────────────┘
│  └───────────┘  │────┐    │  └───────────┘  │           │                 │
│  ┌───────────┐  │    │    │                 │           │  ┌───────────┐  │         ┌───────────────┐
│  │    3.k    │  │    │    │                 │           │  │ KCLResult │──┼────────▶│x.Get("k", &v) │
│  └───────────┘  │    │    │                 │           │  └───────────┘  │         └───────────────┘
│  ┌───────────┐  │    ├───▶│  ┌───────────┐  │──────────▶│                 │
│  │setting.yml│  │    │    │  │RunFiles() │  │           │  ┌───────────┐  │         ┌───────────────┐
│  └───────────┘  │    │    │  └───────────┘  │           │  │ KCLResult │──┼────────▶│x.JSONString() │
└─────────────────┘    │    │                 │           │  └───────────┘  │         └───────────────┘
                       │    │                 │           │                 │
┌─────────────────┐    │    │                 │           │  ┌───────────┐  │         ┌───────────────┐
│     Options     │    │    │  ┌───────────┐  │           │  │ KCLResult │──┼────────▶│x.YAMLString() │
│WithOptions      │    │    │  │MustRun()  │  │           │  └───────────┘  │         └───────────────┘
│WithOverrides    │────┘    │  └───────────┘  │           │                 │
│WithWorkDir      │         │                 │           │                 │
│WithDisableNone  │         │                 │           │                 │
└─────────────────┘         └─────────────────┘           └─────────────────┘
Example

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

x0 = Person {}
x1 = Person {
    age = 101
}
`

    yaml := kcl.MustRun("testdata/main.k", kcl.WithCode(k_code)).First().YAMLString()
    fmt.Println(yaml)

    fmt.Println("----")

    result := kcl.MustRun("./testdata/main.k").First()
    fmt.Println(result.JSONString())

    fmt.Println("----")
    fmt.Println("x0.name:", result.Get("x0.name"))
    fmt.Println("x1.age:", result.Get("x1.age"))

    fmt.Println("----")

    var person struct {
        Name string
        Age  int
    }
    fmt.Printf("person: %+v\n", result.Get("x1", &person))
}

Index​

Constants​

KclvmAbiVersion is the current kclvm ABI version.

const KclvmAbiVersion = scripts.KclvmAbiVersion

func FormatCode​

func FormatCode(code interface{}) ([]byte, error)

FormatCode returns the formatted code.

Example

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)
    }
    fmt.Println(string(out))

}
a = 1 + 2

func FormatPath​

func FormatPath(path string) (changedPaths []string, err error)

FormatPath formats files from the given path path: if path is `.` or empty string, all KCL files in current directory will be formatted, not recursively if path is `path/file.k`, the specified KCL file will be formatted if path is `path/to/dir`, all KCL files in the specified dir will be formatted, not recursively if path is `path/to/dir/...`, all KCL files in the specified dir will be formatted recursively

the returned changedPaths are the changed file paths (relative path)

Example

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)
    }
    fmt.Println(changedPaths)
}

func GetSchemaTypeMapping​

func GetSchemaTypeMapping(filename string, src any, schemaName string) (map[string]*KclType, error)

GetSchemaTypeMapping returns a \<schemaName>:\<schemaType> 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​

func InitKclvmPath(kclvmRoot string)

InitKclvmPath init kclvm path.

func InitKclvmRuntime​

func InitKclvmRuntime(n int)

InitKclvmRuntime init kclvm process.

func LintPath​

func LintPath(paths []string) (results []string, err error)

LintPath lint files from the given path

Example

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 {
        log.Fatal(err)
    }
    for _, s := range results {
        fmt.Println(s)
    }

}
Module 'a' is reimported multiple times
Module 'a' imported but unused
Module 'a' imported but unused

func ListDepFiles​

func ListDepFiles(workDir string, opt *ListDepFilesOption) (files []string, err error)

ListDepFiles return the depend files from the given path

func ListDownStreamFiles​

func ListDownStreamFiles(workDir string, opt *ListDepsOptions) ([]string, error)

ListDownStreamFiles return a list of downstream depend files from the given changed path list.

func ListUpStreamFiles​

func ListUpStreamFiles(workDir string, opt *ListDepsOptions) (deps []string, err error)

ListUpStreamFiles return a list of upstream depend files from the given path list

func OverrideFile​

func OverrideFile(file string, specs, importPaths []string) (bool, error)

OverrideFile rewrites a file with override spec file: string. The File that need to be overridden specs: []string. List of specs that need to be overridden. importPaths. List of import statements that need to be added. See https://www.kcl-lang.io/docs/user_docs/guides/automation for more override spec guide.

func Validate​

func Validate(dataFile, schemaFile string, opts *ValidateOptions) (ok bool, err error)

Validate validates the given data file against the specified schema file with the provided options.

func ValidateCode​

func ValidateCode(data, code string, opts *ValidateOptions) (ok bool, err error)

ValidateCode validate data string match code string

type KCLResult​

type KCLResult = kcl.KCLResult
Example

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

x0 = Person {name = "kcl-go"}
x1 = Person {age = 101}
`

    result := kcl.MustRun("testdata/main.k", kcl.WithCode(k_code)).First()

    fmt.Println("x0.name:", result.Get("x0.name"))
    fmt.Println("x1.age:", result.Get("x1.age"))

}
x0.name: kcl-go
x1.age: 101

Example (Get)

package main

import (
    "fmt"

    kcl "kcl-lang.io/kcl-go"
)

func main() {
    const k_code = `
schema Person:
    name: str = "kcl"
    age: int = 1
    X: int = 2

x = {
    "a": Person {age = 101}
    "b": 123
}
`

    result := kcl.MustRun("testdata/main.k", kcl.WithCode(k_code)).First()

    var person struct {
        Name string
        Age  int
    }
    fmt.Printf("person: %+v\n", result.Get("x.a", &person))
    fmt.Printf("person: %+v\n", person)

}
person: &{Name:kcl Age:101}
person: {Name:kcl Age:101}

type KCLResultList​

type KCLResultList = kcl.KCLResultList

func MustRun​

func MustRun(path string, opts ...Option) *KCLResultList

MustRun is like Run but panics if return any error.

Example

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)

}
name: kcl

Example (Raw Yaml)

package main

import (
    "fmt"

    kcl "kcl-lang.io/kcl-go"
)

func main() {
    const code = `
b = 1
a = 2
`
    yaml := kcl.MustRun("testdata/main.k", kcl.WithCode(code)).GetRawYamlResult()
    fmt.Println(yaml)

    yaml_sorted := kcl.MustRun("testdata/main.k", kcl.WithCode(code), kcl.WithSortKeys(true)).GetRawYamlResult()
    fmt.Println(yaml_sorted)

}
b: 1
a: 2
a: 2
b: 1

Example (Schema Type)

package main

import (
    "fmt"

    kcl "kcl-lang.io/kcl-go"
)

func main() {
    const code = `
schema Person:
    name: str = ""

x = Person()
`
    json := kcl.MustRun("testdata/main.k", kcl.WithCode(code)).First().JSONString()
    fmt.Println(json)

}
{
    "x": {
        "name": ""
    }
}

Example (Settings)

package main

import (
    "fmt"

    kcl "kcl-lang.io/kcl-go"
)

func main() {
    yaml := kcl.MustRun("./testdata/app0/kcl.yaml").First().YAMLString()
    fmt.Println(yaml)
}

func Run​

func Run(path string, opts ...Option) (*KCLResultList, error)

Run evaluates the KCL program with path and opts, then returns the object list.

func RunFiles​

func RunFiles(paths []string, opts ...Option) (*KCLResultList, error)

RunFiles evaluates the KCL program with multi file path and opts, then returns the object list.

Example

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())
}

type KclType​

type KclType = kcl.KclType

func GetSchemaType​

func GetSchemaType(filename string, src any, schemaName string) ([]*KclType, error)

GetSchemaType returns 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.

type ListDepFilesOption​

type ListDepFilesOption = list.Option

type ListDepsOptions​

type ListDepsOptions = list.DepOptions

type ListOptionsArgs​

type ListOptionsArgs = loader.ListOptionsArgs

type ListOptionsResult​

type ListOptionsResult = loader.ListOptionsResult

func ListOptions​

func ListOptions(args *ListOptionsArgs) (*ListOptionsResult, error)

ListOptions provides users with the ability to parse kcl program and get all option calling information.

Example

package main

import (
    "fmt"
    "log"

    kcl "kcl-lang.io/kcl-go"
)

func main() {
    result, err := kcl.ListOptions(&kcl.ListOptionsArgs{
        Paths: []string{"testdata/option/main.k"},
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(result)

}
options:{name:"key1"} options:{name:"key2" required:true} options:{name:"metadata-key"}

type ListVariablesArgs​

type ListVariablesArgs = loader.ListVariablesArgs

type ListVariablesResult​

type ListVariablesResult = loader.ListVariablesResult

func ListVariables​

func ListVariables(args *ListVariablesArgs) (*ListVariablesResult, error)

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

Example

package main

import (
    "fmt"
    "log"

    kcl "kcl-lang.io/kcl-go"
)

func main() {
    result, err := kcl.ListVariables(&kcl.ListVariablesArgs{
        Files: []string{"testdata/main.k"},
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(result)

}
variables:{key:"age"  value:{variables:{value:"2"  op_sym:"="}}}  variables:{key:"four"  value:{variables:{value:"4"  op_sym:"="}}}  variables:{key:"name"  value:{variables:{value:"\"kcl-go\""  op_sym:"="}}}  variables:{key:"x0"  value:{variables:{value:"Person {}"  type_name:"Person"  op_sym:"="}}}  variables:{key:"x1"  value:{variables:{value:"Person {age = 101}"  type_name:"Person"  op_sym:"="  dict_entries:{key:"age"  value:{value:"101"  op_sym:"="}}}}}

type LoadPackageArgs​

type LoadPackageArgs = loader.LoadPackageArgs

type LoadPackageResult​

type LoadPackageResult = loader.LoadPackageResult

func LoadPackage​

func LoadPackage(args *LoadPackageArgs) (*LoadPackageResult, error)

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

Example

package main

import (
    "fmt"
    "log"

    kcl "kcl-lang.io/kcl-go"
)

func main() {
    result, err := kcl.LoadPackage(&kcl.LoadPackageArgs{
        ParseArgs: &kcl.ParseProgramArgs{
            Paths: []string{"testdata/main.k"},
        },
        ResolveAst: true,
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(result)
}

type Option​

type Option = kcl.Option

func NewOption​

func NewOption() *Option

NewOption returns a new Option.

func WithCode​

func WithCode(codes ...string) Option

WithCode returns a Option which hold a kcl source code list.

func WithDisableNone​

func WithDisableNone(disableNone bool) Option

WithDisableNone returns a Option which hold a disable none switch.

func WithExternalPkgAndPath​

func WithExternalPkgAndPath(name, path string) Option

WithExternalPkgAndPath returns a Option which hold a external package.

func WithExternalPkgs​

func WithExternalPkgs(externalPkgs ...string) Option

WithExternalPkgs returns a Option which hold a external package list.

func WithFullTypePath​

func WithFullTypePath(fullTypePath bool) Option

WithFullTypePath returns a Option which hold a include full type string in the `_type` attribute.

func WithIncludeSchemaTypePath​

func WithIncludeSchemaTypePath(includeSchemaTypePath bool) Option

WithIncludeSchemaTypePath returns a Option which hold a include schema type path switch.

func WithKFilenames​

func WithKFilenames(filenames ...string) Option

WithKFilenames returns a Option which hold a filenames list.

func WithLogger​

func WithLogger(l io.Writer) Option

WithLogger returns a Option which hold a logger.

func WithOptions​

func WithOptions(key_value_list ...string) Option

WithOptions returns a Option which hold a key=value pair list for option function.

Example

package main

import (
    "fmt"
    "log"

    kcl "kcl-lang.io/kcl-go"
)

func main() {
    const code = `
name = option("name")
age = option("age")
`
    x, err := kcl.Run("hello.k", kcl.WithCode(code),
        kcl.WithOptions("name=kcl", "age=1"),
    )
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(x.First().YAMLString())

}
age: 1
name: kcl

func WithOverrides​

func WithOverrides(override_list ...string) Option

WithOverrides returns a Option which hold a override list.

func WithPrintOverridesAST​

func WithPrintOverridesAST(printOverridesAST bool) Option

WithPrintOverridesAST returns a Option which hold a printOverridesAST switch.

func WithSelectors​

func WithSelectors(selectors ...string) Option

WithSelectors returns a Option which hold a path selector list.

func WithSettings​

func WithSettings(filename string) Option

WithSettings returns a Option which hold a settings file.

func WithShowHidden​

func WithShowHidden(showHidden bool) Option

WithShowHidden returns a Option which holds a showHidden switch.

func WithSortKeys​

func WithSortKeys(sortKeys bool) Option

WithSortKeys returns a Option which holds a sortKeys switch.

func WithWorkDir​

func WithWorkDir(workDir string) Option

WithWorkDir returns a Option which hold a work dir.

type ParseProgramArgs​

type ParseProgramArgs = parser.ParseProgramArgs

type ParseProgramResult​

type ParseProgramResult = parser.ParseProgramResult

func ParseProgram​

func ParseProgram(args *ParseProgramArgs) (*ParseProgramResult, error)

Parse KCL program with entry files and return the AST JSON string.

Example

package main

import (
    "fmt"
    "log"

    kcl "kcl-lang.io/kcl-go"
)

func main() {
    result, err := kcl.ParseProgram(&kcl.ParseProgramArgs{
        Paths: []string{"testdata/main.k"},
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(result)
}

type TestCaseInfo​

type TestCaseInfo = testing.TestCaseInfo

type TestOptions​

type TestOptions = testing.TestOptions

type TestResult​

type TestResult = testing.TestResult

func Test​

func Test(testOpts *TestOptions, opts ...Option) (TestResult, error)

Test calls the test tool to run uni tests in packages.

type UpdateDependenciesArgs​

type UpdateDependenciesArgs = module.UpdateDependenciesArgs

type UpdateDependenciesResult​

type UpdateDependenciesResult = module.UpdateDependenciesResult

func UpdateDependencies​

func UpdateDependencies(args *UpdateDependenciesArgs) (*UpdateDependenciesResult, error)

Download and update dependencies defined in the kcl.mod file and return the external package name and location list.

Example

package main

import (
    "fmt"
    "log"

    kcl "kcl-lang.io/kcl-go"
    "kcl-lang.io/kcl-go/pkg/spec/gpyrpc"
)

func main() {
    // [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" }

    result, err := kcl.UpdateDependencies(&gpyrpc.UpdateDependencies_Args{
        ManifestPath: "testdata/update_dependencies",
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(result)
}

Example (Exec Program)

package main

import (
    "fmt"
    "log"

    kcl "kcl-lang.io/kcl-go"
    "kcl-lang.io/kcl-go/pkg/spec/gpyrpc"
)

func main() {
    // [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" }

    result, err := kcl.UpdateDependencies(&gpyrpc.UpdateDependencies_Args{
        ManifestPath: "testdata/update_dependencies",
    })
    if err != nil {
        log.Fatal(err)
    }

    // import helloworld
    // import flask
    // a = helloworld.The_first_kcl_program
    // fmt.Println(result.ExternalPkgs)

    opt := kcl.NewOption()
    opt.ExternalPkgs = result.ExternalPkgs

    runResult, err := kcl.Run("testdata/update_dependencies/main.k", *opt)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(runResult.GetRawYamlResult())

}
a: Hello World!

type ValidateOptions​

type ValidateOptions = validate.ValidateOptions

type VersionResult​

type VersionResult = kcl.VersionResult

func GetVersion​

func GetVersion() (*VersionResult, error)

GetVersion returns the KCL service version information.