Update KCL docs

content/pages/docs/kcl-lang/arithmetic.md

@@ -18,7 +18,9 @@ KCL supports the usual arithmetic operators on numbers and logic operators on bo
 | `\|` | Logical 'or' |
 | `!` | Unary logical 'not' |
 
-KCL also supports comparsion operators which operate on numbers and produce booleans:
+KCL also supports comparison operators which produce booleans. Ordering
+comparisons operate on numbers, while `==` and `!=` operate on numbers or
+strings:
 
 | Operator | Meaning |
 |----------|---------|
@@ -29,6 +31,9 @@ KCL also supports comparsion operators which operate on numbers and produce bool
 | `<=` | Less than or equal |
 | `>=` | Greater than or equal |
 
+String equality is exact and case-sensitive. It does not perform Unicode
+normalization.
+
 Arithmetics and logic expressions can be arbitrairly combined with the usual rules of associativity and precedence, e.g.,
 
 ```

content/pages/docs/kcl-std/functions/std-fail.md

@@ -0,0 +1,45 @@
+---
+title: "fail"
+subtitle: "Function in std"
+excerpt: "Stop KCL evaluation with a user-defined error."
+layout: manual
+---
+
+**WARNING:** This function is experimental and may change or be removed.
+
+Stop KCL evaluation with a user-defined error.
+
+```kcl
+fail(@msg: string): never
+```
+
+Use `fail` when evaluation cannot continue and the caller should receive a
+specific error message. `fail` never returns a value.
+
+### Arguments
+
+| Name | Type | Description | Required |
+|----------|------|-------------|----------|
+| `msg` | [`string`](/docs/kcl-std/types/std-types-string) | Message reported to the caller. | Yes |
+
+### Returns
+
+[`never`](/docs/kcl-std/types/std-types-never) - The uninhabited type of computations that never complete normally.
+
+
+### Examples
+
+```kcl
+fn positive(@value: number): number {
+  return if value > 0 {
+    value
+  } else {
+    fail("value must be positive")
+  }
+}
+
+```
+
+
+
+

content/pages/docs/kcl-std/functions/std-runtime-exit.md

@@ -13,7 +13,16 @@ Exit the program early.
 exit()
 ```
 
+Exiting early can be helpful to see the intermediate output of a program to
+help debug. Remember to always remove the call to `exit()` after debugging
+is complete.
 
+When `exit()` is used in an imported module, only the imported module exits
+early. Because imported modules execute concurrently, `exit()` in one module
+does not affect other modules.
+
+On the other hand, if you import a function from another module, and that
+function calls `exit()`, then calling the function exits the caller.
 
 
 

content/pages/docs/kcl-std/functions/std-sketch-extrude.md

