
;; Welcome to the GDS tutorial!

;; This tutorial teaches the use of GDS by leading you through a set
;; of examples where you actually use GDS, in Emacs, along the way.
;; To get maximum benefit, therefore, you should be reading this
;; tutorial in Emacs.

;; 0. GDS setup

;; The first thing to do, if you haven't already, is to load the GDS
;; library into Emacs.  The Emacs Lisp expression for this is:

(require 'gds)

;; So, if you don't already have this in your .emacs, either add it
;; and then restart Emacs, or evaluate it just for this Emacs session
;; by moving the cursor to just after the closing parenthesis and
;; typing `C-x C-e'.

;; 1. Help

;; GDS makes it easy to access the Guile help system when working on a
;; Scheme program in Emacs.  For example, suppose that you are writing
;; code that uses list-ref, and need to remind yourself about
;; list-ref's arguments ...

(define (penultimate l)
  (list-ref

;; Just place the cursor on the word "list-ref" and type `C-h g'.  Try
;; it now!

;; If GDS is working correctly, a window should have popped up above
;; or below showing the Guile help for list-ref.  The window contains
;; other information as well, but we'll cover that later.

;; You can also do an "apropos" search through Guile's help.  If you
;; couldn't remember the name list-ref, for example, you could search
;; for anything matching "list" by typing `C-h C-g' and entering
;; "list" at the minibuffer prompt.  Try doing this now: you should
;; see a longish list of Guile definitions whose names include "list".
;; As usual in Emacs, you can use `M-PageUp' and `M-PageDown' to
;; conveniently scroll the other window without having to select it.

;; The functions called by `C-h g' and `C-h C-g' are gds-help-symbol
;; and gds-apropos.  They both look up the symbol or word at point by
;; default, but that default can be overidden by typing something else
;; at the minibuffer prompt.

;; 2. Completion

;; As you are typing Scheme code, you can ask GDS to complete the
;; symbol before point for you, by typing `ESC TAB'.  GDS selects
;; possible completions by matching the text so far against all
;; definitions in the Guile environment.  (This may be compared with
;; the "dabbrev" completion performed by `M-/', which selects possible
;; completions from the contents of Emacs buffers.  So, if you are
;; trying to complete "with-ou", to get "with-output-to-string", for
;; example, `ESC TAB' will always work, because with-output-to-string
;; is always defined in Guile's default environment, whereas `M-/'
;; will only work if one of Emacs's buffers happens to contain the
;; full name "with-output-to-string".)

;; To illustrate the idea, here are some partial names that you can
;; try completing.  For each one, move the cursor to the end of the
;; line and type `ESC TAB' to try to complete it.

list-
with-ou
with-output-to-s
mkst

;; (If you are not familiar with any of the completed definitions,
;; feel free to use `C-h g' to find out about them!)

;; 3. Evaluation

;; GDS provides several ways for you to evaluate Scheme code from
;; within Emacs.

;; Just like in Emacs Lisp, a single expression in a buffer can be
;; evaluated using `C-x C-e' or `C-M-x'.  For `C-x C-e', the
;; expression is that which ends immediately before point (so that it
;; is useful for evaluating something just after you have typed it).
;; For `C-M-x', the expression is the "top level defun" around point;
;; this means the balanced chunk of code around point whose opening
;; parenthesis is in column 0.

;; Take this code fragment as an example:

(let ((x 1) (y 2))
  (let ((z (atan x y)))
    (display "Arctangent is: ")
    (display z)
    (newline)
    z))

;; If you move the cursor to the end of the (display z) line and type
;; `C-x C-e', the code evaluated is just "(display z)", which normally
;; produces an error, because z is not defined in the usual Guile
;; environment.  If, however, you type `C-M-x' with the cursor in the
;; same place, the code evaluated is the whole "(let ((x 1) (y 2))
;; ...)" kaboodle, because that is the most recent expression before
;; point that starts in column 0.

;; Try these now.  The Guile Interaction window should pop up again,
;; and show you:
;; - the expression that was evaluated (probably abbreviated)
;; - the module that it was evaluated in
;; - anything that the code wrote to its standard output
;; - the return value(s) of the evaluation.
;; Following the convention of the Emacs Lisp and Guile manuals,
;; return values are indicated by the symbol "=>".

;; To see what happens when an expression has multiple return values,
;; try evaluating this one:

(values 'a (begin (display "hello world\n") 'b) 'c)

;; You can also evaluate a region of a buffer using `C-c C-r'.  If the
;; code in the region consists of multiple expressions, GDS evaluates
;; them sequentially.  For example, try selecting the following three
;; lines and typing `C-c C-r'.

    (display "Arctangent is: ")
    (display z)
    (newline)

;; If the code in the region evaluated isn't syntactically balanced,
;; GDS will indicate a read error, for example for this code:

  (let ((z (atan x y)))
    (display "Arctangent is: ")
    (display z)
    (newline)

;; Finally, if you want to evaluate something quickly that is not in a
;; buffer, you can use `C-c C-e' and type the code to evaluate at the
;; minibuffer prompt.  The results are popped up in the same way as
;; for code from a buffer.

;; 4. Breakpoints

;; Before evaluating Scheme code from an Emacs buffer, you may want to
;; set some breakpoints in it.  With GDS you can set a breakpoint in
;; Scheme code by typing `C-x SPC'.

(for-each (lambda (x)
	    (format #t "~A cubed is ~A\n" x (* x x x)))
	  (iota 6))

;; To see how breakpoints work, first move the cursor to the "f" of
;; "format" and type `C-x SPC'.  The symbol "=?=" should appear to
;; indicate the breakpoint location, so that the beginning of the line
;; looks like this: "(=?= format".  Then evaluate the whole for-each
;; expression by typing `C-M-x'.

;; Three things now happen at once.
;;
;; 1. The "=?=" symbol changes to "=|=".  This indicates that the
;; breakpoint is now known to Guile (whereas before the code was
;; evaluated, the breakpoint was really just a marker in Emacs).
;;
;; 2. The Guile Interaction window pops up again displaying the Scheme
;; call stack at the point where the breakpoint was hit.  Guile has
;; been stopped at the point where it is just about to evaluate the
;; format expression for the first time, with x set to 0.
;;
;; 3. In the code above, the whole of the format expression has been
;; highlighted.  Whenever GDS displays a call stack because Guile has
;; been stopped, it also tries to display the corresponding source
;; code and highlight the expression that Guile is working on or about
;; to work on.

;; You now have control over the continuing evaluation of this code.
;; Here are some of the things you can do - please try them as you
;; read.
;;
;; - Type `g' (or select Go from the Guile->Debug menu) to run the
;;   evaluator until a breakpoint is hit again.  In this example, the
;;   same breakpoint is hit again, but this time for x equals 1.
;;
;; - Type `SPC' (or select Next from the Guile->Debug menu) to run
;;   just the next step of the evaluation.  Pressing `SPC' repeatedly
;;   is a nice way to step through code and gain a detailed
;;   understanding of how it works.
;;
;; - Type `e' (or select Eval In This Frame... from the Guile->Debug
;;   menu) to evaluate an expression in the context where Guile has
;;   stopped.  Often this is most useful just to see the value of a
;;   variable: in this example, you can query the local value of x by
;;   typing `e x RET'.

;; Local Variables:
;; mode: scheme
;; End:

