Highlight v3.50

Using Custom Data Folders and Files

Notes on how to make Highlight CLI use custom lang defs, themes and plug-ins.

Table of Contents

Introduction
Highlight Configuration-Search Paths
- Search Paths Priorities
Debugging The Configuration Paths
Linux and Mac References
Windows Tutorial
Reference Links

Introduction

Sometime you might need Highlight to use language definitions and/or themes/plugins from some custom path, instead of Highlight’s default folder (ie: the /langDefs/, /themes/ and /plugins/ subfolders in the main installation folder) — or even a custom "filetypes.conf" file.

There are three different ways to achieve this:

Set HIGHLIGHT_DATADIR environment variable.
Use the --data-dir=<directory> command line option.
Use the --config-file=<file> command line option.

Methods (1) and (2) leverage Highlight’s search-path list, and their effect is folder-wide; method (3) forces Highlight to disregard the search-path list and use a specific langdef or theme, and its effect is limited to a single target langdef and/or theme per invocation.

method	description
`--data-dir` CLI option	overrides Highlight defaults.
`HIGHLIGHT_DATADIR` env var	new scripts only.
`--config-file=<file>` CLI option	bypasses configurations altogether.

Highlight Configuration-Search Paths

Here you’ll find the list of folder paths in which Highlight looks for configuration scripts for both Linux and Mac, on the one hand, and for Windows, on the other (Highlight behavior differs slightly on Windows).

Linux/Mac	Windows
`~/.highlight/`
`--data-dir`	`--data-dir`	path of `--data-dir` option
`$HIGHLIGHT_DATADIR`	`%HIGHLIGHT_DATADIR%`	path of `HIGHLIGHT_DATADIR` env var
`/usr/share/highlight/`	Highlight directory	path of Highlight executable
`/etc/highlight/`		location of "`filetypes.conf`"
current directory	current directory	(fallback)

These folders are expected to mirror the folders structure found in Highlight’s setup folder — ie: to contain subfolder with the corresponding scripts:

"/langDefs/": *.lang files (language definitions)
"/themes/": *.theme files (themes)
"/plugins/": *.lua files (plug-ins)

You can also place a custom "filetypes.conf" file in the root of these paths.

Whenever Highlight finds a configuration script matching the current requirements, it will load it from the currently searched path and stop looking. This means that you can override the required language definition but not the theme (or viceversa), as Highlight will search for each file separately (each time going again through all the folders in the search-path list).

Search Paths Priorities

So, the --data-dir option will always have a higher precedence, and any matching configuration scripts find therein will prevail over other paths.

 -D, --data-dir=<directory>     set path to data directory

On the other hand, the path of HIGHLIGHT_DATADIR env var will always come after Highlight’s path when no --data-dir option is specified, so it won’t override any same-named scripts present therein, nor the filetypes.conf file — effictely leaving --data-dir as the only viable option to override existing configuration scripts (unless also the --data-dir option is specified, and the path it points to doesn’t override the configuration script of HIGHLIGHT_DATADIR’s folder).

As for new language definitions, themes or plugins scripts (ie: for which there are no same-named files present in Highlight’s subfolders), both the --data-dir option and HIGHLIGHT_DATADIR env var are viable ways to make visible to Highlight our custom scripts.

Debugging The Configuration Paths

When in doubt (or, indeed, in trouble), remember that the --print-config option is there to show you Highlight’s list of search directories:

--print-config             print path configuration

… so just append --print-config to the invocation options you’re using and you’ll be shown the exact locations Highlight is looking for configuration files, ordered by priority.

Linux and Mac References

Configuration scripts are searched in the following directories:

~/.highlight/
path of --data-dir option
path of HIGHLIGHT_DATADIR env var
/usr/share/highlight/
/etc/highlight/ (location of "filetypes.conf")
current working directory (fallback)

Windows Tutorial

On Windows OS, Highlight searches for configuration scripts in these folders:

path of --data-dir option (if present), otherwise Highlight’s path
path of HIGHLIGHT_DATADIR env var
Highlight’s path
current folder/path of invocation script

