README: Rephrase "Implementation details."
[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 (supporting only regular
39 languages) are used to tokenize the characters within a string or
40 port and return a list consisting of two types of values: strings
41 and two element tagged lists. A tagged list consists of a symbol
42 designating the type of the text (symbol, keyword, string literal,
43 etc.) and a string of the text fragment itself.
44
45 #+BEGIN_SRC scheme
46 ((open "(")
47 (special "define")
48 " "
49 (open "(")
50 (symbol "square")
51 " "
52 (symbol "x")
53 (close ")")
54 " "
55 (string "\"Return the square of X.\"")
56 " "
57 (open "(")
58 (symbol "*")
59 " "
60 (symbol "x")
61 " "
62 (symbol "x")
63 (close ")")
64 (close ")"))
65 #+END_SRC
66
67 The term "parse" is used loosely here as the general act of reading
68 text and building a machine readable data structure out of it based
69 on a set of rules. These parsers perform lexical analysis; they are
70 not intended to produce the abstract syntax-tree for any given
71 language. The parsers, or lexers, attempt to tokenize and tag
72 fragments of the source. A "catch all" rule in each language's
73 highlighter is used to deal with text that doesn't match any
74 recognized syntax and simply produces an untagged string.
75
76 * Requirements
77
78 - GNU Guile >= 2.0.9
79
80 * Building
81
82 Guile-syntax-highlight uses the familiar GNU build system and
83 requires GNU Make to build.
84
85 ** From tarball
86
87 After extracting the tarball, run:
88
89 #+BEGIN_SRC sh
90 ./configure
91 make
92 make install
93 #+END_SRC
94
95 ** From Git
96
97 In addition to GNU Make, building from Git requires GNU Automake
98 and Autoconf.
99
100 #+BEGIN_SRC sh
101 git clone git@dthompson.us:guile-syntax-highlight.git
102 cd guile-syntax-highlight
103 ./bootstrap
104 ./configure
105 make
106 make install
107 #+END_SRC
108
109 * License
110
111 LGPLv3 or later. See =COPYING= for the full license text.