Skip to main content
Version: 0.8

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(file, code, 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.

Each spec string satisfies the form: <pkgpath>:<field_path>=<filed_value> or <pkgpath>:<field_path>-
When the pkgpath is '__main__', it can be omitted.

importPaths. List of import statements that need to be added

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 ('et_struct)

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.

Example (Get Field)

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"))

}
R000A

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(file, code, 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 Option

type Option = kcl.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 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 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 ValidateOptions

type ValidateOptions = validate.ValidateOptions