| 1 |
.. _lint-sub-command: |
| 2 |
|
| 3 |
lint sub-command |
| 4 |
================ |
| 5 |
|
| 6 |
Goal is to provide a :subcmd:`lint` sub-command to check syntax of |
| 7 |
modulefiles. |
| 8 |
|
| 9 |
|
| 10 |
Configuration |
| 11 |
------------- |
| 12 |
|
| 13 |
* :mconfig:`tcl_linter` configuration option defines linter program to use and |
| 14 |
its options |
| 15 |
|
| 16 |
* ``nagelfar.tcl`` is the default |
| 17 |
* :instopt:`--with-tcl-linter` and :instopt:`--with-tcl-linter-opts` |
| 18 |
installation options help to change this default at installation time |
| 19 |
* When changed with :subcmd:`config` sub-command, :envvar:`MODULES_LINTER` |
| 20 |
environment variable is set |
| 21 |
|
| 22 |
* Tcl linter program defined is checked for existence by ``configure`` script |
| 23 |
|
| 24 |
* Use fully qualified path resolved if found |
| 25 |
* Print a warning message if not found |
| 26 |
* No error if not found as :subcmd:`lint` is not the central use case |
| 27 |
|
| 28 |
* Could be configured or installed after Modules installation |
| 29 |
|
| 30 |
* :instopt:`--enable-nagelfar-addons` installation option defines if |
| 31 |
Nagelfar-specific syntax databases and plugins to lint modulefiles have to |
| 32 |
be installed. |
| 33 |
|
| 34 |
* Specific syntax databases and plugins to lint modulefiles, modulerc, |
| 35 |
modulecache and global/user rc are not enabled if this option is disabled |
| 36 |
|
| 37 |
* :instopt:`--nagelfardatadir` installation option defines where to install |
| 38 |
Nagelfar-specific files to lint modulefiles. |
| 39 |
|
| 40 |
|
| 41 |
Sub-command properties |
| 42 |
---------------------- |
| 43 |
|
| 44 |
General properties: |
| 45 |
|
| 46 |
* Shortcut name: none |
| 47 |
* Accepted option: ``--all``, ``--icase`` |
| 48 |
* Expected number of argument: 0 to N |
| 49 |
* Accept boolean variant specification: no |
| 50 |
* Parse module version specification: yes |
| 51 |
* Fully read modulefile when checking validity: no |
| 52 |
* Sub-command only called from top level: yes |
| 53 |
|
| 54 |
Sub-command acts similarly than :subcmd:`edit` sub-command: |
| 55 |
|
| 56 |
* Resolves each specification passed as argument to a single modulefile |
| 57 |
* Modulefile could be specified with icase, extended_default and |
| 58 |
advanced_version_spec features |
| 59 |
|
| 60 |
* But no boolean specification, as we are looking for modulefiles, not a |
| 61 |
module variant |
| 62 |
|
| 63 |
* Call an external command over the resolved modulefiles |
| 64 |
|
| 65 |
In case no argument is provided, it means to select everything: |
| 66 |
|
| 67 |
* Every global and user rc file |
| 68 |
* Every .modulecache in enabled modulepaths |
| 69 |
* Every .modulerc and .version files in enabled modulepaths |
| 70 |
* Every available modulefiles in enabled modulepaths |
| 71 |
* Include modules declared forbidden |
| 72 |
* If ``--all`` option set also select all hidden modulefiles in enabled |
| 73 |
modulepaths |
| 74 |
|
| 75 |
Arguments could also be a file path: |
| 76 |
|
| 77 |
* need to distinguish if it is a global/user rc file, a modulerc or a |
| 78 |
modulefile to accurately lint designated file |
| 79 |
* file is considered a global/user rc file if file path corresponds to user or |
| 80 |
global rc file location |
| 81 |
* file is considered a modulerc if filename equals ``.version`` or |
| 82 |
``.modulerc`` |
| 83 |
* file is considered a modulecache if filename equals ``.modulecache`` |
| 84 |
* otherwise file is considered a modulefile |
| 85 |
|
| 86 |
Processing is aborted as soon as one lint command execution fails |
| 87 |
|
| 88 |
|
| 89 |
Nagelfar linting |
| 90 |
---------------- |
| 91 |
|
| 92 |
* Analyze full content of designated files |
| 93 |
* It does not evaluate files sourced by designated files |
| 94 |
* If :instopt:`--enable-nagelfar-addons` is enabled (default) a specific |
| 95 |
syntax database and plugin is added to the Nagelfar command line to lint |
| 96 |
specified file depending on its type (global/user rc, modulerc, modulecache |
| 97 |
or modulefile) |
| 98 |
|
| 99 |
* Modulefile command, their options and syntaxes are checked based on this |
| 100 |
file type |
| 101 |
* Since not the same command set can be used in global/user rc file, in |
| 102 |
modulerc, modulecache and modulefile |
| 103 |
|
| 104 |
|
| 105 |
Report output |
| 106 |
------------- |
| 107 |
|
| 108 |
* New message block: ``Linting <modulefile>`` |
| 109 |
* All messages produced by Nagelfar reported under modulefile message block |
| 110 |
* Parse Nagelfar messages to report in a structured way: |
| 111 |
|
| 112 |
* ``<SEVERITY> line <line_number>: message`` |
| 113 |
* Message is output as a block in case it consists of several lines |
| 114 |
* All message prefix (prior ``:``) is highlighted based on severity |
| 115 |
* Nagelfar severities mapped to Modules severities: |
| 116 |
|
| 117 |
* W = WARNING (sgrkey: wa) |
| 118 |
* E = ERROR (sgrkey: er) |
| 119 |
* N = NOTICE (sgrkey: in) |
| 120 |
|
| 121 |
* Output and verbosity levels: |
| 122 |
|
| 123 |
* By default, do not output message block if no message to report for |
| 124 |
modulefile |
| 125 |
* If verbose mode set, report empty block if no linting message |
| 126 |
* If silent mode set, report nothing, exit code helps to know if linter has |
| 127 |
reported error |
| 128 |
|
| 129 |
.. vim:set tabstop=2 shiftwidth=2 expandtab autoindent: |