Go API
import "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))
}
Constants
KclAbiVersion is the current kcl ABI version.
const KclAbiVersion = scripts.KclAbiVersion
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 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)
}
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.UpdateDependenciesArgs{
ManifestPath: "testdata/update_dependencies",
})
if err != nil {
log.Fatal(err)
}
fmt.Println(result)
}
Example (Exec Program)
package main
import (
"fmt"
"log"
"kcl-lang.io/kcl-go/pkg/native"
"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" }
svc := native.NewNativeServiceClient()
result, err := svc.UpdateDependencies(&gpyrpc.UpdateDependenciesArgs{
ManifestPath: "testdata/update_dependencies",
})
if err != nil {
log.Fatal(err)
}
// import helloworld
// import flask
// a = helloworld.The_first_kcl_program
// fmt.Println(result.ExternalPkgs)
execResult, err := svc.ExecProgram(&gpyrpc.ExecProgramArgs{
KFilenameList: []string{"testdata/update_dependencies/main.k"},
ExternalPkgs: result.ExternalPkgs,
})
if err != nil {
log.Fatal(err)
}
fmt.Println(execResult.YamlResult)
}
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.