;;; File:
;;;   verbose-bindings.ss
;;; Author:
;;;   Samuel A. Rebelsky
;;; Summary:
;;;   A set of macros that make it easier to observe what's
;;;   happening when we bind names to values.
;;; Contents:
;;;   (verbose-define name value)
;;;      Assign value to name, describing the binding.
;;;   (verbose-let (name-value-pairs) exp1 ...)
;;;      Assign each value to the corresponding name, but
;;;      also describes the bindings.
;;;   (verbose-let* (name-value-pairs) exp1 ...)
;;;      Assign each value to the corresponding name, in sequence.
;;; Version:
;;;   0.3.1 of 17 February 2007
;;; History:
;;;   At end.

; +--------+---------------------------------------------------------------
; | Macros |
; +--------+

;;; Procedure (Macro):
;;;   verbose-define
;;; Parameters:
;;;   name, a symbol [unverified]
;;;   exp, a valid expression.
;;; Purpose:
;;;   Globally binds val to name while reporting the binding (for
;;;   observation).
;;; Preconditions:
;;;   val must be a valid expression.
;;; Postconditions:
;;;   name can be now used in future expressions, and gives the value
;;;     of exp.
;;; Philosophy:
;;;   It may be helpful to students learning about the techniques for
;;;   binding values to see the bindings happen.  This procedure does
;;;   little more than report the binding and then call define.
(define-syntax verbose-define
  (syntax-rules ()
    ((_ name exp)
     (begin
       (report-binding name exp)
       (display "with define.")
       (newline)
       (define name exp)))))

;;; Procedure (Macro):
;;;   verbose-let
;;; Parameters:
;;;   list-of-bindings, a list of name/expression lists
;;;   exp0 ..., a list of expressions
;;; Purpose:
;;;   Does the same thing as (let list-of-bindings exp0 ...), except that
;;;   it also provides a report on what happens.
;;; Preconditions:
;;;   The corresponding let operation must be valid.
;;; Postconditions:
;;;   See those for let.
;;; Philosophy:
;;;   It may be helpful to students learning about the techniques for
;;;   binding values to see the bindings happen.  This procedure does
;;;   little more than report the binding and then call let.
(define-syntax verbose-let
  (syntax-rules ()
    ((_ definitions body ...)
     (begin
       (display "Beginning let.")
       (newline)
       (display-let-bindings definitions)
       (let ((result (let definitions body ...)))
         (display "Ending let.")
         (newline)
         result)))))

;;; Procedure (Macro):
;;;   verbose-let*
;;; Parameters:
;;;   list-of-bindings, a list of name/expression lists
;;;   exp0 ..., a list of expressions
;;; Purpose:
;;;   Does the same thing as (let* list-of-bindings exp0 ...), except that
;;;   it also provides a report on what happens.
;;; Preconditions:
;;;   The corresponding let* operation must be valid.
;;; Postconditions:
;;;   See those for let*.
;;; Philosophy:
;;;   It may be helpful to students learning about the techniques for
;;;   binding values to see the bindings happen.  This procedure shows them
;;;   as they happen.
;;; Predecessor:
;;;   This code is based on a definition of let* taken from Chapter 8 of
;;;   the 3rd edition of R Kent Dybvig's _The Scheme Programming Language_,
;;;   found on the Web at <http://www.scheme.com/tspl3/syntax.html>.
(define-syntax verbose-let*
  (syntax-rules ()
    ((_ definitions body ...)
     (begin
       (display "Beginning let*")
       (newline)
       (let ((result (verbose-let*-helper definitions body ...)))
         (display "Ending let*")
         (newline)
         result)))))

(define-syntax verbose-let*-helper
  (syntax-rules ()
    ((_ () e0 ...) 
     (let () e0 ...))
    ((_ ((n0 v0) (n1 v1) ...) e0 ...)
     (begin
       (report-binding n0 v0)
       (display " with let*.")
       (newline)
       (let ((n0 v0)) 
         (verbose-let*-helper ((n1 v1) ...) e0 ...))))))


; +---------+--------------------------------------------------------------
; | Helpers |
; +---------+

(define-syntax report-binding
  (syntax-rules ()
    ((_ name exp)
     (begin
       (display "Binding ")
       (write 'name)
       (display " to ")
       (write 'exp)))))

(define-syntax display-let-bindings
  (syntax-rules ()
    ((_ ())
     (display ""))
    ((_ ((n1 v1) (n2 v2) ...))
     (begin
       (display "  ")
       (report-binding n1 v1)
       (newline)
       (display-let-bindings ((n2 v2) ...))))))

; +---------+--------------------------------------------------------------
; | History |
; +---------+

; Monday, 25 September 2006 (v 0.1) [Samuel A. Rebelsky]
; * Created.

; Tuesday, 26 September 2006 (v 0.2) [Samuel A. Rebelsky]
; * Fixed an error in verbose-let in which it didn't return the value.
; * Updated verbose-let* to print "Started" ... "Finished"

; Tuesday, 26 September 2006 (v 0.3) [Samuel A. Rebelsky]
; * Although it was nice that the bindings displayed both the
;   assigned expression and the value of the expression, if the
;   expression had a side effect, there were possible problems.
;   Hence, we no longer see the value.  Sniff.
; * Improved the strategy for printing "Started" and "Finished"

; Thursday, 27 February 2007 (v 0.3.1) [Samuel A. Rebelsky]
; * Fixed minor error in vebose-define.