dfed3545f0b1a663384e04162d10fb68c70e7301
[guile-syntax-highlight.git] / README
1 -*- mode: org -*-
2
3 Guile-syntax-highlight is a general-purpose syntax highlighting
4 library for GNU Guile. It can parse code written in various
5 programming languages into a simple s-expression that can be easily
6 converted to HTML (via SXML) or any other format for rendering.
7
8 * Supported Languages
9
10 - Scheme
11 - XML
12
13 * Example
14
15 #+BEGIN_SRC scheme
16 (use-modules (syntax-highlight)
17 (syntax-highlight scheme)
18 (sxml simple))
19
20 (define code
21 "(define (square x) \"Return the square of X.\" (* x x))")
22
23 ;; Get raw highlights list.
24 (define highlighted-code
25 (highlight scheme-highlighter code))
26
27 ;; Convert to SXML.
28 (define highlighted-sxml
29 (highlights->sxml highlighted-code))
30
31 ;; Write HTML to stdout.
32 (display (sxml->xml highlighted-sxml))
33 (newline)
34 #+END_SRC
35
36 * Implementation details
37
38 Very simple monadic parser combinators (purposely lacking support
39 for recursive grammars currently) are used to tokenize the
40 characters within a string or port and return a list consisting of
41 two types of values: strings and two element tagged lists. A tagged
42 list consists of a symbol designating the type of the text (symbol,
43 keyword, string literal, etc.) and a string of the text fragment
44 itself.
45
46 #+BEGIN_SRC scheme
47 ((open "(")
48 (special "define")
49 " "
50 (open "(")
51 (symbol "square")
52 " "
53 (symbol "x")
54 (close ")")
55 " "
56 (string "\"Return the square of X.\"")
57 " "
58 (open "(")
59 (symbol "*")
60 " "
61 (symbol "x")
62 " "
63 (symbol "x")
64 (close ")")
65 (close ")"))
66 #+END_SRC
67
68 This means that the parsers are *not* intended to produce the
69 abstract syntax-tree for any given language. They are simply to
70 attempt to tokenize and tag fragments of the source. A "catch all"
71 rule in each language's parser is used to deal with text that
72 doesn't match any recognized syntax and simply produces an untagged
73 string.
74
75 * Requirements
76
77 - GNU Guile >= 2.0.9
78
79 * Building
80
81 Guile-syntax-highlight uses the familiar GNU build system and
82 requires GNU Make to build.
83
84 ** From tarball
85
86 After extracting the tarball, run:
87
88 #+BEGIN_SRC sh
89 ./configure
90 make
91 make install
92 #+END_SRC
93
94 ** From Git
95
96 In addition to GNU Make, building from Git requires GNU Automake
97 and Autoconf.
98
99 #+BEGIN_SRC sh
100 git clone git@dthompson.us:guile-syntax-highlight.git
101 cd guile-syntax-highlight
102 ./bootstrap
103 ./configure
104 make
105 make install
106 #+END_SRC
107
108 * License
109
110 LGPLv3 or later. See =COPYING= for the full license text.