From 6ba2403e318f20eb5c347ed9ef8e8426725d7467 Mon Sep 17 00:00:00 2001 From: peefy Date: Tue, 28 Nov 2023 21:31:37 +0800 Subject: [PATCH] feat: add api gen cmd Signed-off-by: peefy --- .gitignore | 1 - Makefile | 5 + docs/api.md | 981 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 986 insertions(+), 1 deletion(-) create mode 100644 docs/api.md diff --git a/.gitignore b/.gitignore index f3c386de..596f9372 100644 --- a/.gitignore +++ b/.gitignore @@ -21,4 +21,3 @@ __pycache__ profile.cov .idea/ -/docs/ diff --git a/Makefile b/Makefile index ab416ae0..6b43cbfb 100644 --- a/Makefile +++ b/Makefile @@ -28,6 +28,11 @@ test: fmt: go fmt ./... +gen-doc: + go install github.com/princjef/gomarkdoc/cmd/gomarkdoc@latest + gomarkdoc --output api.md . + mv api.md docs + # ---------------- # Docker # ---------------- diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 00000000..260c1276 --- /dev/null +++ b/docs/api.md @@ -0,0 +1,981 @@ + + +# kclvm + +```go +import "kcl-lang.io/kcl-go" +``` + +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 +

+ + + +```go +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](<#constants>) +- [func FormatCode\(code interface\{\}\) \(\[\]byte, error\)](<#FormatCode>) +- [func FormatPath\(path string\) \(changedPaths \[\]string, err error\)](<#FormatPath>) +- [func GetSchemaTypeMapping\(file, code, schemaName string\) \(map\[string\]\*KclType, error\)](<#GetSchemaTypeMapping>) +- [func InitKclvmPath\(kclvmRoot string\)](<#InitKclvmPath>) +- [func InitKclvmRuntime\(n int\)](<#InitKclvmRuntime>) +- [func LintPath\(paths \[\]string\) \(results \[\]string, err error\)](<#LintPath>) +- [func ListDepFiles\(workDir string, opt \*ListDepFilesOption\) \(files \[\]string, err error\)](<#ListDepFiles>) +- [func ListDownStreamFiles\(workDir string, opt \*ListDepsOptions\) \(\[\]string, error\)](<#ListDownStreamFiles>) +- [func ListUpStreamFiles\(workDir string, opt \*ListDepsOptions\) \(deps \[\]string, err error\)](<#ListUpStreamFiles>) +- [func OverrideFile\(file string, specs, importPaths \[\]string\) \(bool, error\)](<#OverrideFile>) +- [func ValidateCode\(data, code string, opt \*ValidateOptions\) \(ok bool, err error\)](<#ValidateCode>) +- [type KCLResult](<#KCLResult>) +- [type KCLResultList](<#KCLResultList>) + - [func MustRun\(path string, opts ...Option\) \*KCLResultList](<#MustRun>) + - [func Run\(path string, opts ...Option\) \(\*KCLResultList, error\)](<#Run>) + - [func RunFiles\(paths \[\]string, opts ...Option\) \(\*KCLResultList, error\)](<#RunFiles>) +- [type KclType](<#KclType>) + - [func GetSchemaType\(file, code, schemaName string\) \(\[\]\*KclType, error\)](<#GetSchemaType>) +- [type ListDepFilesOption](<#ListDepFilesOption>) +- [type ListDepsOptions](<#ListDepsOptions>) +- [type Option](<#Option>) + - [func WithCode\(codes ...string\) Option](<#WithCode>) + - [func WithDisableNone\(disableNone bool\) Option](<#WithDisableNone>) + - [func WithExternalPkgs\(externalPkgs ...string\) Option](<#WithExternalPkgs>) + - [func WithIncludeSchemaTypePath\(includeSchemaTypePath bool\) Option](<#WithIncludeSchemaTypePath>) + - [func WithKFilenames\(filenames ...string\) Option](<#WithKFilenames>) + - [func WithLogger\(l io.Writer\) Option](<#WithLogger>) + - [func WithOptions\(key\_value\_list ...string\) Option](<#WithOptions>) + - [func WithOverrides\(override\_list ...string\) Option](<#WithOverrides>) + - [func WithPrintOverridesAST\(printOverridesAST bool\) Option](<#WithPrintOverridesAST>) + - [func WithSelectors\(selectors ...string\) Option](<#WithSelectors>) + - [func WithSettings\(filename string\) Option](<#WithSettings>) + - [func WithSortKeys\(sortKeys bool\) Option](<#WithSortKeys>) + - [func WithWorkDir\(workDir string\) Option](<#WithWorkDir>) +- [type TestCaseInfo](<#TestCaseInfo>) +- [type TestOptions](<#TestOptions>) +- [type TestResult](<#TestResult>) + - [func Test\(testOpts \*TestOptions, opts ...Option\) \(TestResult, error\)](<#Test>) +- [type ValidateOptions](<#ValidateOptions>) + + +## Constants + +KclvmAbiVersion is the current kclvm ABI version. + +```go +const KclvmAbiVersion = scripts.KclvmAbiVersion +``` + + +## func [FormatCode]() + +```go +func FormatCode(code interface{}) ([]byte, error) +``` + +FormatCode returns the formatted code. + +
Example +

+ + + +```go +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]() + +```go +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 +

+ + + +```go +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]() + +```go +func GetSchemaTypeMapping(file, code, schemaName string) (map[string]*KclType, error) +``` + +GetSchemaTypeMapping returns a \:\ 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]() + +```go +func InitKclvmPath(kclvmRoot string) +``` + +InitKclvmPath init kclvm path. + + +## func [InitKclvmRuntime]() + +```go +func InitKclvmRuntime(n int) +``` + +InitKclvmRuntime init kclvm process. + + +## func [LintPath]() + +```go +func LintPath(paths []string) (results []string, err error) +``` + +LintPath lint files from the given path + +
Example +

+ + + +```go +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]() + +```go +func ListDepFiles(workDir string, opt *ListDepFilesOption) (files []string, err error) +``` + +ListDepFiles return the depend files from the given path + + +## func [ListDownStreamFiles]() + +```go +func ListDownStreamFiles(workDir string, opt *ListDepsOptions) ([]string, error) +``` + +ListDownStreamFiles return a list of downstream depend files from the given changed path list. + + +## func [ListUpStreamFiles]() + +```go +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]() + +```go +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: := or :- +When the pkgpath is '__main__', it can be omitted. +``` + +importPaths. List of import statements that need to be added + + +## func [ValidateCode]() + +```go +func ValidateCode(data, code string, opt *ValidateOptions) (ok bool, err error) +``` + +ValidateCode validate data match code + + +## type [KCLResult]() + + + +```go +type KCLResult = kcl.KCLResult +``` + +
Example +

+ + + +```go +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 +``` + +

+
+ +
Example ('et_struct) +

+ + + +```go +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) + +} +``` + +#### Output + +``` +person: &{Name:kcl Age:101} +person: {Name:kcl Age:101} +``` + +

+
+ + +## type [KCLResultList]() + + + +```go +type KCLResultList = kcl.KCLResultList +``` + + +### func [MustRun]() + +```go +func MustRun(path string, opts ...Option) *KCLResultList +``` + +MustRun is like Run but panics if return any error. + +
Example +

+ + + +```go +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 (Raw Yaml) +

+ + + +```go +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 (Schema Type) +

+ + + +```go +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) +

+ + + +```go +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]() + +```go +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) +

+ + + +```go +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]() + +```go +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 +

+ + + +```go +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]() + + + +```go +type KclType = kcl.KclType +``` + + +### func [GetSchemaType]() + +```go +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]() + + + +```go +type ListDepFilesOption = list.Option +``` + + +## type [ListDepsOptions]() + + + +```go +type ListDepsOptions = list.DepOptions +``` + + +## type [Option]() + + + +```go +type Option = kcl.Option +``` + + +### func [WithCode]() + +```go +func WithCode(codes ...string) Option +``` + +WithCode returns a Option which hold a kcl source code list. + + +### func [WithDisableNone]() + +```go +func WithDisableNone(disableNone bool) Option +``` + +WithDisableNone returns a Option which hold a disable none switch. + + +### func [WithExternalPkgs]() + +```go +func WithExternalPkgs(externalPkgs ...string) Option +``` + +WithExternalPkgs returns a Option which hold a external package list. + + +### func [WithIncludeSchemaTypePath]() + +```go +func WithIncludeSchemaTypePath(includeSchemaTypePath bool) Option +``` + +WithIncludeSchemaTypePath returns a Option which hold a include schema type path switch. + + +### func [WithKFilenames]() + +```go +func WithKFilenames(filenames ...string) Option +``` + +WithKFilenames returns a Option which hold a filenames list. + + +### func [WithLogger]() + +```go +func WithLogger(l io.Writer) Option +``` + +WithLogger returns a Option which hold a logger. + + +### func [WithOptions]() + +```go +func WithOptions(key_value_list ...string) Option +``` + +WithOptions returns a Option which hold a key=value pair list for option function. + +
Example +

+ + + +```go +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]() + +```go +func WithOverrides(override_list ...string) Option +``` + +WithOverrides returns a Option which hold a override list. + + +### func [WithPrintOverridesAST]() + +```go +func WithPrintOverridesAST(printOverridesAST bool) Option +``` + +WithPrintOverridesAST returns a Option which hold a printOverridesAST switch. + + +### func [WithSelectors]() + +```go +func WithSelectors(selectors ...string) Option +``` + +WithSelectors returns a Option which hold a path selector list. + + +### func [WithSettings]() + +```go +func WithSettings(filename string) Option +``` + +WithSettings returns a Option which hold a settings file. + + +### func [WithSortKeys]() + +```go +func WithSortKeys(sortKeys bool) Option +``` + +WithSortKeys returns a Option which hold a sortKeys switch. + + +### func [WithWorkDir]() + +```go +func WithWorkDir(workDir string) Option +``` + +WithWorkDir returns a Option which hold a work dir. + + +## type [TestCaseInfo]() + + + +```go +type TestCaseInfo = testing.TestCaseInfo +``` + + +## type [TestOptions]() + + + +```go +type TestOptions = testing.TestOptions +``` + + +## type [TestResult]() + + + +```go +type TestResult = testing.TestResult +``` + + +### func [Test]() + +```go +func Test(testOpts *TestOptions, opts ...Option) (TestResult, error) +``` + +Test calls the test tool to run uni tests in packages. + + +## type [ValidateOptions]() + + + +```go +type ValidateOptions = validate.ValidateOptions +``` + +Generated by [gomarkdoc]()