We shall now provide some examples covering different working scenearios. Here I'm assuming you have installed Highlight on your Windows machine AND that you've added Highlight directory (%ProgramFiles%\Highlight\) to the system PATH.

Viewing Your Current Configuration

You can always use the --print-config option to check your current Highlight settings. E.g., on Windows:

D:\some\path>highlight --print-config

Config file search directories:
C:\Program Files\Highlight\
C:\Program Files\Highlight\

Filetype config file:
C:\Program Files\Highlight\filetypes.conf

You might wonder why the path of Highlight installation directory is being shown twice. The first entry actually represents the --data-dir option — if no --data-dir option is specified, the Highlight directory will be used as a fallback default value:

Config file search directories:
C:\Program Files\Highlight\   <-- path of `--data-dir` (fallback default)
C:\Program Files\Highlight\   <-- Highlight directory

This will become clearer when we'll look the --data-dir option, further on.

Custom Folders via `--data-dir`

Let's say we're working on a project in D:\myproject\ and want Highlight to use some customized scripts and settings from the myDataDir subfolder via the --data-dir command line option.

We'll first use --print-config to verify how configurations will be read:

D:\myproject>highlight --print-config --data-dir=%CD%\myDataDir

Config file search directories:
D:\myproject\myDataDir\
C:\Program Files\Highlight\

Filetype config file:
D:\myproject\myDataDir\filetypes.conf

We can see that myDataDir is being given top priority for loading configuration scripts, and that filetypes.conf configuration file inside it is being used as the reference configuration file, effectively overriding Highlight default configuration.

This means that any syntaxes inside myDataDir\langDefs will override the syntaxes in Highlight installation folder, and the same goes for themes and plugins.

Custom Folders via `HIGHLIGHT_DATADIR`

Let's now try to use the HIGHLIGHT_DATADIR env var instead, pointing to the HL_DATADIR subfolder. We first set the env var:

D:\myproject>set HIGHLIGHT_DATADIR=%cd%\HL_DATADIR\

and check it's pointing to the expected path:

D:\myproject>echo %HIGHLIGHT_DATADIR%
D:\myproject\HL_DATADIR\

OK. Let's now query Highlight configuration status:

D:\myproject>highlight --print-config

Config file search directories:
C:\Program Files\Highlight\
D:\myproject\HL_DATADIR\
C:\Program Files\Highlight\

Filetype config file:
C:\Program Files\Highlight\filetypes.conf

As you can see, the HIGHLIGHT_DATADIR folder is given lower priority than Highlight installation directory, and the filetypes.conf therein is not overriding Highlight default config file. This means that any same-named language definitions, themes or plugins in the directory of HIGHLIGHT_DATADIR will not override Highlight default scripts. But any new scripts therein will become available to Highlight.

The above should clarify why Highlight uses the Highlight directory as the fallback value for --data-dir when none is specified by the user:

Config file search directories:
C:\Program Files\Highlight\   <-- path of `--data-dir` (fallback default)
D:\myproject\MY_DATADIR\      <-- path of HIGHLIGHT_DATADIR
C:\Program Files\Highlight\   <-- Highlight directory

Combining Both `--data-dir` and `HIGHLIGHT_DATADIR`

And now let's see what happens if we combine both --data-dir and HIGHLIGHT_DATADIR:

D:\myproject>highlight --print-config --data-dir=%CD%\myDataDir

Config file search directories:
D:\myproject\myDataDir\
D:\myproject\HL_DATADIR\
C:\Program Files\Highlight\

Filetype config file:
D:\myproject\myDataDir\filetypes.conf

As expected, now the folder pointed by --data-dir gets higher priority, and the filetypes.conf inside it will be used by Highlight. But now the HIGHLIGHT_DATADIR folder is given higher priority over Highlight installation directory, which means that langDefs, themes and plugins in the HIGHLIGHT_DATADIR directory can now override same-named scripts in Highlight install directory (unless also present inside the --data-dir directory).

Ultimately, which configuration files will be used depends largely on the contents of the custom folders. In the above example, if the myDataDir folder doesn't contain a filetypes.conf file, then HL_DATADIR\filetypes.conf will be used (if present), overriding Highlight installation defaults.

Custom Data Folders