Excerpt - Foicica

SECOND EDITION
Textadept
Quick Reference
Mitchell
Textadept Quick Reference
by Mitchell
Copyright © 2013, 2015 Mitchell. All rights reserved.
Contact the author at [email protected].
Although great care has been taken in preparing this book, the author assumes no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein. All
product names mentioned in this book are trademarks of their respective owners.
Editor: Ana Balan
Cover Designer: Mitchell
Interior Designer: Mitchell
Indexer: Mitchell
Printing history:
December 2013: First Edition
May 2015: Second Edition
ISBN: 978-0-9912379-1-3
Preface to the Second Edition
This book is an updated version of the first edition of Textadept Quick Reference and covers many of the new features
introduced in the Textadept 7.x releases. It reflects the current
state of Textadept 8.0 and provides a collection of new and
updated examples that demonstrate the power and flexibility
of the editor. In a nutshell, this book covers the following
new topics:
• Textadept’s project support, including build commands.
• Its new autocompletion and documentation framework
along with built-in, preregistered list images.
• Multi-input inputbox dialogs and the new option (checkbox) dialog.
• Textadept’s new and improved command entry.
• Spawning and interacting with asynchronous processes.
• The vast number of terminal version improvements, including suspend, resume, Control Sequence Introducer
(CSI), and mouse events.
• Extending existing menus in-place.
For a comprehensive list of changes between Textadept versions, please refer to the editor’s CHANGELOG.md or doc/
CHANGELOG.html files, which are distributed with the application. The online version is located at http://foicica.com/text
adept/CHANGELOG.html.
Contents
Introduction
Download
Conventions
Terminology
1
2
2
2
Environment Variables
3
Important Files and Directories
3
Command Line Options
Define Custom Options
8
9
Global Variables
Platform Variables
9
10
Handle Events
10
Create Buffers and Views
Query View Information
Handle Buffer and View Events
11
12
13
Work with Files and Projects
Detect or Change File Encodings
Query File Information
Handle Input and Output Events
13
15
16
17
Work with Sessions
Configure Session Settings
18
18
Move Around
Move Within Lines
Move Between Lines
Move Between Pages
Move Between Buffers and Views
18
18
19
20
20
Contents | v
Other Movements
Handle Movement Events
21
21
Manipulate Text
Retrieve Text
Set Text
Delete Text
Transform Text
Undo and Redo
Employ the Clipboard
Handle Text Events
22
22
23
25
26
29
29
30
Select Text
Make Simple Selections
Make Multiple Selections
Make Rectangular Selections
Query Selection Information
30
31
34
35
36
Search for Text
Simple Search
Search and Replace
Interact with the Find & Replace Pane
Incremental Search
Handle Find & Replace Events
38
40
41
42
44
44
Query Buffer Information
Query Position Information
Query Line and Line Number Information
Query Measurement Information
45
45
46
47
Configure Line Margins
Query Margin Information
Handle Margin Events
47
49
49
vi | Contents
Mark Lines with Markers
Bookmark Lines
Query Marker Information
50
53
54
Annotate Lines
Query Annotated Lines
54
55
Mark Text with Indicators
Highlight Words
Query Indicator Information
Handle Indicator Events
55
57
58
58
Show an Interactive List
Display an Autocompletion List
Display a User List
Configure List Behavior and Display
Display Images in Lists
Query Interactive List Information
Handle Interactive List Events
58
59
60
61
62
64
65
Show a Call Tip
Configure Call Tip Display
Query Call Tip Information
Handle Call Tip Events
65
66
67
67
Fold or Hide Lines
Query Folded or Hidden Line Information
67
68
Scroll the View
69
Prompt for Input with Dialogs
Prompt with Messagebox Dialogs
Prompt with Inputbox Dialogs
Prompt with File Selection Dialogs
Prompt with a Textbox Dialog
70
70
72
73
75
Contents | vii
Prompt with Dropdown Dialogs
Prompt with a Filtered List Dialog
Prompt with an Option Dialog
76
78
80
Manipulate the Command Entry
Issue Lua Commands
81
83
Compile and Run Code
Configure Compile and Run Settings
Query Compile and Run Information
Handle Compile and Run Events
83
84
85
85
Spawn Processes
85
Configure Textadept
Configure Indentation and Line Endings
Configure Character Settings
Configure the Color Theme
Create or Modify a Color Theme
Configure the Display Settings
Configure File Types
Configure Key Bindings
Configure Key Settings
Configure Snippets
Configure Miscellaneous Settings
87
87
89
90
90
97
106
107
110
111
113
Define a Lexer
Declare the Lexer Configuration
Construct Patterns
Define Tokens
Define Rules
Assign Styles
Specify Fold Points
Embed Lexers
113
113
114
118
118
119
120
120
viii | Contents
Query Lexer Properties and Rules
Handle Lexer Events
121
121
Manually Style Text
Refresh Styling
Assign Plain Text Styles
Style Plain Text
Query Style Information
122
122
122
123
124
Miscellaneous
Handle Miscellaneous Events
124
125
Appendix: Image Formats
XPM Image Format
RGBA Image Format
128
128
129
Index of Key and Mouse Bindings
130
Lua API Index
139
Concept Index
151
Contents | ix
Introduction
Textadept is a fast, minimalist, and remarkably extensible
cross-platform text editor for programmers. Written in a combination of C and Lua1 and relentlessly optimized for speed
and minimalism for over six years, Textadept is an ideal editor for programmers who want endless extensibility without
sacrificing speed or succumbing to code bloat and featuritis.
Textadept runs in both graphical and text-based user interface
environments. The text-based version of the editor is referred
to as the “terminal version”, since it executes within a terminal emulator. Textadept also supports the standard Lua and
LuaJIT2 environments. The version that utilizes LuaJIT is referred to as the “LuaJIT version”.
Textadept Quick Reference is designed to help the user “get
things done” when it comes to scripting and configuring Textadept. Its pragmatic approach assumes the user has a working
knowledge of both Lua and Textadept. This book is broken
up into a number of descriptive sections with conveniently
grouped tasks that cover nearly every aspect of Textadept’s
Application Programming Interface (API). For the most part,
the contents of each task are not listed in conceptual order.
They are listed in procedural order, an order the user would
likely follow when writing Lua scripts. This quick reference
serves as a complement to Textadept’s comprehensive Manual
and extensive API documentation.
While this book aims to be a complete reference, it does omit
some of the less useful features of Textadept’s API. For example, although many of Textadept’s table fields are both readable and writable, this reference sometimes chooses to cover
only one of those operations. (Unless a field is marked “Readonly” or “Write-only”, it is readable and writable.) This book
also does not cover Lua’s standard libraries.
Finally, the facilities in this book are designed to be used primarily in user-written Lua scripts and in the occasional “oneshot” Lua command. If the user keeps this in mind, he or she
can realize Textadept’s full potential.
1
2
http://www.lua.org
http://luajit.org
Introduction | 1
Download
Textadept binary packages for Windows, Mac OSX, and Linux
platforms are available from http://foicica.com/textadept. Each
package is self-contained and need not be installed. Textadept’s source code is also included in each archive. The user
may compile the application manually by following the instructions in the editor’s Manual.
Conventions
This book uses the following conventions.
Italic
Used for filenames and for introducing new terms.
Constant width
Used for environment variables, command line options,
and Lua code, including functions, tables, and variables.
Constant width italic
Used for user-specified parameters.
[]
Used for optional function arguments, except in code examples that index Lua tables. Unless otherwise specified,
optional arguments default to nil.
Terminology
This book uses the following terminology.
Buffer
An object that contains editable text.
View
An object that contains a single buffer.
Caret
Either the visual that represents the text insertion point
or the end point of a text selection.
Anchor
The start point of a text selection or search.
2 | Textadept Quick Reference
Virtual Space
The space past the ends of lines.
Lexer
A Lua module that highlights the syntax of source code
written in a particular programming language. Textadept
refers to a programming language by its lexer’s name.
Style
A collection of display settings specific to source code
comments, strings, keywords, and other ranges of text.
Language Module
A Lua module automatically loaded by Textadept when
editing source code in a particular programming language. The module’s name matches the language’s lexer
name. Not all languages have language modules.
Environment Variables
Textadept utilizes the following environment variables.
HOME or USERHOME
The user’s home directory. Textadept’s user data and
preferences exist in a .textadept/ sub-directory, denoted
as ~/.textadept/ throughout this book.
LANG
The user’s default locale. Textadept will display localized
text and messages in it if possible.
TEXTADEPTJIT (Mac OSX only)
When set, Textadept.app runs its LuaJIT version.
TA_LUA_PATH
TA_LUA_CPATH
The Textadept equivalent of LUA_PATH and LUA_CPATH.
Used by Lua’s require() function for finding modules.
Important Files and Directories
Textadept allows the user to configure and customize the editor using several important files and directories contained
within his or her ~/.textadept/ directory.
Important Files and Directories | 3
notations to match the annotated text, and outlines them
with a box. buffer.ANNOTATION_INDENTED draws indented
annotations without a box, buffer.ANNOTATION_STANDARD
draws annotations left-justified with no decoration, and
buffer.ANNOTATION_HIDDEN hides annotations.
Query Annotated Lines
The user can request a line’s annotation text along with the
number of lines needed to display that text.
buffer.annotation_text[line]
The annotation text for line number line.
buffer.annotation_lines[line] (Read-only)
The number of annotation text lines for line number
line.
Mark Text with Indicators
Textadept supplies 32 indicators, numbered from 0 to 31, to
mark text with. Each indicator has an assigned indicator style
from the list in Table 7. The editor displays indicators along
with any existing styles text may have. Example 12 shows
how to create and interact with clickable hyperlinks.
Table 7. Indicator styles
Indicator Style
Visual or Description
buffer.INDIC_SQUIGGLEPIXMAP
A squiggly underline.
buffer.INDIC_PLAIN
An underline.
buffer.INDIC_DASH
A dashed underline.
buffer.INDIC_DOTS
A dotted underline.
buffer.INDIC_COMPOSITIONTHICK A thick underline.
buffer.INDIC_STRIKEOUT
A strikeout line.
buffer.INDIC_BOX
A bounding box.
buffer.INDIC_DOTBOX
A dotted bounding box.
buffer.INDIC_STRAIGHTBOX
A translucent box.
Mark Text with Indicators | 55
Indicator Style
Visual or Description
buffer.INDIC_ROUNDBOX
A translucent box with rounded corners.
buffer.INDIC_FULLBOX
A translucent box that extends to the
top of its line.
buffer.INDIC_TT
An underline of small ‘T’ shapes.
buffer.INDIC_DIAGONAL
An underline of diagonal hatches.
buffer.INDIC_TEXTFORE
Changes text’s foreground color.
buffer.INDIC_HIDDEN
Plain text with no decorations.
Example 12. Create and interact with hyperlinks
local browser_cmd = 'firefox "%s"'
-- Define the hyperlink indicator.
indic_link = _SCINTILLA.next_indic_number()
buffer.indic_style[indic_link] = buffer.INDIC_HIDDEN
local TEXTFORE = buffer.INDIC_TEXTFORE
buffer.indic_hover_style[indic_link] = TEXTFORE
buffer.indic_hover_fore[indic_link] = 0xFF0000 -- blue
-- Search the buffer and mark hyperlinks.
local text = buffer:get_text()
buffer.indicator_current = indic_link
buffer:indicator_clear_range(0, buffer.length)
for s, e in text:gmatch('()http://%S+()') do
buffer:indicator_fill_range(s - 1, e - s)
end
-- Open clicked hyperlinks in a web browser.
events.connect(events.INDICATOR_CLICK, function(pos)
local indicators = buffer:indicator_all_on_for(pos)
if bit32.band(indicators, indic_link) then
local s = buffer:indicator_start(indic_link, pos)
local e = buffer:indicator_end(indic_link, pos)
local url = buffer:text_range(s, e + 1)
spawn(browser_cmd:format(url))
end
end)
_SCINTILLA.next_indic_number()
Returns a unique indicator number.
buffer.indic_style[indicator] = style
Assigns indicator style style to indicator number indica
tor. Table 7 lists all available indicator styles. The section
“Assign Indicator Colors” on page 95 describes how to
56 | Textadept Quick Reference
change the color and alpha values of indicator.
Also resets buffer.indic_hover_style[indicator] to style.
The terminal version requires style to be buffer.INDIC_
STRAIGHTBOX, but cannot draw it translucently.
TIP
The user should either assign indicator styles in his or her
~/.textadept/properties.lua file or within an events.VIEW_
NEW handler, so subsequent views can recognize them.
buffer.indic_under[indicator] = bool
Draw indicator number indicator behind text instead of
in front of it. The default value is false.
buffer.indic_hover_style[indicator] = style
Assigns indicator style style to indicator number indica
tor when either the mouse is hovering over that indica-
tor or when the caret is within that indicator.
buffer.indicator_current = indicator
Designates indicator number indicator as the indicator
used by buffer:indicator_fill_range() and buffer:indi
cator_clear_range().
buffer:indicator_fill_range(pos, length)
buffer:indicator_clear_range(pos, length)
Fills or clears the range of text from position pos to pos +
length with indicator number buffer.indicator_current.
Highlight Words
The user can highlight all instances of a word (for example,
all instances of a variable name). Subsequent calls to text
adept.editing.select_word() select each occurrence of that
word, providing a simple renaming tool.
textadept.editing.highlight_word()
Highlights all occurrences of the selected text or all occurrences of the current word. buffer.word_chars is a
string that contains all word characters.
Mark Text with Indicators | 57
Query Indicator Information
The user can fetch indicator locations and retrieve the indicators present at particular positions.
buffer:indicator_start(indicator, pos)
buffer:indicator_end(indicator, pos)
Returns the previous or next boundary position, starting
from position pos, of indicator number indicator. Returns
0 or buffer.length, respectively, if indicator was not
found.
buffer:indicator_all_on_for(pos)
Returns a bit-mask that represents the indicators present
at position pos. The mask is a 32-bit value whose bits
correspond to Textadept’s 32 indicators.
Handle Indicator Events
The user can connect to the following indicator click events.
events.INDICATOR_CLICK position, modifiers
Emitted when clicking the mouse on text that has an indicator present. position is the clicked text’s position and
modifiers is a bit-mask of any modifier keys used (buf
fer.MOD_CTRL for Control, buffer.MOD_SHIFT for Shift, buf
fer.MOD_ALT for Alt, and buffer.MOD_META for Command).
events.INDICATOR_RELEASE position
Emitted when releasing the mouse after clicking on text
that has an indicator present. position is the clicked
text’s position.
Show an Interactive List
Textadept has the ability to display two types of interactive
lists that update as the user types: an autocompletion list and
a user list. An autocompletion list is a list of completions
shown for the current word. A user list is a more general list
of options presented to the user. Both types of lists have similar behavior and may display images alongside text. All of the
above is described in the following sections.
58 | Textadept Quick Reference
Concept Index
Symbols
~/.textadept/, 3, 8, 10
A
annotations, 54
autocompleting code, 59
autocompletion list
configuring, 61
displaying, 59
images in,
displaying, 62-64
information, 64
autopaired characters, 25
B
block comments, 28
bookmarks, 21, 53, 95
brace matching, 21, 96, 104
buffers
creating, 12
line information in, 46
list of open, 9
manipulating text in (see
manipulating text)
measurements, 47
moving around in (see
moving around)
moving between, 20
position information
in, 45
searching and replacing
in (see searching
for text)
selecting text in (see
selecting text)
C
call tip
configuring, 66, 92, 96
displaying, 65
information, 67
character classifications, 89
clipboard operations, 29
code autocompletion, 59
code folding, 67, 103, 120
color theme
bookmarks, 95
carets, 93
changing, 90
color definitions, 91, 93
highlighted words, 96
indicators, 95
location of, 6
long lines, 97
margins, 94
markers, 94
matching braces, 96
selections, 94
styles for, 91-93
whitespace, 96
Command Entry, 81
Lua commands with,
issuing, 83
command line options, 8-10
commenting code, 28
compiling and running
code, 83
configuring Textadept
~/.textadept/, 8
autopaired characters, 25
block comments, 28
character classifications,
89
color theme (see color
theme)
compile and run
code, 84
display settings (see
display settings)
file types, 106
Index | 151
configuring Textadept
(continued)
key bindings (see key
bindings)
line endings, 88
line indentation, 87
locale, 5
matching braces, 104
sessions, 8, 18
snippets (see snippets)
typeover characters, 25
D
deleting text, 25
dialogs
dropdown, 76-78
file selection, 73
filtered list, 78
inputbox, 72
messagebox, 70
option, 80
textbox, 75
display settings
carets, 97
indentation guides, 104
long lines, 103
matching braces, 104
mouse cursor, 100
scrollbars, 99
selections, 98
whitespace, 98
window, 104
wrapped lines, 101
zoom, 102
downloading Textadept, 2
dropdown dialog, 76-78
E
encodings
converting between, 28
for files, 15
of filesystem, 10
supported, list of, 15
end of lines, 88
152 | Index
environment variables, 3
events
autocompletion list, 65
buffer and view, 13
call tip, 67
compile and run, 85
connecting to, 11
CSI, 125
double click, 125
dwell, 125
emitting, 11
error, 126
Find & Replace, 44
focus, 126
indicator, 58
initialized, 126
input and output, 17
interactive list, 65
keypress, 126
lexer, 121
margin, 49
mouse, 126
movement, 21
no command line
arguments, 125
quit, 126
reset, 126
resume, 126
suspend, 126
text, 30
update, 126
user list, 65
F
file encodings, 15
file filters, 15
file information, 16
file operations, 13-16
file selection dialog, 73
file types, 106
filesystem encoding, 10
filtered list dialog, 78
filtering text through shell
commands, 27
Find & Replace Pane, 42
Lua pattern syntax for, 39
search flags for, 42
searching and replacing
with, 43
searching in files
with, 43
finding text (see searching
for text)
fold markers, 51
folding lines, 67
fonts and font sizes, 91-93,
102
H
hiding lines, 68
highlighting words, 57, 96
I
image formats,
RGBA, 129
XPM, 128
incremental searching, 44
indentation, 26, 46, 87-89
indentation guides, 104
indicators, 55-58, 95
init.lua, 4
input, prompting for (see
dialogs)
inputbox dialog, 72
inserting text, 23
installing Textadept, 2
interactive lists (see
autocompletion list;
user list)
internationalizing
messages, 9
K
key bindings
configuring, 110
keys.KEYSYMS, 109
modifier keys, list of, 109
terminology, 107-109
L
language modules, location
of, 5
lexers
changing, 106
code folding, 120
defining, 113
embedding, 120
fold points, 120
information, 106
location of, 6
patterns, 114-117
properties for, 121
rules, 118
styles, 119
tokens, 118
line annotations, 54
line endings, 88
line indentation, 26, 46,
87-89
line information, 46
line margins, 47-49, 94
line markers, 50-54, 94
line wrapping, 101
lines
annotations, 54
bookmarking, 53
endings for, 88
folding, 67
hiding, 68
indentation for, 26, 46,
87-89
information for, 46, 68
joining, 27
long, 97, 103
marking, 50-53, 94
moving between, 19
moving up or down, 27
moving within, 18
splitting, 27
transposing, 26
wrapping, 101
locale, 3, 5
Index | 153
localizing messages, 9
long lines, 97, 103
Lua commands, issuing, 8,
83
Lua pattern syntax, 39
M
manipulating text
clipboard, using the, 29
converting between
encodings, 28
deleting, 25
inserting, 23
replacing, 24
retrieving, 22
setting, 23
transforming, 27
margins, 47-49, 94
marking lines, 50-53, 94
marking text, 55-57, 95
matching braces, 21, 96, 104
measurements, 47
messagebox dialog, 70
modules, location of, 5
moving around
between bookmarks, 21
between buffers, 20
between lines, 19
within lines, 18
between matching
braces, 21
between pages, 20
between paragraphs, 21
selecting and, 32, 36
between views, 20
multiple selections, 34, 37
O
option dialog, 80
overtype mode,
toggling, 124
P
pages, moving between, 20
154 | Index
paragraphs, moving
between, 21
piping text through shell
commands, 27
pixmaps, 128
position information, 45
post_init.lua, 5
printing messages, 23
processes, spawning
of, 85-87
properties.lua, 5
Q
quitting, 124
R
rectangular selections, 35-37
replacing text, 24, 41
resetting, 124
retrieving text, 22
RGBA image format, 129
running code, 83
running Textadept, 8
S
scrolling, 69, 99
search flags, 38, 42
searching for text
in files, 43
Find & Replace Pane,
using the, 42
incrementally, 44
regular expression syntax
for, 39
replacing and, 41
search flags for, 38, 42
simple search, 40
selecting text
modal selection, 34
multiple selection, 34
rectangular selection, 35
simple selection, 31
while moving, 32
selections, 36, 94, 98
sessions, 8, 18
setting text, 23
snippets
configuring, 112
inserting, 24
special characters, list
of, 112
terminology, 111
spawning processes, 85-87
split views, 12
style information, 124
styles, 91-93
styling text, 122-124
(see also lexers)
switching buffers, 20
switching views, 20
syntax highlighting, 106, 122
(see also lexers)
user data directory, 3, 8, 10
user list
configuring, 61
displaying, 60
images in,
displaying, 62-64
information, 64
T
window, 104
wrapping lines, 101
target ranges, 24, 27, 41
text indicators, 55-58, 95
text manipulations (see
manipulating text)
text selections (see selecting
text; selections)
Textadept
configuring (see
configuring
Textadept)
downloading, 2
installing, 2
running, 8
user data directory of, 3,
8, 10
textbox dialog, 75
theme (see color theme)
transforming text, 27
transposing characters and
lines, 26
typeover characters, 25
V
variables, 9
views
information, 12
list of open, 9
moving between, 20
scrolling, 69
splitting, 12
unsplitting, 12
W
X
XPM image format, 128
Z
zooming, 102
U
undo and redo actions, 29
Index | 155