Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Lexing & Syntax Highlighting in Lua (using LPeg)
Lua C JavaScript
tag: 0.6.4

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
etc
examples
src
test
Makefile
README.md
TODO.md

README.md

LXSH: Lexing & Syntax Highlighting in Lua

LXSH is a collection of lexers and highlighters written in Lua using the excellent pattern-matching library LPeg. The highlighters generate HTML designed to be easily embedded in web pages. Two programming languages are currently supported, these are Lua and C. The highlighters support three color schemes, here are some examples of both languages in every color scheme:

As you can see in the above examples the highlighters replace standard library identifiers (and then some) with hyperlinks to the relevant documentation. You can also try switching between style sheets while staying on the same page by using your web browsers View → Page styles menu (this works using so-called "alternate style sheets").

Installation

The easiest way to download and install LXSH is using LuaRocks:

$ luarocks install http://peterodding.com/code/lua/lxsh/downloads/lxsh-0.6.1-1.rockspec

If you don't have LuaRocks installed you can download the latest release directly from GitHub as a ZIP archive. To install create an lxsh directory in your $LUA_PATH and copy the contents of the src directory from the ZIP archive to the lxsh directory so that you end up with the following structure:

  • $LUA_PATH/lxsh/init.lua
  • $LUA_PATH/lxsh/lexers/*.lua
  • $LUA_PATH/lxsh/highlighters/*.lua
  • $LUA_PATH/lxsh/colors/*.lua
  • $LUA_PATH/lxsh/docs/*.lua

Usage

If you want to call a lexer or access an LPeg pattern defined by the lexer you can do so as follows (this example demonstrates the Lua lexer but the C lexer works the same):

> -- Load the lexer.
> lexer = require 'lxsh.lexers.lua'

> -- Run the lexer on a string of source code.
> for kind, text in lexer.gmatch 'i = i + 1 -- example' do
>>  print(kind, text)
>> end
identifier  i
whitespace   
operator    =
whitespace   
identifier  i
whitespace   
operator    +
whitespace   
number      1
whitespace   
comment     -- example

> -- Use one of the patterns defined by the lexer.
> lexer.patterns.comment:match '--[=[ this is a long comment ]=]'

The syntax highlighters can be used as follows:

> -- Load the highlighter.
> highlighter = require 'lxsh.highlighters.lua'

> -- Use it to highlight some code (line breaks added for clarity).
> print(highlighter("require 'lpeg'", { external = true }))
<pre class="sourcecode lua">
<a href="http://www.lua.org/manual/5.1/manual.html#pdf-require" class="library">require</a>
<span class="constant">'lpeg'</span>
</pre>

You can customize the output of the highlighters by passing a table with one or more of the following options:

  • encodews: Replace newlines with <br> elements and ordinary spaces with non-breaking spaces so that whitespace is preserved when the highlighted code isn't embedded in a <pre> block
  • external: By default the highlighters generate inline CSS which makes it easier to use the output directly but it also bloats the size significantly. If you want to reduce the size and don't mind including an external style sheet you can set this option to true. You'll need to make sure the required styles are loaded, e.g. by embedding the output of lxsh.includestyles(preferred, includeswitcher) in the <head> of your HTML document (the preferred argument indicates the default style sheet and if you pass includeswitcher as true then an interactive style sheet switcher using JavaScript is included)
  • colors: The color scheme to use, one of the following:

Tokens produced by the lexers

The Lua lexer produces the following tokens:

  • comment
  • constant (true, false and nil)
  • error (invalid input)
  • identifier
  • keyword
  • number
  • operator
  • string
  • whitespace

The C lexer produces the following tokens:

  • comment
  • constant (character and string literals like 'C' and "Lua")
  • error (invalid input)
  • identifier
  • keyword
  • number
  • operator
  • preprocessor
  • whitespace

Contact

If you have questions, bug reports, suggestions, etc. the author can be contacted at peter@peterodding.com. The latest version is available at http://peterodding.com/code/lua/lxsh/ and http://github.com/xolox/lua-lxsh.

License

This software is licensed under the MIT license.
© 2010 Peter Odding <peter@peterodding.com>.

Something went wrong with that request. Please try again.