Syntax sugar booleans (+ and -) which is intuitive for MEs (#6124)

* updates

Signed-off-by: Jess Frazelle <github@jessfraz.com>

* docs

Signed-off-by: Jess Frazelle <github@jessfraz.com>

* docs

Signed-off-by: Jess Frazelle <github@jessfraz.com>

---------

Signed-off-by: Jess Frazelle <github@jessfraz.com>

docs/kcl/std.json

@@ -111905,7 +111905,8 @@
     "unpublished": false,
     "deprecated": true,
     "examples": [
-      "fn cube(center) {\n  return startSketchOn(XY)\n    |> startProfileAt([center[0] - 10, center[1] - 10], %)\n    |> line(endAbsolute = [center[0] + 10, center[1] - 10])\n    |> line(endAbsolute = [center[0] + 10, center[1] + 10])\n    |> line(endAbsolute = [center[0] - 10, center[1] + 10])\n    |> close()\n    |> extrude(length = 10)\n}\n\npart001 = cube([0, 0])\npart002 = cube([8, 8])\n\nintersectedPart = intersect([part001, part002])"
+      "// Intersect two cubes using the stdlib functions.\n\n\nfn cube(center) {\n  return startSketchOn(XY)\n    |> startProfileAt([center[0] - 10, center[1] - 10], %)\n    |> line(endAbsolute = [center[0] + 10, center[1] - 10])\n    |> line(endAbsolute = [center[0] + 10, center[1] + 10])\n    |> line(endAbsolute = [center[0] - 10, center[1] + 10])\n    |> close()\n    |> extrude(length = 10)\n}\n\npart001 = cube([0, 0])\npart002 = cube([8, 8])\n\nintersectedPart = intersect([part001, part002])",
+      "// Intersect two cubes using operators.\n// NOTE: This will not work when using codemods through the UI.\n// Codemods will generate the stdlib function call instead.\n\n\nfn cube(center) {\n  return startSketchOn(XY)\n    |> startProfileAt([center[0] - 10, center[1] - 10], %)\n    |> line(endAbsolute = [center[0] + 10, center[1] - 10])\n    |> line(endAbsolute = [center[0] + 10, center[1] + 10])\n    |> line(endAbsolute = [center[0] - 10, center[1] + 10])\n    |> close()\n    |> extrude(length = 10)\n}\n\npart001 = cube([0, 0])\npart002 = cube([8, 8])\n\n// This is the equivalent of: intersect([part001, part002])\nintersectedPart = part001 & part002"
     ]
   },
   {
@@ -294700,7 +294701,7 @@
         },
         "required": true,
         "includeInSnippet": true,
