Inline Comments¶
Nagelfar supports having comments inlined in the checked source to help it check a file.
Whenever <file>.tcl is checked, any <file>.syntax is run through the syntax checker first. Thus you can put your comments in such a separate file instead of your source if that is not suitable.
A comment should start with “##nagelfar” to be recognized as special. The comment must be a valid Tcl list.
Ignoring messages¶
##nagelfar ignore ?string?
##nagelfar filter ?string?
These two are equivalent and adds a message filter rule for the line following it. The string argument will be part of the filter pattern, which is a glob pattern built like this: “Line $line:$string” If the string is preceded by “N”, “W” or “E”, anything from that severity level and down is ignored. If the string is preceded by an offset like “+2”, a line further down is marked for filtering. No given offset corresponds to “+1”. If the string is preceeded by a count like “#2”, multiple following lines are marked for filtering. No given range corresponds to “#1”. Note: All Inline Comments are lists, and string is formed by joining that list. Thus special chars may need quoting.
Examples:
##nagelfar ignore
set apa [Miffo a b c]
##nagelfar ignore Unknown variable
set apa [lindex $Gurka 1]
##nagelfar ignore Expr without braces
set apa [expr 1 + 2]
##nagelfar ignore N
Nagelfar also recognizes “# PRAGMA: nocheck”, which is equivalent to “##nagelfar ignore”, and ignores messages on the next line.
Specifying variables¶
##nagelfar variable name ?type?
This will make “name” a known variable and optionally set its type. Types are still experimental in Nagelfar. The type “varName” can be used to tell Nagelfar that a variable contains a variable name, which suppresses some warnings.
Example:
##nagelfar variable apaName varName
set hejsan [set $apaName]
##nagelfar vartype name type
This will set the type of the variable “name”. The variable must already be known. Using “variable” for just annotating the type could mask bugs since you will not notice if the variable is missing.
Example:
set apaName [somethingThatReturnsAVarName]
##nagelfar vartype apaName varName
set hejsan [set $apaName]
The latter can also be achieved by specifying the return type for the called command:
##nagelfar return somethingThatReturnsAVarName varName
Special variable types¶
Some variable types are recognised as special by Nagelfar. E.g. “varName” as described above. Another type is “script” which also suppresses some warnings, as well as “option”.
set mode -real
##nagelfar vartype mode option
set hejsan [lsort $mode $lst]
##nagelfar return miffo script
trace add variable apa write [miffo x y]
Specifying implicit variables¶
##nagelfar implicitvarcmd pattern var ?var ...?
Some commands will dynamically create variables that are impossible to predict from static checking. By restricting such usage to a known pattern in your code, it can become checkable by this annotation. The pattern is a glob pattern applied to any statement encountered and if matched will make the listed variables known.
Example:
##nagelfar implicitvarcmd {dict with *Stat {}} name size value
dict with fileStat {}
dostuffwith $name $size $value
Syntax database¶
##nagelfar syntax cmd tokens
##nagelfar subcmd cmd subcmds
##nagelfar subcmd+ cmd subcmds
##nagelfar option cmd options
##nagelfar option+ cmd options
##nagelfar return cmd type
##nagelfar copy from to
All these provides access directly into the syntax database that usually is loaded from syntaxdb.tcl. Check Syntax Tokens and syntaxbuild.tcl for more info.
Examples:
##nagelfar syntax binary s x*
##nagelfar subcmd binary format scan
##nagelfar syntax binary\ scan x x n n*
##nagelfar syntax fcopy x x p*
##nagelfar option fcopy -size -command
Add to subcmd list, e.g. when using namespace ensemble:
##nagelfar subcmd+ string mysubcmd
##nagelfar syntax string\ mysubcmd x x
Copy syntax from command, with added option.
##nagelfar copy binary mybinary
##nagelfar option+ mybinary -mysuperflag
For more examples, use the database browser to see how the comments would look like for the commands known in the database.
Package handling¶
To mark a package as known, use the following. Any subsequent package require for this package will assume it is already there.
##nagelfar package known snit
To trigger loading of a package database, use the following. It is equivalent to encountering the same package require in the code.
##nagelfar package require snit
Other handling¶
Nagelfar tries to pick up namespace path commands to track command resolution. It is possible to manually provide namespace path information, as shown below. If the namespace is given as “current”, the surrounding namespace where the inline comment resides is used.
##nagelfar nspath ns paths
# A line like this is recognised:
namespace path [list {*}[namespace path] ::apa]
# The corresponing inline directive would be:
##nagelfar nspath current ::apa
- When -WunusedVar is active missing read detections can be added with
##nagelfar varused <name>