Add documentation for block children property

nicklockwood · nicklockwood · commit 1f4b45be3bb5 · 2025-10-12T17:54:06.000+01:00
diff --git a/docs/images/sliced-shape.png b/docs/images/sliced-shape.png
diff --git a/docs/images/stacked-shapes.png b/docs/images/stacked-shapes.png
diff --git a/docs/ios/blocks.md b/docs/ios/blocks.md
@@ -29,7 +29,7 @@ star
 
 ![Star](../images/star.png)
 
-**Note:** there is a subtle distinction between the code above and the code below:
+**Note:** There is a subtle distinction between the code above and the code below:
 
 ```swift
 define star path {
@@ -80,5 +80,41 @@ star {
 
 ![Star](../images/six-pointed-star.png)
 
+## Children
+
+ShapeScript's [builder](builders.md) and [csg](csg.md) block commands accept child shapes which they use as inputs to construct a mesh:
+
+```swift
+difference {
+   cube { size 1 }
+   sphere { size 1.1 }
+}
+```
+
+You can do the same with your own custom blocks by using the `children` property. This property is available inside a block definition, and returns a [tuple](literals.md#vectors-and-tuples) of whatever child objects were passed in by the caller.
+
+Here is a simple block that takes whatever child objects are passed in and stacks them vertically along the Y-axis:
+
+```swift
+// define reusable stack command
+define stack {
+    for mesh in children {
+        mesh
+        translate 0 mesh.bounds.size.height
+    }
+}
+
+// stack some shapes
+stack {
+    cube { color red }
+    sphere { color green }
+    cone { color blue }
+}
+```
+
+![Stacked shapes](../images/stacked-shapes.png)
+
+**Note:** The children passed to a block can be any type, not just paths or meshes. ShapeScript uses [type inference](https://en.wikipedia.org/wiki/Type_inference) to raise an error if the caller passes children of a different type than the block expects.
+
 ---
 [Index](index.md) | Next: [Scope](scope.md)
diff --git a/docs/ios/functions.md b/docs/ios/functions.md
@@ -297,7 +297,45 @@ define almostEqual(a b) {
 }
 ```
 
