6.7.7 Procedure Properties and Meta-information

In addition to the information that is strictly necessary to run, procedures may have other associated information. For example, the name of a procedure is information not for the procedure, but about the procedure. This meta-information can be accessed via the procedure properties interface.

Scheme Procedure: procedure? obj
C Function: scm_procedure_p (obj)

Return #t if obj is a procedure.

Scheme Procedure: thunk? obj
C Function: scm_thunk_p (obj)

Return #t if obj is a procedure that can be called with zero arguments. See Compiled Procedures, to get more information on what arguments a procedure will accept.

Procedure properties are general properties associated with procedures. These can be the name of a procedure or other relevant information, such as debug hints.

The most general way to associate a property of a procedure is programmatically:

Scheme Procedure: procedure-property proc key
C Function: scm_procedure_property (proc, key)

Return the property of proc with name key, or #f if not found.

Scheme Procedure: set-procedure-property! proc key value
C Function: scm_set_procedure_property_x (proc, key, value)

Set proc’s property named key to value.

However, there is a more efficient interface that allows constant properties to be embedded into compiled binaries in a way that does not incur any overhead until someone asks for the property: initial non-tail elements of the body of a lambda expression that are literal vectors of pairs are interpreted as declaring procedure properties. This is easiest to see with an example:

(define proc
  (lambda args
    #((a . "hey") (b . "ho")) ;; procedure properties!
    42))
(procedure-property proc 'a) ; ⇒ "hey"
(procedure-property proc 'b) ; ⇒ "ho"

There is a shorthand for declaring the documentation property, which is a literal string instead of a literal vector:

(define proc
  (lambda args
    "This is a docstring."
    42))
(procedure-property proc 'documentation)
;; ⇒ "This is a docstring."

Calling procedure-property with a key of documentation is exactly the same as calling procedure-documentation. Similarly, procedure-name is the same as the name procedure property, and procedure-source is for the source property.

Scheme Procedure: procedure-name proc
C Function: scm_procedure_name (proc)
Scheme Procedure: procedure-source proc
C Function: scm_procedure_source (proc)
Scheme Procedure: procedure-documentation proc
C Function: scm_procedure_documentation (proc)

Return the value of the name, source, or documentation property for proc, or #f if no property is set.

One can also work on the entire set of procedure properties.

Scheme Procedure: procedure-properties proc
C Function: scm_procedure_properties (proc)

Return the properties associated with proc, as an association list.

Scheme Procedure: set-procedure-properties! proc alist
C Function: scm_set_procedure_properties_x (proc, alist)

Set proc’s property list to alist.