filter-declaration-env

Next: map-declaration-env, Previous: declaration-env.policy, Up: API

Syntax

— Function: filter-declaration-env declenv &key affecting not-affecting (include :everything) exclude filter-function

⇒ result-env

Arguments and Values

declenv: A declaration-env.
affecting: A list of normalized binding names.
not-affecting: A list of normalized binding names.
include: Either one of the keywords :everything, :bound, :free, :unknown, or a list of normalized declaration identifiers.
exclude: Either one of the keywords :everything, :bound, :free, :unknown, or a list of normalized declaration identifiers.
filter-function: A function designator for a function with three arguments.
result-env: A fresh declaration-env.

Description

The function filter-declaration-env returns a new declaration-env containing a subset of the declaration specifiers in declenv according to a filtering constituted by the given parameters.

include specifies the declaration specifiers to be considered by the filtering. They can be specified either directly via a list of identifiers, or via a keyword representing a certain set of specifiers. These keywords are:

:bound: Represents the bound declaration specifiers in declenv
:everything: Represents all declaration specifiers in declenv.
:free: Represents the free declaration specifiers in declenv,
:unknown: Represents the unknown declaration specifiers in declenv.

exclude specifies the declaration specifiers to be not considered.

affecting, if given, specifies the set of binding names that the declaration specifiers in the resulting declaration-env must affect. Consequently, only bound declaration specifiers are selected.

not-affecting, if given, specifies the set of binding names that the resulting specifiers must not affect. This possibly includes free declaration specifiers and unknown declaration specifiers

filter-function is called for each declaration specifier in declenv that satisfies the other given parameters. It should return true if this specifier should be included in the resulting declaration-env. The function is invoked with the disassembled parts of this specifier, cf. analyze-declaration-specifier.

Examples

  PARSE-DECLARATIONS> (defparameter *sample-decls*
                        '((declare (optimize (speed 3) (safety 0)))
                          (declare (special *a*) (special *f*))
                          (declare (inline f))
                          (declare (author "Tobias C Rittweiler"))
                          (declare (type integer x y))
                          (declare (optimize (debug 0)))
                          (declare (type fixnum z))
                          (declare ((string 512) output))
                          (declare (type (vector unsigned-byte 32) chunk))
                          (declare (quux *a*))   ; assuming QUUX hasn't been defined as type.
                          (declare (float *f*))
                          (declare (ftype (function (number) float) f))
                          ))
  => *SAMPLE-DECLS*
  PARSE-DECLARATIONS> (defparameter *env* (parse-declarations *sample-decls*))
  => *ENV*
  
  PARSE-DECLARATIONS> (build-declarations 'declare (filter-declaration-env *env* :include :free))
  => ((DECLARE (OPTIMIZE (DEBUG 0))) (DECLARE (OPTIMIZE (SPEED 3) (SAFETY 0))))
  
  PARSE-DECLARATIONS> (build-declarations 'declare (filter-declaration-env *env* :include :unknown))
  => ((DECLARE (QUUX *A*)) (DECLARE (AUTHOR "Tobias C Rittweiler")))
  
  PARSE-DECLARATIONS> (build-declarations 'declare (filter-declaration-env *env* :affecting '(*a*)))
  => ((DECLARE (SPECIAL *A*)))
  
  PARSE-DECLARATIONS> (build-declarations 'declare (filter-declaration-env *env* :affecting '(*f*)))
  => ((DECLARE (TYPE FLOAT *F*)) (DECLARE (SPECIAL *F*)))
  
  PARSE-DECLARATIONS> (build-declarations 'declare (filter-declaration-env *env* :affecting '(#'f)))
  => ((DECLARE (INLINE F)) (DECLARE (FTYPE (FUNCTION (NUMBER) FLOAT) F)))
  
  PARSE-DECLARATIONS> (build-declarations 'declare (filter-declaration-env *env*
                                                      :affecting '(#'f)
                                                      :exclude '(inline notinline)))
  => ((DECLARE (FTYPE (FUNCTION (NUMBER) FLOAT) F)))
  
  PARSE-DECLARATIONS> (build-declarations 'declare (filter-declaration-env *env* :include '(type)))
  => ((DECLARE (TYPE FLOAT *F*)) (DECLARE (TYPE (VECTOR UNSIGNED-BYTE 32) CHUNK))
      (DECLARE (TYPE (STRING 512) OUTPUT)) (DECLARE (TYPE FIXNUM Z))
      (DECLARE (TYPE INTEGER X Y)))

Exceptional Situations

Signals an error of type TYPE-ERROR if a passed argument violates its respective entry in the “Arguments and Values” section.

Notes

If no &key parameter is given, filter-declaration-env will return a copy of the given declaration-env. This follows from the default values of the parameters.