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.