This is the AdaCore Style Checker (ASC). It provides a small program called style_checker whose purpose is to first identify the type of file being checked based on the file's extension, and then apply a number of style checks dependent on the type of file being checked.
The program is designed to be easily callable from git or SVN hooks to validate changes at time of commit or push. It is therefore intentionally agnostic of any version control system.
The simplest way to use this tool is to call with a module name, and a list of files belonging to that module that need to be checked.
For instance:
$ style_checker module file1.py file2.ads
By convention, the name of the module is typically the name of
the repository containing the files being checked. But it can be
any arbitrary name. It just needs to remain consistent, asi
this module name, as it used to read the etc/asc_config.yaml
configuration file to check for module-specific configuration.
Another option for calling the style checker is to pass the list of files via stdin, instead of via the command line. This mode is mostly there to avoid any system limitation while trying to call this script with a large number of files. This is very useful in the context of version control hooks, where it can save a significant amount of time calling the style_checker once for all files, rather than once per file.
For more information on how to use the style_checker, see the output of
$ style_checker --help
The AdaCore Style Checker provides a configuration for use with pre-commit to enable automatic style checking locally as a pre-commit check before a commit is created.
To configure ASC for your repository, create a file called
.pre-commit-config.yaml
at the root of your repository with the following
content (or append to a pre-existing yaml file):
repos:
- repo: https://github.com/AdaCore/style_checker.git
rev: master
hooks:
- id: adacore-style-checker
alias: asc
args:
- "<your module name>"
To activate ASC in a local checkout of a repository pre-configured as above, install pre-commit (alternate installation methods exist at the pre-commit website):
$ pip install pre-commit
And run this at the root of the checkout:
$ pre-commit install
Pre-commit will now run ASC at each git commit
invocation. You can also run it
manually with:
$ pre-commit run --all-files
$ pre-commit run --files ...
More information on pre-commit is available at https://pre-commit.com/.
Turning Style Checks Off ........................
Style checks can be disabled for any given file by writing the following comment in the first or second line of that Python file (the comment must be written exactly as is, with no changes in indentation and no trailing spaces at the end):
// No_Style_Check
Python Fragments ................
Files ending with a .plan
, or .frag.py
extension, or files where
the first or second line starts with # Style_Check:Python_Fragment
are considered Python fragments, meanning that these files contain python
code, but this code is not necessarily complete or self-sufficient.
For those files, the violations which can legitimately occur because they are fragments (e.g. undefined name) are excluded from the list of errors being reported.
Turning Style Checks Off ........................
Style checks can be disabled for any given file by writing the following comment in the first or second line of that Python file (the comment must be written exactly as is, with no changes in indentation and no trailing spaces at the end):
# No_Style_Check
The AdaCore Style Checker starts by reading a system configuration file, which provides a default configuration for all the modules using this style checker.
By default, this system configuration is located in...
<prefix>/etc/asc_config.yaml
... where <prefix>
is the location where the Style Checker
was installed.
This configuration file is a YaML file. When loaded, the Style
Checker first processes the special section named '*'
.
Once this section is processed, it looks for a section whose name is the same as the name of the module passed on the command-line; if found, the Style_Checker processes this section as well.
Note that handling of module-specific sections in the system
configuration file is now deprecated, in favor of module-specific
configuration files (see below). We are planning on removing this
feature soon. This will allow us to remove the need for the special
section '*'
, and thus have the exact same syntax for both
the system configuration file, and the module-specific configuration
file.
For modules that need a Style Checker with options that deviate
from the default (system) configuration, a command-line option
(--config
) tells style_checker
to load this file after the
system configuration file has been loaded. Eg:
$ style_checker --config module_asc_config.yaml module file.py
The configuration provided by the module-specific config file is applied on top of the system configuration, meaning that it does not need to repeat the default configuration.
This configuration file is also a YaML file, and its contents follows the same principles as in the system configuration file.
The Style Checker provides support for checking a number of "rules"
(Eg: copyright headers, end-of-line characters, trailing spaces).
The Style Checker is set up to use a sub-set of those rules which
depends on the type of file (Ada, Python, Shell, etc) being checked.
You can check which rules are being checked for each type of file
using the --dump-checks
command-line option.
If one or more of those rules do not apply to a given module,
create a section called style_checks
in the module's configuration
file. This section should contain a list of the checks that should
be disabled. The name of the check to be disabled can be found
in the output of --dump-checks
(see the "Legend:" section at
the bottom), and should be preceded with the character -
(minus).
For instance, to disable copyright header checks and end-of-line checks, create the following section in your module-specific configuration file:
style_checks:
- -copyright
- -eol
Part of the Style Checks performed when checking Ada files are done
by using the GNAT compiler. How the compiler gets called can be
adjusted for each project by adding one or more of the following
entries in the style_checks
section.
For instance, to call the GNAT compiler in Ada 95 module and with
the -gnatX
option, your style_checks
section should look like
this:
style_checks:
- gnat95
- gnatx
Below are the different configuration options that can be used:
gnatx
(compile the code with-gnatX
)gnat95
(compile the code with-gnat95
; the default is-gnat12
)gnat05
(compile the code with-gnat05
; the default is-gnat12
)gnat12
(compile the code with-gnat12
; the default is-gnat12
)gnat2020
(compile the code with-gnat2020
; the default is-gnat12
)
The default configuration for the copyright header checks can
be found in the system configuration file under the
copyright_header_info
section (a dictionary). It is configured
to expect copyright headers following the AdaCore conventions.
You can either change the default configuration entirely, expand
from it, or anything in between. For this, just create a
copyright_header_info
section in the module-specific configuration
file, and use the same options as in the system configuration file.
For configuration options which are lists, you can prepend them
with a '+'
, which indicates that we are adding to the system
configuration. For instance, the following exerpt indicates that
the "format_help" configuration consists of the format_help
default loaded from the system configuration file, to which
we are adding the following two new alternatives:
copyright_header_info:
+format_help:
# EPL with a single year...
- 'Copyright (c) %(year)d '
# EPL with a range of years year...
- 'Copyright (c) 2014, %(year)d '
The following configuration options are supported:
-
max_lines
[int]: The maximum number of lines after which the Style Checker stops looking for a valid copyright header. -
holders
[list]: A list of valid copyright holders. Each entry is one possible acceptable copyright holder. -
present_re
[list]: A list of regular expressions detecting what looks like a copyright line. Each entry is one alternative of a possible copyright lineThat copyright line may or may not be correctly formed; each regular expression is only used as a way to perform preliminary detection of lines that might contain a copyright header.
-
copyright_re
[list]: A list of regular expressions matching a correctly formed copyright line. Each entry is one alternative of a valid copyright line.Please refer to the system configuration file for a description of the format of those regular expressions, and in particular of some of the assumptions made by the Style Checker (used to help extract some of the information from the copyright line).
-
format_help
[list]: A list of template strings telling the user what format the copyright line should follow. These strings are there to help the user write a correctly formed copyright holder by providing templates of what the copyright line should look like when the copyright line that he used was not valid.Please refer to the system configuration file for a description of the format of those strings.