### Functions as Black-Box Abstractions

`sqrt/1`

is our first example of a program defined by a set of mutually
defined functions. Notice that the definition of `sqrt/2`

is recursive; that
is, the function is defined in terms of itself. The idea of being able to
define a function in terms of itself may be disturbing; it may seem unclear how
such a "circular" definition could make sense at all, much less specify a
well-defined process to be carried out by a computer. This will be addressed
more carefully in the section Functions and the Processes They Generate.
But first let's consider some other important points illustrated by the
examples of the square-root program.

Observe that the problem of computing square roots breaks up naturally into a number of subproblems: how to tell whether a guess is good enough, how to improve a guess, and so on. Each of these tasks is accomplished by a separate function. The entire square-root program can be viewed as a cluster of functions (shown in figure 1.2) that mirrors the decomposition of the problem into subproblems.

**Figure 1.2**: Procedural decomposition of the square-root program.

The importance of this decomposition strategy is not simply that one is
dividing the program into parts. After all, we could take any large program and
divide it into parts -- the first ten lines, the next ten lines, the next ten
lines, and so on. Rather, it is crucial that each function accomplishes an
identifiable task that can be used as a module in defining other functions. For
example, when we define the `good-enough?/2`

function in terms of
`square/1`

, we are able to regard the `square/1`

function as a "black box."
We are not at that moment concerned with how the function computes its result,
only with the fact that it computes the square. The details of how the square
is computed can be suppressed, to be considered at a later time. Indeed, as far
as the `good-enough?/2`

function is concerned, `square/1`

is not quite a
function but rather an abstraction of a function, a so-called procedural
abstraction. At this level of abstraction, any function that computes the
square is equally good.

Thus, considering only the values they return, the following two functions for
squaring a number should be indistinguishable. Each takes a numerical argument
and produces the square of that number as the value.^{1}

```
(defun square (x) (* x x))
(defun square (x)
(exp (double (log x))))
(defun double (x) (+ x x))
```

So a function definition should be able to suppress detail. The users of the function may not have written the function themselves, but may have obtained it from another programmer as a black box. A user should not need to know how the function is implemented in order to use it.

#### Local names

One detail of a function's implementation that should not matter to the user of the function is the implementer's choice of names for the function's formal parameters. Thus, the following functions should not be distinguishable:

```
(defun square (x) (* x x))
(defun square (y) (* y y))
```

This principle -- that the meaning of a function should be independent of the parameter names used by its author -- seems on the surface to be self-evident, but its consequences are profound. The simplest consequence is that the parameter names of a function must be local to the body of the function. For example, we used `square/1`

in the definition of `good-enough?/2`

in our square-root function:

```
(defun good-enough? (guess x)
(< (abs (- (square guess) x)) 0.001))
```

The intention of the author of `good-enough?/2`

is to determine if the square of the first argument is within a given tolerance of the second argument. We see that the author of `good-enough?/2`

used the name `guess`

to refer to the first argument and `x`

to refer to the second argument. The argument of `square/1`

is `guess`

. If the author of `square/1`

used `x`

(as above) to refer to that argument, we see that the x in `good-enough?/2`

must be a different `x`

than the one in square. Running the function square must not affect the value of `x`

that is used by `good-enough?/2`

, because that value of `x`

may be needed by `good-enough?/2`

after `square/1`

is done computing.

If the parameters were not local to the bodies of their respective functions, then the parameter `x`

in `square/1`

could be confused with the parameter `x`

in `good-enough?/2`

, and the behavior of `good-enough?/2`

would depend upon which version of `square/1`

we used. Thus, `square/1`

would not be the black box we desired.

A formal parameter of a function has a very special role in the function definition, in that it doesn't matter what name the formal parameter has. Such a name is called a *bound variable*, and we say that the function definition *binds* its formal parameters. The meaning of a function definition is unchanged if a bound variable is consistently renamed throughout the definition.^{2} If a variable is not bound, we say that it is *free*. The set of expressions for which a binding defines a name is called the *scope* of that name. In a function definition, the bound variables declared as the formal parameters of the function have the body of the function as their scope.

In the definition of `good-enough?/2`

above, `guess`

and `x`

are bound variables but `<`

, `-`

, `abs`

, and `square/1`

are free. The meaning of `good-enough?/2`

should be independent of the names we choose for `guess`

and `x`

so long as they are distinct and different from `<`

, `-`

, `abs`

, and `square`

. (If we were running this code in the LFE REPL and renamed `guess`

to a variable that had been `set`

earlier in the session, we would have introduced a bug by capturing that previously set variable. It would have changed from free to bound.) The meaning of `good-enough?/2`

is not independent of the names of its free variables, however. It surely depends upon the fact (external to this definition) that the symbol `abs`

names a function for computing the absolute value of a number. `good-enough?/2`

will compute a different function if we substitute `cos`

for `abs`

in its definition.

#### Internal definitions and block structure

We have one kind of name isolation available to us so far: The formal parameters of a function are local to the body of the function. The square-root program illustrates another way in which we would like to control the use of names. The existing program consists of separate functions:

```
(defun sqrt (x)
(sqrt (* 0.5 x) x))
(defun sqrt (guess x)
(if (good-enough? guess x)
guess
(sqrt (improve guess x)
x)))
(defun good-enough? (guess x)
(< (abs (- (square guess) x)) 0.001))
(defun improve (guess x)
(average guess (/ x guess)))
(defun average (x y)
(/ (+ x y) 2))
(defun abs
((x) (when (< x 0)) (- x))
((x) x))
(defun square (x) (* x x))
```

The last three are fairly general, useful in many contexts. This leaves us with the following special-purpose functions from our square-root program:

```
(defun sqrt (x)
(sqrt (* 0.5 x) x))
(defun sqrt (guess x)
(if (good-enough? guess x)
guess
(sqrt (improve guess x)
x)))
(defun good-enough? (guess x)
(< (abs (- (square guess) x)) 0.001))
(defun improve (guess x)
(average guess (/ x guess)))
```

The problem with this program is that the only function that is important to users of the square-root program is `sqrt/1`

. The other functions (`sqrt/2`

, `good-enough?/2`

, and `improve/2`

) only clutter up their minds. They may not define any other function called `good-enough?/2`

as part of another program to work together with the square-root program, because the square-root program needs it. The problem is especially severe in the construction of large systems by many separate programmers. For example, in the construction of a large library of numerical functions, many numerical functions are computed as successive approximations and thus might have functions named `good-enough?/2`

and `improve/2`

as auxiliary functions. We would like to localize the subfunctions, hiding them inside `sqrt/1`

so that the square-root program could coexist with other successive approximations, each having its own private `good-enough?/2`

function. To make this possible, we allow a function to have internal definitions that are local to that function. For example, in the square-root problem we can write

```
(defun sqrt (x)
(fletrec ((improve (guess x)
;; Improve a given guess for the square root.
(average guess (/ x guess)))
(good-enough? (guess x)
;; A predicate which determines if a guess is
;; close enough to a correct result.
(< (abs (- (square guess) x)) 0.001))
(sqrt (guess x)
;; A recursive function for approximating
;; the square root of a given number.
(if (good-enough? guess x)
guess
(sqrt (improve guess x)
x))))
;; the main body of the function
(sqrt (* 0.5 x) x)))
```

The use of `flet`

("function let"), `flet*`

(sequential "function let"s) , and `fletrec`

("recursive function let"s) allows one to define *locally scoped* functions, or functions that are only scoped within the given form. This is one of the classic solutions to the problem of naming collisions in older Lisp programs.^{3}

But there is a better idea lurking here. In addition to internalizing the definitions of the auxiliary functions, we can simplify them. Since `x`

is bound in the definition of `sqrt/1`

, the functions `good-enough?/2`

, `improve/2`

, and `sqrt/2`

, which are defined internally to sqrt, are in the scope of `x`