-        "description": "The solids to intersect.",
+        "description": "The solids to use as the base to subtract from.",
         "labelRequired": false
       },
       {
@@ -297904,7 +297905,8 @@
     "unpublished": false,
     "deprecated": true,
     "examples": [
-      "fn cube(center) {\n  return startSketchOn(XY)\n    |> startProfileAt([center[0] - 10, center[1] - 10], %)\n    |> line(endAbsolute = [center[0] + 10, center[1] - 10])\n    |> line(endAbsolute = [center[0] + 10, center[1] + 10])\n    |> line(endAbsolute = [center[0] - 10, center[1] + 10])\n    |> close()\n    |> extrude(length = 10)\n}\n\npart001 = cube([0, 0])\npart002 = startSketchOn(XY)\n  |> circle(center = [0, 0], radius = 2)\n  |> extrude(length = 10)\n\nsubtractedPart = subtract([part001], tools = [part002])"
+      "// Subtract a cylinder from a cube using the stdlib functions.\n\n\nfn cube(center) {\n  return startSketchOn(XY)\n    |> startProfileAt([center[0] - 10, center[1] - 10], %)\n    |> line(endAbsolute = [center[0] + 10, center[1] - 10])\n    |> line(endAbsolute = [center[0] + 10, center[1] + 10])\n    |> line(endAbsolute = [center[0] - 10, center[1] + 10])\n    |> close()\n    |> extrude(length = 10)\n}\n\npart001 = cube([0, 0])\npart002 = startSketchOn(XY)\n  |> circle(center = [0, 0], radius = 2)\n  |> extrude(length = 10)\n\nsubtractedPart = subtract([part001], tools = [part002])",
+      "// Subtract a cylinder from a cube using operators.\n// NOTE: This will not work when using codemods through the UI.\n// Codemods will generate the stdlib function call instead.\n\n\nfn cube(center) {\n  return startSketchOn(XY)\n    |> startProfileAt([center[0] - 10, center[1] - 10], %)\n    |> line(endAbsolute = [center[0] + 10, center[1] - 10])\n    |> line(endAbsolute = [center[0] + 10, center[1] + 10])\n    |> line(endAbsolute = [center[0] - 10, center[1] + 10])\n    |> close()\n    |> extrude(length = 10)\n}\n\npart001 = cube([0, 0])\npart002 = startSketchOn(XY)\n  |> circle(center = [0, 0], radius = 2)\n  |> extrude(length = 10)\n\n// This is the equivalent of: subtract([part001], tools=[part002])\nsubtractedPart = part001 - part002"
     ]
   },
   {
@@ -337325,7 +337327,9 @@
     "unpublished": false,
     "deprecated": true,
     "examples": [
-      "fn cube(center) {\n  return startSketchOn(XY)\n    |> startProfileAt([center[0] - 10, center[1] - 10], %)\n    |> line(endAbsolute = [center[0] + 10, center[1] - 10])\n    |> line(endAbsolute = [center[0] + 10, center[1] + 10])\n    |> line(endAbsolute = [center[0] - 10, center[1] + 10])\n    |> close()\n    |> extrude(length = 10)\n}\n\npart001 = cube([0, 0])\npart002 = cube([20, 10])\n\nunionedPart = union([part001, part002])"
+      "// Union two cubes using the stdlib functions.\n\n\nfn cube(center) {\n  return startSketchOn(XY)\n    |> startProfileAt([center[0] - 10, center[1] - 10], %)\n    |> line(endAbsolute = [center[0] + 10, center[1] - 10])\n    |> line(endAbsolute = [center[0] + 10, center[1] + 10])\n    |> line(endAbsolute = [center[0] - 10, center[1] + 10])\n    |> close()\n    |> extrude(length = 10)\n}\n\npart001 = cube([0, 0])\npart002 = cube([20, 10])\n\nunionedPart = union([part001, part002])",
+      "// Union two cubes using operators.\n// NOTE: This will not work when using codemods through the UI.\n// Codemods will generate the stdlib function call instead.\n\n\nfn cube(center) {\n  return startSketchOn(XY)\n    |> startProfileAt([center[0] - 10, center[1] - 10], %)\n    |> line(endAbsolute = [center[0] + 10, center[1] - 10])\n    |> line(endAbsolute = [center[0] + 10, center[1] + 10])\n    |> line(endAbsolute = [center[0] - 10, center[1] + 10])\n    |> close()\n    |> extrude(length = 10)\n}\n\npart001 = cube([0, 0])\npart002 = cube([20, 10])\n\n// This is the equivalent of: union([part001, part002])\nunionedPart = part001 + part002",
+      "// Union two cubes using the more programmer-friendly operator.\n// NOTE: This will not work when using codemods through the UI.\n// Codemods will generate the stdlib function call instead.\n\n\nfn cube(center) {\n  return startSketchOn(XY)\n    |> startProfileAt([center[0] - 10, center[1] - 10], %)\n    |> line(endAbsolute = [center[0] + 10, center[1] - 10])\n    |> line(endAbsolute = [center[0] + 10, center[1] + 10])\n    |> line(endAbsolute = [center[0] - 10, center[1] + 10])\n    |> close()\n    |> extrude(length = 10)\n}\n\npart001 = cube([0, 0])\npart002 = cube([20, 10])\n\n// This is the equivalent of: union([part001, part002])\n// Programmers will understand `|` as a union operation, but mechanical engineers\n// will understand `+`, we made both work.\nunionedPart = part001 | part002"
     ]
   },
   {

rust/kcl-lib/src/execution/exec_ast.rs

@@ -902,6 +902,33 @@ impl Node<BinaryExpression> {
             }
         }
 
