kclvm

README

KCL Go SDK

KCL is an open-source, constraint-based record and functional language that enhances the writing of complex configurations, including those for cloud-native scenarios. With its advanced programming language technology and practices, KCL is dedicated to promoting better modularity, scalability, and stability for configurations. It enables simpler logic writing and offers ease of automation APIs and integration with homegrown systems.

What is it for?

You can use KCL to

• Generate low-level static configuration data such as JSON, YAML, etc., or integrate with existing data.
• Reduce boilerplate in configuration data with the schema modeling.
• Define schemas with rule constraints for configuration data and validate them automatically.
• Organize, simplify, unify and manage large configurations without side effects through gradient automation schemes and GitOps.
• Manage large configurations in a scalable way with isolated configuration blocks.
• Mutating or validating Kubernetes resources with cloud-native configuration tool plugins.
• Used as a platform engineering programming language to deliver modern applications with Kusion Stack.

Building

• Install Go 1.19+

go run ./cmds/kcl-go run hello.k
name: kcl
age: 1
two: 2
x0:
  name: kcl
  age: 1
x1:
  name: kcl
  age: 101

Testing

go test ./...

Run KCL Code with Go SDK

package main

import (
	"fmt"

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

func main() {
	yaml := kcl.MustRun("kubernetes.k", kcl.WithCode(k_code)).GetRawYamlResult()
	fmt.Println(yaml)
}

const k_code = `
apiVersion = "apps/v1"
kind = "Deployment"
metadata = {
    name = "nginx"
    labels.app = "nginx"
}
spec = {
    replicas = 3
    selector.matchLabels = metadata.labels
    template.metadata.labels = metadata.labels
    template.spec.containers = [
        {
            name = metadata.name
            image = "${metadata.name}:1.14.2"
            ports = [{ containerPort = 80 }]
        }
    ]
}
`

Run the command:

go run ./examples/kubernetes/main.go

Output:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
  labels:
    app: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.2
        ports:
        - containerPort: 80

Documents

See the KCL website

License

Apache License Version 2.0

Documentation

Overview

Package kclvm

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

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
• func FormatCode(code interface{}) ([]byte, error)
• func FormatPath(path string) (changedPaths []string, err error)
• func GetSchemaTypeMapping(file, code, schemaName string) (map[string]*KclType, error)
• func InitKclvmPath(kclvmRoot string)
• func InitKclvmRuntime(n int)
• func LintPath(paths []string) (results []string, err error)
• func ListDepFiles(workDir string, opt *ListDepFilesOption) (files []string, err error)
• func ListDownStreamFiles(workDir string, opt *ListDepsOptions) ([]string, error)
• func ListUpStreamFiles(workDir string, opt *ListDepsOptions) (deps []string, err error)
• func OverrideFile(file string, specs, importPaths []string) (bool, error)
• func ValidateCode(data, code string, opt *ValidateOptions) (ok bool, err error)
• type KCLResult
• type KCLResultList
  • func MustRun(path string, opts ...Option) *KCLResultList
  • func Run(path string, opts ...Option) (*KCLResultList, error)
  • func RunFiles(paths []string, opts ...Option) (*KCLResultList, error)
• type KclType
  • func GetSchemaType(file, code, schemaName string) ([]*KclType, error)
• type ListDepFilesOption
• type ListDepsOptions
• type Option
  • func WithCode(codes ...string) Option
  • func WithDisableNone(disableNone bool) Option
  • func WithExternalPkgs(externalPkgs ...string) Option
  • func WithIncludeSchemaTypePath(includeSchemaTypePath bool) Option
  • func WithKFilenames(filenames ...string) Option
  • func WithOptions(key_value_list ...string) Option
  • func WithOverrides(override_list ...string) Option
  • func WithPrintOverridesAST(printOverridesAST bool) Option
  • func WithSelectors(selectors ...string) Option
  • func WithSettings(filename string) Option
  • func WithSortKeys(sortKeys bool) Option
  • func WithWorkDir(workDir string) Option
• type TestCaseInfo
• type TestOptions
• type TestResult
  • func Test(testOpts *TestOptions, opts ...Option) (TestResult, error)
• type ValidateOptions

Examples

• Package
• FormatCode
• FormatPath
• KCLResult
• LintPath
• MustRun
• MustRun (RawYaml)
• MustRun (SchemaType)
• MustRun (Settings)
• Run (GetField)
• RunFiles
• WithOptions

Constants

const KclvmAbiVersion = scripts.KclvmAbiVersion

KclvmAbiVersion is the current kclvm ABI version.

Functions

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

}

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

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

}

Output:

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 ValidateCode

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

ValidateCode validate data match code

Types

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

}

Output:

x0.name: kcl-go
x1.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)

}

Output:

name: kcl

Example (RawYaml)

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)

}

Output:

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

Example (SchemaType)

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)

}

Output:

{
    "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 (GetField)

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

}

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

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

}

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