scintillua.luadoc

-- Copyright 2007-2020 Mitchell. See LICENSE.
-- This is a DUMMY FILE used for making LuaDoc for the Scintillua API.

---
-- ### Overview
--
-- The Scintillua Scintilla lexer has its own API in order to avoid any modifications to
-- Scintilla itself. It is invoked using [`SCI_PRIVATELEXERCALL`][]. Please note that some of
-- the names of the API calls do not make perfect sense. This is a tradeoff in order to keep
-- Scintilla unmodified.
--
-- [`SCI_PRIVATELEXERCALL`]: https://scintilla.org/ScintillaDoc.html#LexerObjects
--
-- The following notation is used:
--
--     SCI_PRIVATELEXERCALL (int operation, void *pointer)
--
-- This means you would call Scintilla like this:
--
--     SendScintilla(sci, SCI_PRIVATELEXERCALL, operation, pointer);
--
-- ### Scintillua Usage Example
--
-- Here is a pseudo-code example:
--
--     init_app() {
--       SetLibraryProperty("lpeg.home", "/home/mitchell/app/lexers")
--       SetLibraryProperty("lpeg.color.theme", "light")
--       sci = scintilla_new()
--     }
--
--     create_doc() {
--       doc = SendScintilla(sci, SCI_CREATEDOCUMENT)
--       SendScintilla(sci, SCI_SETDOCPOINTER, 0, doc)
--       SendScintilla(sci, SCI_SETILEXER, 0, CreateLexer(NULL))
--       fn = SendScintilla(sci, SCI_GETDIRECTFUNCTION)
--       SendScintilla(sci, SCI_PRIVATELEXERCALL, SCI_GETDIRECTFUNCTION, fn)
--       psci = SendScintilla(sci, SCI_GETDIRECTPOINTER)
--       SendScintilla(sci, SCI_PRIVATELEXERCALL, SCI_SETDOCPOINTER, psci)
--       SendScintilla(sci, SCI_PRIVATELEXERCALL, SCI_SETILEXER, "lua")
--     }
--
--     set_lexer(lang) {
--       psci = SendScintilla(sci, SCI_GETDIRECTPOINTER)
--       SendScintilla(sci, SCI_PRIVATELEXERCALL, SCI_SETDOCPOINTER, psci)
--       SendScintilla(sci, SCI_PRIVATELEXERCALL, SCI_SETILEXER, lang)
--     }
module('Scintillua')

