Merge pull request #116 from Peefy/more-cpp-api-and-examples

feat: add more cpp api and examples

Author: Peefy

cpp/CMakeLists.txt

@@ -40,27 +40,18 @@ set_target_properties(kcl-lib-cpp
         PROPERTIES ADDITIONAL_CLEAN_FILES ${CARGO_TARGET_DIR}
 )
 
-add_executable(exec_api examples/exec_api.cpp)
-target_include_directories(exec_api PUBLIC ${CPP_INCLUDE_DIR})
-target_link_libraries(exec_api PUBLIC kcl-lib-cpp)
-# Platform-specific test configuration
-if(WIN32)
-    target_link_libraries(exec_api PRIVATE userenv ws2_32 bcrypt)
-endif()
-if(APPLE)
-    target_link_libraries(exec_api PRIVATE "-framework CoreFoundation -framework Security")
-endif()
-
-add_executable(validate_api examples/validate_api.cpp)
-target_include_directories(validate_api PUBLIC ${CPP_INCLUDE_DIR})
-target_link_libraries(validate_api PUBLIC kcl-lib-cpp)
-# Platform-specific test configuration
-if(WIN32)
-    target_link_libraries(validate_api PRIVATE userenv ws2_32 bcrypt)
-endif()
-if(APPLE)
-    target_link_libraries(validate_api PRIVATE "-framework CoreFoundation -framework Security")
-endif()
+set(EXECUTABLES exec_api exec_with_deps_api override_api update_deps_api validate_api)
+foreach(EXE IN LISTS EXECUTABLES)
+    add_executable(${EXE} examples/${EXE}.cpp)
+    target_include_directories(${EXE} PUBLIC ${CPP_INCLUDE_DIR})
+    target_link_libraries(${EXE} PUBLIC kcl-lib-cpp)
+    if(WIN32)
+        target_link_libraries(${EXE} PRIVATE userenv ws2_32 bcrypt)
+    endif()
+    if(APPLE)
+        target_link_libraries(${EXE} PRIVATE "-framework CoreFoundation -framework Security")
+    endif()
+endforeach()
 
 # Platform-specific test configuration
 if(WIN32)

cpp/examples/exec_with_deps_api.cpp

@@ -0,0 +1,17 @@
+#include "kcl_lib.hpp"
+#include <iostream>
+
+int main()
+{
+    auto args = kcl_lib::UpdateDependenciesArgs {
+        .manifest_path = rust::String("../test_data/update_dependencies"),
+    };
+    auto result = kcl_lib::update_dependencies(args);
+    auto exec_args = kcl_lib::ExecProgramArgs {
+        .k_filename_list = rust::Vec({ rust::String("../test_data/update_dependencies/main.k") }),
+        .external_pkgs = result.external_pkgs,
+    };
+    auto exec_result = kcl_lib::exec_program(exec_args);
+    std::cout << exec_result.yaml_result.c_str() << std::endl;
+    return 0;
+}

cpp/examples/override_api.cpp

@@ -0,0 +1,14 @@
+#include "kcl_lib.hpp"
+#include <iostream>
+
+int main()
+{
+    auto args = kcl_lib::OverrideFileArgs {
+        .file = rust::String("../test_data/override_file/main.k"),
+        .specs = rust::Vec({ rust::String("b.a=2") }),
+    };
+    auto result = kcl_lib::override_file(args);
+    std::cout << result.result << std::endl;
+    std::cout << result.parse_errors.size() << std::endl;
+    return 0;
+}

cpp/examples/update_deps_api.cpp

@@ -0,0 +1,13 @@
+#include "kcl_lib.hpp"
+#include <iostream>
+
+int main()
+{
+    auto args = kcl_lib::UpdateDependenciesArgs {
+        .manifest_path = rust::String("../test_data/update_dependencies"),
+    };
+    auto result = kcl_lib::update_dependencies(args);
+    std::cout << result.external_pkgs[0].pkg_name.c_str() << std::endl;
+    std::cout << result.external_pkgs[1].pkg_name.c_str() << std::endl;
+    return 0;
+}

cpp/examples/validate_api.cpp

