Skip to main content
Version: 0.10

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.