Skip to content

Commit cf42494

Browse files
authored
Merge pull request #418 from Peefy/update-c-and-cpp-api-docs
docs: add C and Cpp API initial reference docs
2 parents e970040 + cfd8f58 commit cf42494

File tree

8 files changed

+1148
-0
lines changed

8 files changed

+1148
-0
lines changed

docs/reference/xlang-api/c-api.md

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
---
2+
sidebar_position: 8
3+
---
4+
5+
# C API
6+
7+
The [C API](https://github.com/kcl-lang/lib/tree/main/c) is in the development stage and contributions are welcome.
8+
9+
## Prerequisites
10+
11+
+ Make
12+
+ C Compiler
13+
+ Cargo
14+
15+
## API Reference
16+
17+
### exec_program
18+
19+
Execute KCL file with arguments and return the JSON/YAML result.
20+
21+
<details><summary>Example</summary>
22+
<p>
23+
24+
```c
25+
#include <kcl_lib.h>
26+
27+
int exec_file(const char* file_str) {
28+
uint8_t buffer[BUFFER_SIZE];
29+
uint8_t result_buffer[BUFFER_SIZE];
30+
size_t message_length;
31+
bool status;
32+
struct Buffer file = {
33+
.buffer = file_str,
34+
.len = strlen(file_str),
35+
};
36+
struct Buffer* files[] = { &file };
37+
struct RepeatedString strs = { .repeated = &files[0], .index = 0, .max_size = 1 };
38+
ExecProgram_Args args = ExecProgram_Args_init_zero;
39+
args.k_filename_list.funcs.encode = encode_str_list;
40+
args.k_filename_list.arg = &strs;
41+
42+
pb_ostream_t stream = pb_ostream_from_buffer(buffer, sizeof(buffer));
43+
status = pb_encode(&stream, ExecProgram_Args_fields, &args);
44+
message_length = stream.bytes_written;
45+
46+
if (!status) {
47+
printf("Encoding failed: %s\n", PB_GET_ERROR(&stream));
48+
return 1;
49+
}
50+
51+
const char* api_str = "KclvmService.ExecProgram";
52+
size_t result_length = call_native((const uint8_t*)api_str, strlen(api_str), buffer, message_length, result_buffer);
53+
if (check_error_prefix(result_buffer)) {
54+
printf("%s", result_buffer);
55+
return 1;
56+
}
57+
pb_istream_t istream = pb_istream_from_buffer(result_buffer, result_length);
58+
59+
ExecProgram_Result result = ExecProgram_Result_init_default;
60+
61+
uint8_t yaml_value_buffer[BUFFER_SIZE] = { 0 };
62+
result.yaml_result.arg = yaml_value_buffer;
63+
result.yaml_result.funcs.decode = decode_string;
64+
65+
uint8_t json_value_buffer[BUFFER_SIZE] = { 0 };
66+
result.json_result.arg = json_value_buffer;
67+
result.json_result.funcs.decode = decode_string;
68+
69+
uint8_t err_value_buffer[BUFFER_SIZE] = { 0 };
70+
result.err_message.arg = err_value_buffer;
71+
result.err_message.funcs.decode = decode_string;
72+
73+
uint8_t log_value_buffer[BUFFER_SIZE] = { 0 };
74+
result.log_message.arg = log_value_buffer;
75+
result.log_message.funcs.decode = decode_string;
76+
77+
status = pb_decode(&istream, ExecProgram_Result_fields, &result);
78+
79+
if (!status) {
80+
printf("Decoding failed: %s\n", PB_GET_ERROR(&istream));
81+
return 1;
82+
}
83+
84+
if (result.yaml_result.arg) {
85+
printf("%s\n", (char*)result.yaml_result.arg);
86+
}
87+
88+
return 0;
89+
}
90+
91+
int main()
92+
{
93+
exec_file("./test_data/schema.k");
94+
return 0;
95+
}
96+
```
97+
98+
</p>
99+
</details>
100+
101+
### validate_code
102+
103+
Validate code using schema and JSON/YAML data strings.
104+
105+
<details><summary>Example</summary>
106+
<p>
107+
108+
```rust
109+
#include <kcl_lib.h>
110+
111+
int validate(const char* code_str, const char* data_str)
112+
{
113+
uint8_t buffer[BUFFER_SIZE];
114+
uint8_t result_buffer[BUFFER_SIZE];
115+
size_t message_length;
116+
bool status;
117+
118+
ValidateCode_Args validate_args = ValidateCode_Args_init_zero;
119+
validate_args.code.funcs.encode = encode_string;
120+
validate_args.code.arg = (void*)code_str;
121+
validate_args.data.funcs.encode = encode_string;
122+
validate_args.data.arg = (void*)data_str;
123+
124+
pb_ostream_t stream = pb_ostream_from_buffer(buffer, sizeof(buffer));
125+
status = pb_encode(&stream, ValidateCode_Args_fields, &validate_args);
126+
message_length = stream.bytes_written;
127+
128+
if (!status) {
129+
printf("Encoding failed: %s\n", PB_GET_ERROR(&stream));
130+
return 1;
131+
}
132+
133+
const char* api_str = "KclvmService.ValidateCode";
134+
size_t result_length = call_native((const uint8_t*)api_str, strlen(api_str), buffer, message_length, result_buffer);
135+
pb_istream_t istream = pb_istream_from_buffer(result_buffer, result_length);
136+
ValidateCode_Result result = ValidateCode_Result_init_default;
137+
138+
result.err_message.funcs.decode = decode_string;
139+
uint8_t value_buffer[BUFFER_SIZE] = { 0 };
140+
result.err_message.arg = value_buffer;
141+
142+
status = pb_decode(&istream, ValidateCode_Result_fields, &result);
143+
144+
if (!status) {
145+
printf("Decoding failed: %s\n", PB_GET_ERROR(&istream));
146+
return 1;
147+
}
148+
149+
printf("Validate Status: %d\n", result.success);
150+
if (result.err_message.arg) {
151+
printf("Validate Error Message: %s\n", (char*)result.err_message.arg);
152+
}
153+
return 0;
154+
}
155+
156+
int main()
157+
{
158+
const char* code_str = "schema Person:\n"
159+
" name: str\n"
160+
" age: int\n"
161+
" check:\n"
162+
" 0 < age < 120\n";
163+
const char* data_str = "{\"name\": \"Alice\", \"age\": 10}";
164+
const char* error_data_str = "{\"name\": \"Alice\", \"age\": 1110}";
165+
validate(code_str, data_str);
166+
validate(code_str, error_data_str);
167+
return 0;
168+
}
169+
```
170+
171+
</p>
172+
</details>

docs/reference/xlang-api/cpp-api.md

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
---
2+
sidebar_position: 9
3+
---
4+
5+
# C++ API
6+
7+
The [C++ API](https://github.com/kcl-lang/lib/tree/main/cpp) is in the development stage and contributions are welcome.
8+
9+
## Prerequisites
10+
11+
+ CMake >= 3.10
12+
+ C++ Compiler with C++17 Support
13+
+ Cargo
14+
15+
## Installation
16+
17+
### CMake
18+
19+
You can use FetchContent to add KCL C++ Lib to your project.
20+
21+
```shell
22+
FetchContent_Declare(
23+
kcl-lib
24+
GIT_REPOSITORY https://github.com/kcl-lang/lib.git
25+
GIT_TAG v0.9.1
26+
SOURCE_SUBDIR cpp
27+
)
28+
FetchContent_MakeAvailable(kcl-lib)
29+
```
30+
31+
Or you can download the source code and add it to your project.
32+
33+
```shell
34+
mkdir third_party
35+
cd third_party
36+
git clone https://github.com/kcl-lang/lib.git
37+
```
38+
39+
Update your CMake files.
40+
41+
```shell
42+
add_subdirectory(third_party/lib/cpp)
43+
```
44+
45+
```shell
46+
target_link_libraries(your_target kcl-lib-cpp)
47+
```
48+
49+
## API Reference
50+
51+
### exec_program
52+
53+
Execute KCL file with arguments and return the JSON/YAML result.
54+
55+
<details><summary>Example</summary>
56+
<p>
57+
58+
```cpp
59+
#include "kcl_lib.hpp"
60+
#include <iostream>
61+
62+
int main()
63+
{
64+
auto args = kcl_lib::ExecProgramArgs();
65+
auto files = rust::Vec<rust::String>();
66+
files.push_back(rust::String("../test_data/schema.k"));
67+
args.k_filename_list = files;
68+
auto result = kcl_lib::exec_program(args);
69+
std::cout << result.yaml_result.c_str() << std::endl;
70+
}
71+
```
72+
73+
</p>
74+
</details>
75+
76+
### validate_code
77+
78+
Validate code using schema and JSON/YAML data strings.
79+
80+
<details><summary>Example</summary>
81+
<p>
82+
83+
```rust
84+
#include "kcl_lib.hpp"
85+
#include <iostream>
86+
87+
int validate(const char* code_str, const char* data_str) {
88+
auto args = kcl_lib::ValidateCodeArgs();
89+
args.code = rust::String(code_str);
90+
args.data = rust::String(data_str);
91+
auto result = kcl_lib::validate_code(args);
92+
std::cout << result.success << std::endl;
93+
std::cout << result.err_message.c_str() << std::endl;
94+
return 0;
95+
}
96+
97+
int main()
98+
{
99+
const char* code_str = "schema Person:\n"
100+
" name: str\n"
101+
" age: int\n"
102+
" check:\n"
103+
" 0 < age < 120\n";
104+
const char* data_str = "{\"name\": \"Alice\", \"age\": 10}";
105+
const char* error_data_str = "{\"name\": \"Alice\", \"age\": 1110}";
106+
// Right case
107+
validate(code_str, data_str);
108+
// Error case
109+
validate(code_str, error_data_str);
110+
return 0;
111+
}
112+
```
113+
114+
</p>
115+
</details>

0 commit comments

Comments
 (0)