Source-highlight for color capable terminal emulators..
This tiny project allows you to have a generalised access to colors used by source-highlight for color capable terminal emulator like xterm, gnome-terminal, mate-terminal, terminator, etc..
This is useful for GDB user's who can then easily customize their source color in the CLI/TUI
To use it directly in GDB, Once installed (cloned) simply do
$ cd InstallDir
$ export SOURCE_HIGHLIGHT_DATADIR=$PWD
$ gdb -tui YourProg
OR
$ cd InstallDir
$ SOURCE_HIGHLIGHT_DATADIR=$PWD gdb -tui YourProg
OR
Hide the above in a wrapper.
GDB will source-highlight your source code with the predefined colors.
You can then hack the TH-default.th file to change colors that suite your
needs. (see Shxt256 gen-theme
).
To install, simply git clone this project.
$ git clone https://github.com/phidebian/shxt256 InstallDir
This come with default setup (ColorMap, Theme, Languages) suitable for a direct GDB use.
Initially to fix GDB CLI/TUI source rendering. GDB use source-highlight to colorize the source code, which in turn produce escape sequence suitable for color terminals.
In this whole chain, there are glitches that we try to workaround here.
+------------------+
| SHELL | export SOURCE_HIGHLIGHT_DATADIR=InstallDir
+------------------+
|
+------------------+
| GDB | CLI/TUI use hard coded esc.style esc.outlang
+------------------+ provided by source-highlight.
|
+------------------+
| source-highlight | source-highlight use SOURCE_HIGHLIGHT_DATADIR to
+------------------+ access .lang .outlang .style.
| It use esc.style and esc.outlang to generate
| escape sequences for the X terminal.
| esc.outlang define a colormap that map color
| name on terminal color 'number'.
| The possible color names are Hard coded in
| source-highlight and the list is very limited (see
| SOURCE-HIGHLIGHT below)
|
+------------------+
| Xterminal | Display GDB source code with color and attributes
+------------------+ escape sequences rendering.
When accessing color by index [0..255] then the
color used for each index as a default color, but the
user can redefines them, so color #0 is
traditionally "black" but can setup to anything
else, and this is true for all indexes. Because
the default color for indexes [0..15] are
generally ugly many people redefines them to
smoother colors. Some redefine colors [0..32],
and theorically could define the whole range.
In the following we will use Shxt256
from the InstallDir
You can request the help like this
$ ./Shxt256 -h
$ ./Shxt256 help
Source-highlight .lang files define the Language Element (LE's) of a given language (C for instance).
Source-highlight .style file define what color and attribute to use per LE's.
The color names usable in a .style file is very limited, it is hard coded, i.e "green", "red", "darkred", "blue", "brown", "pink", "yellow", "cyan", "purple", "orange", "brightorange", "darkgreen", "brightgreen", "black", "teal", "gray", "darkblue", "white".
Source-highlight .outlang define how to render the output, for terminal this is esc.outlang or esc256.outlang.
The .outlang file defines a color map, that map the few legal color name found in .style to colors and attribute, but here again some .outlang, like esc.outlang, only define a subset of the limited subset of colors.
To work around all those limitations, we define xt256.outlang wich define how we emit attributes to the terminal in a generalised manner.
We then define our own color map mechanism with no limit on color names, and color values (See COLORMAP).
On top of color map we define our own theme mechanism that define a color name for each LE's found in all languages. This way if many language define the variable LE, we can have a homoneous color mapped to the variable for all languages. (See THEME)
You have to decide if you want to use the Xterminal color indexes or true color #RRGGBB. The later use long escape sequences, so may be not too good on slow lines, yet this tends not to be a problem nowaday. With color indexes, escape sequences are shorter, but then you got to decide if you want to use the inherited color index color map, or if you prefere to reset the terminal so the color for each index are always the same color.
In its default usage shxt256 use the inherited color indexes colors, this is because it is very common for users to defines their own colors for at least indexes [0.15], so we inherit that.
In order to check what colors are displayed for color indexes you can use
$ ./Shxt256 show-indexes
$ ./Shxt256 si
The color index can then be used in your own color map. (See below).
The color maps are named CM-ColorMap.cm The CM- namespace is used to differenciate shxt256 files (start with uppercase) with source-highlight distribution files (lower cases).
The color map will map your own color name to Xterminal color. We have predefined color maps.
$ ls *.cm
CM-html.cm CM-minecraft.cm CM-roblox.cm CM-x11.cm
It is very easy to create one, you can look at Shxt256 import
for
examples that import colormap from the web.
The CM-ColorMap.cm sytax is a bash
sourced file like this
#List of X11 RGB Colors (/usr/share/X11/rgb/txt)
name+=(NavyBlue ) ; color+=(\#000080)
name+=(DodgerBlue4 ) ; color+=(\#104e8b)
name+=(DodgerBlue3 ) ; color+=(\#1874cd)
name+=(MidnightBlue ) ; color+=(\#191970)
In this example the colors are given by #RRGGBB true color code.
It is possible to give the colors by index like
name+=(Red) ; color+=(1) # Small index [0..7]
name+=(Yellow) ; color+=(@154) # Big index [0..255]
Note that small index 1 is the same as big index @1 except that escape sequence sent for @1 is longer. It is perfectly ledgit to mix'n'match all the color specifications.
When a CM-ColorMap.cm is defined it is possible to see its rendering with
$ ./Shxt256 show-colormap CM-x11.cm
$ ./Shxt256 show-colormap CM-x11
$ ./Shxt256 show-colormap x11
$ ./Shxt256 sc html
A theme TH-theme.th file is a mapping between language elements (LE's) defined in Language.lang files and a color name found in a CM-ColorMap.cm file.
The structure is of a TH-theme.th file is.
// Set a ColorMap.cm to your liking on the next line.
// ColorMap=CM-x11.cm
ColorMap=CM-html.cm
and_but Normal ;
argument Normal ;
assignment Normal ;
We have a predefined theme TH-style1.th
To create your own theme, yo do
$ ./Shxt256 new-theme foo
$ ./Shxt256 nt foo
This creates TH-foo.th from a pristine template, all the LE's are set
to Normal;
meaning not rendered.
Then you edit TH-foo.th, uncomment a color map of your choice, or add one you have created.
Then you assign color names from the color name set defined in yout CM-ColorMap.color to LE's given in your TH-foo.th.
Now you can create a TH-Theme.style file (See STYLE)
A .style
is consumed (needed) by source-highlight, you generate one
from a TH-Theme.th file
$ ./Shxt256 gen-style TH-foo.th
$ ./Shxt256 g TH-foo.th
$ ./Shxt256 g TH-foo
$ ./Shxt256 g foo
$ ./Shxt256 g style1
TH-style1.style is generated, you can use it with source-highlight.
The generated .style file is named after the theme name, so TH-foo.th produce TH-foo.style, the later is the one we will provide to source-highlight(1).
NOTE: It is important to regen your .style
file from your .th
file after each.th
modification. This check can be enforced in a wrappers
for source-highlight(1), and the same for GDB(1).
When your .style
is generated you can check its rendering with
$ ./Shxt256 show-style TH-style1.th
$ ./Shxt256 show-style TH-style1
$ ./Shxt256 show-style style1
NOTE: LE's set as "Normal;" are not displayed, so doing a
show-style
on a pristine theme display nothing.
You can check your latest TH-style1.style rendering on a source file like this
$ export SOURCE_HIGHLIGHT_DATADIR=$PWD
$ source-highlight -f xt256 --style-file=TH-style1.style -i ~/hw/hw.c
NOTE: xt256
i.e xt256.outlang
is the file we use for rendering
escape sequences for Xterminals.
Because GDB use harcoded esc.outlang
and esc.style
to access
source-highlight we got to symlink them to our setup, this is done by
doing.
$ ./Shxt256 gdb link style1
$ ll esc.*
lrwxrwxrwx 1 phi phi 13 Mar 9 06:49 esc.outlang -> xt256.outlang
-rw-r--r-- 1 phi phi 949 Mar 6 10:39 esc.outlang.ori
lrwxrwxrwx 1 phi phi 15 Mar 9 06:49 esc.style -> TH-style1.style
-rw-r--r-- 1 phi phi 660 Mar 6 10:39 esc.style.ori
At this point *GDB(1) will use your own .style file with the xt256.outlang terminal rendering escape sequences.
From there you can run GDB with to proper environment setup
$ export SOURCE_HIGHLIGHT_DATADIR=$PWD
$ gdb -tui ~/hw/hw
$ SOURCE_HIGHLIGHT_DATADIR=$PWD gdb -tui ~/hw/hw
$ Gdb -tui ~/hw/hw # Wrapper (see below)
NOTE: The export can be setup in a Gdb wrapper, along with a check that TH-Theme.th and TH-Theme.style are in sync.
In the InstallDir we find the current source-highlight files, most of them are lowercase.
Our files are uppercase except when notified.
CM-ColorMap.cm
are color map filesTH-Theme.th
are theme filesTH-Theme.style
are generated style filesxt256.outlang
is our output driver for source-highlight.c.lang.ori
is the original source-highlight file whilec.lang
is our hacked version, it mostly add a rule so thelabel
following agoto
produce alabel
LE, and then will match the color of alabel:
statement.- Help.lang define a tiny language used by shell script for self documenting.