feat: add Box.peek

Box.peek allows users to transform a reference to a box into a a
reference to the box's contained value. The returned reference will have
the same lifetime as the box. This function allows callers to manipulate
the value in a box without re-allocation, for example:

```clojure
(deftype Num [val Int])

(let-do [box (Box.init (Num.init 0))]
  (Num.set-val! (Box.peek &box) 1)
  @(Num.val (Box.peek &box)))
```

This commit also includes tests for Box.peek.

Co-authored-by: TimDeve <[email protected]>

Author: scolsen

src/BoxTemplates.hs

@@ -7,6 +7,7 @@ module BoxTemplates
     BoxTemplates.init,
     copy,
     unbox,
+    peek,
   )
 where
 
@@ -56,6 +57,21 @@ unbox = let path = SymPath ["Box"] "unbox"
             template = TemplateCreator $ \_ _ -> Template t decl body deps
          in defineTypeParameterizedTemplate template path t docs
 
+-- | Defines a template for getting a reference to the value stored in a box without performing an additional allocation.
+peek :: (String, Binder)
+peek = let path = SymPath ["Box"] "peek"
+           t = FuncTy [(RefTy (StructTy (ConcreteNameTy (SymPath [] "Box")) [(VarTy "t")]) (VarTy "q"))] (RefTy (VarTy "t") (VarTy "q")) StaticLifetimeTy
+           docs = "Returns a reference to the value stored in a box without performing an additional allocation."
+           decl = templateLiteral "$t* $NAME($t** box_ref)"
+           body = const (multilineTemplate
+                          [ "$DECL {",
+                            "  return *box_ref;",
+                            "}"
+                          ])
+           deps = const []
+           template = TemplateCreator $ \_ _ -> Template t decl body deps
+        in defineTypeParameterizedTemplate template path t docs
+
 -- | Defines a template for copying a box. The copy will also be heap allocated.
 copy :: (String, Binder)
 copy =

src/StartingEnv.hs

@@ -124,6 +124,7 @@ boxModule =
     bindings = Map.fromList
       [ BoxTemplates.init,
         BoxTemplates.unbox,
+        BoxTemplates.peek,
         BoxTemplates.delete,
         BoxTemplates.copy,
         BoxTemplates.prn,

test/box.carp

@@ -3,13 +3,22 @@
 
 (Debug.sanitize-addresses)
 
-(deftest test 
-  (assert-equal test 
+(deftype Num [val Int])
+
+(deftest test
+  (assert-equal test
     &(Box.init @"foo")
     &(Box.init @"foo")
     "init works as expected")
   (assert-equal test
     2
     (Box.unbox (Box.init 2))
     "unbox works as expected")
+  (assert-equal test
+    1
+    (let-do [box (Box.init (Num.init 0))]
+      (Num.set-val! (Box.peek &box) 1)
+      @(Num.val (Box.peek &box)))
+    "peek works as expected"
+  )
 )