;
;; Function calls
;

; ...

(random 128)

; ...

(list)

; now call the list function with one argument:

(list 1)

; calling the list function with two args:

(list 1 2)

; ...

(list  1 2 3 
        4 + 5    6 7)

; ...

(list 1 (+ 2 4) (between 100 200))

; In this example the outer-most function call has two arguments, each
; is a nested function call. Each of the nested function calls have
; three arguments.

(list (list 1 2 3) (list 100 200 300))

; Note that nesting can occur to any level. Hint: you can double-click
; parenthesis to see exactly the scope of arguments they surround:

(list (list (list (list 1 2 3) 4) 5) 6)

; things can get pretty hairy if you want them too!

(list 1 (+ 2 3) (sin (+ pi (random 2.0))) (list 4 5 6))

;
;; Function parameters
;

; Functions accept their arguments (input values) via special
; variables called 'parameters'. When a function is called the
; arguments inside the argument list are processed in a left to right
; manner, each parameter in the function is assigned its corresponding
; input value. This process of associating input values with
; parameters is called 'binding'. The manner in which each parameter
; is bound to its in the argument list depends on the type of
; parameter involved. There are three basic types of parameters:
; 'required', 'optional' and 'named'.  Note that the order or
; parameters and their types are determined by the composer when they
; define the function.

; Required parameters

; A required parameter MUST be passed an argument value when the
; function is called.  For example, the predicate function 'odd?'  is
; defined to take a single required parameter:

(odd? 1)

; This means that it is an error to pass this function more or less
; than one argument when you call it. both of these examples are
; errors:

(odd?)

(odd? 1 2 3)

; Optional parameters

; An 'optional' parameter means that the argument can be supplied or
; not. If a value is not supplied then the optional parameter receives
; a 'default value' determined by the programmer when the function was
; defined. Some functions take only optional parameters, and you can
; specify as many of them as you want to. The 'list' function is an
; example of this type of function. 

; some functions support both required and optional parameters. In
; this case the required parameters must always specified first
; followed by any optional parameters.

; For example, Common Music's 'odds' function is defined with one
; required parameter and two optional ones. This means that the first
; (required) parameter must be supplied, the remaining two can be
; supplied or not. The required argument for 'odds' is a probability
; factor where 0 odds means always false, .5 odds means the function
; is true half the time, and 1 is always true. Execute each command
; several times to see the boolean value the function produces:

(odds 0)

(odds 0.5)

(odds 1)

; But 'odds' also has two optional parameters that you can pass values
; to. If specified these values will become the actual true and false
; values that the function returns:

(odds .5 "winner!")

(odds .5  "Heads"  "Tails")

;
;; Named parameters
;

; ...

(odds .3 :false "fooey!")

(odds .3 :false "fooey!" :true 99)