Introduction and Overview
nano-colour is a command-line syntax highlighter which reads nano syntax definition files and writes ANSI-coloured text to standard output. It is intended for terminal viewing, filters and pipeline use where nano-style syntax colouring is useful outside the editor itself.
The command selects a syntax either explicitly or by matching the target file against the syntax and header rules present in nanorc files. It then applies the colour rules to the input stream and emits ordinary text with ANSI escape sequences inserted where colour changes are required.
Technical Details
The command reads nanorc definitions from either the path supplied on the command line or the NANOCOLOUR_DIR environment variable. The supplied path may identify a single nanorc file or a directory containing files whose names end in .nanorc, together with a file named nanorc.
Syntax selection
If -s or --syntax is supplied, the named syntax is used directly. Otherwise the command attempts automatic selection in two stages.
First, the path supplied as the target file is matched against the regular expressions from each syntax command. If no match is found, the command reads the first line of the target file and compares it with each header expression. The first matching syntax is selected.
When no syntax is identified, normal text is copied to standard output unchanged. However, if --supported is used, the command exits with failure instead of producing output.
Input handling
The target file may be a host file path or - to read from standard input. Automatic syntax detection depends on the supplied file path and, for header matching, on the first line of a real file. When reading from standard input, explicit syntax selection is therefore the normal mode of operation.
If no target file is supplied, the command is only valid when either --supported is being used or an explicit syntax has been requested. In the latter case input is read from standard input.
Nanorc syntax and colours
Nanorc files may include other files through the include directive. Relative include paths are resolved relative to the including file, and a leading ~ is expanded using the caller's HOME environment variable.
The command recognises the subset of nanorc syntax that it needs for syntax discovery and colour application.
| Directive | Meaning |
|---|---|
| include path | Load another nanorc file. Relative paths are interpreted relative to the file containing the directive. |
| syntax "name" ["fileregex" ...] | Begin a syntax definition named name. Any following file regular expressions are used for automatic syntax selection. |
| header "regex" ... | Add one or more header-matching expressions for the current syntax. These are compared with the first line of the target file if no file-pattern match succeeds. |
| comment "string" | Accepted in nanorc files, but not used by nano-colour when colouring output. |
| color colour-spec "regex" ... | Apply the specified colours to each match of the regular expression or expressions. |
| icolor colour-spec "regex" ... | As for color, but regular-expression matching is case-insensitive. |
| color colour-spec start="start_re" end="end_re" | Apply colours from the text matching start_re until the corresponding match of end_re, including multi-line ranges. |
Within regular expressions, nano word-boundary expressions \< and \> are translated to Perl word boundaries before matching.
Rules are applied in the order in which they are encountered in the nanorc files. Later rules may therefore overwrite colouring applied by earlier rules to the same text.
The recognised foreground and background colour names are black, red, green, yellow, blue, magenta, cyan, white and normal. Foreground colours may additionally use the bright prefix, such as brightred.
Output and exit behaviour
The command writes coloured text to standard output and appends a reset sequence at the end of every output line, ensuring that terminal attributes do not leak into later output.
With --supported, a successful match prints the selected syntax name followed by a line break and exits with status 0. If no syntax matches, the command produces no output and exits with status 1. Invalid command-line usage causes the command to terminate with an error message.
| Condition | Result |
|---|---|
| Syntax identified with --supported | The syntax name is written to standard output and the exit status is 0. |
| No syntax identified with --supported | No output is produced and the exit status is 1. |
| Normal colouring mode with matching syntax | The input is written to standard output with ANSI colour sequences. |
| Normal colouring mode with no matching syntax | The input is copied to standard output unchanged. |
| Invalid options or missing nanorc path | Usage text is reported and the command exits with failure. |
Commands
<file> | - | The target file to be highlighted. Use - to read from standard input. | ||||
<nanorc_dir> | - | Directory containing nanorc files, or a single nanorc file to load. If omitted, the path is taken from the NANOCOLOUR_DIR environment variable. | ||||
| - | Select the named syntax explicitly instead of using automatic detection. | ||||
-supported | - | Test whether the target file matches a known syntax. If it does, print the syntax name and exit successfully. |
This command reads the target text, selects a syntax definition, and writes colourised output to standard output. When a syntax is forced, standard input may be coloured even when no target filename is available for discovery.
The command requires a nanorc source either as the final positional argument or through NANOCOLOUR_DIR. If neither is present, the command reports usage information and fails.
Highlight a Perl source file using a directory of nanorc files
The syntax is selected automatically from the target path.
nano-colour myfile.pl examples/
Force a syntax while reading from standard input
This is the normal way to colour piped input.
cat myfile.pl | nano-colour -s perl - examples/
Check whether a file is supported
If a syntax matches, its name is printed and the command exits with status 0.
nano-colour --supported prminxml/nanocolourtool.xml examples/
Examples
Using an environment variable
If the same nanorc directory is used repeatedly, set NANOCOLOUR_DIR once and omit the second positional argument.
Using the environment variable for repeated runs
The command then only needs the file name.
export NANOCOLOUR_DIR=$(pwd)/examples
nano-colour README.md
Highlighting PRM-in-XML
The supplied PRM-in-XML syntax can match files by directory and name, which is useful for documentation trees such as this repository's prminxml directory.
Colour a PRM-in-XML source file
The file path is sufficient for automatic syntax selection.
nano-colour prminxml/nanocolourtool.xml examples/