utils.scrbl: Add eval-with.

scribblings/utils.scrbl

@@ -1,5 +1,6 @@
 #lang scribble/manual
-@(require (for-label racket graph "../utils.rkt"))
+@(require scribble/example racket/sandbox
+	  (for-label racket graph "../utils.rkt"))
 
 @title[#:tag "utils"]{dds/utils: Various Utilities}
 
@@ -9,11 +10,39 @@ This module defines miscellaneous utilities, supporting the other modules of
 the package: evaluating sexps, manipulating lists,
 @hyperlink["https://orgmode.org/"]{Org-mode} interoperability, etc.
 
+
+@(define utils-evaluator
+  (parameterize ([sandbox-output 'string]
+  		 [sandbox-error-output 'string]
+		 [sandbox-memory-limit 50])
+   (make-evaluator 'racket/base #:requires '("utils.rkt"))))
+
 @section{Hashtable injection}
 
 This section defines some utilities to streamline the usage of hash tables
 mapping symbols to values.  The goal is essentially to avoid having to write
-explicit hash-ref calls.
+explicit @racket[hash-ref] calls.
+
+@defproc[(eval-with [ht variable-mapping?] [expr any/c]) any]{
+
+Temporarily injects the mappings from the given hash table as bindings in
+a namespace including @racket[racket/base] and then evaluates the expression.
+
+@examples[#:eval utils-evaluator
+(let ([ht (hash 'a 1 'b 1)])
+  (eval-with ht '(+ b a 1)))
+]
+
+The local bindings from the current lexical scope are not
+conserved.  Therefore, the following outputs an error about a
+missing identifier:
+
+@examples[#:eval utils-evaluator
+(eval:error
+(let ([ht (hash 'a 1 'b 1)]
+      [z 1])
+  (eval-with ht '(+ b z a 1)))
+)]}
 
 @section{Analysis of quoted expressions}