Theme System

JLine version > 3.21.0

In the theme system highlight styles are specified in nanorc theme configuration file using token type name, mixin and parser configurations, instead of hard-coded styles. Mixin and parser configurations are specific for syntaxHighlighters while the token type name configurations are used by all REPL demo highlight definitions (nano syntaxHighlighters, COLORS variables:HELP_COLORS, LS_COLORS, etc and lineReader's COMPLETION_STYLEs).

Theme system idea has been copied from YSakhno/nanorc and adopted to JLine.

Functionality

Theme system configuration is set by adding 'theme theme-system-file' command in jnanorc configuration file. At the REPL startup theme system token type name configurations are copied to CLI console map variable CONSOLE_OPTIONS[NANORC_THEME]. All the REPL highlight styles are defined by either nano syntaxHighlighters or console variables. Highlight styles in various configurations are specified using the theme system token type names.

The console variable CONSOLE_OPTIONS[NANORC_THEME] is recreated when executing the builtins command: highlighter --refresh or highlighter --switch=<new-theme>. The highlighter command will refresh also lineReader's COMPLETION_STYLEs and all syntaxHighlighters used by REPL demo.

Below is shown relevant console variables and configurations used by the REPL theme system:

Theme system file syntax

Token type name

Token type name configuration

TOKEN_TYPE_NAME <style>

where TOKEN_TYPE_NAME is the name of the token type in camel case and <style> is its style, see nanorc style definition syntax.

Mixin

Mixin configuration

+MIXIN_NAME TOKEN_TYPE_1 <regex> ... \n TOKEN_TYPE_2 <regex2> ... \n ...

where MIXIN_NAME is the name in camel case and TOKEN_TYPE_<n> are the token type names. Mixin configurations are relevant only in nanorc syntax highlight.

Parser configurations

In the theme system has been implemented three parsing configurations for line comments, block comments and literal strings: $LINE_COMMENT, $BLOCK_COMMENT and $BALANCED_DELIMITERS. The literal string and comment delimiters parsing configuration is placed in nanorc syntax file and syntax highlight rules in system theme file.

nanorc syntax file:

$LINE_COMMENT        "<delimiter>"
$BLOCK_COMMENT       "<start_delimiter>, <end_delimiter>"
$BALANCED_DELIMITERS "<delimiter_1>, <delimiter_2>, ..."

nanorctheme file:

$PARSER TOKEN_TYPE \n TOKEN_TYPE_2: <condition> \n ...

where <condition> = <regex> ... | startWith=<value> | continueAs=<regex> and TOKEN_TYPE_<n> are the token type names.

Parser configurations are relevant only in nanorc syntax highlight.

Example

Theme system configuration file:

BOOLEAN     brightwhite
NUMBER      blue
CONSTANT    yellow
COMMENT     brightblack
DOC_COMMENT white
TODO        brightwhite,yellow
WHITESPACE  ,green
#
# mixin
#
+LINT   WHITESPACE: "[[:space:]]+$" \n WHITESPACE: "\t*"
#
# parser
#
$LINE_COMMENT   COMMENT \n TODO: "(FIXME|TODO|XXX)"
$BLOCK_COMMENT  COMMENT \n DOC_COMMENT: startWith=/** \n TODO: "(FIXME|TODO|XXX)"

nanorc syntax file using above system theme configurations:

BOOLEAN:  "\b(true|false)\b"
CONSTANT: "\b[A-Z]+([_]{1}[A-Z]+){0,}\b"
~NUMBER:  "\b(([1-9][0-9]+)|0+)\.[0-9]+\b" "\b[1-9][0-9]*\b" "\b0[0-7]*\b" "\b0x[1-9a-f][0-9a-f]*\b"
$LINE_COMMENT:        "//"
$BLOCK_COMMENT:       "/*, */"
+LINT

Equivalent self contained nanorc syntax file that does not use theme system:

color brightwhite "\b(true|false)\b"
color yellow      "\b[A-Z]+([_]{1}[A-Z]+){0,}\b"
icolor blue       "\b(([1-9][0-9]+)|0+)\.[0-9]+\b" "\b[1-9][0-9]*\b" "\b0[0-7]*\b" "\b0x[1-9a-f][0-9a-f]*\b"
color brightblack "//.*"
color brightblack start="^\s*/\*" end="\*/"
color white       start="/\*\*" end="\*/"
color brightwhite,yellow "(FIXME|TODO|XXX)"
color ,green      "[[:space:]]+$"
color ,green      "\t*"

Note: That in case of self contained nanorc syntax file highlighter uses only regexes for highlighting.

Creating nanorc themes

You can define your nanorc theme using 16 colors palette and switch between different color themes by changing your terminal palette. Available themes and installation instructions see for example Gogh, iTerm2-Color-Schemes and microsoft/ColorTool.

If your terminal color palette is not easily replaceable (or 16 colors palette is not enough) you can use hard-coded color definitions in your nanorc theme file. Nanorc theme with hard-coded color definitions can be created using nanorctheme.template, apply-colors.sh and Gogh install like:

Linux:

\> cd git/jline3
\> ./build rebuild
\> cd demo/target/nanorc
\> bash -c  "$(wget -qO- https://git.io/vQgMr)"