@@ -9,11 +9,11 @@ Extend a 2-dimensional sketch or individual segment of a sketch through a third
 
 ```kcl
 extrude(
-  @sketches: [Sketch | Face | TaggedFace | TaggedEdge | Edge | Segment; 1+],
+  @sketches: [Sketch | Face | TaggedFace | TaggedEdge | Edge | Segment | any; 1+],
   length?: number(Length),
   to?: Point3d | Axis3d | Plane | Edge | Face | Sketch | Solid | TaggedEdge | TaggedFace | any,
   symmetric?: bool,
-  direction?: Point3d | Edge | TaggedEdge | Segment,
+  direction?: Point3d | Edge | TaggedEdge | Segment | any,
   bidirectionalLength?: number(Length),
   tagStart?: TagDecl,
   tagEnd?: TagDecl,
@@ -39,11 +39,11 @@ can change this behavior by using the `method` parameter. See
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| `sketches` | [[`Sketch`](/docs/kcl-std/types/std-types-Sketch) or [`Face`](/docs/kcl-std/types/std-types-Face) or [`TaggedFace`](/docs/kcl-std/types/std-types-TaggedFace) or [`TaggedEdge`](/docs/kcl-std/types/std-types-TaggedEdge) or [`Edge`](/docs/kcl-std/types/std-types-Edge) or [`Segment`](/docs/kcl-std/types/std-types-Segment); 1+] | Which sketch or sketches should be extruded. | Yes |
+| `sketches` | [[`Sketch`](/docs/kcl-std/types/std-types-Sketch) or [`Face`](/docs/kcl-std/types/std-types-Face) or [`TaggedFace`](/docs/kcl-std/types/std-types-TaggedFace) or [`TaggedEdge`](/docs/kcl-std/types/std-types-TaggedEdge) or [`Edge`](/docs/kcl-std/types/std-types-Edge) or [`Segment`](/docs/kcl-std/types/std-types-Segment) or [`any`](/docs/kcl-std/types/std-types-any); 1+] | Which sketch or sketches should be extruded. Experimental face API: edge specifier objects (`{ sideFaces = [faceTag1, faceTag2], endFaces? = [...], index? }`) are not ready for generated or user-facing KCL yet; prefer existing sketch, face, tagged face, tagged edge, edge, or segment forms until point-and-click and migration support ships. | Yes |
 | `length` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | How far to extrude the given sketches. Incompatible with `to`. | No |
 | `to` | [`Point3d`](/docs/kcl-std/types/std-types-Point3d) or [`Axis3d`](/docs/kcl-std/types/std-types-Axis3d) or [`Plane`](/docs/kcl-std/types/std-types-Plane) or [`Edge`](/docs/kcl-std/types/std-types-Edge) or [`Face`](/docs/kcl-std/types/std-types-Face) or [`Sketch`](/docs/kcl-std/types/std-types-Sketch) or [`Solid`](/docs/kcl-std/types/std-types-Solid) or [`TaggedEdge`](/docs/kcl-std/types/std-types-TaggedEdge) or [`TaggedFace`](/docs/kcl-std/types/std-types-TaggedFace) or [`any`](/docs/kcl-std/types/std-types-any) | Reference to extrude to. Incompatible with `length` and `twistAngle`. Experimental face API: edge specifier objects (`{ sideFaces = [faceTag1, faceTag2], endFaces? = [...], index? }`) are not ready for generated or user-facing KCL yet; prefer existing point, axis, plane, edge, face, sketch, solid, or tag forms until point-and-click and migration support ships. | No |
 | `symmetric` | [`bool`](/docs/kcl-std/types/std-types-bool) | If true, the extrusion will happen symmetrically around the sketch. Otherwise, the extrusion will happen on only one side of the sketch. | No |
-| `direction` | [`Point3d`](/docs/kcl-std/types/std-types-Point3d) or [`Edge`](/docs/kcl-std/types/std-types-Edge) or [`TaggedEdge`](/docs/kcl-std/types/std-types-TaggedEdge) or [`Segment`](/docs/kcl-std/types/std-types-Segment) | **Experimental.** If specified, will extrude in this direction instead of the sketch plane normal. If an edge is being extruded, this defaults to halfway between the faces on either side of the edge. | No |
+| `direction` | [`Point3d`](/docs/kcl-std/types/std-types-Point3d) or [`Edge`](/docs/kcl-std/types/std-types-Edge) or [`TaggedEdge`](/docs/kcl-std/types/std-types-TaggedEdge) or [`Segment`](/docs/kcl-std/types/std-types-Segment) or [`any`](/docs/kcl-std/types/std-types-any) | If specified, will extrude in this direction instead of the sketch plane normal. If an edge is being extruded, this defaults to halfway between the faces on either side of the edge. | No |
 | `bidirectionalLength` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | If specified, will also extrude in the opposite direction to 'distance' to the specified distance. If 'symmetric' is true, this value is ignored. | No |
 | `tagStart` | [`TagDecl`](/docs/kcl-std/types/std-types-TagDecl) | A named tag for the face at the start of the extrusion, i.e. the original sketch. | No |
 | `tagEnd` | [`TagDecl`](/docs/kcl-std/types/std-types-TagDecl) | A named tag for the face at the end of the extrusion, i.e. the new face created by extruding the original sketch. | No |
@@ -646,7 +646,7 @@ extrude(
 </model-viewer>
 
 ```kcl
-@settings(kclVersion = 2.0, experimentalFeatures = allow)
+@settings(kclVersion = 2.0)
 
 // The direction parameter can apply to sketches, segments, or edges
 // Directions can be specified by an axis, a sketch segment, or a body's edge.

content/pages/docs/kcl-std/functions/std-string-isEqual.md

@@ -0,0 +1,58 @@
+---
+title: "string::isEqual"
+subtitle: "Function in std::string"
+excerpt: "Compare two strings for equality."
+layout: manual
+---
+
+Compare two strings for equality.
+
+```kcl
+string::isEqual(
+  @text: string,
+  to: string,
+  caseInsensitive?: bool,
+): bool
+```
+
+By default, this performs an exact, case-sensitive comparison equivalent
+to the `==` operator. Set `caseInsensitive` to `true` to compare using
+locale-independent full Unicode case folding.
+
+Full case folding may expand characters; for example, `Straße` and
+`STRASSE` compare as equal. The exact mappings follow the Unicode data
+bundled with KCL.
+
+Unicode normalization is not performed. Canonically equivalent strings
+with different representations therefore compare as unequal. Empty strings
+are valid inputs, and comparison is symmetric.
+
+This function always returns a Boolean predicate, including inside a sketch
+block. It does not create an equivalence constraint.
+
+### Arguments
+
+| Name | Type | Description | Required |
+|----------|------|-------------|----------|
+| `text` | [`string`](/docs/kcl-std/types/std-types-string) | The string to compare. | Yes |
+| `to` | [`string`](/docs/kcl-std/types/std-types-string) | The string to compare `text` with. | Yes |
+| `caseInsensitive` | [`bool`](/docs/kcl-std/types/std-types-bool) | Whether to compare using locale-independent full Unicode case folding. | No |
+
+### Returns
+
+[`bool`](/docs/kcl-std/types/std-types-bool) - A boolean value.
+
+
+### Examples
+
+```kcl
+matches = "Straße"
+  |> string::isEqual(to = "STRASSE", caseInsensitive = true)
+
+assertIs(matches)
+
+```
+
+
+
+

content/pages/docs/kcl-std/functions/std-string-lowercase.md

@@ -0,0 +1,48 @@
+---
+title: "string::lowercase"
+subtitle: "Function in std::string"
+excerpt: "Convert all cased characters in a string to lowercase."
+layout: manual
+---
+
+Convert all cased characters in a string to lowercase.
+
+```kcl
+string::lowercase(@text: string): string
+```
+
+This conversion is Unicode-aware and locale-independent. Some conversions
+depend on the surrounding characters; for example, a Greek capital sigma
+becomes `ς` at the end of a word and `σ` elsewhere. Some characters expand
+into multiple characters; for example, `İ` becomes `i` followed by a
+combining dot above. The exact mappings follow the Unicode data bundled
+with KCL.
+
+Unicode normalization is not performed. Canonically equivalent strings
+therefore retain their original representations. Empty strings and strings
+without cased characters are returned unchanged.
+
+### Arguments
+
+| Name | Type | Description | Required |
+|----------|------|-------------|----------|
+| `text` | [`string`](/docs/kcl-std/types/std-types-string) | The string to convert. | Yes |
+
+### Returns
+
+[`string`](/docs/kcl-std/types/std-types-string) - A sequence of characters
+
+
+### Examples
+
+```kcl
+result = "KCL ΟΣ"
+  |> string::lowercase()
+
+assertIs(result == "kcl ος")
+
+```
+
+
+
+

content/pages/docs/kcl-std/functions/std-string-trim.md

@@ -0,0 +1,44 @@
+---
+title: "string::trim"
+subtitle: "Function in std::string"
+excerpt: "Remove whitespace from the start and end of a string."
+layout: manual
+---
+
+Remove whitespace from the start and end of a string.
+
+```kcl
+string::trim(@text: string): string
+```
+
+Whitespace is defined by Unicode's `White_Space` property and includes
+spaces, tabs, newlines, and non-breaking spaces. Whitespace inside the
+string is preserved.
+
+If the input is empty or contains only whitespace, this returns an empty
+string. Unicode normalization and case conversion are not performed.
+
+### Arguments
+
+| Name | Type | Description | Required |
+|----------|------|-------------|----------|
+| `text` | [`string`](/docs/kcl-std/types/std-types-string) | The string to trim. | Yes |
+
+### Returns
+
+[`string`](/docs/kcl-std/types/std-types-string) - A sequence of characters
+
+
+### Examples
+
+```kcl
+result = "  KCL strings  "
+  |> string::trim()
+
+assertIs(result == "KCL strings")
+
+```
+
+
+
+

content/pages/docs/kcl-std/functions/std-string-trimEnd.md

@@ -0,0 +1,47 @@
+---
+title: "string::trimEnd"
+subtitle: "Function in std::string"
+excerpt: "Remove whitespace from the end of a string."
+layout: manual
+---
+
+Remove whitespace from the end of a string.
+
+```kcl
+string::trimEnd(@text: string): string
+```
+
+Whitespace is defined by Unicode's `White_Space` property and includes
+spaces, tabs, newlines, and non-breaking spaces. Only the contiguous
+whitespace at the end is removed; whitespace at the start or inside the
+string is preserved.
+
+The end is the end of the string's character sequence, independent of how
+the text is displayed. If the input is empty or contains only whitespace,
+this returns an empty string. Unicode normalization and case conversion are
+not performed.
+
+### Arguments
+
+| Name | Type | Description | Required |
+|----------|------|-------------|----------|
+| `text` | [`string`](/docs/kcl-std/types/std-types-string) | The string to trim. | Yes |
+
+### Returns
+
+[`string`](/docs/kcl-std/types/std-types-string) - A sequence of characters
+
+
+### Examples
+
+```kcl
+result = "  KCL strings  "
+  |> string::trimEnd()
+
+assertIs(result == "  KCL strings")
+
+```
+
+
+
+

content/pages/docs/kcl-std/functions/std-string-trimStart.md

@@ -0,0 +1,47 @@
+---
+title: "string::trimStart"
+subtitle: "Function in std::string"
+excerpt: "Remove whitespace from the start of a string."
+layout: manual
+---
+
+Remove whitespace from the start of a string.
+
+```kcl
+string::trimStart(@text: string): string
+```
+
+Whitespace is defined by Unicode's `White_Space` property and includes
+spaces, tabs, newlines, and non-breaking spaces. Only the contiguous
+whitespace at the start is removed; whitespace inside or at the end of the
+string is preserved.
+
+The start is the beginning of the string's character sequence, independent
+of how the text is displayed. If the input is empty or contains only
+whitespace, this returns an empty string. Unicode normalization and case
+conversion are not performed.
+
+### Arguments
+
+| Name | Type | Description | Required |
+|----------|------|-------------|----------|
+| `text` | [`string`](/docs/kcl-std/types/std-types-string) | The string to trim. | Yes |
+
+### Returns
+
+[`string`](/docs/kcl-std/types/std-types-string) - A sequence of characters
+
+
+### Examples
+
+```kcl
+result = "  KCL strings  "
+  |> string::trimStart()
+
+assertIs(result == "KCL strings  ")
+
+```
+
+
+
+