Contribute to Earl Grey

Here is an (incomplete) list of ways you can contribute to the development and tooling of Earl Grey, and information about how to do it.

Earl Grey's source code is available on Github.

It is written in Earl Grey. Of course. Unfortunately, it is not yet very well documented, but I will get around to it (I will get around to it faster if you show interest).

Syntax highlighting

Okay. Let's say you want to highlight Earl Grey.

First of all, there are really only two criteria for good syntax highlighting (at least from my understanding):

  1. Make it look good.
  2. Make the important parts of the code stand out.

Now, Earl Grey is a bit unique because it has a macro system, and this macro system lets you define your own shiny new control structures, for example describe and it from earl-mocha:

describe "MyClass":
   it "my-method":

Or task from earl-gulp:

task my-task < task-it-depends-on:

Wouldn't it be nice if a syntax highlighter could pick up on describe and it and task and make them stand out? Good news: this can be done. It requires some lookahead and lookbehind, so it may be a bit tricky to do it properly in some editors/libraries, but it's really great if you can get it working.

Here's how it works.

Given that:

What we want to highlight are these:

Now, the basic idea is this:

Keyword highlighting test

You should highlight key like in the following block of code, but avoid highlighting nokey.

key x
key +x; key @x; key .x; key "x"; key 0
key (x); key [x]; key {x}
nokey.x; nokey{x}

key x + y
key key x
x + key y
nokey + x

key: x
key nokey: y
key x > nokey: z
x + key nokey: z

x + nokey: y
x mod nokey: y
x = key: y
x each key: y

nokey mod: y      ;; do not highlight nokey, because mod is an operator

;; Highlight all of these:
await; break; chain; continue; else; expr-value; match; return; yield

Just for the record, there is a small bug in the highlighter I use on this page that makes it so that the mod operator above isn't bolded, even though it should be. This is caused by some unfortunate interference between some of my rules. Pretend they are bolded.

Edge-case highlighting test

Dashes in variable names can complicate highlighting a bit, so here are tests for edge cases:

key-word: xyz
nokey - x: yz

;; Some keywords may contain operators as a subpart. If your regexp
;; uses \b to single out operators like each, is or in, you may
;; fail to highlight these properly:
beaches           ;; Do not highlight each inside the word beaches
each-thing        ;; Do not highlight each
sleep-in          ;; Do not highlight in
before-each: xyz  ;; Highlight before-each as a keyword
is-great: xyz     ;; Highlight is-great as a keyword

Highlighting wishlist

I never implemented these, but I wish someone would:

;; highlight a word followed by indent
key       ;; <- highlight this; my highlighter doesn't

Existing code

For this website, I highlight EG using the highlight.js library. The code for the syntax mode is here

It is fairly basic. It doesn't do string interpolation, nor does it have fancy features like highlighting function arguments. But I only have so much time!

Feel free to do better :)

Editor support

Please follow the guidelines above for syntax highlighting.

You can use the REPL as a baseline of what I believe minimum editor support should be like.

Some features not found in the REPL (I'm lazy) but recommended: