The lowlight Reference Manual

This is the lowlight Reference Manual, version 0.99.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Sep 15 05:58:02 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 lowlight

A simple and flexible syntax highlighter

Author

Christoph Finkensiep <>

License

MIT/X11

Version

0.99.0

Dependencies
  • cl-ppcre (system).
  • alexandria (system).
  • spinneret (system).
  • cl-who (system).
  • graylex (system).
  • yacc (system).
Source

lowlight.asd.

Child Components

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


3.1 Lisp


3.1.1 lowlight/lowlight.asd

Source

lowlight.asd.

Parent Component

lowlight (system).

ASDF Systems

lowlight.


3.1.2 lowlight/package.lisp

Source

lowlight.asd.

Parent Component

lowlight (system).

Packages

lowlight.1.


3.1.3 lowlight/common.lisp

Dependency

package.lisp (file).

Source

lowlight.asd.

Parent Component

lowlight (system).

Public Interface
Internals

3.1.4 lowlight/simple.lisp

Dependency

common.lisp (file).

Source

lowlight.asd.

Parent Component

lowlight (system).

Public Interface
Internals

3.1.5 lowlight/grammar.lisp

Dependency

simple.lisp (file).

Source

lowlight.asd.

Parent Component

lowlight (system).

Public Interface
Internals

3.1.6 lowlight/lowlight.lisp

Dependency

grammar.lisp (file).

Source

lowlight.asd.

Parent Component

lowlight (system).

Public Interface
Internals

3.1.7 lowlight/style-lisp.lisp

Dependency

lowlight.lisp (file).

Source

lowlight.asd.

Parent Component

lowlight (system).

Internals

4 Packages

Packages are listed by definition order.


4.1 lowlight.1

Source

package.lisp.

Nicknames
  • lowlight
  • ll
  • ll1
Use List

common-lisp.

Public Interface
Internals

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


5.1 Public Interface


5.1.1 Special variables

Special Variable: *debug*

controls debug output (‘t‘ or ‘nil‘)

Package

lowlight.1.

Source

common.lisp.

Special Variable: *lexer-buffer-size*

controlling knob for the graylex buffer size

Package

lowlight.1.

Source

common.lisp.


5.1.2 Macros

Macro: define-cfg-style (name rules productions)

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)‘.

Package

lowlight.1.

Source

grammar.lisp.

Macro: define-simple-style (name &body rules)

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.

Package

lowlight.1.

Source

simple.lisp.


5.1.3 Ordinary functions

Function: light (style input &optional output)

=> 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.

Package

lowlight.1.

Source

lowlight.lisp.

Function: light-blocks (style input &key output blocks)

=> 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‘.

Package

lowlight.1.

Source

lowlight.lisp.

Function: light-file (style in &key out css title raw)

=> ‘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.

Package

lowlight.1.

Source

lowlight.lisp.

Function: light-file-blocks (style in &key out blocks)

=> ‘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.

Package

lowlight.1.

Source

lowlight.lisp.

Function: make-cfg-style (name rules productions)

=> 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‘.

Package

lowlight.1.

Source

grammar.lisp.

Function: make-simple-style (name rules)

=> 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‘.

Package

lowlight.1.

Source

simple.lisp.


5.1.4 Generic functions

Generic Function: style-classes (style)

=> the set of token classes generated by ‘style‘

Package

lowlight.1.

Source

common.lisp.

Methods
Method: style-classes ((style simple-style))
Source

simple.lisp.

Method: style-classes (style)

5.2 Internals


5.2.1 Special variables

Special Variable: *parser*
Package

lowlight.1.

Source

style-lisp.lisp.

Special Variable: *styles*

An alist mapping from style keywords to style definitions.

Package

lowlight.1.

Source

common.lisp.

Special Variable: *token-printer*
Package

lowlight.1.

Source

grammar.lisp.


5.2.2 Macros

Macro: make-cfg-style% (name rules productions)
Package

lowlight.1.

Source

grammar.lisp.


5.2.3 Ordinary functions

Function: classify-symbol (str)
Package

lowlight.1.

Source

style-lisp.lisp.

Function: inject-ignorables (terminals ignores productions)

=> 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.

Package

lowlight.1.

Source

grammar.lisp.

Function: light-blocks% (style input output blocks)

highlight all blocks in input

Package

lowlight.1.

Source

lowlight.lisp.

Function: light-blocks%* (style input output blocks)
Package

lowlight.1.

Source

lowlight.lisp.

Function: make-blocks-regex (blocks)
Package

lowlight.1.

Source

lowlight.lisp.

Function: maprec (fn tree &optional depth)
Package

lowlight.1.

Source

grammar.lisp.

Function: print-define (def name)
Package

lowlight.1.

Source

style-lisp.lisp.

Function: print-if (cnd obj &optional stream)
Package

lowlight.1.

Source

grammar.lisp.

Function: print-setf-define (def setf name)
Package

lowlight.1.

Source

style-lisp.lisp.

Function: print-token (class token output)
Package

lowlight.1.

Source

simple.lisp.

Function: print-token* (class token)
Package

lowlight.1.

Source

grammar.lisp.

Function: print-typedef (def name)
Package

lowlight.1.

Source

style-lisp.lisp.

Function: print-vardef (def name)
Package

lowlight.1.

Source

style-lisp.lisp.

Function: read-into-string (in-stream &key buffer-size)

=> a string containing the whole stream data from ‘in-stream‘ Taken from Alexandria’s ‘read-file-into-string.‘

Package

lowlight.1.

Source

lowlight.lisp.

