Textadept Quick Reference

Transcription

1

2

3 SECOND EDITION Textadept Quick Reference Mitchell

4 Textadept Quick Reference by Mitchell Copyright 2013, 2015 Mitchell. All rights reserved. Contact the author at 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:

5 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 adept/changelog.html.

6

7 Contents Introduction 1 Download 2 Conventions 2 Terminology 2 Environment Variables 3 Important Files and Directories 3 Command Line Options 8 Define Custom Options 9 Global Variables 9 Platform Variables 10 Handle Events 10 Create Buffers and Views 11 Query View Information 12 Handle Buffer and View Events 13 Work with Files and Projects 13 Detect or Change File Encodings 15 Query File Information 16 Handle Input and Output Events 17 Work with Sessions 18 Configure Session Settings 18 Move Around 18 Move Within Lines 18 Move Between Lines 19 Move Between Pages 20 Move Between Buffers and Views 20 Contents v

8 Other Movements 21 Handle Movement Events 21 Manipulate Text 22 Retrieve Text 22 Set Text 23 Delete Text 25 Transform Text 26 Undo and Redo 29 Employ the Clipboard 29 Handle Text Events 30 Select Text 30 Make Simple Selections 31 Make Multiple Selections 34 Make Rectangular Selections 35 Query Selection Information 36 Search for Text 38 Simple Search 40 Search and Replace 41 Interact with the Find & Replace Pane 42 Incremental Search 44 Handle Find & Replace Events 44 Query Buffer Information 45 Query Position Information 45 Query Line and Line Number Information 46 Query Measurement Information 47 Configure Line Margins 47 Query Margin Information 49 Handle Margin Events 49 vi Contents

9 Mark Lines with Markers 50 Bookmark Lines 53 Query Marker Information 54 Annotate Lines 54 Query Annotated Lines 55 Mark Text with Indicators 55 Highlight Words 57 Query Indicator Information 58 Handle Indicator Events 58 Show an Interactive List 58 Display an Autocompletion List 59 Display a User List 60 Configure List Behavior and Display 61 Display Images in Lists 62 Query Interactive List Information 64 Handle Interactive List Events 65 Show a Call Tip 65 Configure Call Tip Display 66 Query Call Tip Information 67 Handle Call Tip Events 67 Fold or Hide Lines 67 Query Folded or Hidden Line Information 68 Scroll the View 69 Prompt for Input with Dialogs 70 Prompt with Messagebox Dialogs 70 Prompt with Inputbox Dialogs 72 Prompt with File Selection Dialogs 73 Prompt with a Textbox Dialog 75 Contents vii

10 Prompt with Dropdown Dialogs 76 Prompt with a Filtered List Dialog 78 Prompt with an Option Dialog 80 Manipulate the Command Entry 81 Issue Lua Commands 83 Compile and Run Code 83 Configure Compile and Run Settings 84 Query Compile and Run Information 85 Handle Compile and Run Events 85 Spawn Processes 85 Configure Textadept 87 Configure Indentation and Line Endings 87 Configure Character Settings 89 Configure the Color Theme 90 Create or Modify a Color Theme 90 Configure the Display Settings 97 Configure File Types 106 Configure Key Bindings 107 Configure Key Settings 110 Configure Snippets 111 Configure Miscellaneous Settings 113 Define a Lexer 113 Declare the Lexer Configuration 113 Construct Patterns 114 Define Tokens 118 Define Rules 118 Assign Styles 119 Specify Fold Points 120 Embed Lexers 120 viii Contents

11 Query Lexer Properties and Rules 121 Handle Lexer Events 121 Manually Style Text 122 Refresh Styling 122 Assign Plain Text Styles 122 Style Plain Text 123 Query Style Information 124 Miscellaneous 124 Handle Miscellaneous Events 125 Appendix: Image Formats 128 XPM Image Format 128 RGBA Image Format 129 Index of Key and Mouse Bindings 130 Lua API Index 139 Concept Index 151 Contents ix

12 Introduction Textadept is a fast, minimalist, and remarkably extensible cross-platform text editor for programmers. Written in a combination of C and Lua 1 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 LuaJIT 2 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 Introduction 1

13 Download Textadept binary packages for Windows, Mac OSX, and Linux platforms are available from 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

14 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

15 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 buffer.indic_squigglepixmap buffer.indic_plain buffer.indic_dash buffer.indic_dots Visual or Description A squiggly underline. An underline. A dashed underline. A dotted underline. buffer.indic_compositionthick A thick underline. buffer.indic_strikeout buffer.indic_box buffer.indic_dotbox buffer.indic_straightbox A strikeout line. A bounding box. A dotted bounding box. A translucent box. Mark Text with Indicators 55

16 Indicator Style buffer.indic_roundbox buffer.indic_fullbox buffer.indic_tt buffer.indic_diagonal buffer.indic_textfore buffer.indic_hidden Visual or Description A translucent box with rounded corners. A translucent box that extends to the top of its line. An underline of small T shapes. An underline of diagonal hatches. Changes text s foreground color. 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] = 0xFF 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('() % 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

17 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 indicator 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

18 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

19 Concept Index Symbols ~/.textadept/, 3, 8, 10 A annotations, 54 autocompleting code, 59 autocompletion list configuring, 61 displaying, 59 images in, displaying, 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, 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

20 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, 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, E encodings converting between, 28 for files, 15 of filesystem, 10 supported, list of, 15 end of lines, 88 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, file selection dialog, 73 file types, 106 filesystem encoding, 10 filtered list dialog, 78 filtering text through shell commands, Index

21 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, 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, 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, properties for, 121 rules, 118 styles, 119 tokens, 118 line annotations, 54 line endings, 88 line indentation, 26, 46, 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, 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

22 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 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, properties.lua, 5 Q quitting, 124 R rectangular selections, 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, Index

23 sessions, 8, 18 setting text, 23 snippets configuring, 112 inserting, 24 special characters, list of, 112 terminology, 111 spawning processes, split views, 12 style information, 124 styles, styling text, (see also lexers) switching buffers, 20 switching views, 20 syntax highlighting, 106, 122 (see also lexers) T 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 U undo and redo actions, 29 user data directory, 3, 8, 10 user list configuring, 61 displaying, 60 images in, displaying, information, 64 V variables, 9 views information, 12 list of open, 9 moving between, 20 scrolling, 69 splitting, 12 unsplitting, 12 W window, 104 wrapping lines, 101 X XPM image format, 128 Z zooming, 102 Index 155