7.2 Simple Contracts on Functions
When a module exports a function, it establishes two channels of communication between itself and the client module that imports the function. If the client module calls the function, it sends a value into the “server” module. Conversely, if such a function call ends and the function returns a value, the “server” module sends a value back to the “client” module.
It is important to keep this picture in mind when you read the explanations of the various ways of imposing contracts on functions.
7.2.1 Restricting the Arguments of a Function
Functions usually don’t work on all possible Scheme values but only on a select subset such as numbers, booleans, etc. Here is a module that may represent a bank account:
|
|
(define amount 0) |
It exports two functions:
create: The function’s contract says that it consumes two arguments, a string and a number, and it promises nothing about the return value.
deposit: The function’s contract demands from the client modules that they apply it to numbers. It promises nothing about the return value.
If a “client” module were to apply deposit to 'silly, it would violate the contract. The contract monitoring system would catch this violation and blame “client” for breaking the contract with the above module.
Note: Instead of any you could also use the more specific contract void?, which says that the function will always return the (void) value. This contract, however, would require the contract monitoring system to check the return value every time the function is called, even though the “client” module can’t do much with this value anyway. In contrast, any tells the monitoring system not to check the return value. Additionally, it tells a potential client that the “server” module makes no promises at all about the function’s return value.
7.2.2 Arrows
It is natural to use an arrow to say that an exported value is a function. In decent high schools, you learn that a function has a domain and a range, and that you write this fact down like this:
f : A -> B
Here the A and B are sets; A is the domain and B is the range.
Functions in a programming language have domains and ranges, too. In statically typed languages, you write down the names of types for each argument and for the result. When all you have, however, is a Scheme name, such as create or deposit, you want to tell the reader what the name represents (a function) and, if it is a function (or some other complex value) what the pieces are supposed to be. This is why we use a -> to say "hey, expect this to be a function."
So -> says “this is a contract for a function.” What follows in a function contracts are contracts (sub-contracts if you wish) that tell the reader what kind of arguments to expect and what kind of a result the function produces. For example,
says that create is a function of three arguments: a string, a number, and a boolean. Its result is an account.
In short, the arrow -> is a contract combinator. Its purpose is to combine other contracts into a contract that says "this is a function and its arguments and its result are like that."
7.2.3 Infix Contract Notation
If you are used to mathematics, you like the arrow in between the domain and the range of a function, not at the beginning. If you have read How to Design Programs, you have seen this many times. Indeed, you may have seen contracts such as these in other people’s code:
If a PLT Scheme S-expression contains two dots with a symbol in the middle, the reader re-arranges the S-expression and place the symbol at the front. Thus,
(string? number? boolean? . -> . account?)
is really just a short-hand for
(-> string? number? boolean? account?)
Of course, placing the arrow to the left of the range follows not only mathematical tradition but also that of typed functional languages.
7.2.4 Rolling Your Own Contracts for Function Arguments
The deposit function adds the given number to the value of amount. While the function’s contract prevents clients from applying it to non-numbers, the contract still allows them to apply the function to complex numbers, negative numbers, or inexact numbers, all of which do not represent amounts of money.
To this end, the contract system allows programmers to define their own contracts:
|
(define (amount? a) |
|
; an amount is a natural number of cents |
; is the given number an amount? |
|
(define this 0) |
The module introduces a predicate, amount?. The provide clause refers to this predicate, as a contract, for its specification of the contract of deposit.
Of course it makes no sense to restrict a channel of communication to values that the client doesn’t understand. Therefore the module also exports the amount? predicate itself, with a contract saying that it accepts an arbitrary value and returns a boolean.
In this case, we could also have used natural-number/c, which is a contract defined in scheme/contract that is equivalent to amount (modulo the name):
|
; an amount is a natural number of cents |
[deposit (-> natural-number/c any)]) |
|
(define this 0) |
Lesson: learn about the built-in contracts in scheme/contract.
7.2.5 The and/c, or/c, and listof Contract Combinators
Both and/c and or/c ombine contracts and they do what you expect them to do.
For example, if we didn’t have natural-number/c, the amount? contract is a bit opaque. Instead, we would define it as follows:
|
(define amount |
|
; an amount is a natural number of cents |
; is the given number an amount? |
|
(define this 0) |
That is, amount is a contract that enforces the following conditions: the value satisfies number? and integer? and exact? and is either positive? or zero?.
Oh, we almost forgot. What do you think (listof char?) means? Hint: it is a contract!
7.2.6 Restricting the Range of a Function
Consider a utility module for creating strings from banking records:
|
(define (has-decimal? str) |
(define L (string-length str)) |
#\. |
(string-ref result (- L 3))))) |
|
; convert a random number to a string |
|
; convert an amount into a dollar based string |
[format-nat (-> natural-number/c |
The contract of the exported function format-number specifies that the function consumes a number and produces a string.
The contract of the exported function format-nat is more interesting than the one of format-number. It consumes only natural numbers. Its range contract promises a string that has a . in the third position from the right.
Exercise 2 Strengthen the promise of the range contract for format-nat so that it admits only strings with digits and a single dot.
Solution to exercise 2
|
(define (digit-char? x) |
(member x '(#\1 #\2 #\3 #\4 #\5 #\6 #\7 #\8 #\9 #\0))) |
|
(define (has-decimal? str) |
(define L (string-length str)) |
#\. |
(string-ref result (- L 3))))) |
|
(define (is-decimal-string? str) |
(define L (string-length str)) |
(and (has-decimal? str) |
(andmap digit-char? |
(string->list (substring result 0 (- L 3)))) |
(andmap digit-char? |
(string->list (substring result (- L 2) L))))) |
|
; convert a random number to a string |
|
; convert an amount (natural number) of cents |
; into a dollar based string |
[format-nat (-> natural-number/c |
(lambda (result) |
(is-decimal-string? result))))]) |
7.2.7 The Difference Between any and any/c
The contract any/c accepts any value, and any is a keyword that can appear in the range of the function contracts (->, ->*, and ->d), so it is natural to wonder what the difference between these two contracts is:
Both allow any result, right? There are two differences:
In the first case, the function may return anything at all, including multiple values. In the second case, the function may return any value, but not more than one. For example, this function:
(define (f x) (values (+ x 1) (- x 1)))
meets the first contract, but not the second one.
Relatedly, this means that a call to a function that has the second contract is not a tail call. So, for example, the following program is an infinite loop that takes only a constant amount of space, but if you replace any with any/c, it uses up all of the memory available.
(module server scheme
[f (-> (-> procedure? any) boolean?)])
(define (f g) (g g)))
(module client scheme
(require 'server)
(f f))
(require 'client)