Syntax Warnings

This library includes forms and functions for working with syntax warnings. A syntax warning is a compile-time source code annotation meant to draw attention to potential defects. Syntax warnings can be used to point out bad code style, sub-optimal constructs, excessively verbose code, or use of deprecated features. Additionally included in this library are the raco warn and raco fix commands for finding and fixing warnings, and the #lang racket/base/warn language which provides many forms in racket/base with warnings attached in various ways.

Source code for this library is avaible at https://github.com/jackfirth/syntax-warn

This library is provided as several packages. These packages are organized as follows:

• syntax-warn-base — The core API of syntax warnings, as defined by the syntax/warn module.

• syntax-warn-cli — The raco command line tools for working with warnings.

• syntax-warn-lang — The racket/base/warn language.

• syntax-warn-doc — The documentation part of the library.

• syntax-warn — A wrapper package that implies installation of all of the above packages.

1 The Syntax Warnings Reference

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.

2 The Syntax Warning Command Line Interface

This document describes the raco warn and raco fix commands. This commands allow a programmer to check for syntax warnings and, where possible, automatically fix them. The two commands are designed to work together - when raco warn outputs no warnings, raco fix makes no changes to any modules. Additionally, both commands accept the same flags for specifying which modules to check.

2.1 raco warn: Checking Syntax Warnings

The raco warn command searches for syntax warnings in a specified set of modules. Any found warnings are displayed with a message, the offending source code, and a suggested fix (if present). If any warnings are found the command exits as a failure, making it suitable for use in continuous integration systems.

Not all warnings need cause a failure. The raco warn command allows certain warnings to be suppressed by configuration. For every module that raco warn examines, the command looks for a warning configuration value named config provided by that module’s 'warning-config submodule. If this module or the expected binding isn’t present, empty-warning-config is used. This allows for per-module suppression of particular kinds of warnings, see the documentation of warning-config for details. Warnings may also be suppressed via command line flags.

The raco warn command accepts any number of arguments along with the following flags:

• --arg-kind — Sets how to interpret the given arguments. Defaults to "collection". Valid interpretation modes are:

  • "file" — Each argument is interpreted as a relative or absolute file path to a module.

  • "directory" — Each argument is interpreted as a relative or absolute directory path, which is recursively scanned for modules. All files in the given directories are assumed to be modules.

  • "collection" — Each argument is interpreted as a collection, whose modules are checked recursively.

  • "package" — Each argument is interpreted as a package, whose modules are checked recursively.

• -f or --files — Shorthand for --arg-kind file.

• -d or --directories — Shorthand for --arg-kind directory.

• -c or --collections — Shorthand for --arg-kind collection.

• -p or --packages — Shorthand for --arg-kind package.

• --config-submod — Sets the name of the submodule to look for warning configuration in. Required prior to loading of the surrounding module to check. Defaults to 'warning-config.

• --config-submod-binding — Sets the name of the value to look for in the warning configuration submodule. Defaults to config. The warning configuration submodule should provide a warning-configuration? value under this name.

• --suppress — Repeated, sets a list of warning kinds to suppress. Example usage: raco warn --suppress foo --suppress bar -p some-package.

• --unsuppress — Like --suppress but for unsuppressing warnings. Use this to turn back on warnings that module configuration turned off.

2.2 raco fix: Fixing Syntax Warnings

The raco fix command searches for syntax warnings in a specified set of modules and fixes them, if possible. For each module checked, the set of warnings is filtered to only warnings with suggested fixes that won’t interfere with each other. For instance, if two warnings suggest changing the same piece of code, raco fix will either fix one of the warnings if its affected source code fully encompasses the other warning’s source code, or fix neither warning if they only partially overlap. The raco fix command also accepts a run mode argument that can configure how raco fix applies changes, if at all.

The raco fix command accepts any number of arguments along with the following flags:

• --arg-kind — Sets how to interpret the given arguments. This flag accepts the same values and has the same default as it does for raco warn. Additionally, the same shorthand flags for the various values are accepted.

• --run-mode — Sets how to handle fixable warnings. Valid options are:

  • "wet" — Default behavior. Write any found fixes to the module files indicated by source locations.

  • "dry" — Operate as a dry run. In a dry run, raco fix performs no file writes and merely outputs what it would fix in which modules.

• -D or --dry — Shorthand for --run-mode dry.

• -E or --wet — Shorthand for --run-mode wet.

In addition, the raco fix command looks for warning configuration in the same way as raco warn with the same flags to control this behavior. Warnings can also be suppressed and unsuppressed with direct flags in the same manner as raco warn.

3 The Syntax Warnings Language

This library provides a variant of the racket/base language that adds syntax warning wrappers around various forms. For example, the require binding introduced by this language enforces a few "good style" practices around require clauses.

When racket/base/warn is used as a #lang language, everything from racket/base is provided. Various forms are adjusted to attach syntax warnings in certain cases. Warning kinds for these warnings are also exported.