ByoungSooPark/modeling-app
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add tags to Rust std lib functions (#6701)

Browse Source 
Signed-off-by: Nick Cameron <nrc@ncameron.org>
This commit is contained in:
Nick Cameron
2025-05-06 14:14:11 +12:00
committed by GitHub
parent 0464de33b1
commit 9c52f5b19a
127 changed files with 892 additions and 447 deletions
Download Patch File Download Diff File Expand all files Collapse all files

62
rust/kcl-derive-docs/src/lib.rs
View File

@ -232,30 +232,16 @@ fn do_stdlib_inner(
quote! { "" }
};
let cb = doc_info.code_blocks.clone();
let code_blocks = if !cb.is_empty() {
quote! {
let code_blocks = vec![#(#cb),*];
code_blocks.iter().map(|cb| {
let program = crate::Program::parse_no_errs(cb).unwrap();
let mut options: crate::parsing::ast::types::FormatOptions = Default::default();
options.insert_final_newline = false;
program.ast.recast(&options, 0)
}).collect::<Vec<String>>()
}
} else {
if doc_info.code_blocks.is_empty() {
errors.push(Error::new_spanned(
&ast.sig,
"stdlib functions must have at least one code block",
));
quote! { vec![] }
};
}
// Make sure the function name is in all the code blocks.
for code_block in doc_info.code_blocks.iter() {
if !code_block.contains(&name) {
if !code_block.0.contains(&name) {
errors.push(Error::new_spanned(
&ast.sig,
format!(
@ -270,9 +256,28 @@ fn do_stdlib_inner(
.code_blocks
.iter()
.enumerate()
.map(|(index, code_block)| generate_code_block_test(&fn_name_str, code_block, index))
.map(|(index, (code_block, norun))| {
if !norun {
generate_code_block_test(&fn_name_str, code_block, index)
} else {
quote! {}
}
})
.collect::<Vec<_>>();
let (cb, norun): (Vec<_>, Vec<_>) = doc_info.code_blocks.into_iter().unzip();
let code_blocks = quote! {
let code_blocks = vec![#(#cb),*];
let norun = vec![#(#norun),*];
code_blocks.iter().zip(norun).map(|(cb, norun)| {
let program = crate::Program::parse_no_errs(cb).unwrap();
let mut options: crate::parsing::ast::types::FormatOptions = Default::default();
options.insert_final_newline = false;
(program.ast.recast(&options, 0), norun)
}).collect::<Vec<(String, bool)>>()
};
let tags = metadata
.tags
.iter()
@ -534,7 +539,7 @@ fn do_stdlib_inner(
#feature_tree_operation
}
fn examples(&self) -> Vec<String> {
fn examples(&self) -> Vec<(String, bool)> {
#code_blocks
}
@ -577,7 +582,7 @@ fn get_crate(var: Option<String>) -> proc_macro2::TokenStream {
struct DocInfo {
pub summary: Option<String>,
pub description: Option<String>,
pub code_blocks: Vec<String>,
pub code_blocks: Vec<(String, bool)>,
}
fn extract_doc_from_attrs(attrs: &[syn::Attribute]) -> DocInfo {
@ -597,21 +602,22 @@ fn extract_doc_from_attrs(attrs: &[syn::Attribute]) -> DocInfo {
});
// Parse any code blocks from the doc string.
let mut code_blocks: Vec<String> = Vec::new();
let mut code_block: Option<String> = None;
let mut code_blocks: Vec<(String, bool)> = Vec::new();
let mut code_block: Option<(String, bool)> = None;
let mut parsed_lines = Vec::new();
for line in raw_lines {
if line.starts_with("```") {
if let Some(ref inner_code_block) = code_block {
code_blocks.push(inner_code_block.trim().to_string());
if let Some((inner_code_block, norun)) = code_block {
code_blocks.push((inner_code_block.trim().to_owned(), norun));
code_block = None;
} else {
code_block = Some(String::new());
let norun = line.contains("kcl,norun") || line.contains("kcl,no_run");
code_block = Some((String::new(), norun));
}
continue;
}
if let Some(ref mut code_block) = code_block {
if let Some((code_block, _)) = &mut code_block {
code_block.push_str(&line);
code_block.push('\n');
} else {
@ -619,8 +625,8 @@ fn extract_doc_from_attrs(attrs: &[syn::Attribute]) -> DocInfo {
}
}
if let Some(code_block) = code_block {
code_blocks.push(code_block.trim().to_string());
if let Some((code_block, norun)) = code_block {
code_blocks.push((code_block.trim().to_string(), norun));
}
let mut summary = None;

10
rust/kcl-derive-docs/tests/args_with_lifetime.gen
View File

@ -138,17 +138,19 @@ impl crate::docs::StdLibFn for SomeFn {
false
}
fn examples(&self) -> Vec<String> {
fn examples(&self) -> Vec<(String, bool)> {
let code_blocks = vec!["someFn()"];
let norun = vec![false];
code_blocks
.iter()
.map(|cb| {
.zip(norun)
.map(|(cb, norun)| {
let program = crate::Program::parse_no_errs(cb).unwrap();
let mut options: crate::parsing::ast::types::FormatOptions = Default::default();
options.insert_final_newline = false;
program.ast.recast(&options, 0)
(program.ast.recast(&options, 0), norun)
})
.collect::<Vec<String>>()
.collect::<Vec<(String, bool)>>()
}
fn std_lib_fn(&self) -> crate::std::StdFn {

10
rust/kcl-derive-docs/tests/args_with_refs.gen
View File

@ -138,17 +138,19 @@ impl crate::docs::StdLibFn for SomeFn {
false
}
fn examples(&self) -> Vec<String> {
fn examples(&self) -> Vec<(String, bool)> {
let code_blocks = vec!["someFn()"];
let norun = vec![false];
code_blocks
.iter()
.map(|cb| {
.zip(norun)
.map(|(cb, norun)| {
let program = crate::Program::parse_no_errs(cb).unwrap();
let mut options: crate::parsing::ast::types::FormatOptions = Default::default();
options.insert_final_newline = false;
program.ast.recast(&options, 0)
(program.ast.recast(&options, 0), norun)
})
.collect::<Vec<String>>()
.collect::<Vec<(String, bool)>>()
}
fn std_lib_fn(&self) -> crate::std::StdFn {

10
rust/kcl-derive-docs/tests/array.gen
View File

@ -139,17 +139,19 @@ impl crate::docs::StdLibFn for Show {
false
}
fn examples(&self) -> Vec<String> {
fn examples(&self) -> Vec<(String, bool)> {
let code_blocks = vec!["This is another code block.\nyes sirrr.\nshow"];
let norun = vec![false];
code_blocks
.iter()
.map(|cb| {
.zip(norun)
.map(|(cb, norun)| {
let program = crate::Program::parse_no_errs(cb).unwrap();
let mut options: crate::parsing::ast::types::FormatOptions = Default::default();
options.insert_final_newline = false;
program.ast.recast(&options, 0)
(program.ast.recast(&options, 0), norun)
})
.collect::<Vec<String>>()
.collect::<Vec<(String, bool)>>()
}
fn std_lib_fn(&self) -> crate::std::StdFn {

10
rust/kcl-derive-docs/tests/box.gen
View File

@ -139,17 +139,19 @@ impl crate::docs::StdLibFn for Show {
false
}
fn examples(&self) -> Vec<String> {
fn examples(&self) -> Vec<(String, bool)> {
let code_blocks = vec!["This is code.\nIt does other shit.\nshow"];
let norun = vec![false];
code_blocks
.iter()
.map(|cb| {
.zip(norun)
.map(|(cb, norun)| {
let program = crate::Program::parse_no_errs(cb).unwrap();
let mut options: crate::parsing::ast::types::FormatOptions = Default::default();
options.insert_final_newline = false;
program.ast.recast(&options, 0)
(program.ast.recast(&options, 0), norun)
})
.collect::<Vec<String>>()
.collect::<Vec<(String, bool)>>()
}
fn std_lib_fn(&self) -> crate::std::StdFn {

10
rust/kcl-derive-docs/tests/doc_comment_with_code.gen
View File

@ -140,17 +140,19 @@ impl crate::docs::StdLibFn for MyFunc {
false
}
fn examples(&self) -> Vec<String> {
fn examples(&self) -> Vec<(String, bool)> {
let code_blocks = vec!["This is another code block.\nyes sirrr.\nmyFunc"];
let norun = vec![false];
code_blocks
.iter()
.map(|cb| {
.zip(norun)
.map(|(cb, norun)| {
let program = crate::Program::parse_no_errs(cb).unwrap();
let mut options: crate::parsing::ast::types::FormatOptions = Default::default();
options.insert_final_newline = false;
program.ast.recast(&options, 0)
(program.ast.recast(&options, 0), norun)
})
.collect::<Vec<String>>()
.collect::<Vec<(String, bool)>>()
}
fn std_lib_fn(&self) -> crate::std::StdFn {

10
rust/kcl-derive-docs/tests/lineTo.gen
View File

@ -151,17 +151,19 @@ impl crate::docs::StdLibFn for LineTo {
false
}
fn examples(&self) -> Vec<String> {
fn examples(&self) -> Vec<(String, bool)> {
let code_blocks = vec!["This is another code block.\nyes sirrr.\nlineTo"];
let norun = vec![false];
code_blocks
.iter()
.map(|cb| {
.zip(norun)
.map(|(cb, norun)| {
let program = crate::Program::parse_no_errs(cb).unwrap();
let mut options: crate::parsing::ast::types::FormatOptions = Default::default();
options.insert_final_newline = false;
program.ast.recast(&options, 0)
(program.ast.recast(&options, 0), norun)
})
.collect::<Vec<String>>()
.collect::<Vec<(String, bool)>>()
}
fn std_lib_fn(&self) -> crate::std::StdFn {

10
rust/kcl-derive-docs/tests/min.gen
View File

@ -139,17 +139,19 @@ impl crate::docs::StdLibFn for Min {
false
}
fn examples(&self) -> Vec<String> {
fn examples(&self) -> Vec<(String, bool)> {
let code_blocks = vec!["This is another code block.\nyes sirrr.\nmin"];
let norun = vec![false];
code_blocks
.iter()
.map(|cb| {
.zip(norun)
.map(|(cb, norun)| {
let program = crate::Program::parse_no_errs(cb).unwrap();
let mut options: crate::parsing::ast::types::FormatOptions = Default::default();
options.insert_final_newline = false;
program.ast.recast(&options, 0)
(program.ast.recast(&options, 0), norun)
})
.collect::<Vec<String>>()
.collect::<Vec<(String, bool)>>()
}
fn std_lib_fn(&self) -> crate::std::StdFn {

10
rust/kcl-derive-docs/tests/option.gen
View File

@ -139,17 +139,19 @@ impl crate::docs::StdLibFn for Show {
false
}
fn examples(&self) -> Vec<String> {
fn examples(&self) -> Vec<(String, bool)> {
let code_blocks = vec!["This is code.\nIt does other shit.\nshow"];
let norun = vec![false];
code_blocks
.iter()
.map(|cb| {
.zip(norun)
.map(|(cb, norun)| {
let program = crate::Program::parse_no_errs(cb).unwrap();
let mut options: crate::parsing::ast::types::FormatOptions = Default::default();
options.insert_final_newline = false;
program.ast.recast(&options, 0)
(program.ast.recast(&options, 0), norun)
})
.collect::<Vec<String>>()
.collect::<Vec<(String, bool)>>()
}
fn std_lib_fn(&self) -> crate::std::StdFn {

10
rust/kcl-derive-docs/tests/option_input_format.gen
View File

@ -139,17 +139,19 @@ impl crate::docs::StdLibFn for Import {
false
}
fn examples(&self) -> Vec<String> {
fn examples(&self) -> Vec<(String, bool)> {
let code_blocks = vec!["This is code.\nIt does other shit.\nimport"];
let norun = vec![false];
code_blocks
.iter()
.map(|cb| {
.zip(norun)
.map(|(cb, norun)| {
let program = crate::Program::parse_no_errs(cb).unwrap();
let mut options: crate::parsing::ast::types::FormatOptions = Default::default();
options.insert_final_newline = false;
program.ast.recast(&options, 0)
(program.ast.recast(&options, 0), norun)
})
.collect::<Vec<String>>()
.collect::<Vec<(String, bool)>>()
}
fn std_lib_fn(&self) -> crate::std::StdFn {

10
rust/kcl-derive-docs/tests/return_vec_box_sketch.gen
View File

@ -139,17 +139,19 @@ impl crate::docs::StdLibFn for Import {
false
}
fn examples(&self) -> Vec<String> {
fn examples(&self) -> Vec<(String, bool)> {
let code_blocks = vec!["This is code.\nIt does other shit.\nimport"];
let norun = vec![false];
code_blocks
.iter()
.map(|cb| {
.zip(norun)
.map(|(cb, norun)| {
let program = crate::Program::parse_no_errs(cb).unwrap();
let mut options: crate::parsing::ast::types::FormatOptions = Default::default();
options.insert_final_newline = false;
program.ast.recast(&options, 0)
(program.ast.recast(&options, 0), norun)
})
.collect::<Vec<String>>()
.collect::<Vec<(String, bool)>>()
}
fn std_lib_fn(&self) -> crate::std::StdFn {

10
rust/kcl-derive-docs/tests/return_vec_sketch.gen
View File

@ -139,17 +139,19 @@ impl crate::docs::StdLibFn for Import {
false
}
fn examples(&self) -> Vec<String> {
fn examples(&self) -> Vec<(String, bool)> {
let code_blocks = vec!["This is code.\nIt does other shit.\nimport"];
let norun = vec![false];
code_blocks
.iter()
.map(|cb| {
.zip(norun)
.map(|(cb, norun)| {
let program = crate::Program::parse_no_errs(cb).unwrap();
let mut options: crate::parsing::ast::types::FormatOptions = Default::default();
options.insert_final_newline = false;
program.ast.recast(&options, 0)
(program.ast.recast(&options, 0), norun)
})
.collect::<Vec<String>>()
.collect::<Vec<(String, bool)>>()
}
fn std_lib_fn(&self) -> crate::std::StdFn {

10
rust/kcl-derive-docs/tests/show.gen
View File

@ -139,17 +139,19 @@ impl crate::docs::StdLibFn for Show {
false
}
fn examples(&self) -> Vec<String> {
fn examples(&self) -> Vec<(String, bool)> {
let code_blocks = vec!["This is code.\nIt does other shit.\nshow"];
let norun = vec![false];
code_blocks
.iter()
.map(|cb| {
.zip(norun)
.map(|(cb, norun)| {
let program = crate::Program::parse_no_errs(cb).unwrap();
let mut options: crate::parsing::ast::types::FormatOptions = Default::default();
options.insert_final_newline = false;
program.ast.recast(&options, 0)
(program.ast.recast(&options, 0), norun)
})
.collect::<Vec<String>>()
.collect::<Vec<(String, bool)>>()
}
fn std_lib_fn(&self) -> crate::std::StdFn {

10
rust/kcl-derive-docs/tests/test_args_with_exec_state.gen
View File

@ -130,17 +130,19 @@ impl crate::docs::StdLibFn for SomeFunction {
false
}
fn examples(&self) -> Vec<String> {
fn examples(&self) -> Vec<(String, bool)> {
let code_blocks = vec!["someFunction()"];
let norun = vec![false];
code_blocks
.iter()
.map(|cb| {
.zip(norun)
.map(|(cb, norun)| {
let program = crate::Program::parse_no_errs(cb).unwrap();
let mut options: crate::parsing::ast::types::FormatOptions = Default::default();
options.insert_final_newline = false;
program.ast.recast(&options, 0)
(program.ast.recast(&options, 0), norun)
})
.collect::<Vec<String>>()
.collect::<Vec<(String, bool)>>()
}
fn std_lib_fn(&self) -> crate::std::StdFn {

10
rust/kcl-lib/src/docs/gen_std_tests.rs
View File

@ -339,9 +339,7 @@ fn generate_function_from_kcl(function: &FnData, file_name: String, example_name
"description": function.description,
"deprecated": function.properties.deprecated,
"fn_signature": function.preferred_name.clone() + &function.fn_signature(),
"tags": [],
"examples": examples,
"is_utilities": false,
"args": function.args.iter().map(|arg| {
json!({
"name": arg.name,
@ -408,8 +406,8 @@ fn generate_function(internal_fn: Box<dyn StdLibFn>) -> Result<()> {
.examples()
.iter()
.enumerate()
.map(|(index, example)| {
let image_base64 = if !internal_fn.tags().contains(&"utilities".to_string()) {
.map(|(index, (example, norun))| {
let image_base64 = if !norun {
let image_path = format!(
"{}/tests/outputs/serial_test_example_{}{}.png",
env!("CARGO_MANIFEST_DIR"),
@ -436,9 +434,7 @@ fn generate_function(internal_fn: Box<dyn StdLibFn>) -> Result<()> {
"description": internal_fn.description(),
"deprecated": internal_fn.deprecated(),
"fn_signature": internal_fn.fn_signature(true),
"tags": internal_fn.tags(),
"examples": examples,
"is_utilities": internal_fn.tags().contains(&"utilities".to_string()),
"args": internal_fn.args(false).iter().map(|arg| {
json!({
"name": arg.name,
@ -700,7 +696,7 @@ async fn test_code_in_topics() {
let text = std::fs::read_to_string(&path).unwrap();
for (i, (eg, attr)) in find_examples(&text, &path).into_iter().enumerate() {
if attr.contains("norun") || !attr.contains("kcl") {
if attr.contains("norun") || attr == "no_run" || !attr.contains("kcl") {
continue;
}

6
rust/kcl-lib/src/docs/mod.rs
View File

@ -53,9 +53,9 @@ pub struct StdLibFnData {
pub unpublished: bool,
/// If the function is deprecated.
pub deprecated: bool,
/// Code examples.
/// Code examples. The bool is whether the example is `norun``
/// These are tested and we know they compile and execute.
pub examples: Vec<String>,
pub examples: Vec<(String, bool)>,
}
/// This struct defines a single argument to a stdlib function.
@ -414,7 +414,7 @@ pub trait StdLibFn: std::fmt::Debug + Send + Sync {
fn feature_tree_operation(&self) -> bool;
/// Any example code blocks.
fn examples(&self) -> Vec<String>;
fn examples(&self) -> Vec<(String, bool)>;
/// The function itself.
fn std_lib_fn(&self) -> crate::std::StdFn;

11
rust/kcl-lib/src/docs/templates/function.hbs vendored
View File

@ -16,15 +16,6 @@ layout: manual
{{{fn_signature}}}
```
{{#if tags}}
### Tags
{{#each tags}}
* `{{this}}`
{{/each}}
{{/if}}
{{#if args}}
### Arguments
@ -52,12 +43,10 @@ layout: manual
```
{{/if}}
{{#unless @root.is_utilities}}
{{#if this.image_base64}}
![Rendered example of {{@root.name}} {{@index}}](data:image/png;base64,{{{this.image_base64}}})
{{/if}}
{{/unless}}
{{/each}}
{{/if}}

12
rust/kcl-lib/src/std/array.rs
View File

@ -57,7 +57,8 @@ pub async fn map(exec_state: &mut ExecState, args: Args) -> Result<KclValue, Kcl
args = {
array = { docs = "Input array. The output array is this input array, but every element has had the function `f` run on it." },
f = { docs = "A function. The output array is just the input array, but `f` has been run on every item." },
}
},
tags = ["array"]
}]
async fn inner_map<'a>(
array: Vec<KclValue>,
@ -188,7 +189,8 @@ pub async fn reduce(exec_state: &mut ExecState, args: Args) -> Result<KclValue,
array = { docs = "Each element of this array gets run through the function `f`, combined with the previous output from `f`, and then used for the next run." },
initial = { docs = "The first time `f` is run, it will be called with the first item of `array` and this initial starting value."},
f = { docs = "Run once per item in the input `array`. This function takes an item from the array, and the previous output from `f` (or `initial` on the very first run). The final time `f` is run, its output is returned as the final output from `reduce`." },
}
},
tags = ["array"]
}]
async fn inner_reduce<'a>(
array: Vec<KclValue>,
@ -246,7 +248,8 @@ async fn call_reduce_closure(
args = {
array = { docs = "The array which you're adding a new item to." },
item = { docs = "The new item to add to the array" },
}
},
tags = ["array"]
}]
async fn inner_push(mut array: Vec<KclValue>, item: KclValue, args: &Args) -> Result<KclValue, KclError> {
array.push(item);
@ -289,7 +292,8 @@ pub async fn push(_exec_state: &mut ExecState, args: Args) -> Result<KclValue, K
unlabeled_first = true,
args = {
array = { docs = "The array to pop from. Must not be empty."},
}
},
tags = ["array"]
}]
async fn inner_pop(array: Vec<KclValue>, args: &Args) -> Result<KclValue, KclError> {
if array.is_empty() {

9
rust/kcl-lib/src/std/csg.rs
View File

@ -111,7 +111,8 @@ pub async fn union(exec_state: &mut ExecState, args: Args) -> Result<KclValue, K
args = {
solids = {docs = "The solids to union."},
tolerance = {docs = "The tolerance to use for the union operation."},
}
},
tags = ["solid"]
}]
pub(crate) async fn inner_union(
solids: Vec<Solid>,
@ -236,7 +237,8 @@ pub async fn intersect(exec_state: &mut ExecState, args: Args) -> Result<KclValu
args = {
solids = {docs = "The solids to intersect."},
tolerance = {docs = "The tolerance to use for the intersection operation."},
}
},
tags = ["solid"]
}]
pub(crate) async fn inner_intersect(
solids: Vec<Solid>,
@ -370,7 +372,8 @@ pub async fn subtract(exec_state: &mut ExecState, args: Args) -> Result<KclValue
solids = {docs = "The solids to use as the base to subtract from."},
tools = {docs = "The solids to subtract."},
tolerance = {docs = "The tolerance to use for the subtraction operation."},
}
},
tags = ["solid"]
}]
pub(crate) async fn inner_subtract(
solids: Vec<Solid>,

10
rust/kcl-lib/src/std/edge.rs
View File

@ -57,7 +57,8 @@ pub async fn get_opposite_edge(exec_state: &mut ExecState, args: Args) -> Result
unlabeled_first = true,
args = {
edge = { docs = "The tag of the edge you want to find the opposite edge of." },
}
},
tags = ["sketch"]
}]
async fn inner_get_opposite_edge(
edge: TagIdentifier,
@ -140,7 +141,8 @@ pub async fn get_next_adjacent_edge(exec_state: &mut ExecState, args: Args) -> R
unlabeled_first = true,
args = {
edge = { docs = "The tag of the edge you want to find the next adjacent edge of." },
}
},
tags = ["sketch"]
}]
async fn inner_get_next_adjacent_edge(
edge: TagIdentifier,
@ -232,7 +234,8 @@ pub async fn get_previous_adjacent_edge(exec_state: &mut ExecState, args: Args)
unlabeled_first = true,
args = {
edge = { docs = "The tag of the edge you want to find the previous adjacent edge of." },
}
},
tags = ["sketch"]
}]
async fn inner_get_previous_adjacent_edge(
edge: TagIdentifier,
@ -320,6 +323,7 @@ pub async fn get_common_edge(exec_state: &mut ExecState, args: Args) -> Result<K
args = {
faces = { docs = "The tags of the faces you want to find the common edge between" },
},
tags = ["sketch"]
}]
async fn inner_get_common_edge(
faces: Vec<TagIdentifier>,

3
rust/kcl-lib/src/std/extrude.rs
View File

@ -157,7 +157,8 @@ pub async fn extrude(exec_state: &mut ExecState, args: Args) -> Result<KclValue,
bidirectional_length = { docs = "If specified, will also extrude in the opposite direction to 'distance' to the specified distance. If 'symmetric' is true, this value is ignored."},
tag_start = { docs = "A named tag for the face at the start of the extrusion, i.e. the original sketch" },
tag_end = { docs = "A named tag for the face at the end of the extrusion, i.e. the new face created by extruding the original sketch" },
}
},
tags = ["sketch"]
}]
#[allow(clippy::too_many_arguments)]
async fn inner_extrude(

3
rust/kcl-lib/src/std/loft.rs
View File

@ -131,7 +131,8 @@ pub async fn loft(exec_state: &mut ExecState, args: Args) -> Result<KclValue, Kc
tolerance = {docs = "Tolerance for the loft operation."},
tag_start = { docs = "A named tag for the face at the start of the loft, i.e. the original sketch" },
tag_end = { docs = "A named tag for the face at the end of the loft, i.e. the last sketch" },
}
},
tags = ["sketch"]
}]
#[allow(clippy::too_many_arguments)]
async fn inner_loft(

12
rust/kcl-lib/src/std/mod.rs
View File

@ -353,7 +353,7 @@ pub async fn leg_length(exec_state: &mut ExecState, args: Args) -> Result<KclVal
/// Compute the length of the given leg.
///
/// ```no_run
/// ```kcl,no_run
/// legLen(hypotenuse = 5, leg = 3)
/// ```
#[stdlib {
@ -364,7 +364,7 @@ pub async fn leg_length(exec_state: &mut ExecState, args: Args) -> Result<KclVal
hypotenuse = { docs = "The length of the triangle's hypotenuse" },
leg = { docs = "The length of one of the triangle's legs (i.e. non-hypotenuse side)" },
},
tags = ["utilities"],
tags = ["math"],
}]
fn inner_leg_length(hypotenuse: f64, leg: f64) -> f64 {
(hypotenuse.powi(2) - f64::min(hypotenuse.abs(), leg.abs()).powi(2)).sqrt()
@ -385,7 +385,7 @@ pub async fn leg_angle_x(exec_state: &mut ExecState, args: Args) -> Result<KclVa
/// Compute the angle of the given leg for x.
///
/// ```no_run
/// ```kcl,no_run
/// legAngX(hypotenuse = 5, leg = 3)
/// ```
#[stdlib {
@ -396,7 +396,7 @@ pub async fn leg_angle_x(exec_state: &mut ExecState, args: Args) -> Result<KclVa
hypotenuse = { docs = "The length of the triangle's hypotenuse" },
leg = { docs = "The length of one of the triangle's legs (i.e. non-hypotenuse side)" },
},
tags = ["utilities"],
tags = ["math"],
}]
fn inner_leg_angle_x(hypotenuse: f64, leg: f64) -> f64 {
(leg.min(hypotenuse) / hypotenuse).acos().to_degrees()
@ -417,7 +417,7 @@ pub async fn leg_angle_y(exec_state: &mut ExecState, args: Args) -> Result<KclVa
/// Compute the angle of the given leg for y.
///
/// ```no_run
/// ```kcl,no_run
/// legAngY(hypotenuse = 5, leg = 3)
/// ```
#[stdlib {
@ -428,7 +428,7 @@ pub async fn leg_angle_y(exec_state: &mut ExecState, args: Args) -> Result<KclVa
hypotenuse = { docs = "The length of the triangle's hypotenuse" },
leg = { docs = "The length of one of the triangle's legs (i.e. non-hypotenuse side)" },
},
tags = ["utilities"],
tags = ["math"],
}]
fn inner_leg_angle_y(hypotenuse: f64, leg: f64) -> f64 {
(leg.min(hypotenuse) / hypotenuse).asin().to_degrees()

15
rust/kcl-lib/src/std/patterns.rs
View File

@ -247,7 +247,8 @@ pub async fn pattern_transform_2d(exec_state: &mut ExecState, args: Args) -> Res
instances = { docs = "The number of total instances. Must be greater than or equal to 1. This includes the original entity. For example, if instances is 2, there will be two copies -- the original, and one new copy. If instances is 1, this has no effect." },
transform = { docs = "How each replica should be transformed. The transform function takes a single parameter: an integer representing which number replication the transform is for. E.g. the first replica to be transformed will be passed the argument `1`. This simplifies your math: the transform function can rely on id `0` being the original instance passed into the `patternTransform`. See the examples." },
use_original = { docs = "If the target was sketched on an extrusion, setting this will use the original sketch as the target, not the entire joined solid. Defaults to false." },
}
},
tags = ["solid"]
}]
async fn inner_pattern_transform<'a>(
solids: Vec<Solid>,
@ -300,7 +301,8 @@ async fn inner_pattern_transform<'a>(
instances = { docs = "The number of total instances. Must be greater than or equal to 1. This includes the original entity. For example, if instances is 2, there will be two copies -- the original, and one new copy. If instances is 1, this has no effect." },
transform = { docs = "How each replica should be transformed. The transform function takes a single parameter: an integer representing which number replication the transform is for. E.g. the first replica to be transformed will be passed the argument `1`. This simplifies your math: the transform function can rely on id `0` being the original instance passed into the `patternTransform`. See the examples." },
use_original = { docs = "If the target was sketched on an extrusion, setting this will use the original sketch as the target, not the entire joined solid. Defaults to false." },
}
},
tags = ["sketch"]
}]
async fn inner_pattern_transform_2d<'a>(
sketches: Vec<Sketch>,
@ -872,7 +874,8 @@ pub async fn pattern_linear_3d(exec_state: &mut ExecState, args: Args) -> Result
distance = { docs = "Distance between each repetition. Also known as 'spacing'."},
axis = { docs = "The axis of the pattern. A 2D vector." },
use_original = { docs = "If the target was sketched on an extrusion, setting this will use the original sketch as the target, not the entire joined solid. Defaults to false." },
}
},
tags = ["solid"]
}]
async fn inner_pattern_linear_3d(
solids: Vec<Solid>,
@ -1069,7 +1072,8 @@ pub async fn pattern_circular_2d(exec_state: &mut ExecState, args: Args) -> Resu
arc_degrees = { docs = "The arc angle (in degrees) to place the repetitions. Must be greater than 0."},
rotate_duplicates= { docs = "Whether or not to rotate the duplicates as they are copied."},
use_original= { docs = "If the target was sketched on an extrusion, setting this will use the original sketch as the target, not the entire joined solid. Defaults to false."},
}
},
tags = ["sketch"]
}]
#[allow(clippy::too_many_arguments)]
async fn inner_pattern_circular_2d(
@ -1184,7 +1188,8 @@ pub async fn pattern_circular_3d(exec_state: &mut ExecState, args: Args) -> Resu
arc_degrees = { docs = "The arc angle (in degrees) to place the repetitions. Must be greater than 0."},
rotate_duplicates = { docs = "Whether or not to rotate the duplicates as they are copied."},
use_original = { docs = "If the target was sketched on an extrusion, setting this will use the original sketch as the target, not the entire joined solid. Defaults to false."},
}
},
tags = ["solid"]
}]
#[allow(clippy::too_many_arguments)]
async fn inner_pattern_circular_3d(

33
rust/kcl-lib/src/std/segment.rs
View File

@ -53,7 +53,8 @@ pub async fn segment_end(exec_state: &mut ExecState, args: Args) -> Result<KclVa
unlabeled_first = true,
args = {
tag = { docs = "The line segment being queried by its tag"},
}
},
tags = ["sketch"]
}]
fn inner_segment_end(tag: &TagIdentifier, exec_state: &mut ExecState, args: Args) -> Result<[TyF64; 2], KclError> {
let line = args.get_tag_engine_info(exec_state, tag)?;
@ -94,7 +95,8 @@ pub async fn segment_end_x(exec_state: &mut ExecState, args: Args) -> Result<Kcl
unlabeled_first = true,
args = {
tag = { docs = "The line segment being queried by its tag"},
}
},
tags = ["sketch"]
}]
fn inner_segment_end_x(tag: &TagIdentifier, exec_state: &mut ExecState, args: Args) -> Result<TyF64, KclError> {
let line = args.get_tag_engine_info(exec_state, tag)?;
@ -136,7 +138,8 @@ pub async fn segment_end_y(exec_state: &mut ExecState, args: Args) -> Result<Kcl
unlabeled_first = true,
args = {
tag = { docs = "The line segment being queried by its tag"},
}
},
tags = ["sketch"]
}]
fn inner_segment_end_y(tag: &TagIdentifier, exec_state: &mut ExecState, args: Args) -> Result<TyF64, KclError> {
let line = args.get_tag_engine_info(exec_state, tag)?;
@ -189,7 +192,8 @@ pub async fn segment_start(exec_state: &mut ExecState, args: Args) -> Result<Kcl
unlabeled_first = true,
args = {
tag = { docs = "The line segment being queried by its tag"},
}
},
tags = ["sketch"]
}]
fn inner_segment_start(tag: &TagIdentifier, exec_state: &mut ExecState, args: Args) -> Result<[TyF64; 2], KclError> {
let line = args.get_tag_engine_info(exec_state, tag)?;
@ -230,7 +234,8 @@ pub async fn segment_start_x(exec_state: &mut ExecState, args: Args) -> Result<K
unlabeled_first = true,
args = {
tag = { docs = "The line segment being queried by its tag"},
}
},
tags = ["sketch"]
}]
fn inner_segment_start_x(tag: &TagIdentifier, exec_state: &mut ExecState, args: Args) -> Result<TyF64, KclError> {
let line = args.get_tag_engine_info(exec_state, tag)?;
@ -272,7 +277,8 @@ pub async fn segment_start_y(exec_state: &mut ExecState, args: Args) -> Result<K
unlabeled_first = true,
args = {
tag = { docs = "The line segment being queried by its tag"},
}
},
tags = ["sketch"]
}]
fn inner_segment_start_y(tag: &TagIdentifier, exec_state: &mut ExecState, args: Args) -> Result<TyF64, KclError> {
let line = args.get_tag_engine_info(exec_state, tag)?;
@ -314,7 +320,8 @@ pub async fn last_segment_x(exec_state: &mut ExecState, args: Args) -> Result<Kc
unlabeled_first = true,
args = {
sketch = { docs = "The sketch whose line segment is being queried"},
}
},
tags = ["sketch"]
}]
fn inner_last_segment_x(sketch: Sketch, args: Args) -> Result<TyF64, KclError> {
let last_line = sketch
@ -360,7 +367,8 @@ pub async fn last_segment_y(exec_state: &mut ExecState, args: Args) -> Result<Kc
unlabeled_first = true,
args = {
sketch = { docs = "The sketch whose line segment is being queried"},
}
},
tags = ["sketch"]
}]
fn inner_last_segment_y(sketch: Sketch, args: Args) -> Result<TyF64, KclError> {
let last_line = sketch
@ -409,7 +417,8 @@ pub async fn segment_length(exec_state: &mut ExecState, args: Args) -> Result<Kc
unlabeled_first = true,
args = {
tag = { docs = "The line segment being queried by its tag"},
}
},
tags = ["sketch"]
}]
fn inner_segment_length(tag: &TagIdentifier, exec_state: &mut ExecState, args: Args) -> Result<TyF64, KclError> {
let line = args.get_tag_engine_info(exec_state, tag)?;
@ -452,7 +461,8 @@ pub async fn segment_angle(exec_state: &mut ExecState, args: Args) -> Result<Kcl
unlabeled_first = true,
args = {
tag = { docs = "The line segment being queried by its tag"},
}
},
tags = ["sketch"]
}]
fn inner_segment_angle(tag: &TagIdentifier, exec_state: &mut ExecState, args: Args) -> Result<f64, KclError> {
let line = args.get_tag_engine_info(exec_state, tag)?;
@ -553,7 +563,8 @@ pub async fn tangent_to_end(exec_state: &mut ExecState, args: Args) -> Result<Kc
unlabeled_first = true,
args = {
tag = { docs = "The line segment being queried by its tag"},
}
},
tags = ["sketch"]
}]
async fn inner_tangent_to_end(tag: &TagIdentifier, exec_state: &mut ExecState, args: Args) -> Result<f64, KclError> {
let line = args.get_tag_engine_info(exec_state, tag)?;

6
rust/kcl-lib/src/std/shapes.rs
View File

@ -154,7 +154,8 @@ pub async fn circle_three_point(exec_state: &mut ExecState, args: Args) -> Resul
p2 = {docs = "2nd point to derive the circle."},
p3 = {docs = "3rd point to derive the circle."},
tag = {docs = "Identifier for the circle to reference elsewhere."},
}
},
tags = ["sketch"]
}]
// Similar to inner_circle, but needs to retain 3-point information in the
@ -310,7 +311,8 @@ pub async fn polygon(exec_state: &mut ExecState, args: Args) -> Result<KclValue,
num_sides = { docs = "The number of sides in the polygon", include_in_snippet = true },
center = { docs = "The center point of the polygon", include_in_snippet = true },
inscribed = { docs = "Whether the polygon is inscribed (true, the default) or circumscribed (false) about a circle with the specified radius" },
}
},
tags = ["sketch"]
}]
#[allow(clippy::too_many_arguments)]
async fn inner_polygon(

48
rust/kcl-lib/src/std/sketch.rs
View File

@ -151,7 +151,8 @@ fn involute_curve(radius: f64, angle: f64) -> (f64, f64) {
angle = { docs = "The angle to rotate the involute by. A value of zero will produce a curve with a tangent along the x-axis at the start point of the curve."},
reverse = { docs = "If reverse is true, the segment will start from the end of the involute, otherwise it will start from that start. Defaults to false."},
tag = { docs = "Create a new tag which refers to this line"},
}
},
tags = ["sketch"]
}]
#[allow(clippy::too_many_arguments)]
async fn inner_involute_circular(
@ -267,7 +268,8 @@ pub async fn line(exec_state: &mut ExecState, args: Args) -> Result<KclValue, Kc
end_absolute = { docs = "Which absolute point should this line go to? Incompatible with `end`."},
end = { docs = "How far away (along the X and Y axes) should this line go? Incompatible with `endAbsolute`.", include_in_snippet = true},
tag = { docs = "Create a new tag which refers to this line"},
}
},
tags = ["sketch"]
}]
async fn inner_line(
sketch: Sketch,
@ -434,7 +436,8 @@ pub async fn x_line(exec_state: &mut ExecState, args: Args) -> Result<KclValue,
length = { docs = "How far away along the X axis should this line go? Incompatible with `endAbsolute`.", include_in_snippet = true},
end_absolute = { docs = "Which absolute X value should this line go to? Incompatible with `length`."},
tag = { docs = "Create a new tag which refers to this line"},
}
},
tags = ["sketch"]
}]
async fn inner_x_line(
sketch: Sketch,
@ -498,7 +501,8 @@ pub async fn y_line(exec_state: &mut ExecState, args: Args) -> Result<KclValue,
length = { docs = "How far away along the Y axis should this line go? Incompatible with `endAbsolute`.", include_in_snippet = true},
end_absolute = { docs = "Which absolute Y value should this line go to? Incompatible with `length`."},
tag = { docs = "Create a new tag which refers to this line"},
}
},
tags = ["sketch"]
}]
async fn inner_y_line(
sketch: Sketch,
@ -583,7 +587,8 @@ pub async fn angled_line(exec_state: &mut ExecState, args: Args) -> Result<KclVa
end_absolute_x = { docs = "Draw the line along the given angle until it reaches this point along the X axis. Only one of `length`, `lengthX`, `lengthY`, `endAbsoluteX`, `endAbsoluteY` can be given."},
end_absolute_y = { docs = "Draw the line along the given angle until it reaches this point along the Y axis. Only one of `length`, `lengthX`, `lengthY`, `endAbsoluteX`, `endAbsoluteY` can be given."},
tag = { docs = "Create a new tag which refers to this line"},
}
},
tags = ["sketch"]
}]
#[allow(clippy::too_many_arguments)]
async fn inner_angled_line(
@ -879,7 +884,8 @@ pub async fn angled_line_that_intersects(exec_state: &mut ExecState, args: Args)
intersect_tag = { docs = "The tag of the line to intersect with" },
offset = { docs = "The offset from the intersecting line. Defaults to 0." },
tag = { docs = "Create a new tag which refers to this line"},
}
},
tags = ["sketch"]
}]
pub async fn inner_angled_line_that_intersects(
sketch: Sketch,
@ -1153,7 +1159,8 @@ pub async fn start_sketch_on(exec_state: &mut ExecState, args: Args) -> Result<K
args = {
plane_or_solid = { docs = "The plane or solid to sketch on"},
face = { docs = "Identify a face of a solid if a solid is specified as the input argument (`plane_or_solid`)"},
}
},
tags = ["sketch"]
}]
async fn inner_start_sketch_on(
plane_or_solid: SketchData,
@ -1320,7 +1327,8 @@ pub async fn start_profile(exec_state: &mut ExecState, args: Args) -> Result<Kcl
sketch_surface = { docs = "What to start the profile on" },
at = { docs = "Where to start the profile. An absolute point." },
tag = { docs = "Tag this first starting point" },
}
},
tags = ["sketch"]
}]
pub(crate) async fn inner_start_profile(
sketch_surface: SketchSurface,
@ -1459,7 +1467,8 @@ pub async fn profile_start_x(exec_state: &mut ExecState, args: Args) -> Result<K
unlabeled_first = true,
args = {
profile = {docs = "Profile whose start is being used"},
}
},
tags = ["sketch"]
}]
pub(crate) fn inner_profile_start_x(profile: Sketch) -> Result<f64, KclError> {
Ok(profile.start.to[0])
@ -1488,7 +1497,8 @@ pub async fn profile_start_y(exec_state: &mut ExecState, args: Args) -> Result<K
unlabeled_first = true,
args = {
profile = {docs = "Profile whose start is being used"},
}
},
tags = ["sketch"]
}]
pub(crate) fn inner_profile_start_y(profile: Sketch) -> Result<f64, KclError> {
Ok(profile.start.to[1])
@ -1520,7 +1530,8 @@ pub async fn profile_start(exec_state: &mut ExecState, args: Args) -> Result<Kcl
unlabeled_first = true,
args = {
profile = {docs = "Profile whose start is being used"},
}
},
tags = ["sketch"]
}]
pub(crate) fn inner_profile_start(profile: Sketch) -> Result<[f64; 2], KclError> {
Ok(profile.start.to)
@ -1565,7 +1576,8 @@ pub async fn close(exec_state: &mut ExecState, args: Args) -> Result<KclValue, K
args = {
sketch = { docs = "The sketch you want to close"},
tag = { docs = "Create a new tag which refers to this line"},
}
},
tags = ["sketch"]
}]
pub(crate) async fn inner_close(
sketch: Sketch,
@ -1679,7 +1691,8 @@ pub async fn arc(exec_state: &mut ExecState, args: Args) -> Result<KclValue, Kcl
interior_absolute = { docs = "Any point between the arc's start and end? Requires `endAbsolute`. Incompatible with `angleStart` or `angleEnd`" },
end_absolute = { docs = "Where should this arc end? Requires `interiorAbsolute`. Incompatible with `angleStart` or `angleEnd`" },
tag = { docs = "Create a new tag which refers to this line"},
}
},
tags = ["sketch"]
}]
#[allow(clippy::too_many_arguments)]
pub(crate) async fn inner_arc(
@ -1922,7 +1935,8 @@ pub async fn tangential_arc(exec_state: &mut ExecState, args: Args) -> Result<Kc
radius = { docs = "Radius of the imaginary circle. `angle` must be given. Incompatible with `end` and `endAbsolute`."},
angle = { docs = "Offset of the arc in degrees. `radius` must be given. Incompatible with `end` and `endAbsolute`."},
tag = { docs = "Create a new tag which refers to this arc"},
}
},
tags = ["sketch"]
}]
#[allow(clippy::too_many_arguments)]
async fn inner_tangential_arc(
@ -2200,7 +2214,8 @@ pub async fn bezier_curve(exec_state: &mut ExecState, args: Args) -> Result<KclV
control1 = { docs = "First control point for the cubic" },
control2 = { docs = "Second control point for the cubic" },
tag = { docs = "Create a new tag which refers to this line"},
}
},
tags = ["sketch"]
}]
async fn inner_bezier_curve(
sketch: Sketch,
@ -2318,7 +2333,8 @@ pub async fn subtract_2d(exec_state: &mut ExecState, args: Args) -> Result<KclVa
args = {
sketch = { docs = "Which sketch should this path be added to?" },
tool = { docs = "The shape(s) which should be cut out of the sketch." },
}
},
tags = ["sketch"]
}]
async fn inner_subtract_2d(
sketch: Sketch,

3
rust/kcl-lib/src/std/sweep.rs
View File

@ -160,7 +160,8 @@ pub async fn sweep(exec_state: &mut ExecState, args: Args) -> Result<KclValue, K
tolerance = { docs = "Tolerance for this operation" },
tag_start = { docs = "A named tag for the face at the start of the sweep, i.e. the original sketch" },
tag_end = { docs = "A named tag for the face at the end of the sweep" },
}
},
tags = ["sketch"]
}]
#[allow(clippy::too_many_arguments)]
async fn inner_sweep(

9
rust/kcl-lib/src/std/transform.rs
View File

@ -153,7 +153,8 @@ pub async fn scale(exec_state: &mut ExecState, args: Args) -> Result<KclValue, K
y = {docs = "The scale factor for the y axis. Default is 1 if not provided.", include_in_snippet = true},
z = {docs = "The scale factor for the z axis. Default is 1 if not provided.", include_in_snippet = true},
global = {docs = "If true, the transform is applied in global space. The origin of the model will move. By default, the transform is applied in local sketch axis, therefore the origin will not move."}
}
},
tags = ["transform"]
}]
async fn inner_scale(
objects: SolidOrSketchOrImportedGeometry,
@ -383,7 +384,8 @@ pub async fn translate(exec_state: &mut ExecState, args: Args) -> Result<KclValu
y = {docs = "The amount to move the solid or sketch along the y axis. Defaults to 0 if not provided.", include_in_snippet = true},
z = {docs = "The amount to move the solid or sketch along the z axis. Defaults to 0 if not provided.", include_in_snippet = true},
global = {docs = "If true, the transform is applied in global space. The origin of the model will move. By default, the transform is applied in local sketch axis, therefore the origin will not move."}
}
},
tags = ["transform"]
}]
async fn inner_translate(
objects: SolidOrSketchOrImportedGeometry,
@ -748,7 +750,8 @@ pub async fn rotate(exec_state: &mut ExecState, args: Args) -> Result<KclValue,
axis = {docs = "The axis to rotate around. Must be used with `angle`.", include_in_snippet = false},
angle = {docs = "The angle to rotate in degrees. Must be used with `axis`. Must be between -360 and 360.", include_in_snippet = false},
global = {docs = "If true, the transform is applied in global space. The origin of the model will move. By default, the transform is applied in local sketch axis, therefore the origin will not move."}
}
},
tags = ["transform"]
}]
#[allow(clippy::too_many_arguments)]
async fn inner_rotate(