+        // Then check if we have solids.
+        if self.operator == BinaryOperator::Add || self.operator == BinaryOperator::Or {
+            if let (KclValue::Solid { value: left }, KclValue::Solid { value: right }) = (&left_value, &right_value) {
+                let args = crate::std::Args::new(Default::default(), self.into(), ctx.clone(), None);
+                let result =
+                    crate::std::csg::inner_union(vec![*left.clone(), *right.clone()], exec_state, args).await?;
+                return Ok(result.into());
+            }
+        } else if self.operator == BinaryOperator::Sub {
+            // Check if we have solids.
+            if let (KclValue::Solid { value: left }, KclValue::Solid { value: right }) = (&left_value, &right_value) {
+                let args = crate::std::Args::new(Default::default(), self.into(), ctx.clone(), None);
+                let result =
+                    crate::std::csg::inner_subtract(vec![*left.clone()], vec![*right.clone()], exec_state, args)
+                        .await?;
+                return Ok(result.into());
+            }
+        } else if self.operator == BinaryOperator::And {
+            // Check if we have solids.
+            if let (KclValue::Solid { value: left }, KclValue::Solid { value: right }) = (&left_value, &right_value) {
+                let args = crate::std::Args::new(Default::default(), self.into(), ctx.clone(), None);
+                let result =
+                    crate::std::csg::inner_intersect(vec![*left.clone(), *right.clone()], exec_state, args).await?;
+                return Ok(result.into());
+            }
+        }
+
         // Check if we are doing logical operations on booleans.
         if self.operator == BinaryOperator::Or || self.operator == BinaryOperator::And {
             let KclValue::Bool {

rust/kcl-lib/src/std/csg.rs

@@ -28,6 +28,8 @@ pub async fn union(exec_state: &mut ExecState, args: Args) -> Result<KclValue, K
 /// Union two or more solids into a single solid.
 ///
 /// ```no_run
+/// // Union two cubes using the stdlib functions.
+///
 /// fn cube(center) {
 ///     return startSketchOn('XY')
 ///         |> startProfileAt([center[0] - 10, center[1] - 10], %)
@@ -43,6 +45,52 @@ pub async fn union(exec_state: &mut ExecState, args: Args) -> Result<KclValue, K
 ///
 /// unionedPart = union([part001, part002])
 /// ```
+///
+/// ```no_run
+/// // Union two cubes using operators.
+/// // NOTE: This will not work when using codemods through the UI.
+/// // Codemods will generate the stdlib function call instead.
+///
+/// fn cube(center) {
+///     return startSketchOn('XY')
+///         |> startProfileAt([center[0] - 10, center[1] - 10], %)
+///         |> line(endAbsolute = [center[0] + 10, center[1] - 10])
+///         |> line(endAbsolute = [center[0] + 10, center[1] + 10])
+///         |> line(endAbsolute = [center[0] - 10, center[1] + 10])
+///         |> close()
+///         |> extrude(length = 10)
+/// }
+///
+/// part001 = cube([0, 0])
+/// part002 = cube([20, 10])
+///
+/// // This is the equivalent of: union([part001, part002])
+/// unionedPart = part001 + part002
+/// ```
+///
+/// ```no_run
+/// // Union two cubes using the more programmer-friendly operator.
+/// // NOTE: This will not work when using codemods through the UI.
+/// // Codemods will generate the stdlib function call instead.
+///
+/// fn cube(center) {
+///     return startSketchOn('XY')
+///         |> startProfileAt([center[0] - 10, center[1] - 10], %)
+///         |> line(endAbsolute = [center[0] + 10, center[1] - 10])
+///         |> line(endAbsolute = [center[0] + 10, center[1] + 10])
+///         |> line(endAbsolute = [center[0] - 10, center[1] + 10])
+///         |> close()
+///         |> extrude(length = 10)
+/// }
+///
+/// part001 = cube([0, 0])
+/// part002 = cube([20, 10])
+///
+/// // This is the equivalent of: union([part001, part002])
+/// // Programmers will understand `|` as a union operation, but mechanical engineers
+/// // will understand `+`, we made both work.
+/// unionedPart = part001 | part002
+/// ```
 #[stdlib {
     name = "union",
     feature_tree_operation = true,
@@ -53,7 +101,11 @@ pub async fn union(exec_state: &mut ExecState, args: Args) -> Result<KclValue, K
         solids = {docs = "The solids to union."},
     }
 }]
