Overview

Scintillua adds support for Lua LPeg lexers (over 80 of them) in Scintilla and SciTE. The LPeg lexer is an external lexer so no modifications to Scintilla are necessary. As of SciTE 2.22, Scintillua can be 'dropped-in' to a SciTE install. Prior to 2.21, a precompiled SciTE with some required changes was provided.

With regards to speed, dynamic lexers parse the same amount of text as Scintilla's lexers; any differences in speed should be negligible.

Package Contents

This package contains the following:

1. The external lexer LexLPeg.cxx and its associated Makefile and LexLPeg.def.
2. A lexers/ folder containing a set of Lua LPeg lexers.

Using with SciTE

First, unpack the package to a temporary directory.

If you have direct access to your SciTE installation:

1. Move the lexers/ folder to SciteDefaultHome.

e.g. C:\Program Files\SciTE on Windows.

/usr/share/scite/ on Linux.

If you do not have direct access to your SciTE installation:

1. Move the lexers/ folder to your home directory.

e.g. C:\Documents and Settings\mitchell on Windows.

/home/mitchell/ on Linux.

3. Modify the 'lexer.lpeg.home' property in lexers/lpeg.properties to reflect

where you put the lexers/ folder. e.g lexer.lpeg.home=$(SciteUserHome)\lexers

lexer.lpeg.home=$(SciteUserHome)/.lexers

Additionally for 64-bit Linux machines, you will have to rename lexers/liblexlpeg.x86_64.so to lexers/liblexlpeg.so.

By default, SciTE will use the LPeg lexers wherever possible, falling back to the Scintilla ones if necessary. To disable a particular LPeg lexer, open the lexers/lpeg.properties file and comment out its file.pattern.lexer and lexer.$(file.pattern.lexer) property lines.

If you get incorrect or no syntax highlighting, please do the following:

1. Make sure the language has a lexer in the lexers/ directory.

2. Make sure there is a .properties file that has the language's extension.

e.g. file.patterns.rhtml=*.rhtml

e.g. lexer.$(file.patterns.rhtml)=*.rhtml

lexer.$(file.patterns.java)=java

I do not have the time to continuously update *.properties files with extensions and lexers, so please be patient if you have to do it manually.

Please also note that SciTE lexer-specific features do not work in LPeg lexers; features like:

• Python colon matching.
• HTML/XML tag auto-completion.
• Style, keyword, and folding properties in *.properties files.

Using with Scintilla

If you wish to use the external lexer with an instance of Scintilla, you must set the following properties after calling SCI_SETLEXERLANGUAGE:

• lexer.lpeg.home - directory containing dynamic Lua lexers.
• lexer.lpeg.script - path of lexer.lua file.
• lexer.lpeg.color.theme - universal color theme to use.

Optionally, you may set:

• fold.by.indentation - fold code by indentation level.

Lexer API

The Lua LPeg lexer is responsible for managing multiple lexers and the styling information associated with them. Doing this using the Scintilla API without modifying Scintilla itself is impossible. For example, SCI_SETLEXERLANGUAGE causes Scintilla to look within its own lexer catalog for the desired lexer rather than consulting the Lua LPeg lexer. To solve these problems, a lexer API was created and is available via SCI_PRIVATELEXERCALL.

Please note the names of API calls may not make perfect sense. The idea behind them was to use existing Scintilla names to maximize portability.

The following notation is used: 'code(arg)' expands to 'SendScintilla(sci, SCI_PRIVATELEXERCALL, code, arg)'.

SCI_GETDIRECTFUNCTION(SciFnDirect)

SCI_SETDOCPOINTER(sci)

SciFnDirect is the result of calling Scintilla's SCI_GETDIRECTFUNCTION. sci is the result of calling Scintilla's SCI_GETDIRECTPOINTER. Call these if you would like to have the Lua LPeg lexer set all styles automatically. SCI_GETDIRECTFUNCTION only has to be called once for each Scintilla buffer created with SCI_CREATEDOCUMENT. SCI_SETDOCPOINTER must be called before each call to SCI_SETLEXERLANGUAGE(languageName).

SCI_SETLEXERLANGUAGE(languageName)

Sets the current lexer to languageName. If you are having the Lua LPeg lexer set the styles automatically, make sure you call SCI_SETDOCPOINTER(sci) first.

SCI_GETLEXERLANGUAGE

Returns the string name of the current lexer.

-STYLE_MAX to -1

If the Lua LPeg lexer was not compiled with the NO_SCITE flag, calling SCI_PRIVATELEXERCALL with a negative integer in this range returns a SciTE style property string for the nth style offset by STYLE_MAX. -STYLE_MAX equates to the 0th style number, -1 the (STYLE_MAX - 1)th style number. You can parse these strings to set the lexer styles manually if you chose not to have the Lua LPeg lexer set them for you via SCI_GETDIRECTFUNCTION(SciFnDirect) and SCI_SETDOCPOINTER(sci). Please see the SciTE documentation (http://www.scintilla.org/SciTEDoc.html) for how these strings are formatted.

0 to STYLE_MAX

The integer in this range is the result of calling Scintilla's SCI_GETSTYLEAT. Returns the string name of token associated with this style number.

Using with your App

Here is a pseudo-code example:

    init_app() {
      sci = scintilla_new()
      lib = "/home/mitchell/app/lexers/liblexlpeg.so"
      SendScintilla(sci, SCI_LOADLEXERLIBRARY, 0, lib)
    }

    create_doc() {
      doc = SendScintilla(sci, SCI_CREATEDOCUMENT)
      SendScintilla(sci, SCI_SETDOCPOINTER, 0, doc)
      SendScintilla(sci, SCI_SETLEXERLANGUAGE, 0, "lpeg")
      home = "/home/mitchell/app/lexers"
      SendScintilla(sci, SCI_SETPROPERTY, "lexer.lpeg.home", home)
      script = "/home/mitchell/app/lexers/lexer.lua"
      SendScintilla(sci, SCI_SETPROPERTY, "lexer.lpeg.script", script)
      SendScintilla(sci, SCI_SETPROPERTY, "lexer.lpeg.color.theme", "light")
      fn = SendScintilla(sci, SCI_GETDIRECTFUNCTION)
      SendScintilla(sci, SCI_PRIVATELEXERCALL, SCI_GETDIRECTFUNCTION, fn)
      SendScintilla(sci, SCI_PRIVATELEXERCALL, SCI_SETDOCPOINTER, sci)
      SendScintilla(sci, SCI_PRIVATELEXERCALL, SCI_SETLEXERLANGUAGE, "lua")
    }

    set_lexer(lang) {
      SendScintilla(sci, SCI_PRIVATELEXERCALL, SCI_SETDOCPOINTER, sci)
      SendScintilla(sci, SCI_PRIVATELEXERCALL, SCI_SETLEXERLANGUAGE, lang)
    }

Creating Lexers

Please see http://caladbolg.net/luadoc/textadept/modules/lexer.html.