feat: add go plugin APIs and examples

Signed-off-by: peefy <[email protected]>

README.md

@@ -38,11 +38,11 @@ import (
 )
 
 func main() {
-	yaml := kcl.MustRun("kubernetes.k", kcl.WithCode(k_code)).GetRawYamlResult()
+	yaml := kcl.MustRun("kubernetes.k", kcl.WithCode(code)).GetRawYamlResult()
 	fmt.Println(yaml)
 }
 
-const k_code = `
+const code = `
 apiVersion = "apps/v1"
 kind = "Deployment"
 metadata = {
@@ -96,6 +96,33 @@ spec:
         - containerPort: 80
 ```
 
+## Run KCL Code with Go Plugin
+
+```go
+package main
+
+import (
+	"fmt"
+
+	"kcl-lang.io/kcl-go/pkg/kcl"
+	"kcl-lang.io/kcl-go/pkg/native"                // Import the native API
+	_ "kcl-lang.io/kcl-go/pkg/plugin/hello_plugin" // Import the hello plugin
+)
+
+func main() {
+	// Note we use `native.MustRun` here instead of `kcl.MustRun`, because it needs the cgo feature.
+	yaml := native.MustRun("main.k", kcl.WithCode(code)).GetRawYamlResult()
+	fmt.Println(yaml)
+}
+
+const code = `
+import kcl_plugin.hello
+
+name = "kcl"
+three = hello.add(1,2)  # hello.add is written by Go
+`
+```
+
 ## Documents
 
 See the [KCL website](https://kcl-lang.io)

examples/kubernetes/main.go

@@ -4,15 +4,14 @@ import (
 	"fmt"
 
 	kcl "kcl-lang.io/kcl-go"
-	_ "kcl-lang.io/kcl-go/pkg/kcl_plugin/hello_plugin"
 )
 
 func main() {
-	yaml := kcl.MustRun("kubernetes.k", kcl.WithCode(k_code)).GetRawYamlResult()
+	yaml := kcl.MustRun("kubernetes.k", kcl.WithCode(code)).GetRawYamlResult()
 	fmt.Println(yaml)
 }
 
-const k_code = `
+const code = `
 apiVersion = "apps/v1"
 kind = "Deployment"
 metadata = {

examples/plugin/main.go

@@ -0,0 +1,22 @@
+package main
+
+import (
+	"fmt"
+
+	"kcl-lang.io/kcl-go/pkg/kcl"
+	"kcl-lang.io/kcl-go/pkg/native"                // Import the native API
+	_ "kcl-lang.io/kcl-go/pkg/plugin/hello_plugin" // Import the hello plugin
+)
+
+func main() {
+	// Note we use `native.MustRun` here instead of `kcl.MustRun`, because it needs the cgo feature.
+	yaml := native.MustRun("main.k", kcl.WithCode(code)).GetRawYamlResult()
+	fmt.Println(yaml)
+}
+
+const code = `
+import kcl_plugin.hello
+
+name = "kcl"
+three = hello.add(1,2)
+`

go.mod

@@ -5,6 +5,7 @@ go 1.21
 require (
 	github.com/chai2010/jsonv v1.1.3
 	github.com/chai2010/protorpc v1.1.4
+	github.com/coreos/pkg v0.0.0-20240122114842-bbd7aa9bf6fb
 	github.com/getkin/kin-openapi v0.123.0
 	github.com/goccy/go-yaml v1.11.3
 	github.com/gofrs/flock v0.8.1

go.sum

@@ -99,6 +99,8 @@ github.com/containerd/containerd v1.7.0 h1:G/ZQr3gMZs6ZT0qPUZ15znx5QSdQdASW11nXT
 github.com/containerd/containerd v1.7.0/go.mod h1:QfR7Efgb/6X2BDpTPJRvPTYDE9rsF0FsXX9J8sIs/sc=
 github.com/containerd/continuity v0.3.0 h1:nisirsYROK15TAMVukJOUyGJjz4BNQJBVsNvAXZJ/eg=
 github.com/containerd/continuity v0.3.0/go.mod h1:wJEAIwKOm/pBZuBd0JmeTvnLquTB1Ag8espWhkykbPM=
+github.com/coreos/pkg v0.0.0-20240122114842-bbd7aa9bf6fb h1:GIzvVQ9UkUlOhSDlqmrQAAAUd6R3E+caIisNEyWXvNE=
+github.com/coreos/pkg v0.0.0-20240122114842-bbd7aa9bf6fb/go.mod h1:E3G3o1h8I7cfcXa63jLwjI0eiQQMgzzUDFVpN/nH/eA=
 github.com/creack/pty v1.1.18 h1:n56/Zwd5o6whRC5PMGretI4IdRLlmBXYNjScPaBgsbY=
 github.com/creack/pty v1.1.18/go.mod h1:MOBLtS5ELjhRRrroQr9kyvTxUAFNvYEK993ew/Vr4O4=
 github.com/cyphar/filepath-securejoin v0.2.4 h1:Ugdm7cg7i6ZK6x3xDF1oEu1nfkyfH53EtKeQYTC3kyg=

kclvm.go

@@ -34,7 +34,7 @@ import (
 	"io"
 
 	"kcl-lang.io/kcl-go/pkg/kcl"
-	"kcl-lang.io/kcl-go/pkg/kclvm_runtime"
+	"kcl-lang.io/kcl-go/pkg/runtime"
 	"kcl-lang.io/kcl-go/pkg/tools/format"
 	"kcl-lang.io/kcl-go/pkg/tools/lint"
 	"kcl-lang.io/kcl-go/pkg/tools/list"
@@ -59,12 +59,12 @@ type (
 
 // InitKclvmPath init kclvm path.
 func InitKclvmPath(kclvmRoot string) {
-	kclvm_runtime.InitKclvmRoot(kclvmRoot)
+	runtime.InitKclvmRoot(kclvmRoot)
 }
 
 // InitKclvmRuntime init kclvm process.
 func InitKclvmRuntime(n int) {
-	kclvm_runtime.InitRuntime(n)
+	runtime.InitRuntime(n)
 }
 
 // MustRun is like Run but panics if return any error.

pkg/kcl/api.go

@@ -7,6 +7,7 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"io"
 	"reflect"
 	"strings"
 
@@ -324,19 +325,7 @@ func GetSchemaTypeMapping(file, code, schemaName string) (map[string]*gpyrpc.Kcl
 	return resp.SchemaTypeMapping, nil
 }
 
-func run(pathList []string, opts ...Option) (*KCLResultList, error) {
-	args, err := ParseArgs(pathList, opts...)
-	if err != nil {
-		return nil, err
-	}
-
-	client := service.NewKclvmServiceClient()
-	resp, err := client.ExecProgram(args.ExecProgram_Args)
-	if err != nil {
-		return nil, err
-	}
-	// Output log message
-	logger := args.GetLogger()
+func ExecResultToKCLResult(resp *gpyrpc.ExecProgram_Result, logger io.Writer) (*KCLResultList, error) {
 	if logger != nil && resp.LogMessage != "" {
 		_, err := logger.Write([]byte(resp.LogMessage))
 		if err != nil {
@@ -374,3 +363,17 @@ func run(pathList []string, opts ...Option) (*KCLResultList, error) {
 	result.raw_yaml_result = resp.YamlResult
 	return &result, nil
 }
+
+func run(pathList []string, opts ...Option) (*KCLResultList, error) {
+	args, err := ParseArgs(pathList, opts...)
+	if err != nil {
+		return nil, err
+	}
+
+	client := service.NewKclvmServiceClient()
+	resp, err := client.ExecProgram(args.ExecProgram_Args)
+	if err != nil {
+		return nil, err
+	}
+	return ExecResultToKCLResult(resp, args.GetLogger())
+}