Next: cbb invocation, Up: Scanning for boilerplate [Index]
boilerplate: Show or remove boilerplate in source filesThe boilerplate command shows the comments at the top of source code files. The most common execution of this command is:
$ licensing boilerplate foo.c
The boilerplate command will automatically determine what kind of comment-style is being employed at the beginning of the source code file. This automatic detection has some drawbacks, so various commenting-style options are provided to force the detection of comments in a particular commenting style. See Common Commenting-style options.
Automatic detection of commenting-styles is a heursitic that checks for commenting-styles in a certain order, sometimes avoids paritcular file extensions, and sometimes only operates on certain supported file extensions. The order for automatic detection is: C, C++, javacsript, shell, scheme, texinfo, m4, haskell, groff, gettext, fortran, pascal.
C style comments are featured in other languages: Java, PHP, Javascript, Go, and many more. Shell style commenting is used in python, make, perl, and more.
When auto-detecting shell style comments will not be found in files with extensions: ‘.c .h .cpp .hpp .hh .cc .m4 .ac .po .pot’. M4 comments can only be found in files with extensions: ‘.m4 .ac’. Fortran comments can only be found in files with extensions: ‘.f .for .f90 .f95’. These strategies fail when files are passed via the standard input: e.g. when the file is -.
The boilerplate command can also remove boilerplate from one or more source code files by specifying the --remove option. For example:
$ licensing boilerplate --remove foo.c
By default the commenting style is auto-detected, but each of the commenting style options can be used to remove comment blocks of a specific commenting style. Particular comment blocks can be removed with the --blocks option. The --force option is used to remove comment blocks that contain copyright notices. When removing boilerplate, a backup file (‘.bak’) is usually made. The --no-backup option is provided to prevent this behaviour. When removing boilerplate from the standard input it cannot be backed up, and the resulting file is simply displayed.
The --quiet option prevents error messaging from being displayed when a boilerplate is not found, or an invalid comment-block is referred to with the --blocks option, or when removing a comment-block that contains a copyright notice and the --force option has not been given.
Sometimes the start of a source code file can have more than one comment-block. Block-style comments denote a comment-block, and whitespace separates blocks of whole-line comments.
The --blocks option can show or remove one or more comment-blocks.
For example ‘licensing boilerplate -b1 foo.c’ shows the first comment-block. And ‘licensing boilerplate -b1,3 foo.c’ shows the first and third comment-blocks. ‘licensing boilerplate --remove --blocks=1-3,5 foo.c’ removes the first three comment-blocks, and the fifth comment-block too.
Whitespace between comment-blocks is not shown when the --blocks option is employed.
To find out how many comment-blocks there are in a file, use the cbb command. See cbb invocation for more information.
When the source code file begins with a ‘#!’ line, the boilerplate command does not show or remove that line.
Next: cbb invocation, Up: Scanning for boilerplate [Index]