Tag types (#7458)

* Replace tag type with tagIdent and tagDecl

Signed-off-by: Nick Cameron <nrc@ncameron.org>

* Replace tagIdent with TaggedEdge and TaggedFace

Signed-off-by: Nick Cameron <nrc@ncameron.org>

---------

Signed-off-by: Nick Cameron <nrc@ncameron.org>

rust/kcl-lib/std/prelude.kcl

@@ -64,10 +64,10 @@ export Z = {
 }: Axis3d
 
 /// Identifies the starting face of an extrusion. I.e., the face which is extruded.
-export START = 'start'
+export START = 'start': TaggedFace
 
 /// Identifies the ending face of an extrusion. I.e., the new face created by an extrusion.
-export END = 'end'
+export END = 'end': TaggedFace
 
 /// Create a helix.
 ///

rust/kcl-lib/std/sketch.kcl

@@ -186,7 +186,7 @@ export fn startSketchOn(
   /// Profile whose start is being used.
   @planeOrSolid: Solid | Plane,
   /// Identify a face of a solid if a solid is specified as the input argument (`planeOrSolid`).
-  face?: tag,
+  face?: TaggedFace,
 ): Plane | Face {}
 
 /// Start a new profile at a given point.
@@ -231,7 +231,7 @@ export fn startProfile(
   @(snippetArray = ["0", "0"])
   at: Point2d,
   /// Tag this first starting point.
-  tag?: tag,
+  tag?: TagDecl,
 ): Sketch {}
 
 /// Construct a 2-dimensional circle, of the specified radius, centered at
@@ -268,7 +268,7 @@ export fn circle(
   @(includeInSnippet = true)
   diameter?: number(Length),
   /// Create a new tag which refers to this circle.
-  tag?: tag,
+  tag?: TagDecl,
 ): Sketch {}
 
 /// Extend a 2-dimensional sketch through a third dimension in order to
@@ -375,9 +375,9 @@ export fn extrude(
   /// If specified, will also extrude in the opposite direction to 'distance' to the specified distance. If 'symmetric' is true, this value is ignored.
   bidirectionalLength?: number(Length),
   /// A named tag for the face at the start of the extrusion, i.e. the original sketch.
-  tagStart?: tag,
+  tagStart?: TagDecl,
   /// A named tag for the face at the end of the extrusion, i.e. the new face created by extruding the original sketch.
-  tagEnd?: tag,
+  tagEnd?: TagDecl,
 ): [Solid; 1+] {}
 
 /// Works just like the `extrude` command, but also twists the sketch around
@@ -647,9 +647,9 @@ export fn revolve(
   /// If specified, will also revolve in the opposite direction to 'angle' to the specified angle. If 'symmetric' is true, this value is ignored.
   bidirectionalAngle?: number(Angle),
   /// A named tag for the face at the start of the revolve, i.e. the original sketch.
-  tagStart?: tag,
+  tagStart?: TagDecl,
   /// A named tag for the face at the end of the revolve.
-  tagEnd?: tag,
+  tagEnd?: TagDecl,
 ): [Solid; 1+] {}
 
 /// Just like `patternTransform`, but works on 2D sketches not 3D solids.
@@ -708,7 +708,7 @@ export fn patternTransform2d(
 @(impl = std_rust)
 export fn getOppositeEdge(
   /// The tag of the edge you want to find the opposite edge of.
-  @edge: tag,
+  @edge: TaggedEdge,
 ): Edge {}
 
 /// Get the next adjacent edge to the edge given.
@@ -742,7 +742,7 @@ export fn getOppositeEdge(
 @(impl = std_rust)
 export fn getNextAdjacentEdge(
   /// The tag of the edge you want to find the next adjacent edge of.
-  @edge: tag,
+  @edge: TaggedEdge,
 ): Edge {}
 
 /// Get the previous adjacent edge to the edge given.
@@ -776,7 +776,7 @@ export fn getNextAdjacentEdge(
 @(impl = std_rust)
 export fn getPreviousAdjacentEdge(
   /// The tag of the edge you want to find the previous adjacent edge of.
-  @edge: tag,
+  @edge: TaggedEdge,
 ): Edge {}
 
 /// Get the shared edge between two faces.
@@ -805,7 +805,7 @@ export fn getPreviousAdjacentEdge(
 @(impl = std_rust)
 export fn getCommonEdge(
   /// The tags of the faces you want to find the common edge between.
-  faces: [tag; 2],
+  faces: [TaggedFace; 2],
 ): Edge {}
 
 /// Construct a circle derived from 3 points.
@@ -826,7 +826,7 @@ export fn circleThreePoint(
   /// 3rd point to derive the circle.
   p3: Point2d,
   /// Identifier for the circle to reference elsewhere.
-  tag?: tag,
+  tag?: TagDecl,
 ): Sketch {}
 
 /// Create a regular polygon with the specified number of sides that is either inscribed or circumscribed around a circle of the specified radius.
@@ -984,9 +984,9 @@ export fn sweep(
   /// What is the sweep relative to? Can be either 'sketchPlane' or 'trajectoryCurve'.
   relativeTo?: string = 'trajectoryCurve',
   /// A named tag for the face at the start of the sweep, i.e. the original sketch.
-  tagStart?: tag,
+  tagStart?: TagDecl,
   /// A named tag for the face at the end of the sweep.
-  tagEnd?: tag,
+  tagEnd?: TagDecl,
 ): [Solid; 1+] {}
 
 /// Create a 3D surface or solid by interpolating between two or more sketches.
@@ -1068,9 +1068,9 @@ export fn loft(
   /// Tolerance for the loft operation.
   tolerance?: number(Length),
   /// A named tag for the face at the start of the loft, i.e. the original sketch.
-  tagStart?: tag,
+  tagStart?: TagDecl,
   /// A named tag for the face at the end of the loft.
-  tagEnd?: tag,
+  tagEnd?: TagDecl,
 ): Solid {}
 
 /// Repeat a 2-dimensional sketch along some dimension, with a dynamic amount
@@ -1184,7 +1184,7 @@ export fn patternCircular2d(
 @(impl = std_rust)
 export fn segEnd(
   /// The line segment being queried by its tag.
-  @tag: tag,
+  @tag: TaggedEdge,
 ): Point2d {}
 
 /// Compute the ending point of the provided line segment along the 'x' axis.
@@ -1203,7 +1203,7 @@ export fn segEnd(
 @(impl = std_rust)
 export fn segEndX(
   /// The line segment being queried by its tag.
-  @tag: tag,
+  @tag: TaggedEdge,
 ): number(Length) {}
 
 /// Compute the ending point of the provided line segment along the 'y' axis.
@@ -1223,7 +1223,7 @@ export fn segEndX(
 @(impl = std_rust)
 export fn segEndY(
   /// The line segment being queried by its tag.
-  @tag: tag,
+  @tag: TaggedEdge,
 ): number(Length) {}
 
 /// Compute the starting point of the provided line segment.
@@ -1254,7 +1254,7 @@ export fn segEndY(
 @(impl = std_rust)
 export fn segStart(
   /// The line segment being queried by its tag.
-  @tag: tag,
+  @tag: TaggedEdge,
 ): Point2d {}
 
 /// Compute the starting point of the provided line segment along the 'x' axis.
@@ -1273,7 +1273,7 @@ export fn segStart(
 @(impl = std_rust)
 export fn segStartX(
   /// The line segment being queried by its tag.
-  @tag: tag,
+  @tag: TaggedEdge,
 ): number(Length) {}
 
 /// Compute the starting point of the provided line segment along the 'y' axis.
@@ -1293,7 +1293,7 @@ export fn segStartX(
 @(impl = std_rust)
 export fn segStartY(
   /// The line segment being queried by its tag.
-  @tag: tag,
+  @tag: TaggedEdge,
 ): number(Length) {}
 
 /// Extract the 'x' axis value of the last line segment in the provided 2-d sketch.
@@ -1356,7 +1356,7 @@ export fn lastSegY(
 @(impl = std_rust)
 export fn segLen(
   /// The line segment being queried by its tag.
-  @tag: tag,
+  @tag: TaggedEdge,
 ): number(Length) {}
 
 /// Compute the angle (in degrees) of the provided line segment.
@@ -1377,7 +1377,7 @@ export fn segLen(
 @(impl = std_rust)
 export fn segAng(
   /// The line segment being queried by its tag.
-  @tag: tag,
+  @tag: TaggedEdge,
 ): number(Angle) {}
 
 /// Returns the angle coming out of the end of the segment in degrees.
@@ -1454,7 +1454,7 @@ export fn segAng(
 @(impl = std_rust)
 export fn tangentToEnd(
   /// The line segment being queried by its tag.
-  @tag: tag,
+  @tag: TaggedEdge,
 ): number(Angle) {}
 
 /// Extract the provided 2-dimensional sketch's profile's origin value.
@@ -1526,7 +1526,7 @@ export fn involuteCircular(
   /// If reverse is true, the segment will start from the end of the involute, otherwise it will start from that start.
   reverse?: bool = false,
   /// Create a new tag which refers to this line.
-  tag?: tag,
+  tag?: TagDecl,
 ): Sketch {}
 
 /// Extend the current sketch with a new straight line.
@@ -1563,7 +1563,7 @@ export fn line(
   @(includeInSnippet = true)
   end?: Point2d,
   /// Create a new tag which refers to this line.
-  tag?: tag,
+  tag?: TagDecl,
 ): Sketch {}
 
 /// Draw a line relative to the current origin to a specified distance away
@@ -1598,7 +1598,7 @@ export fn xLine(
   /// Which absolute X value should this line go to? Incompatible with `length`.
   endAbsolute?: number(Length),
   /// Create a new tag which refers to this line.
-  tag?: tag,
+  tag?: TagDecl,
 ): Sketch {}
 
 /// Draw a line relative to the current origin to a specified distance away
@@ -1628,7 +1628,7 @@ export fn yLine(
   /// Which absolute Y value should this line go to? Incompatible with `length`.
   endAbsolute?: number(Length),
   /// Create a new tag which refers to this line.
-  tag?: tag,
+  tag?: TagDecl,
 ): Sketch {}
 
 /// Draw a line segment relative to the current origin using the polar
@@ -1665,7 +1665,7 @@ export fn angledLine(
   /// 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.
   endAbsoluteY?: number(Length),
   /// Create a new tag which refers to this line.
-  tag?: tag,
+  tag?: TagDecl,
 ): Sketch {}
 
 /// Draw an angled line from the current origin, constructing a line segment
@@ -1694,11 +1694,11 @@ export fn angledLineThatIntersects(
   /// Which angle should the line be drawn at?
   angle: number(Angle),
   /// The tag of the line to intersect with.
-  intersectTag: tag,
+  intersectTag: TaggedEdge,
   /// The offset from the intersecting line.
   offset?: number(Length) = 0mm,
   /// Create a new tag which refers to this line.
-  tag?: tag,
+  tag?: TagDecl,
 ): Sketch {}
 
 /// Construct a line segment from the current origin back to the profile's
@@ -1732,7 +1732,7 @@ export fn close(
   /// The sketch you want to close.
   @sketch: Sketch,
   /// Create a new tag which refers to this line.
-  tag?: tag,
+  tag?: TagDecl,
 ): Sketch {}
 
 /// Draw a curved line segment along an imaginary circle.
@@ -1789,7 +1789,7 @@ export fn arc(
   /// Where should this arc end? Requires `interiorAbsolute`. Incompatible with `angleStart` or `angleEnd`.
   endAbsolute?: Point2d,
   /// Create a new tag which refers to this arc.
-  tag?: tag,
+  tag?: TagDecl,
 ): Sketch {}
 
 /// Starting at the current sketch's origin, draw a curved line segment along
@@ -1862,7 +1862,7 @@ export fn tangentialArc(
   /// Offset of the arc. `radius` must be given. Incompatible with `end` and `endAbsolute`.
   angle?: number(Angle),
   /// Create a new tag which refers to this arc.
-  tag?: tag,
+  tag?: TagDecl,
 ): Sketch {}
 
 /// Draw a smooth, continuous, curved line segment from the current origin to
@@ -1910,7 +1910,7 @@ export fn bezierCurve(
   /// Coordinate on the plane at which this line should end.
   endAbsolute?: Point2d,
   /// Create a new tag which refers to this line.
-  tag?: tag,
+  tag?: TagDecl,
 ): Sketch {}
 
 /// Use a 2-dimensional sketch to cut a hole in another 2-dimensional sketch.

rust/kcl-lib/std/solid.kcl

@@ -73,7 +73,7 @@ export fn fillet(
   /// The tolerance for this fillet
   tolerance?: number(Length),
   /// Create a new tag which refers to this fillet
-  tag?: tag,
+  tag?: TagDecl,
 ): Solid {}
 
 /// Cut a straight transitional edge along a tagged path.
@@ -148,7 +148,7 @@ export fn chamfer(
   /// The paths you want to chamfer
   tags: [Edge; 1+],
   /// Create a new tag which refers to this chamfer
-  tag?: tag,
+  tag?: TagDecl,
 ): Solid {}
 
 /// Remove volume from a 3-dimensional shape such that a wall of the
@@ -304,7 +304,7 @@ export fn shell(
   /// The thickness of the shell
   thickness: number(Length),
   /// The faces you want removed
-  faces: [tag; 1+],
+  faces: [TaggedFace; 1+],
 ): [Solid] {}
 
 

rust/kcl-lib/std/types.kcl

@@ -65,7 +65,7 @@ export type string
 ///
 /// ### Tag Declaration
 ///
-/// The syntax for declaring a tag is `$myTag` you would use it in the following
+/// The syntax for declaring a tag is `$myTag`. You would use it in the following
 /// way:
 ///
 /// ```norun,inline
@@ -86,14 +86,6 @@ export type string
 ///   |> close()
 /// ```
 ///
-/// ### Tag Identifier
-///
-/// As per the example above you can use the tag identifier to get a reference to the 
-/// tagged object. The syntax for this is `myTag`.
-/// 
-/// In the example above we use the tag identifier to get the angle of the segment
-/// `segAng(rectangleSegmentA001)`.
-///
 /// ### Tag Scope
 ///
 /// Tags are scoped globally if in the root context meaning in this example you can 
@@ -109,7 +101,8 @@ export type string
 ///     |> angledLine(
 ///          angle = segAng(rectangleSegmentA001) - 90,
 ///          length = 196.99,
-///          tag = $rectangleSegmentB001)
+///          tag = $rectangleSegmentB001
+///        )
 ///     |> angledLine(
 ///          angle = segAng(rectangleSegmentA001),
 ///          length = -segLen(rectangleSegmentA001),
@@ -137,12 +130,12 @@ export type string
 ///     |> angledLine(angle = 0, length = 191.26, tag = $rectangleSegmentA001)
 ///     |> angledLine(
 ///          angle = segAng(rectangleSegmentA001) - 90deg,
-///          length = 196.99
+///          length = 196.99,
 ///          tag = $rectangleSegmentB001,
 ///        )
 ///     |> angledLine(
 ///          angle = segAng(rectangleSegmentA001),
-///          length = -segLen(rectangleSegmentA001)
+///          length = -segLen(rectangleSegmentA001),
 ///          tag = $rectangleSegmentC001,
 ///        )
 ///     |> line(endAbsolute = [profileStartX(%), profileStartY(%)])
@@ -161,7 +154,32 @@ export type string
 /// the `rect` function. This is because the `rect` function is returning the
 /// sketch group that contains the tags.
 @(impl = primitive)
-export type tag
+export type TagDecl
+
+/// A tag which references a line, arc, or other edge in a sketch or an edge of a solid.
+///
+/// Created by using a tag declarator (see the docs for `TagDecl`). Can be used where an `Edge` is
+/// required.
+///
+/// If a line in a sketch is tagged and then the sketch is extruded, the tag is a `TaggedEdge` before
+/// extrusion and a `TaggedFace` after extrusion.
+@(impl = std_rust)
+export type TaggedEdge
+
+/// A tag which references a face of a solid, including the distinguished tags `START` and `END`.
+///
+/// Created by using a tag declarator (see the docs for `TagDecl`).
+///
+/// If a line in a sketch is tagged and then the sketch is extruded, the tag is a `TaggedEdge` before
+/// extrusion and a `TaggedFace` after extrusion.
+@(impl = std_rust)
+export type TaggedFace
+
+/// Reference a previously created tag. Used much like a variable.
+///
+/// Prefer to use `TaggedEdge` or `TaggedFace`. For more details on tags, see the docs for `TagDecl`.
+@(deprecated = true)
+export type tag = TaggedEdge
 
 /// Represents geometry which is defined using some other CAD system and imported into KCL.
 @(impl = primitive)