4.14 Procedures

(procedure? v) → boolean

v : any/c

Returns #t if v is a procedure, #f otherwise.

(apply proc v ... lst) → any

proc : procedure?

v : any/c

lst : list?

The apply Function in A Guide to PLT Scheme introduces apply.

Applies proc using the content of (list* v ... lst) as the (by-position) arguments. The given proc must accept as many arguments as the number of vs plus length of lst, and it must not require any keyword arguments; otherwise, the exn:fail:contract exception is raised. The given proc is called in tail position with respect to the apply call.

Examples:

> (apply + '(1 2 3))

6

> (apply + 1 2 '(3))

6

> (apply + '())

0

(keyword-apply   proc             kw-lst             kw-val-lst             v ...             lst)   →   any

proc : procedure?

kw-lst : (listof keyword?)

kw-val-lst : list?

v : any/c

lst : list?

The apply Function in A Guide to PLT Scheme introduces keyword-apply.

Like apply, but kw-lst and kw-val-lst supply by-keyword arguments in addition to the by-position arguments of the vs and lst. The given kw-lst must be sorted using keyword<, and no keyword can appear twice in kw-lst, otherwise, the exn:fail:contract exception is raised. The given kw-val-lst must have the same length as kw-lst, otherwise, the exn:fail:contract exception is raised. The given proc must accept all of the keywords in kw-lst, it must not require any other keywords, and it must accept as many by-position arguments as supplied via the vs and lst; otherwise, the exn:fail:contract exception is raised.

Examples:

(define (f x #:y y #:z [z 10])     (list x y z))

> (keyword-apply f '(#:y) '(2) '(1))

(1 2 10)

> (keyword-apply f '(#:y #:z) '(2 3) '(1))

(1 2 3)

(procedure-arity proc)

→   (or/c exact-nonnegative-integer?       arity-at-least?       (listof        (or/c exact-nonnegative-integer?              arity-at-least?)))

proc : procedure?

Returns information about the number of by-position arguments accepted by proc. The result a is one of the following:

• An exact non-negative integer, which means that the procedure accepts a arguments, only.

• A arity-at-least instance, which means that the procedure accepts (arity-at-least-value a) or more arguments.

• A list containing integers and arity-at-least instances, which means that the procedure accepts any number of arguments that can match one of the elements of a.

Examples:

> (procedure-arity cons)

2

> (procedure-arity list)

#2(struct:arity-at-least 0)

> (arity-at-least? (procedure-arity list))

#t

> (arity-at-least-value (procedure-arity list))

0

> (arity-at-least-value (procedure-arity (lambda (x . y) x)))

1

> (procedure-arity (case-lambda [(x) 0] [(x y) 1]))

(1 2)

(procedure-arity-includes? proc k) → boolean?

proc : procedure?

k : exact-nonnegative-integer?

Returns #t if the procedure can accept k arguments when no keyword arguments are supplied, #f otherwise.

Examples:

> (procedure-arity-includes? cons 2)

#t

> (procedure-arity-includes? display 3)

#f

(procedure-keywords proc)   →   (values  (listof keyword?)  (or/c (listof keyword?)        false/c))

proc : procedure?

Returns information about the keyword arguments required and accepted by a procedure. The first result is a list of keywords (sorted by keyword<) that are required when applying proc. The second result is a list of accepted keywords (sorted by keyword<), or #f to mean that any keyword is accepted. When the second result is a list, every element in the first list is also in the second list.

Examples:

> (procedure-keywords +)

()

()

> (procedure-keywords (lambda (#:tag t #:mode m) t))

(#:mode #:tag)

(#:mode #:tag)

> (procedure-keywords (lambda (#:tag t #:mode [m #f]) t))

(#:tag)

(#:mode #:tag)

(make-keyword-procedure proc [plain-proc]) → procedure?

proc : (((listof keyword?) list?) list? . ->* . any)

plain-proc   :   procedure?       =   (lambda args (apply proc null null args))

Returns a procedure that accepts all keyword arguments (without requiring any keyword arguments).

When the result is called with keyword arguments, then proc is called; the first argument is a list of keywords sorted by keyword<, the second argument is a parllel list containing a value for each keyword, and the remaining arguments are the by-position arguments.

When the result is called without keyword arguments, then plain-proc is called. Furthermore, procedure-arity obtains its result frmo plain-proc.

Examples:

(define show     (make-keyword-procedure (lambda (kws kw-args . rest)                               (list kws kw-args rest))))

> (show 1)

(() () (1))

> (show #:init 0 1 2 3 #:extra 4)

((#:extra #:init) (4 0) (1 2 3))

(struct   arity-at-least   (value)     #:immutable     #:inspector #f)

value : nonnegative-exact-integer?

This structure type is used for the result of procedure-arity.

prop:procedure : struct-type-property?

A structure type property to indentify structure types whose instances can be applied as procedures. In particular, when procedure? is applied to the instance, the result will be #t, and when an instance is used in the function position of an application expression, a procedure is extracted from the instance and used to complete the procedure call.

If the prop:procedure property value is an integer, it designates a field within the structure that should contain a procedure. The integer must be between 0 (inclusive) and the number of non-automatic fields in the structure type (exclusive, not counting supertype fields). The designated field must also be specified as immutable, so that after an instance of the structure is created, its procedure cannot be changed. (Otherwise, the arity and name of the instance could change, and such mutations are generally not allowed for procedures.) When the instance is used as the procedure in an application expression, the value of the designated field in the instance is used to complete the procedure call. (This procedure can be another structure that acts as a procedure; the immutability of procedure fields disallows cycles in the procedure graph, so that the procedure call will eventually continue with a non-structure procedure.) That procedure receives all of the arguments from the application expression. The procedure’s name (see object-name) and arity (see procedure-arity) are also used for the name and arity of the structure. If the value in the designated field is not a procedure, then the instance behaves like (case-lambda) (i.e., a procedure which does not accept any number of arguments).

Providing an integer proc-spec argument to make-struct-type is the same as both supplying the value with the prop:procedure property and designating the field as immutable (so that a property binding or immutable designation is redundant and disallowed).

Examples:

> (define-struct annotated-proc ([base #:immutable] note)                    #:property prop:procedure (struct-field-index base))

> (define plus1 (make-annotated-proc                     (lambda (x) (+ x 1))                     "adds 1 to its argument"))

> (procedure? plus1)

#t

> (annotated-proc? plus1)

#t

> (plus1 10)

11

> (annotated-proc-note plus1)

"adds 1 to its argument"

When the prop:procedure value is a procedure, it should accept at least one argument. When an instance of the structure is used in an application expression, the property-value procedure is called with the instance as the first argument. The remaining arguments to the property-value procedure are the arguments from the application expression. Thus, if the application expression contained five arguments, the property-value procedure is called with six arguments. The name of the instance (see object-name) is unaffected by the property-value procedure, but the instance’s arity is determined by subtracting one from every possible argument count of the property-value procedure. If the property-value procedure cannot accept at least one argument, then the instance behaves like (case-lambda).

Providing a procedure proc-spec argument to make-struct-type is the same as supplying the value with the prop:procedure property (so that a specific property binding is disallowed).

Examples:

> (define-struct fish (weight color)                    #:property                    prop:procedure                    (lambda (f n) (set-fish-weight! f (+ n (fish-weight f)))))

> (define wanda (make-fish 12 'red))

> (fish? wanda)

#t

> (procedure? wanda)

#t

> (fish-weight wanda)

12

> (for-each wanda '(1 2 3))

> (fish-weight wanda)

18

If a structure type generates procedure instances, then subtypes of the type also generate procedure instances. The instances behave the same as instances of the original type. When a prop:procedure property or non-#f proc-spec is supplied to make-struct-type with a supertype that already behaves as a procedure, the exn:fail:contract exception is raised.

(procedure-struct-type? type) → boolean?

type : struct-type?

Returns #t if instances of the structure type represented by type are procedures (according to procedure?), #f otherwise.