]> Git in Space - hl/blob - README
Add gitignore
[hl] / README
1 ### HighLight ###
2
3 HighLight (HL) is a small domain-specific language for encoding basic
4 syntax-highlighting information in-line with source code. Here is an example:
5
6 %Tint %Vx = %N3 ;
7 %Tstring %Vs = %{S"line 1%{E\n%}line 2"%} ;
8
9 HL has only 3 syntax rules:
10 * `%A` applies rule `A` from the next character until before the next
11 whitespace character or at the start/end of another rule, or a
12 "word style".
13 * `%{A...%}` applies rule `A` across all of `...`, or a "region style".
14 * `%%` applies no rule but instead simply expands to a literal `%`
15 character.
16
17 Rules only have a "start" and "end" and will not modify any text that is not
18 part of a rule marker. Rule identifiers are single characters in the range
19 `A-Za-z`.
20
21 Config files store rules in this format:
22
23 <identifier>\t<start>\t<end>[\t<comment>]
24
25 For example, a config file that converts the example at the top into HTML using
26 `<span>` tags might look like this:
27
28 T <span class="type"> </span> A type
29 V <span class="var"> </span> A variable
30 N <span class="num"> </span> A numeric literal
31 S <span class="str"> </span> A string literal
32 E <span class="escape"> </span> An escape sequence
33
34 For configs that will not work properly when "nested" e.g. with an ANSI escape
35 sequence based config that uses "\x1b[0m" as the end markers, the first (and
36 only the first) line of the config file can be given as `#nonest`. This will
37 mean that this:
38
39 %{Aaaa%{Bbbb%}ccc%}
40
41 will be treated as though it is this:
42
43 %{Aaaa%}%{Bbbb%}%{Accc%}
44
45 # USAGE
46
47 hl -c|--config <config> [-o|--output <output>] [<input>]
48
49 -c|--config <config>
50 Use the given config file. This has no default.
51 -o|--output <output>
52 Write output to the given file. If not provided, will write to stdout.
53 <input>
54 Read from the given input file. If not provided, will read from stdin.
55
56 # INSTALLING
57
58 Where $PREFIX is somewhere in your $PATH (e.g. "~/.bin"):
59
60 dmd hl.d -of="$PREFIX/hl"
61
62 # EXAMPLES
63
64 Use the `test.src` example source file with the two provided example config
65 files like this:
66
67 hl -c term.conf test.src
68 hl -c html.conf test.src
69
70 `term.conf` uses escape sequences so the output to your terminal will be
71 coloured. `html.conf` uses `<span>` tags instead and can be used e.g. for adding
72 syntax-highlighted code snippets to websites.