-Unlike [block options](blocks.md#options), function inputs do not have default values. Calling a function without passing a value for every input will result in an error.
+**Note:** Unlike [block options](blocks.md#options), function parameters do not have default values. Calling a function without passing a value for every parameter will result in an error.
+
+ShapeScript uses [type inference](https://en.wikipedia.org/wiki/Type_inference) to raise an error if the caller passes values of a different type than the function expects.
+
+Function parameters can be any type, including paths and meshes. Here is a function that splits a shape into horizontal slices:
+
+```swift
+// function to split a mesh into slices
+define split(shape slices) {
+    define axis 0 1 0 // y-axis
+    define offset shape.bounds.center
+    define shapeSize shape.bounds.size
+    define step shapeSize / slices
+    for i in 1 to slices {
+        difference {
+            shape
+            cube {
+                size shapeSize
+                position offset + axis * i * step
+            }
+            cube {
+                size shapeSize
+                position offset + axis * ((i - 1) * step - shapeSize)
+            }
+        }
+    }
+}
+
+// split a sphere into 5 slices
+define result split(sphere 5)
+
+// display the result
+for slice in result {
+    slice
+    translate 0.2
+}
+```
+
+![Sliced shape](../images/sliced-shape.png)
 
 ---
 [Index](index.md) | Next: [Commands](commands.md)
diff --git a/docs/ios/index.md b/docs/ios/index.md
@@ -147,6 +147,7 @@ ShapeScript Help
         - [Conditional Defines](control-flow.md#conditional-defines)
     - [Blocks](blocks.md)
         - [Options](blocks.md#options)
+        - [Children](blocks.md#children)
     - [Scope](scope.md)
         - [Block Scope](scope.md#block-scope)
         - [Function Scope](scope.md#function-scope)
diff --git a/docs/mac/blocks.md b/docs/mac/blocks.md
@@ -29,7 +29,7 @@ star
 
 ![Star](../images/star.png)
 
-**Note:** there is a subtle distinction between the code above and the code below:
+**Note:** There is a subtle distinction between the code above and the code below:
 
 ```swift
 define star path {
@@ -80,5 +80,41 @@ star {
 
 ![Star](../images/six-pointed-star.png)
 
+## Children
+
+ShapeScript's [builder](builders.md) and [csg](csg.md) block commands accept child shapes which they use as inputs to construct a mesh:
+
+```swift
+difference {
+   cube { size 1 }
+   sphere { size 1.1 }
+}
+```
+
+You can do the same with your own custom blocks by using the `children` property. This property is available inside a block definition, and returns a [tuple](literals.md#vectors-and-tuples) of whatever child objects were passed in by the caller.
+
+Here is a simple block that takes whatever child objects are passed in and stacks them vertically along the Y-axis:
+
+```swift
+// define reusable stack command
+define stack {
+    for mesh in children {
+        mesh
+        translate 0 mesh.bounds.size.height
+    }
+}
+
+// stack some shapes
+stack {
+    cube { color red }
+    sphere { color green }
+    cone { color blue }
+}
+```
+
+![Stacked shapes](../images/stacked-shapes.png)
+
+**Note:** The children passed to a block can be any type, not just paths or meshes. ShapeScript uses [type inference](https://en.wikipedia.org/wiki/Type_inference) to raise an error if the caller passes children of a different type than the block expects.
+
 ---
 [Index](index.md) | Next: [Scope](scope.md)
diff --git a/docs/mac/functions.md b/docs/mac/functions.md
@@ -297,7 +297,45 @@ define almostEqual(a b) {
 }
 ```
 
-Unlike [block options](blocks.md#options), function inputs do not have default values. Calling a function without passing a value for every input will result in an error.
+**Note:** Unlike [block options](blocks.md#options), function parameters do not have default values. Calling a function without passing a value for every parameter will result in an error.
+
+ShapeScript uses [type inference](https://en.wikipedia.org/wiki/Type_inference) to raise an error if the caller passes values of a different type than the function expects.
+
+Function parameters can be any type, including paths and meshes. Here is a function that splits a shape into horizontal slices:
+
+```swift
+// function to split a mesh into slices
+define split(shape slices) {
+    define axis 0 1 0 // y-axis
+    define offset shape.bounds.center
+    define shapeSize shape.bounds.size
+    define step shapeSize / slices
+    for i in 1 to slices {
+        difference {
+            shape
+            cube {
+                size shapeSize
+                position offset + axis * i * step
+            }
+            cube {
+                size shapeSize
+                position offset + axis * ((i - 1) * step - shapeSize)
+            }
+        }
+    }
+}
+
+// split a sphere into 5 slices
+define result split(sphere 5)
+
+// display the result
+for slice in result {
+    slice
+    translate 0.2
+}
+```
+
+![Sliced shape](../images/sliced-shape.png)
 
 ---
 [Index](index.md) | Next: [Commands](commands.md)
diff --git a/docs/mac/index.md b/docs/mac/index.md
@@ -147,6 +147,7 @@ ShapeScript Help
         - [Conditional Defines](control-flow.md#conditional-defines)
     - [Blocks](blocks.md)
         - [Options](blocks.md#options)
+        - [Children](blocks.md#children)
     - [Scope](scope.md)
         - [Block Scope](scope.md#block-scope)
         - [Function Scope](scope.md#function-scope)
diff --git a/docs/src/blocks.md b/docs/src/blocks.md
@@ -29,7 +29,7 @@ star
 
 ![Star](../images/star.png)
 
-**Note:** there is a subtle distinction between the code above and the code below:
+**Note:** There is a subtle distinction between the code above and the code below:
 
 ```swift
 define star path {
@@ -80,5 +80,41 @@ star {
 
 ![Star](../images/six-pointed-star.png)
 
+## Children
+
+ShapeScript's [builder](builders.md) and [csg](csg.md) block commands accept child shapes which they use as inputs to construct a mesh:
+
+```swift
+difference {
+   cube { size 1 }
+   sphere { size 1.1 }
+}
+```
+
+You can do the same with your own custom blocks by using the `children` property. This property is available inside a block definition, and returns a [tuple](literals.md#vectors-and-tuples) of whatever child objects were passed in by the caller.
+
+Here is a simple block that takes whatever child objects are passed in and stacks them vertically along the Y-axis:
+
+```swift
+// define reusable stack command
+define stack {
+    for mesh in children {
+        mesh
+        translate 0 mesh.bounds.size.height
+    }
+}
+
+// stack some shapes
+stack {
+    cube { color red }
+    sphere { color green }
+    cone { color blue }
+}
+```
+
+![Stacked shapes](../images/stacked-shapes.png)
+
+**Note:** The children passed to a block can be any type, not just paths or meshes. ShapeScript uses [type inference](https://en.wikipedia.org/wiki/Type_inference) to raise an error if the caller passes children of a different type than the block expects.
+
 ---
 [Index](index.md) | Next: [Scope](scope.md)
diff --git a/docs/src/functions.md b/docs/src/functions.md
@@ -297,7 +297,45 @@ define almostEqual(a b) {
 }
 ```
 
-Unlike [block options](blocks.md#options), function inputs do not have default values. Calling a function without passing a value for every input will result in an error.
+**Note:** Unlike [block options](blocks.md#options), function parameters do not have default values. Calling a function without passing a value for every parameter will result in an error.
+
+ShapeScript uses [type inference](https://en.wikipedia.org/wiki/Type_inference) to raise an error if the caller passes values of a different type than the function expects.
+
+Function parameters can be any type, including paths and meshes. Here is a function that splits a shape into horizontal slices:
+
+```swift
+// function to split a mesh into slices
+define split(shape slices) {
+    define axis 0 1 0 // y-axis
+    define offset shape.bounds.center
+    define shapeSize shape.bounds.size
+    define step shapeSize / slices
+    for i in 1 to slices {
+        difference {
+            shape
+            cube {
+                size shapeSize
+                position offset + axis * i * step
+            }
+            cube {
+                size shapeSize
+                position offset + axis * ((i - 1) * step - shapeSize)
+            }
+        }
+    }
+}
+
+// split a sphere into 5 slices
+define result split(sphere 5)
+
+// display the result
+for slice in result {
+    slice
+    translate 0.2
+}
+```
+
+![Sliced shape](../images/sliced-shape.png)
 
 ---
 [Index](index.md) | Next: [Commands](commands.md)
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -147,6 +147,7 @@ ShapeScript Help
         - [Conditional Defines](control-flow.md#conditional-defines)
     - [Blocks](blocks.md)
         - [Options](blocks.md#options)
+        - [Children](blocks.md#children)
     - [Scope](scope.md)
         - [Block Scope](scope.md#block-scope)
         - [Function Scope](scope.md#function-scope)
