Textadept
- Home |
- Download |
- Lua API |
- Source |
- Language Modules |
- Stats |
- Wiki |
- Mailing List
Contents
Appendix
Lua Patterns
The following is taken from the Lua 5.2 Reference Manual.
Character Class:
A character class is used to represent a set of characters. The following combinations are allowed in describing a character class:
x
: (where x is not one of the magic characters^$()%.[]*+-?
) represents the character x itself..
: (a dot) represents all characters.%a
: represents all letters.%c
: represents all control characters.%d
: represents all digits.%g
: represents all printable characters except space.%l
: represents all lowercase letters.%p
: represents all punctuation characters.%s
: represents all space characters.%u
: represents all uppercase letters.%w
: represents all alphanumeric characters.%x
: represents all hexadecimal digits.%
x
: (where x is any non-alphanumeric character) represents the character x. This is the standard way to escape the magic characters. Any punctuation character (even the non magic) can be preceded by a ‘%
’ when used to represent itself in a pattern.[set]
: represents the class which is the union of all characters in set. A range of characters can be specified by separating the end characters of the range with a ‘-
’. All classes%
x described above can also be used as components in set. All other characters in set represent themselves. For example,[%w_]
(or[_%w]
) represents all alphanumeric characters plus the underscore,[0-7]
represents the octal digits, and[0-7%l%-]
represents the octal digits plus the lowercase letters plus the ‘-
’ character.
The interaction between ranges and classes is not defined. Therefore, patterns like[%a-z]
or[a-%%]
have no meaning.[^set]
: represents the complement of set, where set is interpreted as above.
For all classes represented by single letters (%a
, %c
, etc.), the
corresponding uppercase letter represents the complement of the class. For
instance, %S
represents all non-space characters.
The definitions of letter, space, and other character groups depend on the
current locale. In particular, the class [a-z]
may not be equivalent to %l
.
Pattern Item:
A pattern item can be
- a single character class, which matches any single character in the class;
- a single character class followed by ‘
*
’, which matches 0 or more repetitions of characters in the class. These repetition items will always match the longest possible sequence; - a single character class followed by ‘
+
’, which matches 1 or more repetitions of characters in the class. These repetition items will always match the longest possible sequence; - a single character class followed by ‘
-
’, which also matches 0 or more repetitions of characters in the class. Unlike ‘*
’, these repetition items will always match the shortest possible sequence; - a single character class followed by ‘
?
’, which matches 0 or 1 occurrence of a character in the class; %n
, for n between 1 and 9; such item matches a substring equal to the n-th captured string (see below);%bxy
, where x and y are two distinct characters; such item matches strings that start with x, end with y, and where the x and y are balanced. This means that, if one reads the string from left to right, counting +1 for an x and -1 for a y, the ending y is the first y where the count reaches 0. For instance, the item%b()
matches expressions with balanced parentheses.%f[set]
, a frontier pattern; such item matches an empty string at any position such that the next character belongs to set and the previous character does not belong to set. The set set is interpreted as previously described. The beginning and the end of the subject are handled as if they were the character'\0'
.
Pattern:
A pattern is a sequence of pattern items. A ‘^
’ at the beginning of a
pattern anchors the match at the beginning of the subject string. A ‘$
’ at the
end of a pattern anchors the match at the end of the subject string. At other
positions, ‘^
’ and ‘$
’ have no special meaning and represent themselves.
Captures:
A pattern can contain sub-patterns enclosed in parentheses; they describe
captures. When a match succeeds, the substrings of the subject string that
match captures are stored (captured) for future use. Captures are numbered
according to their left parentheses. For instance, in the pattern
"(a*(.)%w(%s*))"
, the part of the string matching "a*(.)%w(%s*)"
is stored
as the first capture (and therefore has number 1); the character matching “.
”
is captured with number 2, and the part matching “%s*
” has number 3.
As a special case, the empty capture ()
captures the current string position
(a number). For instance, if we apply the pattern "()aa()"
on the string
"flaaap"
, there will be two captures: 3 and 5.
Curses Compatibility
Textadept 5.5 beta introduced a curses version that can run in a terminal emulator. However, since curses is quite low-level in terms of graphics capability compared to GTK+, the curses version of Textadept lacks some features in its editing component Scintilla and in general:
- Any settings with alpha values are not supported.
- Autocompletion lists cannot show images (pixmap surfaces are not supported).
Instead, they show the first character in the string passed to
buffer:register_image()
. - Buffered and two-phase drawing is not supported.
- Call tip arrows are not displayed (
surface->Polygon()
is not supported for drawing arrow shapes). - Caret settings like period, line style, and width are not supported (terminals use block carets with their own period definitions).
- Code pages other than UTF-8 have not been tested and it is possible some curses implementations do not support them.
- Edge lines are not displayed properly (the line is drawn over by text lines).
- Extra ascent and decent for lines is not supported.
- Fold lines are not supported (
surface->LineTo()
is not supported). - Indentation guides are not visible (pixmap surfaces are not supported).
- Indicators other than
INDIC_ROUNDBOX
andINDIC_STRAIGHTBOX
are not drawn (surface->LineTo()
is not supported for drawing indicator shapes and pixmap surfaces are not supported). Translucent drawing and rounded corners are not supported either. - Insert mode caret is not drawn properly (no way to detect it from within
surface->FillRectangle()
). - Margins are overwritten by long lines when scrolling to the right.
- Marker types other than
SC_MARK_CHARACTER
are not drawn (pixmap surfaces are not supported andsurface->LineTo()
is not supported for drawing marker shapes). - Mouse interactions, cursor types, and hotspots are not supported.
- Up to 16 colors are supported: black (
0x000000
), red (0x800000
), green (0x008000
), yellow (0x808000
), blue (0x000080
), magenta (0x800080
), cyan (0x008080
), white (0xC0C0C0
), light black (0x404040
), light red (0xFF0000
), light green (0x00FF00
), light yellow (0xFFFF00
), light blue (0x0000FF
), light magenta (0xFF00FF
), light cyan (0x00FFFF
), and light white (0xFFFFFF
). Even if your terminal uses a different color map, you must use these color values with Scintilla; unrecognized colors are set to white by default. For some terminals, you may need to set a lexer style’sbold
attribute in order to use the light color variant. - Scroll bars are not supported.
- Some key sequences are not recognized by the terminal or have unexpected key
- codes.
- Some styles settings like font name, font size, and italic do not display properly (terminals use one only font, size and variant).
- Viewing whitespace does not show the “Tab” character arrows
(
surface->LineTo()
is not supported for drawing arrows). - Visual wrap flags are not supported (
surface->LineTo()
is not supported). - X selections (primary and secondary) are not integrated into the clipboard.
- Zoom is not supported (terminal font size is fixed).
Migration Guides
Textadept 5 to 6
Textadept 6 introduces some API changes.
Function Changes
buffer
Some of the “get” and “set” functions in buffer
have been converted to
properties:
buffer:annotation_get_text(line)
->buffer.annotation_text[line]
buffer:annotation_set_text(line, text)
->buffer.annotation_text[line] = text
buffer:auto_c_get_current()
->buffer.auto_c_current
buffer:auto_c_get_current_text()
->buffer.auto_c_current_text
buffer:get_lexer_language()
->buffer.lexer_language
buffer:get_property(key)
->buffer.property[key]
buffer:get_property_expanded(key)
->buffer.property_expanded[key]
buffer:get_tag(tag_num)
->buffer.tag[tag_num]
buffer:margin_get_text(line)
->buffer.margin_text[line]
buffer:margin_set_text(line, text)
->buffer.margin_text[line] = text
buffer:marker_set_alpha(marker_num, alpha)
->buffer.marker_alpha[marker_num] = alpha
buffer:marker_set_back(marker_num, color)
->buffer.marker_back[marker_num] = color
buffer:marker_set_back_selected(marker_num, color)
->buffer.marker_back_selected[marker_num] = color
buffer:marker_set_fore(marker_num, color)
->buffer.marker_fore[marker_num] = color
buffer:set_fold_flags(flags)
->buffer.fold_flags = flags
buffer:set_lexer_language(language_name)
->buffer.lexer_language = language_name
buffer:style_get_font(style_num)
->buffer.style_font[style_num]
These changes will affect custom themes.
goto_required
_M.lua.goto_required()
, _M.php.goto_required()
, and
_M.ruby.goto_required()
have all been removed. They are inaccurate when
projects re-define or define their own search paths.
prepare_for_save
_M.textadept.editing.prepare_for_save()
was moved directly into an event
handler and cannot be called separately anymore.
Sessions
_M.textadept.session.prompt_load()
and _M.textadept.session.prompt_save()
functionality has been moved into _M.textadept.session.load()
and
_M.textadept.session.save()
. Therefore, replace all instances of
prompt_load
and prompt_save
with load
and save
respectively.
Adeptsense
_M.textadept.adeptsense.complete_symbol()
and
_M.textadept.adeptsense.show_documentation()
functionality has been moved into
_M.textadept.adeptsense.complete()
and
_M.textadept.adeptsense.show_apidoc()
. Therefore, replace all instances
of complete_symbol
and show_documentation
with complete
and show_apidoc
.
user_dofile
_G.user_dofile()
was removed. Use dofile(_USERHOME..'/file.lua')
instead.
gtkmenu
gui.gtkmenu()
was renamed to gui.menu()
. Therefore, replace all instances of
gui.gtkmenu
with gui.menu
.
Bookmarks
_M.textadept.bookmarks.add()
and _M.textadept.bookmarks.remove()
were
consolidated into _M.textadept.bookmarks.toggle()
. Replace add()
with
toggle(true)
and remove()
with toggle(false)
. toggle()
functionality
otherwise remains the same.
rebuild_command_tables
_M.textadept.menu.rebuild_command_tables()
was integrated into
_M.textadept.menu.set_menubar()
. Therefore, remove all calls to
rebuild_command_tables()
after set_menubar()
.
execute
_M.textadept.run.execute()
was removed. Use _M.textadept.run.run()
and
_M.textadept.run.compile()
exclusively.
Textadept 4 to 5
Lua has been upgraded from 5.1 to 5.2, so many scripts written for Textadept 4 are not compatible with Textadept 5. Since incompatible scripts may cause crashes on startup, the following guide will help you migrate your scripts from Textadept 4 to Textadept 5. While this guide is not exhaustive, it covers the changes I had to make to Textadept’s internals.
Module Changes
Syntax Changes
Although Lua 5.2 only deprecates Lua 5.1’s module
syntax, Textadept 5 removes
it. Therefore, replace
-- File ~/.textadept/modules/foo.lua
module('_m.foo', package.seeall)
function bar()
...
end
...
and
-- File ~/.textadept/init.lua
require 'textadept'
require 'foo'
with
-- File ~/.textadept/modules/foo.lua
local M = {}
function M.bar()
...
end
...
return M
or
local M = {}
local _ENV = M
if setfenv then setfenv(1, _ENV) end -- LuaJIT support
function bar()
...
end
function baz()
bar()
end
return M
and
-- File ~/.textadept/init.lua
_M.textadept = require 'textadept'
_M.foo = require 'foo'
Notice that _M
is the new module table instead of _m
. More on this
later.
Module References
Replace all instances of _M
(a reference created by module()
that holds the
current module table) with M
(the local module table you created).
Also, prefix all instances of internal module function calls with M
if you are
not using _ENV
. For example, change
module('foo', package.seeall)
function bar()
...
end
function baz()
bar()
end
to
local M = {}
function M.bar()
...
end
function M.baz()
M.bar()
end
return M
LuaDoc
If you use LuaDoc for your modules, you can still document them like this:
local M = {}
--[[ This comment is for LuaDoc
---
-- This is the documentation for module foo.
module('foo')]]
---
-- Documentation for bar.
-- ...
-- @name bar
function M.bar()
...
end
return M
Global Module Table
Originally, I wanted to use _M
as the global table that contains modules, but
Lua 5.1’s modules used _M
silently, so I had to settle with _m
. Now that
modules have been removed, _M
is available again and is used. Therefore,
replace all instances of _m
with _M
. In Textadept, you can easily do a
search and replace with “Match Case” and “Whole Words” checked – this is what I
did when upgrading Textadept’s internals.
Function Changes
unpack
unpack()
has been renamed to table.unpack()
. Replace all instances of
unpack
with table.unpack
.
xpcall
xpcall()
accepts error function parameters so you can change code from
local args = {...}
xpcall(function() return f(unpack(args)) end, error_function)
to
xpcall(f, error_function, ...)
However, this is not required.
loadstring
loadstring()
has been replaced by load()
since the latter now recognizes a
string chunk. Replace all instances of loadstring
with load
.
setfenv
setfenv()
has been removed. In some cases, use load()
with an environment
instead. For example, change
local f, err = loadstring(command)
if err then error(err) end
setfenv(f, env)()
to
local f, err = load(command, nil, 'bt', env)
if err then error(err) end
f()
(The 'bt'
is necessary for loading both binary and text chunks.)
If instead you want to set a function’s environment, change
setfenv(f, env)
to
debug.setupvalue(f, 1, env)
getfenv
getfenv()
has been removed. Change
local env = getfenv(f)
to
local debug = require 'debug'
local env = debug.getupvalue(f, 1)
os.execute
os.execute()
’s function parameters have changed. If you are only interested in
the return code, change
local code = os.execute(cmd)
to
local _, _, code = os.execute(cmd)
localize
Localization is done using a global table _L
instead of calling
locale.localize()
. Replace all instances of locale.localize('message')
with
_L['message']
. This allows messages to be modified via scripts if desirable.
current_word
_M.textadept.editing.current_word()
has been renamed to select_word()
and
does not take any parameters. There is a _M.textadept.keys.utils.delete_word()
function that replaces current_word('delete')
. You can use it or create a new
function:
local function delete_word()
_M.textadept.editing.select_word()
buffer:delete_back()
end
Theme Changes
Any custom themes need to be changed to remove the module
syntax. Usually this
involves changing
module('lexer', package.seeall)
colors = {
...
}
style_nothing = style { ... }
style_class = style { fore = colors.light_yellow }
...
style_identifier = style_nothing
...
style_default = style {
...
}
style_line_number = { fore = colors.dark_grey, back = colors.black }
...
to
local l, color, style = lexer, lexer.color, lexer.style
l.colors = {
...
}
l.style_nothing = style { ... }
l.style_class = style { fore = l.colors.light_yellow }
...
l.style_identifier = l.style_nothing
...
l.style_default = style {
...
}
l.style_line_number = { fore = l.colors.dark_grey, back = l.colors.black }
...
Notice the l.
prefix before most identifiers.
Textadept 3 to 4
Key and Menu Changes
Textadept 4 allow key bindings to appear in menus, but only simple ones, not
keychains. Therefore, Textadept’s key bindings have changed radically, as has
the menu structure and menu mnemonics. In order for key bindings to appear in
menus, _m.textadept.menu
needs to know which commands are assigned to which
keys. Therefore, the menu module needs to be require
d after
_m.textadept.keys
. If your ~/.textadept/init.lua is calling
require 'textadept'
, you do not have to make any changes. If you are loading
individual modules from _m.textadept
, ensure _m.textadept.menu
is loaded
after _m.textadept.keys
.
On Mac OSX, key binding definition has changed. m
is now ⌘ (command) and a
is now ⌥ (alt/option). c
remains ^ (control). Previously a
was ⌘ and ⌥ was
undefined. Please note, however, that not all ⌥ combinations by themselves will
work since that key is typically used to compose locale-dependent characters.
Function Changes
select_scope
_m.textadept.editing.select_scope()
was renamed to select_style()
.
Therefore, replace all instances of _m.textadept.editing.select_scope
with
_m.textadept.editing.select_style
.
SAVE_STRIPS_WS
_m.textadept.editing.SAVE_STRIPS_WS
was renamed to STRIP_WHITESPACE_ON_SAVE
.
Replace all instances of _m.textadept.editing.SAVE_STRIPS_WS
with
_m.textadept.editing.STRIP_WHITESPACE_ON_SAVE
.
Textadept 2 to 3
Module Changes
Core Extensions
There are no more core extention modules (previously in core/ext/). They have been relocated to modules/textadept/ so putting
require 'textadept'
in your ~/.textadept/init.lua will load all the modules you would expect. Please see the preferences page for instructions on how to load specific modules.
Autoloading
Key bindings in ~/.textadept/key_commands.lua and snippets in
~/.textadept/snippets.lua are no longer auto-loaded. Instead, modify
keys
and/or snippets
from within your ~/.textadept/init.lua or a
file loaded by ~/.textadept/init.lua.
Function Changes
Textadept has a brand new Lua API. It is likely that any external scripts, including themes, need to be rewritten.
Here is a summary of API changes:
_m.textadept.lsnippets
renamed to_m.textadept.snippets
.textadept.events
renamed to_G.events
.events.handle()
renamed toevents.emit()
.events.add_handler()
renamed toevents.connect()
.
textadept.constants
renamed to_SCINTILLA.constants
.textadept.buffer_functions
renamed to_SCINTILLA.functions
.textadept.buffer_properties
renamed to_SCINTILLA.properties
.textadept.buffers
renamed to_BUFFERS
.textadept.views
renamed to_VIEWS
.- New
gui
module.- Renamed
textadept._print()
togui._print()
. - Renamed
textadept.check_focused_buffer()
togui.check_focused_buffer()
. - Renamed
textadept.clipboard_text
togui.clipboard_text
. - Renamed
textadept.context_menu
togui.context_menu
. - Renamed
textadept.command_entry
togui.command_entry
. - Renamed
textadept.dialog
togui.dialog()
. - Renamed
textadept.docstatusbar_text
togui.docstatusbar_text
. - Renamed
textadept.find
togui.find
. - Renamed
textadept.focused_doc_pointer
togui.focused_doc_pointer
. - Renamed
textadept.get_split_table()
togui.get_split_table()
. - Renamed
textadept.gtkmenu()
togui.gtkmenu()
. - Renamed
textadept.goto_view()
togui.goto_view()
. - Renamed
textadept.menubar
togui.menubar
. - Renamed
textadept.print()
togui.print()
. - Renamed
textadept.size
togui.size
. - Renamed
textadept.statusbar_text
togui.statusbar_text
. - Renamed
textadept.switch_buffer()
togui.switch_buffer()
. - Renamed
textadept.title
togui.title
. - Renamed
textadept.new_buffer()
tonew_buffer()
. - Renamed
textadept.quit()
toquit()
. - Renamed
textadept.reset()
toreset()
. - Renamed
textadept.user_dofile()
touser_dofile()
. - Renamed
textadept.iconv()
tostring.iconv()
. - Renamed
textadept.session_file
to_SESSIONFILE
.
- Renamed
- Removed global
textadept
module.