Debian Codegraph @

doc/source/design/lint-sub-command.rst

raw
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: