Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the lowlight Reference Manual, version 0.99.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 16:57:03 2021 GMT+0.
| • Introduction | What lowlight is all about | |
| • Systems | The systems documentation | |
| • Files | The files documentation | |
| • Packages | The packages documentation | |
| • Definitions | The symbols documentation | |
| • Indexes | Concepts, functions, variables and data types |
A simple syntax highlighter in Common Lisp based on a lexer and a parser.
Version 1.0 approaching!
I will probably support more languages in the future, but you can also define your own language styles. Also, patches to get your language style included are welcome.
Lowlight is already available in Quicklisp, but at the time of writing this
you will find an old version there.
If you want the latest version lowlight, please download the source and
load it via ASDF (or as a local Quicklisp project), or make sure.
You know, that the Quicklisp version has been updated to the current version,
if it defines a package lowlight.1.
All lowlight functions and macros live in the package lowlight:
(in-package #:lowlight)
To highlight a string use light:
(light :common-lisp ":bla") ;=> "<span class=\"keyword\">:bla</span>"
If you want to highlight a whole file, use light-file:
(light-file :common-lisp "~/lowlight.lisp" :css "github-colors.css")
As lowlight uses graylex for lexing,
it currently suffers from a bug related do the buffer size graylex uses.
If you experience Problems with the lexer not correctly recognizing tokens
that cross the 1024 or 2048 character border, try to increase the buffer size
lowlight:*lexer-buffer-size*.
The grammars that are created by define-cfg-style are ambiguous by design,
so conflict warnings will be ignored by default. If you run into problems, please
consider using define-simple-style or tell me, how to create unambiguous grammars
in define-cfg-style. Maybe I will provide a third macro to explicitly specify a
complete cfg, so you can make sure it's unambiguous yourself (if anyone actually needs this).
Next: Files, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
| • The lowlight system |
Christoph Finkensiep <chfin@freenet.de>
MIT/X11
A simple and flexible syntax highlighter
0.99.0
lowlight.asd (file)
Files are sorted by type and then listed depth-first from the systems components trees.
| • Lisp files |
Next: The lowlight/package․lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
lowlight.asd
lowlight (system)
Next: The lowlight/common․lisp file, Previous: The lowlight․asd file, Up: Lisp files [Contents][Index]
lowlight (system)
package.lisp
Next: The lowlight/simple․lisp file, Previous: The lowlight/package․lisp file, Up: Lisp files [Contents][Index]
package.lisp (file)
lowlight (system)
common.lisp
Next: The lowlight/grammar․lisp file, Previous: The lowlight/common․lisp file, Up: Lisp files [Contents][Index]
common.lisp (file)
lowlight (system)
simple.lisp
Next: The lowlight/lowlight․lisp file, Previous: The lowlight/simple․lisp file, Up: Lisp files [Contents][Index]
simple.lisp (file)
lowlight (system)
grammar.lisp
Next: The lowlight/style-lisp․lisp file, Previous: The lowlight/grammar․lisp file, Up: Lisp files [Contents][Index]
grammar.lisp (file)
lowlight (system)
lowlight.lisp
Previous: The lowlight/lowlight․lisp file, Up: Lisp files [Contents][Index]
lowlight.lisp (file)
lowlight (system)
style-lisp.lisp
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
| • The lowlight.1 package |
package.lisp (file)
common-lisp
Definitions are sorted by export status, category, package, and then by lexicographic order.
| • Exported definitions | ||
| • Internal definitions |
Next: Internal definitions, Previous: Definitions, Up: Definitions [Contents][Index]
| • Exported special variables | ||
| • Exported macros | ||
| • Exported functions | ||
| • Exported generic functions |
Next: Exported macros, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
controls debug output (‘t‘ or ‘nil‘)
common.lisp (file)
controlling knob for the graylex buffer size
common.lisp (file)
Next: Exported functions, Previous: Exported special variables, Up: Exported definitions [Contents][Index]
Defines a cfg style with token rules ‘rules‘ and CFG productions ‘productions‘.
The resulting ‘cfg-style‘ object is registered under ‘name‘ which should be a keyword.
‘rules‘ is a list of token rules, each of the form ‘(regex class)‘,
where ‘regex‘ is either a string describing a regex or a list with such a string in ‘car‘.
In the latter case the string is taken as a control string for ‘format‘
and the rest of the list is given to it as arguments.
The result is then used as the regex.
‘class‘ can be a keyword or a function. If it is a function, it is called with the token
detected by ‘regex‘ and should return a keyword.
Rules may contain forms like ‘(:other-tokens ...)‘, each containing a list of keywords
that do not appear as a token keyword in other rules (e.g. ‘(:other-tokens :a :b :c)‘).
Those are added to the list of terminals for the production rules.
You should use this for token keywords that are generated by functions,
as described above.
‘productions‘ is a list of productions in cl-yacc syntax.
The productions may contain *one* form ‘(:toplevel ...)‘ containing a list of toplevel
non-terminals (e.g. ‘(:toplevel a b c)‘).
If no such form is given, all nontermials on the left-hand side of the given productions
will become toplevel.
Productions may also contain *one* form ‘(:ignore ...)‘ containing a list of ignorable tokens.
Those may occur at any positition (like whitespace and comments)
and are preserved, if all tokens are printed with ‘print-token*‘.
If no ‘:ignore‘ form is given, it defaults to ‘’(:default)‘.
grammar.lisp (file)
Defines a simple style with the token rules ‘rules‘.
The resulting ‘simple-style‘ object is registered under ‘name‘ which should be a keyword.
‘rules‘ is a list of token rules, each of the form ‘(regex class)‘,
where ‘regex‘ is either a string describing a regex or a list with such a string in ‘car‘.
In the latter case the string is taken as a control string for ‘format‘
and the rest of the list is given to it as arguments.
The result is then used as the regex.
‘class‘ can be a keyword or a function. If it is a function, it is called with the token
detected by ‘regex‘ and should return a keyword.
simple.lisp (file)
Next: Exported generic functions, Previous: Exported macros, Up: Exported definitions [Contents][Index]
=> a highlighted string or ‘t‘
Highlights ‘input‘ which can be either a stream or a string.
The used style is given by ‘style‘.
If ‘output‘ (a stream) is given, the result is printed on it,
otherwise the result is returned as a string.
lowlight.lisp (file)
=> a highlighted string or ‘t‘
Highlights all markdown code blocks in ‘input‘ with ‘style‘
and writes the result to ‘output‘ (or returns the result as a string,
if ‘output‘ is not given).
‘light-blocks‘ only hightlights blocks starting with a language name from ‘blocks‘ which defaults to the name of ‘style‘. So if you are using the style ‘:common-lisp‘ and want to highlight blocks starting with ‘ “‘common-lisp‘, then you may leave out ‘blocks‘. If you want blocks starting with ‘ “‘cl‘ to be highlighted as well, use ‘’(:common-lisp :cl)‘ for ‘blocks‘.
lowlight.lisp (file)
=> ‘t‘
Highlights the file given by ‘in‘.
The used style is denoted by ‘style‘.
If given, the result is written to the file ‘out‘,
otherwise ‘in‘ is used, with the file ending replaced by html.
If given, ‘css‘ is used as the href parameter to a css relation
and ‘title‘ is used as the page title.
If ‘raw‘ is ‘t‘ the highlighted code is *not* wrapped into a html skeleton.
lowlight.lisp (file)
=> ‘t‘
Highlights a file with ‘light-blocks‘.
‘in‘ denotes the input file, if ‘out‘ is given, it denotes the output file.
If not, ‘in‘ is used, with the file extension replaced by ‘.html‘,
so ‘foo.lisp‘ becomes ‘foo.html‘.
Be careful with files already ending on ‘.html‘ as they will not change.
lowlight.lisp (file)
=> a ‘cfg-style‘ object
Creates a new ‘cfg-style‘ with the name ‘name‘, the token rules ‘rules‘ and the
CFG productions ‘productions‘.
For the structure of ‘rules‘ and ‘productions‘ see ‘define-cfg-style‘.
grammar.lisp (file)
=> a ‘simple-style‘ object
Creates a new ‘simple-style‘ with the name ‘name‘.
‘rules‘ is a list of token rules, each of the form described at ‘define-simple-style‘.
simple.lisp (file)
Previous: Exported functions, Up: Exported definitions [Contents][Index]
=> the set of token classes generated by ‘style‘
common.lisp (file)
simple.lisp (file)
Previous: Exported definitions, Up: Definitions [Contents][Index]
| • Internal special variables | ||
| • Internal macros | ||
| • Internal functions | ||
| • Internal generic functions | ||
| • Internal classes |
Next: Internal macros, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
style-lisp.lisp (file)
An alist mapping from style keywords to style definitions.
common.lisp (file)
grammar.lisp (file)
Next: Internal functions, Previous: Internal special variables, Up: Internal definitions [Contents][Index]
grammar.lisp (file)
Next: Internal generic functions, Previous: Internal macros, Up: Internal definitions [Contents][Index]
style-lisp.lisp (file)
=> a list of productions
Takes a list of terminals, a list of ignorables, and a list of productions in cl-yacc syntax.
Transforms the productions to allow an arbitrary number of ignorables after each terminal.
grammar.lisp (file)
highlight all blocks in input
lowlight.lisp (file)
lowlight.lisp (file)
lowlight.lisp (file)
grammar.lisp (file)
style-lisp.lisp (file)
grammar.lisp (file)
style-lisp.lisp (file)
simple.lisp (file)
grammar.lisp (file)
style-lisp.lisp (file)
style-lisp.lisp (file)
=> a string containing the whole stream data from ‘in-stream‘ Taken from Alexandria’s ‘read-file-into-string.‘
lowlight.lisp (file)
=> an ignorable sensitive cl-yacc grammar
Takes style rules and productions and creates a cl-yacc grammar.
Rules may contain forms like ‘(:other-tokens ...)‘, each containing a list of keywords
that do not appear as a token keyword in other rules (e.g. ‘(:other-tokens :a :b :c)‘).
Those are added to the list of terminals for the production rules.
Productions may contain one form ‘(:toplevel ...)‘ containing a list of toplevel
non-terminals (e.g. ‘(:toplevel a b c)‘).
If no such form is given, all nontermials on the left-hand side of the given productions
will become toplevel.
Productions may also contain one form ‘(:ignore ...)‘ containing a list of ignorable tokens.
Those may occur at any positition and are preserved, if all tokens are printed with
‘print-token*‘.
If no ‘:ignore‘ form is given, it defaults to ‘’(:default)‘.
grammar.lisp (file)
simple.lisp (file)
grammar.lisp (file)
Next: Internal classes, Previous: Internal functions, Up: Internal definitions [Contents][Index]
=> a style denoted by ‘style‘ being either a key or an actual style
common.lisp (file)
simple.lisp (file)
common.lisp (file)
Process a stream with a ‘style‘.
grammar.lisp (file)
Process a stream with a ‘simple-style‘.
simple.lisp (file)
=> the name of ‘style‘
common.lisp (file)
automatically generated reader method
simple.lisp (file)
automatically generated reader method
grammar.lisp (file)
automatically generated reader method
simple.lisp (file)
Previous: Internal generic functions, Up: Internal definitions [Contents][Index]
grammar.lisp (file)
simple-style (class)
:parser
style-parser (generic function)
simple.lisp (file)
standard-object (class)
cfg-style (class)
:rules
style-rules (generic function)
:name
style-name (generic function)
Previous: Definitions, Up: Top [Contents][Index]
| • Concept index | ||
| • Function index | ||
| • Variable index | ||
| • Data type index |
Next: Function index, Previous: Indexes, Up: Indexes [Contents][Index]
| Jump to: | F L |
|---|
| Jump to: | F L |
|---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
| Jump to: | C D F G I L M P R S T |
|---|
| Jump to: | C D F G I L M P R S T |
|---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
| Jump to: | *
N P R S |
|---|
| Jump to: | *
N P R S |
|---|
Previous: Variable index, Up: Indexes [Contents][Index]
| Jump to: | C L P S |
|---|
| Jump to: | C L P S |
|---|