Skip to main content

A command-line highlighter syntax-highlighter, using Pygments and widlparser.

Project description

Highlighter

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, like 1, 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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

bs-highlighter-2.0.3.tar.gz (11.9 kB view details)

Uploaded Source

Built Distribution

bs_highlighter-2.0.3-py3-none-any.whl (13.7 kB view details)

Uploaded Python 3

File details

Details for the file bs-highlighter-2.0.3.tar.gz.

File metadata

  • Download URL: bs-highlighter-2.0.3.tar.gz
  • Upload date:
  • Size: 11.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.25.1 setuptools/46.0.0 requests-toolbelt/0.9.1 tqdm/4.43.0 CPython/3.7.0

File hashes

Hashes for bs-highlighter-2.0.3.tar.gz
Algorithm Hash digest
SHA256 03b07c5a2720bc5c0cbae485110083d4b3cebed1e5adb38ac7e081d2d8550b88
MD5 f12df089210074d7d4496791a598bfb2
BLAKE2b-256 2cbd668c9e6143cf021dd9cfbcdb777be0acd6e993d6f9a239a1112f143bd7ad

See more details on using hashes here.

File details

Details for the file bs_highlighter-2.0.3-py3-none-any.whl.

File metadata

  • Download URL: bs_highlighter-2.0.3-py3-none-any.whl
  • Upload date:
  • Size: 13.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.25.1 setuptools/46.0.0 requests-toolbelt/0.9.1 tqdm/4.43.0 CPython/3.7.0

File hashes

Hashes for bs_highlighter-2.0.3-py3-none-any.whl
Algorithm Hash digest
SHA256 7e9447ee51273dd84d572f522bec7940952908b468245daf33ed4e5d75918138
MD5 b9f0c968445115aba64a955ef16ab667
BLAKE2b-256 a253d7e024a50ac92dc4c5fafdb91cee6b07ab8ce0b2576db0aafd0d68514c34

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page