Go API
import "kcl-lang.io/kcl-go"
KCL Go SDK
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ 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
{
const k_code = `
name = "kcl"
age = 1
two = 2
schema Person:
name: str = "kcl"
age: int = 1
x0 = Person {}
x1 = Person {
age = 101
}
`
yaml := kclvm.MustRun("testdata/main.k", kclvm.WithCode(k_code)).First().YAMLString()
fmt.Println(yaml)
fmt.Println("----")
result := kclvm.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
- Go API
- [KCL Go SDK](#kcl-go-sdk)- Index
- Constants
- func FormatCode
- [Output](#output) - func FormatPath
- func InitKclvmPath
- func InitKclvmRuntime
- func LintPath
- [Output](#output-1) - func ListDepFiles
- func ListDownStreamFiles
- func ListUpStreamFiles
- func OverrideFile
- func ValidateCode
- type KCLResult
- [Output](#output-2)
- [Output](#output-3) - type KCLResultList
- type KclType
- type ListDepFilesOption
- type ListDepsOptions
- type Option
- type ValidateOptions
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
{
out, err := kclvm.FormatCode(`a = 1+2`)
if err != nil {
log.Fatal(err)
}
fmt.Println(string(out))
}
Output
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
{
changedPaths, err := kclvm.FormatPath("testdata/fmt")
if err != nil {
log.Fatal(err)
}
fmt.Println(changedPaths)
}
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
{
results, err := kclvm.LintPath([]string{"testdata/lint/import.k"})
if err != nil {
log.Fatal(err)
}
for _, s := range results {
fmt.Println(s)
}
}
Output
Module 'a' is reimported multiple times
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 ValidateCode
func ValidateCode(data, code string, opt *ValidateOptions) (ok bool, err error)
ValidateCode validate data match code
type KCLResult
type KCLResult = kcl.KCLResult
Example
{
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 := kclvm.MustRun("testdata/main.k", kclvm.WithCode(k_code)).First()
fmt.Println("x0.name:", result.Get("x0.name"))
fmt.Println("x1.age:", result.Get("x1.age"))
}
Output
x0.name: kcl-go
x1.age: 101
Example ('et_struct)
{
const k_code = `
schema Person:
name: str = "kcl"
age: int = 1
X: int = 2
x = {
"a": Person {age = 101}
"b": 123
}
`
result := kclvm.MustRun("testdata/main.k", kclvm.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)
}
Output
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
{
yaml := kclvm.MustRun("testdata/main.k", kclvm.WithCode(`name = "kcl"`)).First().YAMLString()
fmt.Println(yaml)
}
Output
name: kcl
Example (Raw Yaml)
{
const code = `
b = 1
a = 2
`
yaml := kclvm.MustRun("testdata/main.k", kclvm.WithCode(code)).GetRawYamlResult()
fmt.Println(yaml)
yaml_sorted := kclvm.MustRun("testdata/main.k", kclvm.WithCode(code), kclvm.WithSortKeys(true)).GetRawYamlResult()
fmt.Println(yaml_sorted)
}
Output
b: 1
a: 2
a: 2
b: 1
Example (Schema Type)
{
const code = `
schema Person:
name: str = ""
x = Person()
`
json := kclvm.MustRun("testdata/main.k", kclvm.WithCode(code)).First().JSONString()
fmt.Println(json)
}
Output
{
"x": {
"name": ""
}
}
Example (Settings)
{
yaml := kclvm.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)
{
x, err := kclvm.Run("./testdata/app0/kcl.yaml")
assert(err == nil, err)
fmt.Println(x.First().Get("deploy_topology.1.zone"))
}
Output
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
{
result, _ := kclvm.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 WithKFilenames
func WithKFilenames(filenames ...string) Option
WithKFilenames returns a Option which hold a filenames list.
func WithOptions
func WithOptions(key_value_list ...string) Option
WithOptions returns a Option which hold a key=value pair list for option function.
Example
{
const code = `
name = option("name")
age = option("age")
`
x, err := kclvm.Run("hello.k", kclvm.WithCode(code),
kclvm.WithOptions("name=kcl", "age=1"),
)
if err != nil {
log.Fatal(err)
}
fmt.Println(x.First().YAMLString())
}
Output
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 WithSettings
func WithSettings(filename string) Option
WithSettings returns a Option which hold a settings file.
func WithSortKeys
func WithSortKeys(sortKeys bool) Option
WithSortKeys returns a Option which hold a sortKeys switch.
func WithWorkDir
func WithWorkDir(workDir string) Option
WithWorkDir returns a Option which hold a work dir.
type ValidateOptions
type ValidateOptions = validate.ValidateOptions