feat: more api and examples (#352)

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

example_test.go

@@ -7,15 +7,10 @@ import (
 	"log"
 
 	kcl "kcl-lang.io/kcl-go"
+	"kcl-lang.io/kcl-go/pkg/native"
+	"kcl-lang.io/kcl-go/pkg/spec/gpyrpc"
 )
 
-func assert(v bool, a ...interface{}) {
-	if !v {
-		a = append([]interface{}{"assert failed"}, a...)
-		log.Panic(a...)
-	}
-}
-
 func ExampleMustRun() {
 	yaml := kcl.MustRun("testdata/main.k", kcl.WithCode(`name = "kcl"`)).First().YAMLString()
 	fmt.Println(yaml)
@@ -94,7 +89,7 @@ x1 = Person {age = 101}
 	// x1.age: 101
 }
 
-func ExampleKCLResult_Get_struct() {
+func ExampleKCLResult_get() {
 	const k_code = `
 schema Person:
     name: str = "kcl"
@@ -214,3 +209,104 @@ age = option("age")
 	// age: 1
 	// name: kcl
 }
+
+func ExampleParseProgram() {
+	result, err := kcl.ParseProgram(&kcl.ParseProgramArgs{
+		Paths: []string{"testdata/main.k"},
+	})
+	if err != nil {
+		log.Fatal(err)
+	}
+	fmt.Println(result)
+}
+
+func ExampleLoadPackage() {
+	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)
+}
+
+func ExampleListVariables() {
+	result, err := kcl.ListVariables(&kcl.ListVariablesArgs{
+		Files: []string{"testdata/main.k"},
+	})
+	if err != nil {
+		log.Fatal(err)
+	}
+	fmt.Println(result)
+}
+
+func ExampleListOptions() {
+	result, err := kcl.ListOptions(&kcl.ListOptionsArgs{
+		Paths: []string{"testdata/option/main.k"},
+	})
+	if err != nil {
+		log.Fatal(err)
+	}
+	fmt.Println(result)
+}
+
+func ExampleUpdateDependencies() {
+	// [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.UpdateDependencies_Args{
+		ManifestPath: "testdata/update_dependencies",
+	})
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	fmt.Println(result)
+}
+
+func ExampleUpdateDependencies_execProgram() {
+	// [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.UpdateDependencies_Args{
+		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.ExecProgram_Args{
+		KFilenameList: []string{"testdata/update_dependencies/main.k"},
+		ExternalPkgs:  result.ExternalPkgs,
+	})
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	fmt.Println(execResult.YamlResult)
+
+	// Output:
+	// a: Hello World!
+}

kclvm.go

@@ -34,10 +34,13 @@ import (
 	"io"
 
 	"kcl-lang.io/kcl-go/pkg/kcl"
+	"kcl-lang.io/kcl-go/pkg/loader"
+	"kcl-lang.io/kcl-go/pkg/parser"
 	"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"
+	"kcl-lang.io/kcl-go/pkg/tools/module"
 	"kcl-lang.io/kcl-go/pkg/tools/override"
 	"kcl-lang.io/kcl-go/pkg/tools/testing"
 	"kcl-lang.io/kcl-go/pkg/tools/validate"
@@ -54,7 +57,18 @@ type (
 	KCLResult          = kcl.KCLResult
 	KCLResultList      = kcl.KCLResultList
 
-	KclType = kcl.KclType
+	KclType                  = kcl.KclType
+	VersionResult            = kcl.VersionResult
+	UpdateDependenciesArgs   = module.UpdateDependenciesArgs
+	UpdateDependenciesResult = module.UpdateDependenciesResult
+	LoadPackageArgs          = loader.LoadPackageArgs
+	LoadPackageResult        = loader.LoadPackageResult
+	ListVariablesArgs        = loader.ListVariablesArgs
+	ListVariablesResult      = loader.ListVariablesResult
+	ListOptionsArgs          = loader.ListOptionsArgs
+	ListOptionsResult        = loader.ListOptionsResult
+	ParseProgramArgs         = parser.ParseProgramArgs
+	ParseProgramResult       = parser.ParseProgramResult
 )
 
 // InitKclvmPath init kclvm path.
@@ -82,12 +96,22 @@ func RunFiles(paths []string, opts ...Option) (*KCLResultList, error) {
 	return kcl.RunFiles(paths, opts...)
 }
 
+// NewOption returns a new Option.
+func NewOption() *Option {
+	return kcl.NewOption()
+}
+
 // WithCode returns a Option which hold a kcl source code list.
 func WithCode(codes ...string) Option { return kcl.WithCode(codes...) }
 
 // WithExternalPkgs returns a Option which hold a external package list.
 func WithExternalPkgs(externalPkgs ...string) Option { return kcl.WithExternalPkgs(externalPkgs...) }
 
+// WithExternalPkgAndPath returns a Option which hold a external package.
+func WithExternalPkgAndPath(name, path string) Option {
+	return kcl.WithExternalPkgNameAndPath(name, path)
+}
+
 // WithKFilenames returns a Option which hold a filenames list.
 func WithKFilenames(filenames ...string) Option { return kcl.WithKFilenames(filenames...) }
 
@@ -179,11 +203,8 @@ func LintPath(paths []string) (results []string, err 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
+// 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 OverrideFile(file string, specs, importPaths []string) (bool, error) {
 	return override.OverrideFile(file, specs, importPaths)
 }
@@ -237,3 +258,35 @@ func GetSchemaType(filename string, src any, schemaName string) ([]*KclType, err
 func GetSchemaTypeMapping(filename string, src any, schemaName string) (map[string]*KclType, error) {
 	return kcl.GetSchemaTypeMapping(filename, src, schemaName)
 }
+
+// Parse KCL program with entry files and return the AST JSON string.
+func ParseProgram(args *ParseProgramArgs) (*ParseProgramResult, error) {
+	return parser.ParseProgram(args)
+}
+
+// LoadPackage provides users with the ability to parse KCL program and semantic model
+// information including symbols, types, definitions, etc.
+func LoadPackage(args *LoadPackageArgs) (*LoadPackageResult, error) {
+	return loader.LoadPackage(args)
+}
+
+// ListVariables provides users with the ability to parse KCL program and get all variables by specs.
+func ListVariables(args *ListVariablesArgs) (*ListVariablesResult, error) {
+	return loader.ListVariables(args)
+}
+
+// ListOptions provides users with the ability to parse kcl program and get all option
+// calling information.
+func ListOptions(args *ListOptionsArgs) (*ListOptionsResult, error) {
+	return loader.ListOptions(args)
+}
+
+// Download and update dependencies defined in the kcl.mod file and return the external package name and location list.
+func UpdateDependencies(args *UpdateDependenciesArgs) (*UpdateDependenciesResult, error) {
+	return module.UpdateDependencies(args)
+}
+
+// GetVersion returns the KCL service version information.
+func GetVersion() (*VersionResult, error) {
+	return kcl.GetVersion()
+}

kclvm_test.go

@@ -270,17 +270,6 @@ alice = Person {
 	defer os.Remove(testdata_main_k)
 }
 
-func _BenchmarkRunFilesParallel(b *testing.B) {
-	b.RunParallel(func(pb *testing.PB) {
-		for pb.Next() {
-			_, err := kcl.RunFiles([]string{"./testdata/app0/kcl.yaml"})
-			if err != nil {
-				b.Fatal(err)
-			}
-		}
-	})
-}
-
 func TestWithKFilenames(t *testing.T) {
 	kcl.WithKFilenames("/testdata/main.k")
 }

pkg/kcl/api.go

@@ -17,7 +17,6 @@ import (
 	"github.com/mitchellh/mapstructure"
 	"gopkg.in/yaml.v3"
 
-	"kcl-lang.io/kcl-go/pkg/source"
 	"kcl-lang.io/kcl-go/pkg/spec/gpyrpc"
 )
 
@@ -377,61 +376,6 @@ func RunFiles(paths []string, opts ...Option) (*KCLResultList, error) {
 	return run(paths, opts...)
 }
 
-func GetSchemaType(filename string, src any, schemaName string) ([]*gpyrpc.KclType, error) {
-	mapping, err := GetSchemaTypeMapping(filename, src, schemaName)
-	if err != nil {
-		return nil, err
-	}
-	return getValues(mapping), nil
-}
-
-func GetFullSchemaType(pathList []string, schemaName string, opts ...Option) ([]*gpyrpc.KclType, error) {
-	mapping, err := GetFullSchemaTypeMapping(pathList, schemaName, opts...)
-	if err != nil {
-		return nil, err
-	}
-	return getValues(mapping), nil
-}
-
-func GetFullSchemaTypeMapping(pathList []string, schemaName string, opts ...Option) (map[string]*gpyrpc.KclType, error) {
-	opts = append(opts, *NewOption().Merge(WithKFilenames(pathList...)))
-	args, err := ParseArgs(pathList, opts...)
-	if err != nil {
-		return nil, err
-	}
-
-	svc := Service()
-	resp, err := svc.GetSchemaTypeMapping(&gpyrpc.GetSchemaTypeMapping_Args{
-		ExecArgs:   args.ExecProgram_Args,
-		SchemaName: schemaName,
-	})
-
-	if err != nil {
-		return nil, err
-	}
-
-	return resp.SchemaTypeMapping, nil
-}
-
-func GetSchemaTypeMapping(filename string, src any, schemaName string) (map[string]*gpyrpc.KclType, error) {
-	source, err := source.ReadSource(filename, src)
-	if err != nil {
-		return nil, err
-	}
-	svc := Service()
-	resp, err := svc.GetSchemaTypeMapping(&gpyrpc.GetSchemaTypeMapping_Args{
-		ExecArgs: &gpyrpc.ExecProgram_Args{
-			KFilenameList: []string{filename},
-			KCodeList:     []string{string(source)},
-		},
-		SchemaName: schemaName,
-	})
-	if err != nil {
-		return nil, err
-	}
-	return resp.SchemaTypeMapping, nil
-}
-
 func getValues(myMap map[string]*gpyrpc.KclType) []*gpyrpc.KclType {
 	var values []*gpyrpc.KclType
 	for _, value := range myMap {

pkg/kcl/opt.go

@@ -97,6 +97,18 @@ func WithExternalPkgs(key_value_list ...string) Option {
 	return *opt
 }
 
+// kcl -E aaa=/xx/xxx/aaa main.k
+func WithExternalPkgNameAndPath(name, path string) Option {
+	var args []*gpyrpc.ExternalPkg
+	args = append(args, &gpyrpc.ExternalPkg{
+		PkgName: name,
+		PkgPath: path,
+	})
+	var opt = NewOption()
+	opt.ExternalPkgs = args
+	return *opt
+}
+
 // kcl -D aa=11 -D bb=22 main.k
 func WithOptions(key_value_list ...string) Option {
 	var args []*gpyrpc.Argument