From: Carl Sorensen <c_sorensen@byu.edu>
Date: Thu, 24 Dec 2009 04:00:31 +0000 (-0700)
Subject: Doc: Extend: Scheme procedures
X-Git-Tag: release/2.13.10-1~83
X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=3c998f6f02db41b77512bb3d610b6fad68c2a18a;p=lilypond.git

Doc: Extend: Scheme procedures
---

diff --git a/Documentation/extending/scheme-tutorial.itely b/Documentation/extending/scheme-tutorial.itely
index c0430762d1..db7c563ef1 100644
--- a/Documentation/extending/scheme-tutorial.itely
+++ b/Documentation/extending/scheme-tutorial.itely
@@ -390,19 +390,29 @@ be used for another calculation.
 @lisp
 guile> (+ 1 (* 3 4))
 13
-guile> (+ 1 (* 3 4))
 @end lisp
 
 These calculations are examples of evaluations; an expression like
 @code{(* 3 4)} is replaced by its value @code{12}.
 
-When the scheme parser encounters an expression that is a list, the
+Scheme calculations are sensitive to the differences between integers
+and non-integers.  Integer calculations are exact, while non-integers
+are calculated to the appropriate limits of precision:
+
+@lisp
+guile> (/ 7 3)
+7/3
+guile> (/ 7.0 3.0)
+2.33333333333333
+@end lisp
+
+When the scheme interpreter encounters an expression that is a list, the
 first element of the list is treated as a procedure to be evaluated
 with the arguments of the remainder of the list.  Therefore, all operators
 in Scheme are prefix operators.
 
-If the first element of a Scheme expression that is a list passed to the parser
-is @emph{not} an operator or procedure, an error will occur:
+If the first element of a Scheme expression that is a list passed to the
+interpreter`is @emph{not} an operator or procedure, an error will occur:
 
 @lisp
 guile> (1 2 3)
@@ -461,11 +471,74 @@ The quote mark @code{'} prevents the Scheme interpreter from substituting
 @node Scheme procedures
 @subsection Scheme procedures
 
+Scheme procedures are executable scheme expressions that return
+a value resulting from their execution.,  They can also manipulate
+variables defined outside of the procedure.
+
+@unnumberedsubsubsec Defining procedures
+
+Procedures are defined in Scheme with define
+
+@example
+(define (function-name arg1 arg2 ... argn)
+ scheme-expression-that-gives-a-return-value)
+@end example
+
+For example, we could define a procedure to calculate the average:
+
+@lisp
+guile> (define (average x y) (/ (+ x y) 2))
+guile> average
+#<procedure average (x y)>
+@end lisp
+
+Once a procedure is defined, it is called by putting the procedure
+name and the arguments in a list.  For example, we can calculate
+the average of 3 and 12:
+
+@lisp
+guile> (average 3 12)
+15/2
+@end list
+
 @unnumberedsubsubsec Predicates
 
+Scheme procedures that return boolean values are often called
+@emph{predicates}.  By convention (but not necessity), predicate names
+typically end in a question mark:
+
+@lisp
+guile> (define (less-than-ten? x) (< x 10))
+guile> (less-than-ten? 9)
+#t
+guile> (less-than-ten? 15)
+#f
+@end lisp
+
 @unnumberedsubsubsec Return values
 
-TODO -- write about scheme procedures
+Sometimes the user would like to have multiple Scheme expressions in
+a procedure.  There are two ways that multiple expressions can be
+combined.  The first is the @code{begin} procedure, which allows
+multiple expressions to be evaluated, and returns the value of
+the last expression.
+
+@lisp
+guile> (begin (+ 1 2) (- 5 8) (* 2 2))
+4
+@end lisp
+
+The second way to combine multiple expressions is in a @code{let} block.
+In a let block, a series of bindings are created, and then a sequence
+of expressions that can include those bindings is evaluated.  The
+return value of the let block is the return value of the last
+statement in the let block:
+
+@lisp
+guile> (let ((x 2) (y 3) (z 4)) (display (+ x y)) (display (- z 4))
+... (+ (* x y) (/ z x)))
+508
+@end lisp
 
 @node Scheme conditionals
 @subsection Scheme conditionals