orthecreedence / highlight-lisp

A Common Lisp syntax highlighter written in Javascript

highlight-lisp - Common Lisp syntax highlighter

This is a syntax highlighter for Common Lisp written in Javascript. It is completely themable via CSS (themes included).

The purpose of this is to make it really easy to embed beautiful Common Lisp code into a website with minimal effort.

See the demo!

Usage

Usage is simple. You include highlight-lisp.js, link to one of the CSS themes, and call one of highlight-lisp's highlighting functions:

<!-- Put these in your document somewhere, probably in the head, although the <script>
     tag can probably go anywhere -->
<script type="text/javascript" src="/js/highlight-lisp/highlight-lisp.js"></script>
<link rel="stylesheet" href="/js/highlight-lisp/themes/github.css">

...

<!-- By default, the highlighter looks for code blocks with class="lisp" -->
<pre><code class="lisp">(defun test-syntax-highlighter ()
  "Docstring explaining what this function does."
  (let ((hash (make-hash-table :test #'equal)))
    ...))</code></pre>

Once the HTML is set up, there are a few ways to initialize highlighting:

// automatically highlight all <code class="lisp">...</code> blocks
HighlightLisp.highlight_auto();

// specify a custom class name (instead of "lisp"):
HighlightLisp.highlight_auto({className: 'common-lisp'});

// highlight *every* code block
HighlightLisp.highlight_auto({className: null});

// manually highlight a code block
var code = document.getElementById('my-code-element');
HighlightLisp.highlight_element(code);

Paren matching

You can now enable paren matching (on mouse hover):

HighlightLisp.paren_match();

This will go through all highlighted blocks of code and add mouseover/mouseout event listeners to all ('s and )'s that highlight the matching paren on hover.

What gets highlighted

• Functions
  CSS class function
  Anything starting with (: (my-function ...)
  • Known functions
    CSS class function known
    Any function known by the highlighter: things like make-hash-table, when, format, etc
  • Special functions
    CSS class function known special
    Mainly let, let\*, lambda.
  • Symbol functions
    CSS class function symbol
    Example: #'my-function
  • Known symbol functions
    CSS class function symbol known
    Examples: #'equalp, #'format
• Keywords
  CSS class keyword
  Anything starting with : like :this-is-a-keyword
  • Known keywords
    CSS class keyword known
    Known keywords are things like :hash-keys, :supersede, etc.
• Symbols
  CSS class symbol
  Anything starting with ': 'my-symbol
• Lambda-list operators
  CSS class lambda-list
  Things like &key, &body, etc.
• Numbers
  CSS class number
  Any numbers: 69, -82.4, #xF047, #b11010
  • Integers
    CSS class number integer
    Simple numbers: 42, 867, etc. (no decimals)
  • Ratios
    CSS class number ratio
    Examples: 80/9, 23/4
  • Floats
    CSS class number float
    Numbers with a decimal: +47.82112, 32.9 3. .009
  • Hex
    CSS class number hex
    Hex numbers: #x8090, #xc001
  • Binary
    CSS class number binary
    Example: #b01101
• Variables
  By themselves, variables remain unhighlighted
  • Known variables
    CSS class variable known
    Examples: *package*, *standard-output*, etc
  • Global variables
    CSS class variable global
    Any symbol surrounded by \*: *main-datastore*, *my-thread-local*, etc
  • Constants
    CSS class variable constant
    Any symbol surrounded by +: +dt+, +contant-time+, etc
• nil/t
  CSS class nil
  Any standalone nil or t will get this class
• Comments
  CSS class comment
  Example: ; this is a comment
• Strings
  CSS class string
  Anthing inside ": "This is a string."
• Parens
  CSS class list
  May be overkill, but any ( or ) characters are classified.

On that note, things that don't get highlighted/aren't properly highlighted:

• Variables...things like let bindings or other symols within code that would be interpreted as variables. Highlighting these would most likely be prohibitive in terms of time (not the mention the return on investment). Feel free to patch!
• Some number notations. For instance 0.44d0.
• Multi-line comments #| ... |# are unsupported
• Many constants (such as pi, internal-time-units-per-second) are classified as functions, not known variables. This is because I pulled the list out of my vim highlight script, and couldn't find a list of "Common Lisp standard variables" to cross reference with. I pulled out the ones I know of and put them into the known variables list, but there are no doubt more. If you see something that is a known variable but gets treated as a known function, please open a github issue.

Why

Aren't there a bunch of Javascript syntax highlighters out there already?

Yes, but truth be told, most ignore lisp. You can write custom parsers for some of them, but the APIs they provide didn't work well enough for me. highlight.js has a very nice lisp highlighting mode, along with really nice themes, but I wanted more control over the process.

For instance, highlight-lisp started as a SyntaxHighlighter brush, but I quickly realized that because of the limitations of Javascript not allowing real lookbehind regular expressions, I needed more direct control over the search/replace process.

What I discovered was that given the proper tools, parsing lisp is easy (in fact, a cake walk after just releasing markdown.cl) and there's no need for a big highlighting framework. You plug in some regexes, slap some tags around certain things, and call it a day.

License

As always, MIT.