@@ -1,7 +1,8 @@
 #include "kcl_lib.hpp"
 #include <iostream>
 
-int validate(const char* code_str, const char* data_str) {
+int validate(const char* code_str, const char* data_str)
+{
     auto args = kcl_lib::ValidateCodeArgs();
     args.code = rust::String(code_str);
     args.data = rust::String(data_str);

cpp/src/lib.rs

@@ -45,17 +45,50 @@ mod ffi {
     }
 
     /// kcl main.k -E name=path
+    #[derive(Clone)]
     pub struct ExternalPkg {
         pub pkg_name: String,
         pub pkg_path: String,
     }
 
     /// kcl main.k -D name=value
+    #[derive(Clone)]
     pub struct Argument {
+        /// Name of the argument.
         pub name: String,
+        /// Value of the argument.
         pub value: String,
     }
 
+    /// Message representing an error.
+    pub struct Error {
+        /// Level of the error (e.g., "Error", "Warning").
+        pub level: String,
+        /// Error code. (e.g., "E1001")
+        pub code: String,
+        /// List of error messages.
+        pub messages: Vec<Message>,
+    }
+
+    /// Message representing a detailed error message with a position.
+    pub struct Message {
+        /// The error message text.
+        pub msg: String,
+        /// The position in the source code where the error occurred.
+        pub pos: Position,
+    }
+
+    /// Message representing a position in the source code.
+    #[derive(Default)]
+    pub struct Position {
+        /// Line number.
+        pub line: i64,
+        /// Column number.
+        pub column: i64,
+        /// Filename the position refers to.
+        pub filename: String,
+    }
+
     /// Message for execute program response.
     pub struct ExecProgramResult {
         /// Result in JSON format.
@@ -94,23 +127,131 @@ mod ffi {
         err_message: String,
     }
 
+    /// Message for override file request arguments.
+    pub struct OverrideFileArgs {
+        /// Path of the file to override.
+        file: String,
+        /// List of override specifications.
+        specs: Vec<String>,
+        /// List of import paths.
+        import_paths: Vec<String>,
+    }
+
+    /// Message for override file response.
+    pub struct OverrideFileResult {
+        /// Result of the override operation.
+        pub result: bool,
+        // List of parse errors encountered.
+        pub parse_errors: Vec<Error>,
+    }
+
+    /// Message for update dependencies request arguments.
+    pub struct UpdateDependenciesArgs {
+        /// Path to the manifest file.
+        pub manifest_path: String,
+        /// Flag to vendor dependencies locally.
+        pub vendor: bool,
+    }
+
+    /// Message for update dependencies response.
+    pub struct UpdateDependenciesResult {
+        /// List of external packages updated.
+        pub external_pkgs: Vec<ExternalPkg>,
+    }
+
     extern "Rust" {
+        /// Execute KCL file with arguments and return the JSON/YAML result.
         fn exec_program(args: &ExecProgramArgs) -> Result<ExecProgramResult>;
+        /// Validate code using schema and JSON/YAML data strings.
         fn validate_code(args: &ValidateCodeArgs) -> Result<ValidateCodeResult>;
+        /// Override KCL file with arguments.
+        /// See [https://www.kcl-lang.io/docs/user_docs/guides/automation](https://www.kcl-lang.io/docs/user_docs/guides/automation)
+        /// for more override spec guide.
+        fn override_file(args: &OverrideFileArgs) -> Result<OverrideFileResult>;
+        /// Download and update dependencies defined in the `kcl.mod` file and return the
+        /// external package name and location list.
+        fn update_dependencies(args: &UpdateDependenciesArgs) -> Result<UpdateDependenciesResult>;
     }
 }
 
 use ffi::*;
 
+impl crate::ffi::Error {
+    pub fn new(e: &kclvm_api::Error) -> Self {
+        Self {
+            level: e.level.clone(),
+            code: e.code.clone(),
+            messages: e
+                .messages
+                .iter()
+                .map(|m| Message {
+                    msg: m.msg.clone(),
+                    pos: m
+                        .pos
+                        .as_ref()
+                        .map(|p| Position {
+                            line: p.line,
+                            column: p.column,
+                            filename: p.filename.clone(),
+                        })
+                        .unwrap_or_default(),
+                })
+                .collect(),
+        }
+    }
+}
+
+impl UpdateDependenciesResult {
+    pub fn new(r: kclvm_api::UpdateDependenciesResult) -> Self {
+        Self {
+            external_pkgs: r
+                .external_pkgs
+                .iter()
+                .map(|p| ExternalPkg {
+                    pkg_name: p.pkg_name.clone(),
+                    pkg_path: p.pkg_path.clone(),
+                })
+                .collect(),
+        }
+    }
+}
+
 /// Execute KCL file with arguments and return the JSON/YAML result.
 fn exec_program(args: &ExecProgramArgs) -> Result<ExecProgramResult> {
     let api = kclvm_api::API::default();
     let result = api.exec_program(&kclvm_api::ExecProgramArgs {
         work_dir: args.work_dir.clone(),
         k_filename_list: args.k_filename_list.clone(),
         k_code_list: args.k_code_list.clone(),
-        // TODO: other arguments.
-        ..Default::default()
+        args: args
+            .args
+            .iter()
+            .map(|a| kclvm_api::Argument {
+                name: a.name.clone(),
+                value: a.value.clone(),
+            })
+            .collect::<Vec<kclvm_api::Argument>>(),
+        external_pkgs: args
+            .external_pkgs
+            .iter()
+            .map(|e| kclvm_api::ExternalPkg {
+                pkg_name: e.pkg_name.clone(),
+                pkg_path: e.pkg_path.clone(),
+            })
+            .collect::<Vec<kclvm_api::ExternalPkg>>(),
+        overrides: args.overrides.clone(),
+        strict_range_check: args.strict_range_check,
+        disable_none: args.disable_none,
+        verbose: args.verbose,
+        debug: args.debug,
+        sort_keys: args.sort_keys,
+        show_hidden: args.show_hidden,
+        compile_only: args.compile_only,
+        path_selector: args.path_selector.clone(),
+        fast_eval: args.fast_eval,
+        disable_yaml_result: args.disable_yaml_result,
+        include_schema_type_path: args.include_schema_type_path,
+        print_override_ast: args.print_override_ast,
     })?;
     Ok(ExecProgramResult {
         yaml_result: result.yaml_result,
@@ -137,3 +278,34 @@ fn validate_code(args: &ValidateCodeArgs) -> Result<ValidateCodeResult> {
         err_message: result.err_message,
     })
 }
+
+/// Override KCL file with arguments.
+/// See [https://www.kcl-lang.io/docs/user_docs/guides/automation](https://www.kcl-lang.io/docs/user_docs/guides/automation)
+/// for more override spec guide.
+fn override_file(args: &OverrideFileArgs) -> Result<OverrideFileResult> {
+    let api = kclvm_api::API::default();
+    let result = api.override_file(&kclvm_api::OverrideFileArgs {
+        file: args.file.clone(),
+        specs: args.specs.clone(),
+        import_paths: args.import_paths.clone(),
+    })?;
+    Ok(OverrideFileResult {
+        result: result.result,
+        parse_errors: result
+            .parse_errors
+            .iter()
+            .map(crate::ffi::Error::new)
+            .collect(),
+    })
+}
+
+/// Download and update dependencies defined in the `kcl.mod` file and return the
+/// external package name and location list.
+fn update_dependencies(args: &UpdateDependenciesArgs) -> Result<UpdateDependenciesResult> {
+    let api = kclvm_api::API::default();
+    let result = api.update_dependencies(&kclvm_api::UpdateDependenciesArgs {
+        manifest_path: args.manifest_path.clone(),
+        vendor: args.vendor,
+    })?;
+    Ok(UpdateDependenciesResult::new(result))
+}

cpp/test_data/override_file/main.k

@@ -0,0 +1,5 @@
+a = 1
+b = {
+    "a": 2
+    "b": 2
+}

cpp/test_data/update_dependencies/kcl.mod

@@ -0,0 +1,8 @@
+[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" }

cpp/test_data/update_dependencies/main.k

@@ -0,0 +1,4 @@
+import helloworld
+import flask
+
+a = helloworld.The_first_kcl_program