diff options
Diffstat (limited to 'emacs/gds-tutorial.txt')
| -rwxr-xr-x | emacs/gds-tutorial.txt | 223 |
1 files changed, 0 insertions, 223 deletions
diff --git a/emacs/gds-tutorial.txt b/emacs/gds-tutorial.txt deleted file mode 100755 index 4254803ec..000000000 --- a/emacs/gds-tutorial.txt +++ /dev/null @@ -1,223 +0,0 @@ - -;; 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. - -;; ** 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'. - -;; (Note that if you _have_ already loaded GDS, and you type `C-x C-e' -;; after this expression, you will see a *Guile Evaluation* window -;; telling you that the evaluation failed because `require' is -;; unbound. Don't worry; this is not a problem, and the rest of the -;; tutorial should still work just fine.) - -;; ** 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 RET'. -;; Try it now! - -;; If GDS is working correctly, a window should have popped up above -;; or below showing the Guile help for list-ref. - -;; 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. - -;; ** 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 contrasted 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!) - -;; ** 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 Evaluation 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. - -;; ** Breakpoints - -;; Before evaluating Scheme code from an Emacs buffer, you may want to -;; set some breakpoints in it. With GDS you can set breakpoints in -;; Scheme code by typing `C-x SPC'. -;; -;; To see how this works, select the second line of the following code -;; (the `(format ...)' line) and type `C-x SPC'. - -(for-each (lambda (x) - (format #t "~A cubed is ~A\n" x (* x x x))) - (iota 6)) - -;; The two opening parentheses in that line should now be highlighted -;; in red, to show that breakpoints have been set at the start of the -;; `(format ...)' and `(* x x x)' expressions. Then evaluate the -;; whole for-each expression by typing `C-M-x' ... -;; -;; In the upper half of your Emacs, a buffer appears showing you the -;; Scheme stack. -;; -;; In the lower half, the `(format ...)' expression is highlighted. -;; -;; What has happened is that Guile started evaluating the for-each -;; code, but then hit the breakpoint that you set on the start of the -;; format expression. Guile therefore pauses the evaluation at that -;; point and passes the stack (which encapsulates everything that is -;; interesting about the state of Guile at that point) to GDS. You -;; can then explore the stack and decide how to tell Guile to -;; continue. -;; -;; - If you move your mouse over any of the identifiers in the -;; highlighted code, a help echo (or tooltip) will appear to tell -;; you that identifier's current value. (Note though that this only -;; works when the stack buffer is selected. So if you have switched -;; to this buffer in order to scroll down and read these lines, you -;; will need to switch back to the stack buffer before trying this -;; out.) -;; -;; - In the stack buffer, the "=>" on the left shows you that the top -;; frame is currently selected. You can move up and down the stack -;; by pressing the up and down arrows (or `u' and `d'). As you do -;; this, GDS will change the highlight in the lower window to show -;; the code that corresponds to the selected stack frame. -;; -;; - You can evaluate an arbitrary expression in the local environment -;; of the selected stack frame by typing `e' followed by the -;; expression. -;; -;; - You can show various bits of information about the selected frame -;; by typing `I', `A' and `S'. Feel free to try these now, to see -;; what they do. -;; -;; You also have control over the continuing evaluation of this code. -;; Here are some of the things you can do - please try them as you -;; read. -;; -;; - `g' tells Guile to continue execution normally. In this case -;; that means that evaluation will continue until it hits the next -;; breakpoint, which is on the `(* x x x)' expression. -;; -;; - `SPC' tells Guile to continue until the next significant event in -;; the same source file as the selected frame. A "significant -;; event" means either beginning to evaluate an expression in the -;; relevant file, or completing such an evaluation, in which case -;; GDS tells you the value that it is returning. Pressing `SPC' -;; repeatedly is a nice way to step through all the details of the -;; code in a given file, but stepping over calls that involve code -;; from other files. -;; -;; - `o' tells Guile to continue execution until the selected stack -;; frame completes, and then to show its return value. - -;; Local Variables: -;; mode: scheme -;; End: |