Skip to content

Commit c1c5323

Browse files
authored
KCL: New KCL type formatter and parser (#8774)
The "clean up type string" logic [here](https://github.com/KittyCAD/modeling-app/blob/achalmers/array-of-unions/rust/kcl-lib/src/docs/gen_std_tests.rs#L517) is a bit complicated, and it doesn't support arrays of unions. IMO it's difficult to do both formatting and parsing of KCL types in the same function. A better approach would be to recursively parse the type into a tree structure (where arrays have a subtype, and unions have multiple subtypes), then format that tree. This PR: - Adds unit tests for the cleanup_type_string function, in the first commit. - Adds a new proper recursive parser for KCL type strings (parses them into a tree) - Changes the KCL type formatter `cleanup_type_string` to use this parsed tree, rather than adhoc string processing. This includes changes to the unit tests added in the first commit. - Updates all the docs This has some very slight changes to the resulting Markdown, which should be easy to see. They're basically change how arrays are nested in their markdown links. As a side-effect this should nicely render arrays of unions in types, such as the ones Serena's adding in her [PR](#8661). Old: the Markdown link contains a `[string]` in its text New: the Markdown link is just around `string`, and the surrounding array braces are outside the link.
1 parent 7dd859b commit c1c5323

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

48 files changed

+387
-134
lines changed

docs/kcl-std/functions/std-appearance-hexString.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ appearance::hexString(@rgb: [number(_); 3]): string
1717

1818
| Name | Type | Description | Required |
1919
|----------|------|-------------|----------|
20-
| `rgb` | [`[number(_); 3]`](/docs/kcl-std/types/std-types-number) | The red, blue and green components of the color. Must be between 0 and 255. | Yes |
20+
| `rgb` | [[`number(_)`](/docs/kcl-std/types/std-types-number); 3] | The red, blue and green components of the color. Must be between 0 and 255. | Yes |
2121

2222
### Returns
2323

docs/kcl-std/functions/std-array-concat.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -20,12 +20,12 @@ Returns a new array with the all the elements of the first array followed by all
2020

2121
| Name | Type | Description | Required |
2222
|----------|------|-------------|----------|
23-
| `array` | [`[any]`](/docs/kcl-std/types/std-types-any) | The array of starting elements. | Yes |
24-
| `items` | [`[any]`](/docs/kcl-std/types/std-types-any) | The array of ending elements. | Yes |
23+
| `array` | [[`any`](/docs/kcl-std/types/std-types-any)] | The array of starting elements. | Yes |
24+
| `items` | [[`any`](/docs/kcl-std/types/std-types-any)] | The array of ending elements. | Yes |
2525

2626
### Returns
2727

28-
[`[any]`](/docs/kcl-std/types/std-types-any)
28+
[[`any`](/docs/kcl-std/types/std-types-any)]
2929

3030

3131
### Examples

docs/kcl-std/functions/std-array-count.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ count(@array: [any]): number
1717

1818
| Name | Type | Description | Required |
1919
|----------|------|-------------|----------|
20-
| `array` | [`[any]`](/docs/kcl-std/types/std-types-any) | The array whose length will be returned. | Yes |
20+
| `array` | [[`any`](/docs/kcl-std/types/std-types-any)] | The array whose length will be returned. | Yes |
2121

2222
### Returns
2323

docs/kcl-std/functions/std-array-map.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,12 +21,12 @@ Given a list like `[a, b, c]`, and a function like `f`, returns
2121

2222
| Name | Type | Description | Required |
2323
|----------|------|-------------|----------|
24-
| `array` | [`[any]`](/docs/kcl-std/types/std-types-any) | Input array. The output array is this input array, but every element has had the function `f` run on it. | Yes |
24+
| `array` | [[`any`](/docs/kcl-std/types/std-types-any)] | Input array. The output array is this input array, but every element has had the function `f` run on it. | Yes |
2525
| `f` | [`fn(any): any`](/docs/kcl-std/types/std-types-fn) | A function. The output array is just the input array, but `f` has been run on every item. | Yes |
2626

2727
### Returns
2828

29-
[`[any]`](/docs/kcl-std/types/std-types-any)
29+
[[`any`](/docs/kcl-std/types/std-types-any)]
3030

3131

3232
### Examples

docs/kcl-std/functions/std-array-pop.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,11 +17,11 @@ Returns a new array with the last element removed.
1717

1818
| Name | Type | Description | Required |
1919
|----------|------|-------------|----------|
20-
| `array` | [`[any; 1+]`](/docs/kcl-std/types/std-types-any) | The array to pop from. Must not be empty. | Yes |
20+
| `array` | [[`any`](/docs/kcl-std/types/std-types-any); 1+] | The array to pop from. Must not be empty. | Yes |
2121

2222
### Returns
2323

24-
[`[any]`](/docs/kcl-std/types/std-types-any)
24+
[[`any`](/docs/kcl-std/types/std-types-any)]
2525

2626

2727
### Examples

docs/kcl-std/functions/std-array-push.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,12 +20,12 @@ Returns a new array with the element appended.
2020

2121
| Name | Type | Description | Required |
2222
|----------|------|-------------|----------|
23-
| `array` | [`[any]`](/docs/kcl-std/types/std-types-any) | The array which you're adding a new item to. | Yes |
23+
| `array` | [[`any`](/docs/kcl-std/types/std-types-any)] | The array which you're adding a new item to. | Yes |
2424
| `item` | [`any`](/docs/kcl-std/types/std-types-any) | The new item to add to the array | Yes |
2525

2626
### Returns
2727

28-
[`[any; 1+]`](/docs/kcl-std/types/std-types-any)
28+
[[`any`](/docs/kcl-std/types/std-types-any); 1+]
2929

3030

3131
### Examples

docs/kcl-std/functions/std-array-reduce.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ reduce(
2121

2222
| Name | Type | Description | Required |
2323
|----------|------|-------------|----------|
24-
| `array` | [`[any]`](/docs/kcl-std/types/std-types-any) | 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. | Yes |
24+
| `array` | [[`any`](/docs/kcl-std/types/std-types-any)] | 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. | Yes |
2525
| `initial` | [`any`](/docs/kcl-std/types/std-types-any) | The first time `f` is run, it will be called with the first item of `array` and this initial starting value. | Yes |
2626
| `f` | [`fn(any, accum: any): any`](/docs/kcl-std/types/std-types-fn) | 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`. | Yes |
2727

docs/kcl-std/functions/std-gdt-flatness.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ gdt::flatness(
2727

2828
| Name | Type | Description | Required |
2929
|----------|------|-------------|----------|
30-
| `faces` | [`[TaggedFace; 1+]`](/docs/kcl-std/types/std-types-TaggedFace) | The faces to be annotated. | Yes |
30+
| `faces` | [[`TaggedFace`](/docs/kcl-std/types/std-types-TaggedFace); 1+] | The faces to be annotated. | Yes |
3131
| `tolerance` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | The amount of deviation from a perfect plane that is acceptable. | Yes |
3232
| `precision` | [`number(_)`](/docs/kcl-std/types/std-types-number) | The number of decimal places to display. The default is `3`. Must be greater than or equal to `0` and less than or equal to `9`. | No |
3333
| `framePosition` | [`Point2d`](/docs/kcl-std/types/std-types-Point2d) | The position of the feature control frame relative to the leader arrow. The default is `[100mm, 100mm]`. | No |
@@ -37,7 +37,7 @@ gdt::flatness(
3737

3838
### Returns
3939

40-
[`[GdtAnnotation; 1+]`](/docs/kcl-std/types/std-types-GdtAnnotation)
40+
[[`GdtAnnotation`](/docs/kcl-std/types/std-types-GdtAnnotation); 1+]
4141

4242

4343
### Examples

docs/kcl-std/functions/std-hole-hole.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ hole::hole(
3131
| `holeBottom` | | Define bottom feature of the hole. E.g. drilled or flat. | Yes |
3232
| `holeBody` | | Define the main length of the hole. E.g. a blind distance. | Yes |
3333
| `holeType` | | Define the top feature of the hole. E.g. countersink, counterbore, simple. | Yes |
34-
| `cutAt` | [`[number(Length); 2]`](/docs/kcl-std/types/std-types-number) | Where to place the cut on the given face of the solid. Given as absolute coordinates in the global scene. | Yes |
34+
| `cutAt` | [[`number(Length)`](/docs/kcl-std/types/std-types-number); 2] | Where to place the cut on the given face of the solid. Given as absolute coordinates in the global scene. | Yes |
3535

3636

3737
### Examples

docs/kcl-std/functions/std-hole-holes.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ hole::holes(
3131
| `holeBottom` | | Define bottom feature of the hole. E.g. drilled or flat. | Yes |
3232
| `holeBody` | | Define the main length of the hole. E.g. a blind distance. | Yes |
3333
| `holeType` | | Define the top feature of the hole. E.g. countersink, counterbore, simple. | Yes |
34-
| `cutsAt` | `[[number(Length); 2]]` | Where to place the holes, given as absolute coordinates in the global scene. | Yes |
34+
| `cutsAt` | [[[`number(Length)`](/docs/kcl-std/types/std-types-number); 2]] | Where to place the holes, given as absolute coordinates in the global scene. | Yes |
3535

3636

3737

0 commit comments

Comments
 (0)