. Thus, it is not necessary to pass `x`

explicitly to each of these functions. Instead, we allow `x`

to be a free variable in the internal definitions, as shown below. Then `x`

gets its value from the argument with which the enclosing function `sqrt/1`

is called. This discipline is called *lexical scoping*.^{4}

```
(defun sqrt (x)
(fletrec ((improve (guess)
;; Improve a given guess for the square root.
(average guess (/ x guess)))
(good-enough? (guess)
;; A predicate which determines if a guess is
;; close enough to a correct result.
(< (abs (- (square guess) x)) 0.001))
(sqrt-rec (guess)
;; A recursive function for approximating
;; the square root of a given number.
(if (good-enough? guess)
guess
(sqrt-rec (improve guess)))))
;; the main body of the function
(sqrt-rec (* 0.5 x))))
```

Note that this required the renaming of the `sqrt/2`

function. We dropped the
arity of `sqrt/2`

from 2 to 1, thus causing a name collision with our
outer-most `sqrt/1`

and thus renamed it to `sqrt-rec/1`

.

The idea of this sort of nested structure originated with the programming language Algol 60. It appears in most advanced programming languages and, as mentioned, used to be an important tool for helping to organize the construction of large programs.

#### Modules, exports, and private functions

While Algol 60 pioneered the concept of nested function definitions,^{5}
later versions of Algol 68 advanced the concept of *modules*.^{6} This made a
significant impact in the world of practical computing to the extent that most
modern languages have some form of module support built in.

LFE supports modules. The proper way to provide a "black box" program to an LFE developer for their use is to define all the functions in one or more modules and export only those functions which are intended to be consumed by a developer.

Instead of using `fletrec`

, here is the square-root program using a module
with one exported function:

```
(defmodule sqrt
(export (sqrt 1)))
(defun sqrt (x)
(sqrt (* 0.5 x) x))
(defun sqrt (guess x)
(if (good-enough? guess x)
guess
(sqrt (improve guess x)
x)))
(defun good-enough? (guess x)
(< (abs (- (square guess) x)) 0.001))
(defun improve (guess x)
(average guess (/ x guess)))
(defun average (x y)
(/ (+ x y) 2))
(defun abs
((x) (when (< x 0)) (- x))
((x) x))
(defun square (x) (* x x))
```

Then from the LFE REPL we can compile the module and run it, using the LFE `(module:function ...)`

calling syntax

```
> (c "ch1/sqrt.lfe")
#(module sqrt)
> (sqrt:sqrt 25)
5.000012953048684
> (sqrt:sqrt 1)
1.0003048780487804
> (sqrt:sqrt 2)
1.4142156862745097
```

Attempting to use functions that are not exported results in an error

```
> (sqrt:sqrt 1 25)
exception error: undef
in (: sqrt sqrt 1 25)
```

We will use modules extensively to help us break up large programs into tractable pieces.

^{1}. It is not even clear which of these functions is a more efficient implementation. This depends upon the hardware available. There are machines for which the "obvious" implementation is the less efficient one. Consider a machine that has extensive tables of logarithms and antilogarithms stored in a very efficient manner. ↩

^{2}. The concept of consistent renaming is actually subtle and difficult to define formally. Famous logicians have made embarrassing errors here. ↩

^{3}. This is one of the pillars of the structured programming paradigm. ↩

^{4}. Lexical scoping dictates that free variables in a function are taken to refer to bindings made by enclosing function definitions; that is, they are looked up in the environment in which the function was defined. We will see how this works in detail in chapter 11 when we study environments and the detailed behavior of the interpreter. ↩

^{5}. Also calledblock structures. ↩

^{6}. Extensions for module support in Algol 68 were released in 1970. In 1975, Modula was the first language designed from the beginning to have support for modules. Due to Modula's use of the "dot"`.`

to separate modules and objects, that usage became popular in such languages as Python and and Java. In contrast, Erlang and LFE use the colon`:`

to separate modules from functions. ↩