Function: rules-to-grammar (rules productions)

=> 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)‘.

Package

lowlight.1.

Source

grammar.lisp.

Function: tokenize (lexer output)
Package

lowlight.1.

Source

simple.lisp.

Function: tree-sub (table tree &optional depth)
Package

lowlight.1.

Source

grammar.lisp.


5.2.4 Generic functions

Generic Function: get-style (style)

=> a style denoted by ‘style‘ being either a key or an actual style

Package

lowlight.1.

Source

common.lisp.

Methods
Method: get-style ((style simple-style))
Source

simple.lisp.

Method: get-style (style)
Generic Function: process-style (style input output)
Package

lowlight.1.

Source

common.lisp.

Methods
Method: process-style ((style cfg-style) input output)

Process a stream with a ‘style‘.

Source

grammar.lisp.

Method: process-style ((style simple-style) input output)

Process a stream with a ‘simple-style‘.

Source

simple.lisp.

Generic Function: style-name (style)

=> the name of ‘style‘

Package

lowlight.1.

Source

common.lisp.

Methods
Reader Method: style-name ((simple-style simple-style))

automatically generated reader method

Source

simple.lisp.

Target Slot

name.

Method: style-name (style)
Generic Reader: style-parser (object)
Package

lowlight.1.

Methods
Reader Method: style-parser ((cfg-style cfg-style))

automatically generated reader method

Source

grammar.lisp.

Target Slot

parser.

Generic Reader: style-rules (object)
Package

lowlight.1.

Methods
Reader Method: style-rules ((simple-style simple-style))

automatically generated reader method

Source

simple.lisp.

Target Slot

rules.


5.2.5 Classes

Class: cfg-style
Package

lowlight.1.

Source

grammar.lisp.

Direct superclasses

simple-style.

Direct methods
Direct slots
Slot: parser
Initargs

:parser

Readers

style-parser.

Writers

This slot is read-only.

Class: simple-style
Package

lowlight.1.

Source

simple.lisp.

Direct subclasses

cfg-style.

Direct methods
Direct slots
Slot: rules
Initargs

:rules

Readers

style-rules.

Writers

This slot is read-only.

Slot: name
Initargs

:name

Readers

style-name.

Writers

This slot is read-only.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   C   D   F   G   I   L   M   P   R   S   T  
Index Entry  Section

C
classify-symbol: Private ordinary functions

D
define-cfg-style: Public macros
define-simple-style: Public macros

F
Function, classify-symbol: Private ordinary functions
Function, inject-ignorables: Private ordinary functions
Function, light: Public ordinary functions
Function, light-blocks: Public ordinary functions
Function, light-blocks%: Private ordinary functions
Function, light-blocks%*: Private ordinary functions
Function, light-file: Public ordinary functions
Function, light-file-blocks: Public ordinary functions
Function, make-blocks-regex: Private ordinary functions
Function, make-cfg-style: Public ordinary functions
Function, make-simple-style: Public ordinary functions
Function, maprec: Private ordinary functions
Function, print-define: Private ordinary functions
Function, print-if: Private ordinary functions
Function, print-setf-define: Private ordinary functions
Function, print-token: Private ordinary functions
Function, print-token*: Private ordinary functions
Function, print-typedef: Private ordinary functions
Function, print-vardef: Private ordinary functions
Function, read-into-string: Private ordinary functions
Function, rules-to-grammar: Private ordinary functions
Function, tokenize: Private ordinary functions
Function, tree-sub: Private ordinary functions

G
Generic Function, get-style: Private generic functions
Generic Function, process-style: Private generic functions
Generic Function, style-classes: Public generic functions
Generic Function, style-name: Private generic functions
Generic Function, style-parser: Private generic functions
Generic Function, style-rules: Private generic functions
get-style: Private generic functions
get-style: Private generic functions
get-style: Private generic functions

I
inject-ignorables: Private ordinary functions

L
light: Public ordinary functions
light-blocks: Public ordinary functions
light-blocks%: Private ordinary functions
light-blocks%*: Private ordinary functions
light-file: Public ordinary functions
light-file-blocks: Public ordinary functions

M
Macro, define-cfg-style: Public macros
Macro, define-simple-style: Public macros
Macro, make-cfg-style%: Private macros
make-blocks-regex: Private ordinary functions
make-cfg-style: Public ordinary functions
make-cfg-style%: Private macros
make-simple-style: Public ordinary functions
maprec: Private ordinary functions
Method, get-style: Private generic functions
Method, get-style: Private generic functions
Method, process-style: Private generic functions
Method, process-style: Private generic functions
Method, style-classes: Public generic functions
Method, style-classes: Public generic functions
Method, style-name: Private generic functions
Method, style-name: Private generic functions
Method, style-parser: Private generic functions
Method, style-rules: Private generic functions

P
print-define: Private ordinary functions
print-if: Private ordinary functions
print-setf-define: Private ordinary functions
print-token: Private ordinary functions
print-token*: Private ordinary functions
print-typedef: Private ordinary functions
print-vardef: Private ordinary functions
process-style: Private generic functions
process-style: Private generic functions
process-style: Private generic functions

R
read-into-string: Private ordinary functions
rules-to-grammar: Private ordinary functions

S
style-classes: Public generic functions
style-classes: Public generic functions
style-classes: Public generic functions
style-name: Private generic functions
style-name: Private generic functions
style-name: Private generic functions
style-parser: Private generic functions
style-parser: Private generic functions
style-rules: Private generic functions
style-rules: Private generic functions

T
tokenize: Private ordinary functions
tree-sub: Private ordinary functions