Rust API
Installation
cargo add --git https://github.com/kcl-lang/lib
Quick Start
use kcl_lang::*;
use anyhow::Result;
fn main() -> Result<()> {
let api = API::default();
let args = &ExecProgramArgs {
k_filename_list: vec!["main.k".to_string()],
k_code_list: vec!["a = 1".to_string()],
..Default::default()
};
let exec_result = api.exec_program(args)?;
println!("{}", exec_result.yaml_result);
Ok(())
}
More Rust APIs can be found here. If you want to use the sub crate of KCL Rust core, you can run the following command.
# Take the kclvm-runtime as an example.
cargo add --git https://github.com/kcl-lang/kcl kclvm-runtime
API Reference
exec_program
Execute KCL file with args.
Example
use kcl_lang::*;
use std::path::Path;
// File case
let serv = API::default();
let args = &ExecProgramArgs {
work_dir: Path::new(".").join("src").join("testdata").canonicalize().unwrap().display().to_string(),
k_filename_list: vec!["test.k".to_string()],
..Default::default()
};
let exec_result = serv.exec_program(args).unwrap();
assert_eq!(exec_result.yaml_result, "alice:\n age: 18");
// Code case
let args = &ExecProgramArgs {
k_filename_list: vec!["file.k".to_string()],
k_code_list: vec!["alice = {age = 18}".to_string()],
..Default::default()
};
let exec_result = serv.exec_program(args).unwrap();
assert_eq!(exec_result.yaml_result, "alice:\n age: 18");
// Error case
let args = &ExecProgramArgs {
k_filename_list: vec!["invalid_file.k".to_string()],
..Default::default()
};
let error = serv.exec_program(args).unwrap_err();
assert!(error.to_string().contains("Cannot find the kcl file"), "{error}");
let args = &ExecProgramArgs {
k_filename_list: vec![],
..Default::default()
};
let error = serv.exec_program(args).unwrap_err();
assert!(error.to_string().contains("No input KCL files or paths"), "{error}");
format_code
Service for formatting a code source and returns the formatted source and whether the source is changed.
Example
use kcl_lang::*;
let serv = API::default();
let source = r#"schema Person:
name: str
age: int
person = Person {
name = "Alice"
age = 18
}
"#.to_string();
let result = serv.format_code(&FormatCodeArgs {
source: source.clone(),
..Default::default()
}).unwrap();
assert_eq!(result.formatted, source.as_bytes().to_vec());
format_path
Service for formatting kcl file or directory path contains kcl files and returns the changed file paths.
Example
use kcl_lang::*;
let serv = API::default();
let result = serv.format_path(&FormatPathArgs {
path: "./src/testdata/test.k".to_string(),
..Default::default()
}).unwrap();
assert!(result.changed_paths.is_empty());
lint_path
Service for KCL Lint API, check a set of files, skips execute, returns error message including errors and warnings.
Example
use kcl_lang::*;
let serv = API::default();
let result = serv.lint_path(&LintPathArgs {
paths: vec!["./src/testdata/test-lint.k".to_string()],
..Default::default()
}).unwrap();
assert_eq!(result.results, vec!["Module 'math' imported but unused".to_string()]);
validate_code
Service for validating the data string using the schema code string, when the parameter schema is omitted, use the first schema appeared in the kcl code.
Example
use kcl_lang::*;
let serv = API::default();
let code = r#"
schema Person:
name: str
age: int
check:
0 < age < 120
"#.to_string();
let data = r#"
{
"name": "Alice",
"age": 10
}
"#.to_string();
let result = serv.validate_code(&ValidateCodeArgs {
code,
data,
..Default::default()
}).unwrap();
assert_eq!(result.success, true);
load_settings_files
Service for building setting file config from args.
Example
use kcl_lang::*;
let serv = API::default();
let result = serv.load_settings_files(&LoadSettingsFilesArgs {
files: vec!["./src/testdata/settings/kcl.yaml".to_string()],
work_dir: "./src/testdata/settings".to_string(),
..Default::default()
}).unwrap();
assert_eq!(result.kcl_options.len(), 1);
rename
Service for renaming all the occurrences of the target symbol in the files. This API will rewrite files if they contain symbols to be renamed. return the file paths got changed.
Example
use kcl_lang::*;
let result = serv.rename(&RenameArgs {
package_root: "./src/testdata/rename_doc".to_string(),
symbol_path: "a".to_string(),
file_paths: vec!["./src/testdata/rename_doc/main.k".to_string()],
new_name: "a2".to_string(),
}).unwrap();
assert_eq!(result.changed_files.len(), 1);
rename_code
Service for renaming all the occurrences of the target symbol and rename them. This API won’t rewrite files but return the modified code if any code has been changed. return the changed code.
Example
use kcl_lang::*;
let serv = API::default();
let result = serv.rename_code(&RenameCodeArgs {
package_root: "/mock/path".to_string(),
symbol_path: "a".to_string(),
source_codes: vec![("/mock/path/main.k".to_string(), "a = 1\nb = a".to_string())].into_iter().collect(),
new_name: "a2".to_string(),
}).unwrap();
assert_eq!(result.changed_codes.len(), 1);
assert_eq!(result.changed_codes.get("/mock/path/main.k").unwrap(), "a2 = 1\nb = a2");
test
Service for the testing tool.
Example
use kcl_lang::*;
let serv = API::default();
let result = serv.test(&TestArgs {
pkg_list: vec!["./src/testdata/testing/module/...".to_string()],
..TestArgs::default()
}).unwrap();
assert_eq!(result.info.len(), 2);
// Passed case
assert!(result.info[0].error.is_empty());
// Failed case
assert!(result.info[1].error.is_empty());
update_dependencies
update_dependencies provides users with the ability to update kcl module dependencies.
Example
use kcl_lang::*;
use std::path::Path;
use std::fs::remove_dir_all;
let serv = API::default();
let result = serv.update_dependencies(&UpdateDependenciesArgs {
manifest_path: "./src/testdata/update_dependencies".to_string(),
..Default::default()
}).unwrap();
assert_eq!(result.external_pkgs.len(), 1);
let result = serv.update_dependencies(&UpdateDependenciesArgs {
manifest_path: "./src/testdata/update_dependencies".to_string(),
vendor: true,
}).unwrap();
assert_eq!(result.external_pkgs.len(), 1);
let vendor_path = Path::new("./src/testdata/update_dependencies/vendor");
remove_dir_all(vendor_path);