go-api

kclvm

import "github.com/kcl-lang/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 = `
import kcl_plugin.hello

name = "kcl"
age = 1

two = hello.add(1, 1)

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

• func FormatCode(code interface{}) ([]byte, error)
• func FormatPath(path string) (changedPaths []string, err error)
• func InitKclvmRuntime(n int)
• func LintPath(path string) (results []string, err error)
• func OverrideFile(file string, specs []string) (bool, error)
• func RunPlayground(address string) error
• func ValidateCode(data, code string, opt *ValidateOptions) (ok bool, err error)
• type KCLResult
  • func EvalCode(code string) (*KCLResult, error)
• 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 Option
  • func WithCode(codes ...string) Option
  • func WithDisableNone(disableNone 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 WithSettings(filename string) Option
  • func WithWorkDir(workDir string) Option
• type ValidateOptions

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 InitKclvmRuntime

func InitKclvmRuntime(n int)

InitKclvmRuntime init kclvm process.

func LintPath

func LintPath(path string) (results []string, err error)

LintPath lint files from the given path

Example

{

    results, err := kclvm.LintPath("testdata/lint/import.k")
    if err != nil {
        log.Fatal(err)
    }
    for _, s := range results {
        fmt.Println(s)
    }

}

Output

Unable to import abc.
a is reimported multiple times.
a imported but unused.

func OverrideFile

func OverrideFile(file string, specs []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.

func RunPlayground

func RunPlayground(address string) error

RunPlayground start KCL playground on given address.

Example

{
    addr := "localhost:2022"
    fmt.Printf("listen at http://%s\n", addr)

    kclvm.RunPlayground(addr)
}

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 = `
import kcl_plugin.hello

name = "kcl"
age = 1
    
two = hello.add(1, 1)
    
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}

func EvalCode

func EvalCode(code string) (*KCLResult, error)

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

RZ24A

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

func WithWorkDir(workDir string) Option

WithWorkDir returns a Option which hold a work dir.

type ValidateOptions

type ValidateOptions = validate.ValidateOptions

Generated by gomarkdoc