---
-- Tells Scintillua the address of the function that handles Scintilla messages.
--
-- Despite the name `SCI_GETDIRECTFUNCTION`, it only notifies Scintillua what the value of
-- `SciFnDirect` obtained from [`SCI_GETDIRECTFUNCTION`][] is. It does not return anything.
-- Use this if you would like to have the Scintillua lexer set all Lua LPeg lexer styles
-- automatically. This is useful for maintaining a consistent color theme. Do not use this if
-- your application maintains its own color theme.
--
-- If you use this call, it *must* be made *once* for each Scintilla buffer that was created using
-- [`SCI_CREATEDOCUMENT`][]. You must also use the [`SCI_SETDOCPOINTER()`](#SCI_SETDOCPOINTER)
-- Scintillua API call.
--
-- [`SCI_GETDIRECTFUNCTION`]: https://scintilla.org/ScintillaDoc.html#SCI_GETDIRECTFUNCTION
-- [`SCI_CREATEDOCUMENT`]: https://scintilla.org/ScintillaDoc.html#SCI_CREATEDOCUMENT
-- @param SciFnDirect The pointer returned by [`SCI_GETDIRECTFUNCTION`][].
-- @usage fn = SendScintilla(sci, SCI_GETDIRECTFUNCTION)
-- @usage SendScintilla(sci, SCI_PRIVATELEXERCALL, SCI_GETDIRECTFUNCTION, fn)
-- @see SCI_SETDOCPOINTER
-- @name SCI_GETDIRECTFUNCTION
function SCI_PRIVATELEXERCALL(SCI_GETDIRECTFUNCTION, SciFnDirect) end

---
-- Tells Scintillua the address of the Scintilla window currently in use.
--
-- Despite the name `SCI_SETDOCPOINTER`, it has no relationship to Scintilla documents.
--
-- Use this call only if you are using the [`SCI_GETDIRECTFUNCTION()`](#SCI_GETDIRECTFUNCTION)
-- Scintillua API call. It *must* be made *before* each call to the
-- [`SCI_SETILEXER()`](#SCI_SETILEXER) Scintillua API call.
-- @param sci The pointer returned by [`SCI_GETDIRECTPOINTER`][].
--
-- [`SCI_GETDIRECTPOINTER`]: https://scintilla.org/ScintillaDoc.html#SCI_GETDIRECTPOINTER
-- @usage SendScintilla(sci, SCI_PRIVATELEXERCALL, SCI_SETDOCPOINTER, sci)
-- @see SCI_GETDIRECTFUNCTION
-- @see SCI_SETILEXER
-- @name SCI_SETDOCPOINTER
function SCI_PRIVATELEXERCALL(SCI_SETDOCPOINTER, sci) end

---
-- Tells Scintillua to use `lua` as its Lua state instead of creating a separate state.
--
-- `lua` must have already opened the "base", "string", "table", and "lpeg" libraries.
--
-- Scintillua will create a single `lexer` package (that can be used with Lua's `require()`),
-- as well as a number of other variables in the `LUA_REGISTRYINDEX` table with the "sci_" prefix.
--
-- Instead of including the path to Scintillua's lexers in the `package.path` of the given
-- Lua state, set the "lexer.lpeg.home" property appropriately instead. Scintillua uses that
-- property to find and load lexers.
-- @param lua (`lua_State *`) The Lua state to use.
-- @usage lua = luaL_newstate()
-- @usage SendScintilla(sci, SCI_PRIVATELEXERCALL, SCI_CHANGELEXERSTATE, lua)
-- @name SCI_CHANGELEXERSTATE
function SCI_PRIVATELEXERCALL(SCI_CHANGELEXERSTATE, lua) end

---
-- Sets the current Lua LPeg lexer to `languageName`.
--
-- If you are having the Scintillua lexer set the Lua LPeg lexer styles automatically, make
-- sure you call the [`SCI_SETDOCPOINTER()`](#SCI_SETDOCPOINTER) Scintillua API *first*.
-- @param languageName (`const char*`) The name of the Lua LPeg lexer to use.
-- @usage SendScintilla(sci, SCI_PRIVATELEXERCALL, SCI_SETILEXER, "lua")
-- @see SCI_SETDOCPOINTER
-- @see SCI_GETLEXERLANGUAGE
-- @name SCI_SETILEXER
function SCI_PRIVATELEXERCALL(SCI_SETILEXER, languageName) end

---
-- Returns the length of the string name of the current Lua LPeg lexer or stores the name into
-- the given buffer. If the buffer is long enough, the name is terminated by a `0` character.
--
-- For parent lexers with embedded children or child lexers embedded into parents, the name is in
-- "lexer/current" format, where "lexer" is the actual lexer's name and "current" is the parent
-- or child lexer at the current caret position. In order for this to work, you must have called
-- [`SCI_GETDIRECTFUNCTION`](#SCI_GETDIRECTFUNCTION) and [`SCI_SETDOCPOINTER`](#SCI_SETDOCPOINTER).
-- @param languageName (`char *`) If `NULL`, returns the length that should be allocated to
--   store the string Lua LPeg lexer name. Otherwise fills the buffer with the name.
-- @name SCI_GETLEXER
function SCI_PRIVATELEXERCALL(SCI_GETLEXER, languageName) end

---
-- Returns the length of the associated SciTE-formatted style definition for the given style
-- number or stores that string into the given buffer. If the buffer is long enough, the string
-- is terminated by a `0` character.
--
-- Please see the [SciTE documentation][] for the style definition format
-- specified by `style.*.stylenumber`. You can parse these definitions
-- to set Lua LPeg lexer styles manually if you chose not to have them set
-- automatically using the [`SCI_GETDIRECTFUNCTION()`](#SCI_GETDIRECTFUNCTION) and
-- [`SCI_SETDOCPOINTER()`](#SCI_SETDOCPOINTER) Scintillua API calls.
--
-- [SciTE documentation]: https://scintilla.org/SciTEDoc.html
-- @param styleNum (`int`) For the range `-STYLE_MAX <= styleNum < 0`, uses the Scintilla style
--   number `-styleNum - 1` for returning SciTE-formatted style definitions. (Style `0` would be
--   `-1`, style `1` would be `-2`, and so on.)
-- @param style (`char *`) If `NULL`, returns the length that should be allocated to store the
--   associated string. Otherwise fills the buffer with the string.
-- @name styleNum
function SCI_PRIVATELEXERCALL(styleNum, style) end

---
-- Returns the error message of the Scintillua or Lua LPeg lexer error that occurred (if any).
--
-- If no error occurred, the returned message will be empty.
--
-- Since Scintillua does not throw errors as they occur, errors can only be handled passively. Note
-- that Scintillua does print all errors to stderr.
-- @usage SendScintilla(sci, SCI_PRIVATELEXERCALL, SCI_GETSTATUS, errmsg)
-- @usage if (strlen(errmsg) > 0) { /* handle error */ }
-- @name SCI_GETSTATUS
function SCI_PRIVATELEXERCALL(SCI_GETSTATUS) end

---
-- Tells Scintillua that the given path is where Scintillua's lexers are located, or is a path
-- that contains additional lexers and/or themes to load (e.g. user-defined lexers/themes).
--
-- This call may be made multiple times in order to support lexers and themes across multiple
-- directories.
-- @param path (`const char *`) A path containing Scintillua lexers and/or themes.
-- @usage SendScintilla(sci, SCI_PRIVATELEXERCALL, SCI_CREATELOADER, "path/to/lexers")
-- @name SCI_CREATELOADER
function SCI_PRIVATELEXERCALL(SCI_CREATELOADER, path) end

---
-- Returns the length of a '\n'-separated list of known lexer names, or stores the lexer list into
-- the given buffer. If the buffer is long enough, the string is terminated by a `0` character.
--
-- The lexers in this list can be passed to the [`SCI_SETILEXER`](#SCI_SETILEXER) Scintillua
-- API call.
-- @param names (`char *`) If `NULL`, returns the length that should be allocated to store the
--   list of lexer names. Otherwise fills the buffer with the names.
-- @usage SendScintilla(sci, SCI_PRIVATELEXERCALL, SCI_GETLEXERLANGUAGE, lexers)
-- @usage // lexers now contains a '\n'-separated list of known lexer names
-- @see SCI_SETILEXER
-- @name SCI_GETLEXERLANGUAGE
function SCI_PRIVATELEXERCALL(SCI_GETLEXERLANGUAGE, names) end

---
-- Returns the style number associated with *styleName*, or `STYLE_DEFAULT` if *styleName*
-- is not known.
-- @param styleName (`const char *`) Style name to get the style number of.
-- @usage SendScintilla(sci, SCI_PRIVATELEXERCALL, SCI_GETNAMEDSTYLES, "error")
-- @usage SendScintilla(sci, SCI_ANNOTATIONSETSTYLE, line, style) // match error style
-- @name SCI_GETNAMEDSTYLES
function SCI_PRIVATELEXERCALL(SCI_GETNAMEDSTYLES, styleName) end