8.12
1 The Syntax Warnings Reference
| (require syntax/warn) | |
| packages: syntax-warn, syntax-warn-base | |
This module defines the programmatic API for adding syntax warnings to syntax objects. Warnings added via this library can be detected and manipulated by the tools outlined in The Syntax Warning Command Line Interface.
procedure
(syntax-warning #:message message #:stx stx [ #:kind kind #:fix fix]) → syntax-warning? message : string? stx : syntax? kind : warning-kind? = #f fix : syntax? = #f
Constructs a syntax warning of kind kind that identifies
stx as the syntax to blame and fix as a suggested replacement
to use in place of stx. If kind is not provided, the warning
doesn’t declare itself as having a particular kind. If fix is not
provided, the warning makes no suggestions about how to resolve it.
procedure
(syntax-warning? v) → boolean?
v : any/c
Predicate that recognizes syntax warnings.
procedure
(syntax-warning/fix? v) → boolean?
v : any/c
Predicate that recognizes syntax warnings that include a suggested
fix.
procedure
(syntax-warning-message warning) → string?
warning : syntax-warning?
procedure
(syntax-warning-stx warning) → syntax?
warning : syntax-warning?
procedure
(syntax-warning-kind warning) → (or/c warning-kind? #f)
warning : syntax-warning?
procedure
(syntax-warning-fix warning) → (or/c syntax? #f)
warning : syntax-warning?
Accessors for fields of syntax warnings.
value
Predicate recognizing warning kinds.
syntax
(define-warning-kind id)
Binds id as a warning kind, a value that
can be used to classify similar warnings. The warning kind has a name,
which is the quoted form of id. The raco warn tool uses
warning kind names in its output.
procedure
(warning-kind-name kind) → symbol?
kind : warning-kind?
Returns the name of kind.
procedure
(syntax-warn stx warning) → syntax?
stx : syntax? warning : syntax-warning?
Returns a syntax object equivalent to stx, but with warning
attached as a syntax warning. The syntax warning need not blame
stx as the source of the problem, this procedure merely provides the
ability to attach warnings to syntax objects via syntax properties.
Examples:
> (define-warning-kind identifier-capitalization-warning)
> (syntax-warn #'(foo Bar) (syntax-warning #:message "Don't capitalize the \"Bar\" identifier" #:stx #'foo #:kind identifier-capitalization-warning)) #<syntax:eval:2:0 (foo Bar)>
procedure
(syntax-warnings stx) → (listof syntax?)
stx : syntax?
Returns a list of all syntax warnings present in stx. This includes
syntax warnings in any syntax objects nested within stx.
procedure
(read-syntax-warnings [ #:input-port in #:source-name source #:namespace namespace]) → (listof syntax-warning?) in : input-port? = (current-input-port) source : any/c = (object-name in) namespace : namespace? = (current-namespace)
Constructs a syntax object from in using read-syntax, fully
expands it using expand-syntax in namespace, and returns a
list of all syntax warnings found in the fully expanded module.
procedure
(read-syntax-warnings/file filepath [ #:namespace namespace]) → (listof syntax-warning?) filepath : path-string? namespace : namespace? = (current-namespace)
Like read-syntax-warnings, but reads filepath as a module.
Sets the current-directory to the directory part of filepath
and uses filepath as the source name.
procedure
(warning-config? v) → boolean?
v : any/c
Predicate that recognizes warning configurations,
values used to control the behavior of tools that analyze syntax warnings.
Configurations from different souces may be merged with
warning-config-merge. Currently, warning configurations contain
information about what kinds of warnings should be suppressed or unsuppressed
(in the case of warnings that aren’t on by default). See suppress
and unsuppress for details on how to construct these configurations.
procedure
(warning-config-merge config ...) → warning-config?
config : warning-config?
Merges the given config values into a single warning
configuration. In the case of more than one config attempting to
suppress or unsuppress a warning kind, the rightmost configuration takes
precedence. Merging any config with the empty-warning-config is
equivalent to leaving the config unchanged. If no configurations are provided,
returns empty-warning-config.
The empty warning config. Represents no changes from default behavior.
procedure
(suppress kind ...) → warning-config?
kind : (or/c warning-kind? symbol?)
procedure
(unsuppress kind ...) → warning-config?
kind : (or/c warning-kind? symbol?)
Constructs a warning configuration where warnings of each of the
given kinds is either suppressed or unsuppressed, depending on the
function called. Warnings may be suppressed using an explicit warning kind
value or suppressed by a symbol representing the name of the warning kind to
suppress. Symbols allow configuration sources to construct warning kind configs
without access to the warning kind bindings. To suppress some warnings and
unsuppress others, see warning-config-merge.
procedure
(filter-unsuppressed-warnings warnings config) → (listof syntax-warning?) warnings : (listof syntax-warning?) config : warning-config?