This package requires Scintilla/SciTE >= 2.25.

### Topics covered in this README

* Overview.
* Package Contents.
* Using with SciTE.
* Using with Scintilla.
* Lexer API.
* Using with your App.
* Creating Lexers.

### Overview

Scintillua adds support for Lua LPeg lexers in Scintilla and SciTE. The LPeg
lexer is an external lexer so no modifications to Scintilla are necessary.

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.
2. Add 'import lexers/lpeg' to your SciTEGlobal.properties (no quotes).

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.
2. Add 'import lexers/lpeg' to your SciTEUser.properties (Windows) or
   .SciTEUser.properties (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
3. Make sure the file pattern's lexer is correct or exists.
   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.
  * fold.line.comments - fold line comments.

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