e2ansi - Syntax highlighting support for
less, powered by Emacs
Author: Anders Lindgren
e2ansi (Emacs to ANSI) provides syntax highlighting support for
less and for other tools that run in terminal windows.
e2ansi-cat command line tool use ANSI escape sequences to
syntax highlight source files. The actual syntax highlighting is
performed by Emacs, the mother of all text editors, running in
Pager applications like
less can be configured to
e2ansi-cat, so that all viewed files will be
syntax highlighted. A nice side effect is that other conversions
that Emacs normally performs, like uncompressing files, are also
e2ansi-cat command line tool is written in Emacs Lisp. To
start it, use:
emacs --batch [...Emacs options...] -l bin/e2ansi-cat [...options...]
Alternatively, on UNIX-like operating systems the
be executed directly, assuming that the
bin directory is in the
load path. This assumes that Emacs is installed as
Note, due to how Emacs parses options, some options passed to
e2ansi-cat is parsed by Emacs. Most notably, passing the option
e2ansi-cat displays help for Emacs itself.
Command line options:
--colors-- Number of colors, or
rgb24for full 24 bit colors. This is both used when mapping faces to actual colors and to decide the kind of ANSI sequences that is used.
--theme-- Specify the color theme to use.
--usage-- Show help text.
The standard command line tool
less can be configured to
preprocess any output given to it.
e2ansi-cat can be used to
generate a syntax highlighted version. This is enabled by setting
the following environment variables, for example, to (using bash
export "LESSOPEN=|emacs --batch -l ~/.emacs -l bin/e2ansi-cat %s" export "LESS=-R" export "MORE=-R"
LESSOPEN environment variable is used by
less to specify an
input preprocessor. When using
e2ansi, the first character should
|, this signals to less that the input preprocessor prints
the result on standard output.
The above example assumes that your init file is named
located in your home directory. It also assumes that it adds the
location of the
e2ansi package to the load path.
less and pipes
Modern versions of
less can also use the input preprocessor when
used in a pipe, for example:
svn diff | less
For this, the
LESSOPEN environment variable must start with
In this case, the file name
- is passed to the input
preprocessor, which is expected to read from standard input.
export "LESSOPEN=|-emacs --batch -l ~/.emacs -l bin/e2ansi-cat %s"
Note: If your version of
less is too old, using
yields error like "/bin/bash: -/: invalid option".
Also note that this makes it hard for Emacs to select a suitable
major mode, as it can not base this on the file name extension.
Typically, this result in incorrect or no highlighting.
Fortunately, Emacs has the ability inspect the file content when
selecting major mode, see
magic-mode-alist for details. The
e2ansi-magic.el adds some file types to the list,
diff format used by
svn. You must explicitly load it
to take effect, either using
-l e2ansi-magic.el or by loading in
from another file that is being loaded, like your init file.
Emacs init files
When using Emacs in batch mode, Emacs reads the system init file but not the user init file.
If you want to load your personal init file, you can load it using -l command line option, for example:
emacs -l ~/.emacs -l bin/e2ansi-cat file ...
To avoid loading the system init file, you can specify the -Q command line option:
emacs -Q -l ~/.emacs -l bin/e2ansi-cat file ...
Adapting your init file to batch mode
As Emacs most often is used in interactive mode there is a risk that parts of the system or your init file doesn't work in batch mode.
To exclude something when in batch mode, you can use:
(unless noninteractive .. original code goes here ... )
When Emacs is used in batch mode, message are emitted on the standard error stream. This includes messages emitted when files are loaded.
On UNIX-like operating systems, the standard error stream can be redirected to /dev/null, for example:
emacs --batch -l ~/.emacs -l bin/e2ansi-cat 2> /dev/null
Alternatively, the file
e2ansi-silent can be loaded. This file
has the advantages that the Usage information of
printed (when started without arguments) and that it works on all
operating systems. (If you load it before your init file, you might
need to specify the full path.)
emacs --batch -l e2ansi-silent -l ~/.emacs -l bin/e2ansi-cat ...
Silencing messages in
Normally, the file
site-start.el is loaded by Emacs before any
file specified on the command line. To silence messages emitted by
this file, you can suppress loading it using -Q, load
e2ansi-silent and explicitly load the site-start file:
emacs --batch -Q -l e2ansi-silent -l ../site-lisp/site-start -l ...
Note: When -Q is used, the
site-lisp directory is not included in
the load path, the
../site-lisp part compensate for this.
e2ansi.el-- Render a syntax highlighted buffer using ANSI escape sequences. This can be used both in normal interactive mode and in batch mode.
e2ansi-magic.el-- Set up
magic-mode-alistto recognize file formats based on the content of files. This is useful when using
lessin pipes where Emacs can't use the file name extension to select a suitable major mode.
e2ansi-silent.el-- Load this in batch mode to silence some messages from init files.
bin/e2ansi-cat-- The command line tool for converting files in batch mode.
bin/e2ansi-info-- Print various ANSI-related information to help you trim your ANSI environment.
What is Emacs
Emacs is a the mother of all text editors. It originates from the 1970:s, but is still in active development. It runs under all major operating systems, including MS-Windows, Mac OS X, and various UNIX-like systems like Linux. You can use normal windows, run it in a terminal window (great when working remotely), or use it to run scripts in batch mode, which is how it is used by the command line tools provided by this package.
Emacs provides state-of-the-art syntax highlighting.
Why use Emacs to power syntax highlighting in the terminal:
- Emacs has support for a vast range of programming languages and other structured text formats.
- Emacs is fast and accurate -- it is designed for interactive use, and provides advanced support for ensuring that a source buffer is parsed correctly.
- Emacs supports color themes. If you don't like the ones provided, and can't find one on internet, you can easily write your own.
- To add syntax highlighting support for other formats can easily be
done by providing a standard Emacs major mode, where the syntax
highlighting is provided by Font Lock keywords. You can use
font-lock-studioto debug those keywords, it allows you single step match by match and it visualizes matches using a palette of background colors.
ANSI sequences, formally known as ISO/IEC 6429, is a system used by various physical terminals and console programs to, for example, render colors and text attributes such as bold and italics.
See Wikipedia for more information.
Both foreground and background colors can be rendered. Note that faces with the same background as the default face is not rendered with a background.
Four modes are supported:
- 8 -- The eight basic ANSI colors are supported.
- 16 -- The eight basic colors, plus 8 "bright" colors. These are represented as "bold" versions of the above.
- 256 -- Some modern terminal programs support a larger palette. This consist of the 16 basic colors, a 666 color cube plus a grayscale.
- 24 bit -- Support for 256256256 colors.
Operating system notes
Mac OS X
Mas OS X comes bundled with Emacs. Unfortunately, it's a relatively old version, 22.1.1. It is fully functional, but it lacks some features. Most notably, the default face definitions are broken when 8 colors are used.
You can download a modern version from
EmacsForOSX. Once installed, the path to
the Emacs binary is typically
The version of
less that is preinstalled on 10.9 is 418 dating
from 2007. It supports the input preprocessors for named files (the
| syntax) but not for pipes (The
Fortunately, it's easy to download and build a new version of
less from http://www.greenwoodsoftware.com/less
Why Apple has not included a newer version, I do not understand.
Some claim that Apple is actively avoiding software licensed under
less is available under two licenses so this
should not be a problem. I guess it's down to laziness and opting
to spend resources to invent yet another way of making menus
semi-opaque rather than providing their users with up to date
The command window in Microsoft Windows does not understand ANSI
sequences. Fortunately, modern versions of
less is capable of
rendering ANSI sequences using colors.
Unfortunately, I'm not aware of any up to date distribution of
prebuilt versions of
less. To make things worse, the build
scripts provided with
less is somewhat hard to use.
In the document
I describe how to build
cmake, a modern build
All images are screen captures of
less running in a terminal
window. White or black backgrounds were used, even though some
themes have other backgrounds, when used inside Emacs.
Default 8 colors
Default 256 colors
Grayscale 256 colors
The following themes are included in the Emacs distribution.
This sections consists of things that might or might not appear in this package in the future.
More command line tools
More command line tools could make life simpler. For example:
e2ansi-exec-- Run another command line tools and convert all arguments (that looks like files) to the corresponding ansi format. (To avoid converting files that should not be converted, this tool must include knowledge regarding common commands.) One problem with this tool is the bizarre way Emacs treats command line options -- hence, the entire tool, or parts of it, must be written in another script language like Ruby.q
e2ansi-tmp-- Render a syntax highlighted version of a file as a temporary file and print the file name. This way a user could use the shell backquote syntax to feed syntax highlighted versions of a file to a third tool, for example:
atool `e2ansi-tmp afile.c`
A technical problem with this tool is that it leaves the temporary file behind. Hence, some kind of garbage collection mechanism must be put in place.
Much of the code in this package is generic. It could most likely be used to generate other output formats like Markdown. One idea is to break out the generic parts to a separate package.
Faster response time:
- By using a resident Emacs process, response time could be greatly reduced. Today, a bare-bone Emacs start fast, however, if you use a heavy init file (like I do) the start-up time goes up noticeably.
- Incremental syntax highlighting. Today, the entire buffer is
syntax highlighted at once, before it is converted to ANSI. By
only run font-lock on parts of the buffer before printing it, a
receiving application like
lesscould start faster.
- Check how things look when using a dark background, maybe something would need to be added to the overrides list.
- Don't use the "brightxxx" color names, they are not used by Emacs and it's only confusing.
- Add unit tests for individual parts and full source file tests
where the entire output is compared against a known ANSI
representation, as done in my
- Describe Emacs font specification selection process.
- Better error handling when parsing command line arguments.
- Customization support.
- Optimize ANSI sequences. Today, whenever there is a change, a reset is emitted, plus codes to set all properties. However, sometimes it would be shorter to simple, say, add underline, and without touching the other properties.
- Security issues: Don't allow file local variables, or anything else, allow arbitrary elisp code to be executed when a file is viewed.
- Use floating point numbers when scoring, rather than scaling down.
- Promote some of the "list" commands from the "test" package.
- Inhibit rendering ANSI sequences when running
lesson a file already containing ANSI sequences.
--forceto force e2ansi to render a file using ANSI sequences, even when such sequences are found in the file.
||-in the documentation.
- Investigate why backgrounds spanning mutiple lines misbehaves in Terminal.app (and other terminals). Maybe always reset the background at the end of each line?
Mark, thanks for writing
e2ansi.el by el2markdown.