Textadept Documentation

Textadept is an event-driven application where nearly all features (syntax highlighting, file I/O, search/replace) are implemented in Lua. It includes an internal copy of Lua 5.4.

Core Concepts

• Event-Driven Model: Textadept responds to inputs (key presses, mouse clicks, state changes) by executing Lua functions. For example, pressing Ctrl+O triggers the io.open_file() function via the events.KEYPRESS event.
• Entry Point: Your ~/.textadept/init.lua file is the primary location for custom scripting. Use it to define custom key bindings, menu items, and event handlers.

Common Scripting Tasks

• Custom Key Bindings & Menus: Manipulate buffer contents or extend the textadept.menu.menubar.
• Event Handling: Listen for events like events.FILE_SAVED to trigger asynchronous processes (e.g., linters via os.spawn) or events.BUFFER_BEFORE_SWITCH to implement auto-save.
• UI Customization: Modify the find/replace pane using ui.find or add items to the right-click context menu by appending to textadept.menu.context_menu.
• CLI Extensions: Register new command line arguments using args.register().

Placeholder transforms allow you to modify the text of a mirrored or captured placeholder using regex. The syntax is ${n/*regex*/*format*/*options*}.

Supported Format Tokens:

• $m or ${m}: The content of the m-th capture (0 is the whole match).
• ${m:/upcase}, ${m:/downcase}, ${m:/capitalize}: Built-in text transformations.
• ${m:?*if*:*else*}: Inserts if if capture m is non-empty, otherwise else.
• ${m:+*if*}: Inserts if if capture m is non-empty, otherwise nothing.
• ${m:*default*}: Inserts default if capture m is empty, otherwise mirrors the content.
• ${m:-*default*}: Inserts default if capture m is empty, otherwise mirrors the content.

Options:

• g: Global replacement (replace all matches, not just the first).

-- Example: Creating an attribute with a getter and setter
-- Uses /./ to match any character and /upcase to transform it
snippets.attr = [[
	${1:int} ${2:name};

	${1} get${2/./${0:/upcase}/}() { return $2; }
	void set${2/./${0:/upcase}/}(${1} ${3:value}) { $2 = $3; }
]]

When running Textadept in a terminal, certain GUI features are unavailable due to terminal constraints. Users should be aware of the following limitations:

• Visuals: No alpha/transparency, no images in autocompletion (shows first character instead), no zoom, and no style settings (font name, size, italics).
• UI Elements: No drag and drop, no mouse cursor types, and no hotspot underlines on hover.
• Drawing: No buffered/two-phase drawing, no extra line ascent/descent, and no fold lines above/below lines.
• Markers/Guides: Fold marker highlighting is limited to bold (no color), and indent guide highlighting is limited to white.
• Interaction: Not all key sequences (like Shift+Arrow) are recognized, and caret styles (period, line style, width) are unavailable.
• Indicators: Only INDIC_ROUNDBOX and INDIC_STRAIGHTBOX are supported, but they lack translucency and rounded corners.

Textadept splits the Scintilla editing component's API into two distinct parts: buffers and views.

• Buffers: Responsible for the data model, including text editing, selections, and navigation.
• Views: Responsible for the visual representation, such as text display, selection display, margins, markers, and highlights.

Key Relationships

• Interchangeability: The API is largely interchangeable. view.field or view:function() are often equivalent to buffer.field or buffer:function(). However, a view operation is only equivalent to a buffer operation if the buffer is the one currently contained by that view (buffer == view.buffer).
• Focus: Only one buffer and one view are considered "current" (having focus) at a time.
• Background Edits: You can perform "background" edits on non-current buffers. For example, calling buf:replace_sel('') on a buffer that is not the current one will still modify that buffer's text, even if it isn't visible in the current view.
• Visual vs. Data: Operations like buffer:select_all() on a non-current buffer will modify the selection data in that buffer, but it will not result in a visible selection in the current view.

Placeholders allow you to create templates that you can navigate using the Tab key.

• Tab Stops: Use $n or ${n}. When the snippet is inserted, the caret starts at $1. Tab moves to $2, and so on.
• Exit Point: After the last placeholder, the caret moves to $0 if it exists, otherwise to the end of the snippet.
• Default Values: Use ${n:default} to provide a value that can be overwritten.
• Mirrors: Use the same index (e.g., $1) in multiple places. Typing in one will automatically update all others with that index.
• Multiple Choice: Use ${n|option1,option2|} to provide a list of selectable items.

-- A snippet with tab stops and default values
snippets.lua.fori = [[
for ${1:i} = ${2:1}, $3 do
	$0
end]]

-- A snippet with mirrors (HTML tags)
snippets.tag = '<${1:div}>$0</$1>'

-- A snippet with multiple choice
snippets.choice = '${1|foo,bar,baz|}'