draw: Add get-/set-ctx functions (#160)

manual.typ

@@ -491,6 +491,37 @@ scale((x: 1.8))
 circle((0,0))
 ```
 
+== Context Modification
+
+The context of a canvas holds the canvas' internal state like style and transformation.
+Note that the fields of the context of a canvas are considered private and therefore
+unstable. You can add custom values to the context, but in order to prevent naming
+conflicts with future CeTZ versions, try to assign unique names.
+
+#show-module-fn(draw-module, "set-ctx")
+```example
+// Setting a custom transformation matrix
+set-ctx(ctx => {
+  let mat = ((1, 0, .5, 0),
+             (0, 1, 0, 0),
+             (0, 0, 1, 0),
+             (0, 0, 0, 1))
+  ctx.transform = mat
+  return ctx
+})
+circle((z: 0), fill: red)
+circle((z: 1), fill: blue)
+circle((z: 2), fill: green)
+```
+
+#show-module-fn(draw-module, "get-ctx")
+```example
+// Print the transformation matrix
+get-ctx(ctx => {
+  content((), [#repr(ctx.transform)])
+})
+```
+
 = Coordinate Systems <coordinate-systems>
 A _coordinate_ is a position on the canvas on which the picture is drawn. They take the form of dictionaries and the following sub-sections define the key value pairs for each system. Some systems have a more implicit form as an array of values and `CeTZ` attempts to infer the system based on the element types.
 

src/draw.typ

@@ -234,6 +234,31 @@
   },
 ),)
 
+/// Modify the canvas' context
+///
+/// - callback (function): Function of the form `ctx => ctx` that returns the
+///                        new canvas context.
+#let set-ctx(callback) = {
+  assert(type(callback) == "function")
+  ((
+    before: callback,
+  ),)
+}
+
+/// Get the canvas' context and return children
+///
+/// - body (function): Function of the form `ctx => elements` that receives the
+///                    current context and returns draw commands.
+#let get-ctx(body) = {
+  assert(type(body) == "function")
+  ((
+    children: ctx => {
+      let c = body(ctx)
+      return if c == none { () } else { c }
+    },
+  ),)
+}
+
 /// Push a group
 ///
 /// A group has a local transformation matrix.
@@ -249,6 +274,7 @@
 /// - anchor (string): Element origin
 /// - body (draw,function): Children or function of the form (`ctx => elements`)
 #let group(name: none, anchor: none, body) = {
+  let body = if body == none { () } else { body }
   ((
     name: name,
     anchor: anchor,

tests/set-get-ctx/test.typ

@@ -0,0 +1,18 @@
+#set page(width: auto, height: auto)
+#import "../../src/lib.typ": *
+
+#box(stroke: 2pt + red, canvas(length: 1cm, {
+  import draw: *
+  set-ctx(ctx => {
+    ctx.my-custom-attribute = "123"
+    return ctx
+  })
+
+  get-ctx(ctx => {
+    set-style(stroke: green)
+    content((0, 0), ctx.my-custom-attribute, frame: "rect")
+  })
+
+  // Note that the set-style is _not_ scoped!
+  circle((0,0))
+}))