Highlighter
(Important, see the note at the end about Pygments, or else this project won't work.)
This project extracts and abstracts Bikeshed's syntax-highlighting functionality for usage by other tools.
To use, clone this git repo into your project folder, and then:
import highlighter
html,css = highlighter.highlight(elementGoesHere, lang="whatever")
Alternately, you can invoke it directly from the command line, passing it a string of JSON on stdin, and it will output via stdout:
echo '["pre", {}, "interface Foo {};"]' | ./__init__.py webidl
When invoked this way,
it will return a string containing a JSON object with html
and css
keys:
the html
value will be the marked-up HTML, still in JSON form;
the css
value will be a string containing CSS.
(See Command-Line Options
or run highlighter/__init__.py -h
to see all the command-line options.)
The elementGoesHere
argument needs to be a chunk of HTML,
converted into JSON using the following transformation:
<p class=foo>text<span>nested text</span></p>
=> becomes =>
["p", {"class":"foo"}, "text", ["span", {}, "nested text"]]
That is, each element is encoded as an array, with the first item being the tagname, the second being an object containing the attributes (if no attributes, an empty object is still required), and the remaining items being the children of the element, either straight text or further nested elements.
It's generally assumed that the root element will be a ["pre", {}]
,
but that's not strictly necessary;
the default styling uses CSS Grid,
and doesn't depend on newlines being preserved.
The supported languages are everything that Pygments supports, plus "webidl" for WebIDL.
The return value is a 2-tuple (html, css)
:
html
is the highlighted HTML
(also formatted as JSON);
css
is the accompanying CSS that supports the highlighting,
which you can use or replace as you wish.
Alternately, if you pass output=html
to the highlight()
function,
the html
return value will be a string containing HTML,
rather than JSON.
Line Numbers or Highlights
You can also add line numbers to the outputted HTML, or highlight specific lines.
To add line numbers,
pass lineNumbers=True
to highlight()
.
By default the numbers start at 1;
to change that, pass lineStart=5
or whatever you need.
To highlight specific lines,
pass lineHighlights=...
,
where the ...
is either a set()
containing the line numbers you want highlighted,
or a comma-separated string containing line numbers and/or ranges, like 1, 3-5
(equivalent to set(1, 3, 4, 5)
).
Again, it defaults to assuming the first line is line 1,
and you can change this by passing lineStart
.
The two options can be combined for both numbering and highlighting.
Command-Line Options
Highlighter has a number of command-line options to customize its operation (many inspired by its first major user, if they seem oddly ideosyncratic).
--output=json
or--output=html
-
Defaults to
json
.Determines whether the highlighted output is returned as JSON-encoded HTML (like the input), or just as a plain string of HTML.
--numbers
-
If passed, adds line numbers to the output.
Defaults to treating the first line as "1"; use in conjunction with
--start
for more customization. --highlights=<range>
-
Tells the processor which lines to specially highlight, by default giving them a darker background to draw the eye.
The
<range>
is a list of comma-separated line ranges, each of which is either a single number or a hyphenated range, like1, 3-5
to highlight the lines 1, 3, 4, and 5.The highlighted lines will be numbered automatically, even if
--numbers
isn't passed.Same as
--numbers
, defaults to treating the first line as "1"; use in conjunction with--start
for more customization. --start=<number>
-
Defaults to
1
.Tells the highlighter what number the first line should be treated as.
For example, if you're showing a small fragment of code from a larger file, you can tell it that the code actually starts on, say, line 1500 with
--start=1500
, so the displayed line numbers will match up with those of the source file you're excerpting. --just=html
or--just=css
-
If passed, the output will be just the HTML or CSS for the highlighting, rather than a JSON object containing both. There will be no overall wrapping JSON object.
Pygments Errors
This project relies on the Pygments library for most of its highlighting. In an attempt to make this library standalone, I include a local copy of Pygments. As documented in this Pygments issue, however, Pygments actually can't be used stand-alone, as it is written to pervasively use global imports of its own code.
I'm in the process of fixing this in my local copy of the Pygments source
(and hope to upstream it eventually),
but it's a decent chunk of work.
In the meantime,
you should pip install pygments
to get a global install of the library as well,
or else this project won't work.
(Or otherwise install it with whatever tools you have,
as documented on the Pygments site.)