-async fn inner_union(solids: Vec<Solid>, exec_state: &mut ExecState, args: Args) -> Result<Vec<Solid>, KclError> {
+pub(crate) async fn inner_union(
+    solids: Vec<Solid>,
+    exec_state: &mut ExecState,
+    args: Args,
+) -> Result<Vec<Solid>, KclError> {
     // Flush the fillets for the solids.
     args.flush_batch_for_solids(exec_state, &solids).await?;
 
@@ -90,6 +142,8 @@ pub async fn intersect(exec_state: &mut ExecState, args: Args) -> Result<KclValu
 /// verifying fit, and analyzing overlapping geometries in assemblies.
 ///
 /// ```no_run
+/// // Intersect two cubes using the stdlib functions.
+///
 /// fn cube(center) {
 ///     return startSketchOn('XY')
 ///         |> startProfileAt([center[0] - 10, center[1] - 10], %)
@@ -105,6 +159,28 @@ pub async fn intersect(exec_state: &mut ExecState, args: Args) -> Result<KclValu
 ///
 /// intersectedPart = intersect([part001, part002])
 /// ```
+///
+/// ```no_run
+/// // Intersect two cubes using operators.
+/// // NOTE: This will not work when using codemods through the UI.
+/// // Codemods will generate the stdlib function call instead.
+///
+/// fn cube(center) {
+///     return startSketchOn('XY')
+///         |> startProfileAt([center[0] - 10, center[1] - 10], %)
+///         |> line(endAbsolute = [center[0] + 10, center[1] - 10])
+///         |> line(endAbsolute = [center[0] + 10, center[1] + 10])
+///         |> line(endAbsolute = [center[0] - 10, center[1] + 10])
+///         |> close()
+///         |> extrude(length = 10)
+/// }
+///
+/// part001 = cube([0, 0])
+/// part002 = cube([8, 8])
+///
+/// // This is the equivalent of: intersect([part001, part002])
+/// intersectedPart = part001 & part002
+/// ```
 #[stdlib {
     name = "intersect",
     feature_tree_operation = true,
@@ -115,7 +191,11 @@ pub async fn intersect(exec_state: &mut ExecState, args: Args) -> Result<KclValu
         solids = {docs = "The solids to intersect."},
     }
 }]
-async fn inner_intersect(solids: Vec<Solid>, exec_state: &mut ExecState, args: Args) -> Result<Vec<Solid>, KclError> {
+pub(crate) async fn inner_intersect(
+    solids: Vec<Solid>,
+    exec_state: &mut ExecState,
+    args: Args,
+) -> Result<Vec<Solid>, KclError> {
     // Flush the fillets for the solids.
     args.flush_batch_for_solids(exec_state, &solids).await?;
 
@@ -145,6 +225,8 @@ pub async fn subtract(exec_state: &mut ExecState, args: Args) -> Result<KclValue
 /// and complex multi-body part modeling.
 ///
 /// ```no_run
+/// // Subtract a cylinder from a cube using the stdlib functions.
+///
 /// fn cube(center) {
 ///     return startSketchOn('XY')
 ///         |> startProfileAt([center[0] - 10, center[1] - 10], %)
@@ -162,6 +244,30 @@ pub async fn subtract(exec_state: &mut ExecState, args: Args) -> Result<KclValue
 ///
 /// subtractedPart = subtract([part001], tools=[part002])
 /// ```
+///
+/// ```no_run
+/// // Subtract a cylinder from a cube using operators.
+/// // NOTE: This will not work when using codemods through the UI.
+/// // Codemods will generate the stdlib function call instead.
+///
+/// fn cube(center) {
+///     return startSketchOn('XY')
+///         |> startProfileAt([center[0] - 10, center[1] - 10], %)
+///         |> line(endAbsolute = [center[0] + 10, center[1] - 10])
+///         |> line(endAbsolute = [center[0] + 10, center[1] + 10])
+///         |> line(endAbsolute = [center[0] - 10, center[1] + 10])
+///         |> close()
+///         |> extrude(length = 10)
+/// }
+///
+/// part001 = cube([0, 0])
+/// part002 = startSketchOn('XY')
+///     |> circle(center = [0, 0], radius = 2)
+///     |> extrude(length = 10)
+///
+/// // This is the equivalent of: subtract([part001], tools=[part002])
+/// subtractedPart = part001 - part002
+/// ```
 #[stdlib {
     name = "subtract",
     feature_tree_operation = true,
@@ -169,11 +275,11 @@ pub async fn subtract(exec_state: &mut ExecState, args: Args) -> Result<KclValue
     unlabeled_first = true,
     deprecated = true,
     args = {
-        solids = {docs = "The solids to intersect."},
+        solids = {docs = "The solids to use as the base to subtract from."},
         tools = {docs = "The solids to subtract."},
     }
 }]
-async fn inner_subtract(
+pub(crate) async fn inner_subtract(
     solids: Vec<Solid>,
     tools: Vec<Solid>,
     exec_state: &mut ExecState,