### Highlight Guide Configuration

Source: https://orbitalquark.github.io/textadept/api.html

Configure highlighting for indentation guides.

```APIDOC
## `view.highlight_guide`

### Description
The indentation guide column number to also highlight when highlighting matching braces, or `0` to stop indentation guide highlighting.
```

--------------------------------

### Migrated Lexer Example

Source: https://orbitalquark.github.io/textadept/api.html

The migrated version of the legacy lexer example, showcasing the updated API for tokenization, word matching, and styling.

```lua
local lexer = lexer
local P, S = lpeg.P, lpeg.S

local lex = lexer.new(...)

lex:add_rule('keyword', lex:tag(lexer.KEYWORD, lex:word_match(lexer.KEYWORD)))
lex:add_rule('custom', lex:tag('custom', 'quux'))
lex:add_rule('identifier', lex:tag(lexer.IDENTIFIER, lexer.word))
lex:add_rule('string', lex:tag(lexer.STRING, lexer.range('"')))
lex:add_rule('comment', lex:tag(lexer.COMMENT, lexer.to_eol('#')))
lex:add_rule('number', lex:tag(lexer.NUMBER, lexer.number))
lex:add_rule('operator', lex:tag(lexer.OPERATOR, S('+-*/%^=<>,.()[]{}')))

lex:add_fold_point(lexer.OPERATOR, '{', '}')

lex:set_word_list(lexer.KEYWORD, {'foo', 'bar', 'baz'})

return lex

```

--------------------------------

### Example Legacy Lexer

Source: https://orbitalquark.github.io/textadept/api.html

A concrete example of a legacy lexer demonstrating various token types like keywords, strings, comments, and operators.

```lua
local lexer = require('lexer')
local token, word_match = lexer.token, lexer.word_match
local P, S = lpeg.P, lpeg.S

local lex = lexer.new('legacy')

lex:add_rule('whitespace', token(lexer.WHITESPACE, lexer.space^1))
lex:add_rule('keyword', token(lexer.KEYWORD, word_match('foo bar baz')))
lex:add_rule('custom', token('custom', 'quux'))
lex:add_style('custom', lexer.styles.keyword .. {bold = true})
lex:add_rule('identifier', token(lexer.IDENTIFIER, lexer.word))
lex:add_rule('string', token(lexer.STRING, lexer.range('"')))
lex:add_rule('comment', token(lexer.COMMENT, lexer.to_eol('#')))
lex:add_rule('number', token(lexer.NUMBER, lexer.number))
lex:add_rule('operator', token(lexer.OPERATOR, S('+-*/%^=<>,.()[]{}')))

lex:add_fold_point(lexer.OPERATOR, '{', '}')

return lex

```

--------------------------------

### Indentation Guides Configuration

Source: https://orbitalquark.github.io/textadept/api.html

Configure the display of indentation guides within the editor.

```APIDOC
## `view.indentation_guides`

### Description
Draw indentation guides. Indentation guides are dotted vertical lines that appear within indentation whitespace at each level of indentation.

### Options
* `view.IV_NONE`: Do not draw any guides.
* `view.IV_REAL`: Draw guides only within indentation whitespace.
* `view.IV_LOOKFORWARD`: Draw guides beyond the current line up to the next non-empty line’s indentation level, but with an additional level if the previous non-empty line is a fold point.
* `view.IV_LOOKBOTH`: Draw guides beyond the current line up to either the indentation level of the previous or next non-empty line, whichever is greater.

### Default Values
The default value is `view.IV_LOOKBOTH` in the GUI version, and `view.IV_NONE` in the terminal version.
```

--------------------------------

### Configure Textadept via init.lua

Source: https://orbitalquark.github.io/textadept/manual.html

Example configuration for themes, indentation, key bindings, and language-specific settings in the user initialization file.

```lua
-- Adjust the default theme's font and size.
if not CURSES then
	view:set_theme('light', {font = 'Monospace', size = 12})
end

-- Always use spaces for indentation.
io.detect_indentation = false
buffer.use_tabs = false
buffer.tab_width = 2

-- Always strip trailing spaces on save, automatically highlight the current
-- word, and use C89-style block comments in C code.
textadept.editing.strip_trailing_spaces = true
textadept.editing.highlight_words = textadept.editing.HIGHLIGHT_CURRENT
textadept.editing.comment_string.c = '/*|*/'

-- Create a key binding to the "Edit > Preferences" menu item.
if not OSX and not CURSES then
	keys['ctrl+,'] = textadept.menu.menubar['Edit/Preferences'][2]
end

-- Load an external module and bind a key to it.
local lsp = require('lsp')
keys['ctrl+f12'] = lsp.goto_declaration

-- Recognize .luadoc files as Lua code.
lexer.detect_extensions.luadoc = 'lua'

-- Change the run commands for Lua and Python
textadept.run.run_commands.lua = 'lua5.1 "%f"'
textadept.run.run_commands.python = 'python3 "%f"'

-- Always use PEP-8 indentation style for Python files, and spaces for YAML files.
events.connect(events.LEXER_LOADED, function(name)
	if name == 'python' or name == 'yaml' then
		buffer.use_tabs = false
		buffer.tab_width = 4
	end
end)
```

--------------------------------

### Match at Start of Line

Source: https://orbitalquark.github.io/textadept/api.html

Creates a pattern that matches only at the beginning of a line, optionally allowing for indentation.

```lua
local preproc = lex:tag(lexer.PREPROCESSOR, lexer.starts_line(lexer.to_eol('#')))
```

--------------------------------

### Open Files and Projects from Command Line

Source: https://orbitalquark.github.io/textadept/manual.html

Examples of how to open files and projects using Textadept from the command line. Textadept assumes file paths are relative to the current working directory unless an absolute path is provided.

```bash
textadept /path/to/file1 ../relative/path/to/file2
```

```bash
textadept /path/to/project/ relative/path/to/file1 relative/file2
```

--------------------------------

### Register Command Line Argument Example

Source: https://orbitalquark.github.io/textadept/api.html

Illustrates the basic syntax for registering a command-line option with its short and long forms, argument count, callback function, and description.

```lua
args.register('-r', '--read-only', 0, function() ... end, 'Read-only mode')
```

--------------------------------

### Define Custom Build, Test, and Project Run Commands

Source: https://orbitalquark.github.io/textadept/manual.html

Configure `textadept.run.build_commands`, `textadept.run.test_commands`, and `textadept.run.run_project_commands` for specific project directories. This example sets a 'make' command for building, a 'lua' command for testing, and a function for running project commands.

```lua
textadept.run.build_commands['/path/to/project'] = 'make -C src -j4'
textadept.run.test_commands['/path/to/project'] = 'lua tests.lua'
textadept.run.run_project_commands['/path/to/project'] = function() ... end

```

--------------------------------

### Run Command Entry

Source: https://orbitalquark.github.io/textadept/api.html

Opens the command entry with a specified label and callback function. The second example demonstrates spawning a shell process.

```lua
ui.command_entry.run('echo:', ui.print)
ui.command_entry.run('$', os.spawn, 'bash', 'env', ui.print) -- spawn a process
```

--------------------------------

### Implement a Vi-like Command Mode

Source: https://orbitalquark.github.io/textadept/api.html

This example demonstrates creating a key mode named 'command_mode' with vi-like navigation keys and an 'i' key to switch to insert mode. It also includes an event handler to update the status bar and sets the default mode to 'command_mode'. Ensure a mechanism to exit modes is defined to avoid restarting Textadept.

```lua
keys.command_mode = {
	['h'] = buffer.char_left,
	['j'] = buffer.line_up,
	['k'] = buffer.line_down,
	['l'] = buffer.char_right,
	['i'] = function()
		keys.mode = nil
		ui.statusbar_text = 'INSERT MODE'
	end
}
keys['esc'] = function() keys.mode = 'command_mode' end
events.connect(events.UPDATE_UI, function()
	if keys.mode == 'command_mode' then return end
	ui.statusbar_text = 'INSERT MODE'
end)
keys.mode = 'command_mode' -- default mode
```

--------------------------------

### Compile Textadept with CMake

Source: https://orbitalquark.github.io/textadept

Standard sequence of commands to configure, build, and install Textadept. Requires CMake 3.22+ and appropriate UI toolkit development libraries.

```bash
cmake -S . -B build_dir -D CMAKE_BUILD_TYPE=RelWithDebInfo \
	-D CMAKE_INSTALL_PREFIX=build_dir/install
cmake --build build_dir -j # compiled binaries are in build_dir/
cmake --install build_dir # self-contained installation is in build_dir/install/
```

--------------------------------

### Register Custom Command Line Arguments

Source: https://orbitalquark.github.io/textadept/api.html

Register custom command-line options to modify Textadept's behavior on startup. This example sets buffers to read-only and hides the menubar.

```lua
args.register('-r', '--read-only', 0, function()
	events.connect(events.FILE_OPENED, function()
		buffer.read_only = true -- make all opened buffers read-only
	end)
	textadept.menu.menubar = nil -- hide the menubar
end, "Read-only mode")
```

--------------------------------

### Find Word Start Position

Source: https://orbitalquark.github.io/textadept/api.html

Calculates the start position of a word based on the current buffer text and word character definitions.

```lua
-- Consider the buffer text "word....word"
buffer:word_start_position(3, true) --> 1
buffer:word_start_position(7, true) --> 7
buffer:word_start_position(7, false) --> 5
buffer:word_start_position(9, false) --> 5
buffer:word_start_position(9, true) --> 9
```

--------------------------------

### LFS File Filtering Patterns

Source: https://orbitalquark.github.io/textadept/api.html

Examples of shell-style glob patterns used for filtering files and directories in lfs.walk().

```lua
'*.lua' -- match all Lua files in the top-level directory
'**/*.lua' -- match all Lua files in any directory
{'**/*.{c,h}', '!build'} -- match all C source files except in the top-level build/ directory
{'include/*', 'src/*'} -- match all immediate children of the 'include/' and 'src/' dirs
{'include/**', 'src/**'} -- match everything in 'include/' and 'src/', including subdirectories
```

--------------------------------

### Legacy Lexer Structure

Source: https://orbitalquark.github.io/textadept/api.html

This is an example of a legacy lexer structure before migration. It includes rules for whitespace, keywords, custom tokens, and fold points.

```lua
local lexer = require('lexer')
local token, word_match = lexer.token, lexer.word_match
local P, S = lpeg.P, lpeg.S

local lex = lexer.new('?')

-- Whitespace.
lex:add_rule('whitespace', token(lexer.WHITESPACE, lexer.space^1))

-- Keywords.
lex:add_rule('keyword', token(lexer.KEYWORD, word_match{
  --[[...]]
}))

--[[... other rule definitions ...]]

-- Custom.
lex:add_rule('custom_rule', token('custom_token', ...))
lex:add_style('custom_token', lexer.styles.keyword .. {bold = true})

-- Fold points.
lex:add_fold_point(lexer.OPERATOR, '{', '}')

return lex

```

--------------------------------

### Define Custom Compile and Run Commands

Source: https://orbitalquark.github.io/textadept/manual.html

Modify `textadept.run.compile_commands` and `textadept.run.run_commands` to set custom commands for compiling and running files. The example shows how to define a command for a file named 'foo' and an executable named './"%e"'.

```lua
textadept.run.compile_commands.foo = 'foo "%f"'
textadept.run.run_commands.foo = './"%e"'

```

--------------------------------

### Define Global and Language-Specific Key Bindings

Source: https://orbitalquark.github.io/textadept/api.html

Assign commands to key sequences globally or for specific lexers. Language-specific bindings take priority. The example shows binding 'ctrl+n' to `buffer.new`, 'ctrl+z' to `buffer.undo`, and a custom function for 'shift+
' in 'c' lexer.

```lua
keys['ctrl+n'] = buffer.new
keys['ctrl+z'] = buffer.undo
keys.c['shift+
'] = function() -- language-specific key
	buffer:line_end()
	buffer:add_text(';')
	buffer:new_line()
end
keys['0x1234'] = function() ... end -- key code not in keys.KEYSYMS
```

--------------------------------

### Register RGBA Image for Autocompletion

Source: https://orbitalquark.github.io/textadept/api.html

This example shows how to register an RGBA image for autocompletion lists. It requires defining the image dimensions and scale beforehand using view.rgba_image_width, view.rgba_image_height, and view.rgba_image_scale. The pixel data should be a sequence of 4-byte values (R, G, B, A) per pixel.

```lua
view:register_rgba_image(type, pixels)
```

--------------------------------

### Get Call Tip Start Position

Source: https://orbitalquark.github.io/textadept/api.html

Returns the display position of the active call tip. This function does not take any parameters.

```lua
view:call_tip_pos_start()
```

--------------------------------

### Define PHP Start and End Rules for Child

Source: https://orbitalquark.github.io/textadept/api.html

Define LPeg patterns for the start and end of PHP code blocks within HTML. The start rule uses `lexer.space` to consume whitespace after '<?php', and the end rule matches '?>'.

```lua
local php_start_rule = lex:tag('php_tag', '<?php' * lexer.space)
local php_end_rule = lex:tag('php_tag', '?>')
```

--------------------------------

### Require and Configure LSP Module

Source: https://orbitalquark.github.io/textadept/manual.html

Load the 'lsp' module and configure a C++ language server command. Place this in your ~/.textadept/init.lua.

```lua
local lsp = require('lsp')
lsp.server_commands.cpp = 'clangd'

```

--------------------------------

### Apply Tag to CSS Start Rule

Source: https://orbitalquark.github.io/textadept/api.html

Append the `tag` rule to the CSS start pattern to ensure the 'style' tag itself is correctly identified as an HTML tag before switching to the CSS lexer.

```lua
local css_start_rule = #css_tag * tag
```

--------------------------------

### Define CSS Start Rule for HTML Parent

Source: https://orbitalquark.github.io/textadept/api.html

Define an LPeg pattern to identify the start of a CSS block within HTML, specifically looking for a '<style type="text/css">' tag. This pattern is used to signal the transition to the child lexer.

```lua
local css_tag = P('<style') * P(function(input, index)
  if input:find('^[^>]+type="text/css"', index) then return true end
end)
```

--------------------------------

### Move caret to beginning of buffer

Source: https://orbitalquark.github.io/textadept/api.html

Moves the caret to the very start of the buffer.

```lua
buffer:document_start()
```

--------------------------------

### ui.dialogs.open

Source: https://orbitalquark.github.io/textadept/api.html

Prompts the user to select one or more files or directories from the filesystem.

```APIDOC
## ui.dialogs.open(_options_)

### Description
Prompts the user to select a file from the filesystem.

### Parameters
* _options_ : Table of key-value option pairs for the dialog.
  * `title`: String title.
  * `dir`: String directory to initially show.
  * `file`: String file to initially select. This option requires `dir` to be set.
  * `multiple`: Allow the user to select multiple files. The terminal version does not support this option.
  * `only_dirs`: Only allow the user to select directories.

### Returns
string filename or table of filenames; or `nil` if the user canceled the dialog

### Usage Example
```lua
ui.dialogs.open{title = 'Open File', dir = _HOME, multiple = true}
```
```

--------------------------------

### GET buffer:text_range

Source: https://orbitalquark.github.io/textadept/api.html

Retrieves a specific range of text from the buffer.

```APIDOC
## GET buffer:text_range

### Description
Returns a range of text from the buffer.

### Method
GET

### Endpoint
buffer:text_range(start_pos, end_pos)

### Parameters
#### Path Parameters
- **start_pos** (number) - Required - Start position of the range.
- **end_pos** (number) - Required - End position of the range.
```

--------------------------------

### Move caret to beginning of line

Source: https://orbitalquark.github.io/textadept/api.html

Moves the caret to the start of the current line.

```lua
buffer:home()
```

--------------------------------

### Open a file selection dialog

Source: https://orbitalquark.github.io/textadept/api.html

Prompts the user to select one or more files from the filesystem.

```lua
ui.dialogs.open{title = 'Open File', dir = _HOME, multiple = true}
```

--------------------------------

### Configure Quick Open Max Files and Filters

Source: https://orbitalquark.github.io/textadept/manual.html

Adjust the maximum number of files displayed in the quick open dialog and define project-specific filters to include or exclude directories. This is useful for managing large projects or customizing search results.

```lua
io.quick_open_max = 10000 -- support huge projects
io.quick_open_filters['/path/to/project'] = {'include/**', 'src/**'} -- only show these directories
```

--------------------------------

### Text Retrieval

Source: https://orbitalquark.github.io/textadept/api.html

Functions to get the text content of the buffer or the selected portion.

```APIDOC
## `buffer:get_text`()

Returns the buffer’s text.

## `buffer:get_sel_text`()

Returns the selected text.
Multiple selections are included in order, separated by `buffer.copy_separator`. Rectangular selections are included from top to bottom with end of line characters. Virtual space is not included.

## `buffer.copy_separator`

The string added between multiple selections in `buffer:get_sel_text()`.
The default value is the empty string (no separators).
```

--------------------------------

### Get entire buffer text

Source: https://orbitalquark.github.io/textadept/api.html

Retrieves all text content from the current buffer.

```lua
buffer:get_text()
```

--------------------------------

### Iterate over directory files using lfs.walk

Source: https://orbitalquark.github.io/textadept/api.html

Demonstrates using lfs.walk to iterate through files in the current buffer's directory.

```lua
for filename in lfs.walk(buffer.filename:match('^.+[/\]')) do ... end
```

--------------------------------

### Selection Data Access

Source: https://orbitalquark.github.io/textadept/api.html

Accessors for selection start and end positions, including virtual space.

```APIDOC
### Selection Data Access

#### `buffer.selection_n_anchor`

Map of existing selection numbers to their start positions.

#### `buffer.selection_n_caret`

Map of existing selection numbers to their end positions.

#### `buffer.selection_n_start`

Map of existing selection numbers to their start positions.

#### `buffer.selection_n_end`

Map of existing selection numbers to their end positions.

#### `buffer.selection_n_anchor_virtual_space`

Map of existing selection numbers to their virtual space start positions.

#### `buffer.selection_n_caret_virtual_space`

Map of existing selection numbers to their virtual space end positions.

#### `buffer.selection_n_start_virtual_space`

Map of existing selection numbers to their virtual space start positions. (Read-only)

#### `buffer.selection_n_end_virtual_space`

Map of existing selection numbers to their virtual space end positions. (Read-only)
```

--------------------------------

### Move caret to beginning of wrapped line

Source: https://orbitalquark.github.io/textadept/api.html

Moves the caret to the start of the current wrapped line.

```lua
buffer:home_display()
```

--------------------------------

### Get Buffer Length

Source: https://orbitalquark.github.io/textadept/api.html

Reads the total number of bytes currently in the buffer. This is a read-only property.

```lua
buffer.length
```

--------------------------------

### Configure Project Run Command with Custom Environment

Source: https://orbitalquark.github.io/textadept/api.html

Defines a function for `textadept.run.run_project_commands` to execute a Textadept build. It customizes the environment by including TEXTADEPT_HOME and other system environment variables, specifies a working directory, and sets the command to run a test instance of Textadept.

```lua
textadept.run.run_project_commands[_HOME] = function()
	local env = {TEXTADEPT_HOME = _HOME}
	for setting in os.spawn('env'):read('a'):gmatch('[^
]+') do env[#env + 1] = setting end
	return _HOME .. '/build/textadept -f -n', '/tmp', env -- run test instance of Textadept
end

```

--------------------------------

### Line Information

Source: https://orbitalquark.github.io/textadept/api.html

Read-only maps providing information about lines, including their start and end positions, and indentation.

```APIDOC
## `lexer.line_end`

### Description
Map of line numbers (starting from 1) to their end positions. (Read-only)

## `lexer.line_start`

### Description
Map of line numbers (starting from 1) to their start positions. (Read-only)

## `lexer.line_state`

### Description
Map of line numbers (starting from 1) to their 32-bit integer line states. Line states can be used by lexers for keeping track of persistent states (up to 32 states with 1 state per bit). For example, the output lexer uses this to mark lines that have warnings or errors.
```

--------------------------------

### textadept.keys Module

Source: https://orbitalquark.github.io/textadept/api.html

Overview of key binding definitions and platform-specific conventions for Textadept.

```APIDOC
## textadept.keys

### Description
Defines key bindings for Textadept. The bindings are designed to be consistent across operating systems, with specific adjustments for macOS and terminal environments.

### Platform Conventions
- **macOS**: Uses Command (⌘) instead of Control, and Control (^) instead of Alt, with exceptions for word/paragraph movement.
- **Terminal**: Maps Ctrl+Shift and Ctrl+symbol combinations to M- sequences due to terminal input limitations.
- **Windows Note**: International keyboard layouts using AltGr may conflict with Ctrl+Alt bindings; these can be disabled in init.lua by setting the binding to nil.
```

--------------------------------

### Match Block Comments

Source: https://orbitalquark.github.io/textadept/api.html

Define C-style block comments using lexer.range with start and end delimiters.

```lua
local c_comment = lex:tag(lexer.COMMENT, lexer.range('/*', '*/'))
```

--------------------------------

### textadept.run.run_project

Source: https://orbitalquark.github.io/textadept/api.html

Prompts the user to run a shell command for a project.

```APIDOC
## textadept.run.run_project

### Description
Prompts the user with the command entry to run a shell command for a project.

### Parameters
#### Path Parameters
- **dir** (string) - Optional - String path to the project to run a command for. Defaults to current project.
- **cmd** (string) - Optional - String command to run.
```

--------------------------------

### Get Line Indentation Map

Source: https://orbitalquark.github.io/textadept/api.html

Provides a map of line numbers to their corresponding indentation column amounts.

```lua
buffer.line_indentation
```

--------------------------------

### Creating Menus with ui.menu

Source: https://orbitalquark.github.io/textadept/api.html

Constructs a menu structure using nested tables. Use this for low-level menu definitions.

```lua
ui.menu{ {'_New', 1}, {'_Open', 2}, {''}, {'&Quit', 4} }
ui.menu{ {'_New', 1, string.byte('n'), view.MOD_CTRL} } -- 'Ctrl+N'
```

--------------------------------

### Key Chains Configuration

Source: https://orbitalquark.github.io/textadept/api.html

Explains how to define and use key chains for multi-key sequences.

```APIDOC
## Key Chains

### Description
Key chains allow assigning multiple key bindings to one key sequence. Pressing the initial sequence activates the chain, and subsequent keys invoke specific functions.

### Request Example
keys['alt+a'] = {
	a = function1,
	b = function2,
	c = {...}
}
```

--------------------------------

### Get Buffer Text Length

Source: https://orbitalquark.github.io/textadept/api.html

Reads the total number of bytes in the buffer, equivalent to `buffer.length`. This is a read-only property.

```lua
buffer.text_length
```

--------------------------------

### Add fold points to a lexer

Source: https://orbitalquark.github.io/textadept/api.html

Configures fold points for a lexer using specific start and end symbols or custom functions.

```lua
lex:add_fold_point(lexer.OPERATOR, '{', '}')
lex:add_fold_point(lexer.KEYWORD, 'if', 'end')
lex:add_fold_point('custom', function(text, pos, line, s, symbol) ... end)
```

--------------------------------

### Lua Command Entry Equivalents

Source: https://orbitalquark.github.io/textadept/manual.html

Illustrates how certain Lua API calls can be simplified when entered in Textadept's command entry. Parentheses and table prefixes can often be omitted for brevity.

```lua
buffer:reload()

```

```lua
view:split(true)

```

```lua
tabs = false

```

```lua
keys['ctrl+n'] = new

```

--------------------------------

### ui.goto_view

Source: https://orbitalquark.github.io/textadept/api.html

Switches focus to another view.

```APIDOC
## ui.goto_view(view)

### Description
Switches focus to another view.

### Parameters
#### Path Parameters
- **view** (View/Integer) - Required - View to switch to, or index of a relative view to switch to (typically 1 or -1).
```

--------------------------------

### Load Optional Textadept Modules with Lua

Source: https://orbitalquark.github.io/textadept

To use optional modules, require them using Lua's `require()` function in your configuration, then save and restart Textadept.

```lua
require('lsp')
require('file_diff')
require('spellcheck')
```

--------------------------------

### Define a numeric for loop snippet

Source: https://orbitalquark.github.io/textadept/api.html

Creates a numeric for loop in Lua using placeholders for the iterator variable, start value, and end value.

```lua
snippets.lua.fori = [[
for ${1:i} = ${2:1}, $3 do
	$0
end]]
```

--------------------------------

### Set Theme and Font Size

Source: https://orbitalquark.github.io/textadept/manual.html

Set the editor's theme to 'light' with a specified font and size. This configuration should be placed in your ~/.textadept/init.lua and is conditional on not using the CURSES terminal.

```lua
if not CURSES then
	view:set_theme('light', {font = 'Monospace', size = 12})
	-- You can alternatively use the following to keep the default theme:
	-- view:set_theme{font = 'Monospace', size = 12}
end

```

--------------------------------

### Buffer Target Range Information

Source: https://orbitalquark.github.io/textadept/api.html

Properties related to the target range within the buffer, including start and end positions and virtual space.

```APIDOC
## Buffer Target Range Properties

### Description
Properties that define the start and end of a target range within the buffer, along with their associated virtual space.

### Properties
- **buffer.target_start** (Position) - The start position of the target range. Set by `buffer:search_in_target()`.
- **buffer.target_end** (Position) - The end position of the target range. Set by `buffer:search_in_target()`.
- **buffer.target_start_virtual_space** (Integer) - The start position of the target range's virtual space. Reset when `buffer.target_start`, `buffer.target_end`, or `buffer:set_target_range()` is called.
- **buffer.target_end_virtual_space** (Integer) - The end position of the target range's virtual space. Reset when `buffer.target_start`, `buffer.target_end`, or `buffer:set_target_range()` is called.
- **buffer.tag** (Map) - A read-only map of regular expression capture numbers to captured text.
```

--------------------------------

### Configure Custom Lexer Detection

Source: https://orbitalquark.github.io/textadept/manual.html

Add custom patterns and extensions to the lexer detection tables in your init.lua file.

```lua
lexer.detect_patterns['^#!.+/zsh'] = 'bash'
lexer.detect_extensions.luadoc = 'lua'
```

--------------------------------

### Example of incorrectly tagged interpolated string

Source: https://orbitalquark.github.io/textadept/api.html

Demonstrates Ruby code that fails to tag correctly when a language attempts to embed itself into an interpolated string.

```ruby
    sum = "1 + 2 = #{1 + 2}"
```

--------------------------------

### Lexer Initialization and Loading

Source: https://orbitalquark.github.io/textadept/api.html

Functions for initializing, loading, and creating lexer objects.

```APIDOC
## `lexer.load`(_name_[, _alt_name_])

### Description
Initializes or loads a lexer. Scintilla calls this function in order to load a lexer. Parent lexers also call this function in order to load child lexers and vice-versa. The user calls this function in order to load a lexer when using Scintillua as a Lua library.

### Parameters
  * _name_ : String name of the lexing language.
  * _alt_name_ : String alternate name of the lexing language. This is useful for embedding the same child lexer with multiple sets of start and end tags.

### Returns
lexer object

## `lexer.new`(_name_[, _opts_])

### Description
Creates a new lexer.

### Parameters
  * _name_ : String lexer name. Use `...` to inherit from the file’s name.
  * _opts_ : Table of lexer options. Options currently supported: 
    * `lex_by_line`: Only processes whole lines of text at a time (instead of arbitrary chunks of text). Line lexers cannot look ahead to subsequent lines. The default value is `false`.
    * `fold_by_indentation`: Calculate fold points based on changes in line indentation. The default value is `false`.
    * `case_insensitive_fold_points`: Fold points added via `lexer.add_fold_point()` should ignore case. The default value is `false`.
    * `no_user_word_lists`: Do not automatically allocate word lists that can be set by users. This should really only be set by non-programming languages like markup languages.
    * `inherit`: Lexer to inherit from. The default value is `nil`.

### Returns
lexer object

### Usage
```lua
lexer.new(..., {inherit = lexer.load('html')}) -- name is 'rhtml' in rhtml.lua file
```
```

--------------------------------

### Example of incorrectly tagged embedded code

Source: https://orbitalquark.github.io/textadept/api.html

Demonstrates code that may not be tagged correctly due to limitations in embedded preprocessor language support.

```html
    <div id="<?php echo $id; ?>">
```

--------------------------------

### Navigate bookmarks with textadept.bookmarks.goto_mark

Source: https://orbitalquark.github.io/textadept/api.html

Jumps between bookmarked lines in the current buffer. Passing true or false determines the direction of the jump.

```lua
textadept.bookmarks.goto_mark(true) -- jump to the next bookmark
textadept.bookmarks.goto_mark(false) -- jump to the previous bookmark
```

--------------------------------

### Initialize a line-based lexer

Source: https://orbitalquark.github.io/textadept/api.html

Configures a lexer to process input one line at a time.

```lua
local lex = lexer.new(..., {lex_by_line = true})
```

--------------------------------

### Tagging identifiers with custom strings and patterns

Source: https://orbitalquark.github.io/textadept/api.html

Demonstrates manual tag assignment using a string identifier and a custom LPeg pattern.

```lua
lex:tag('identifier', (lpeg.R('AZ', 'az')  + '_') * (lpeg.R('AZ', 'az', '09') + '_')^0)
```

--------------------------------

### Get selected text

Source: https://orbitalquark.github.io/textadept/api.html

Retrieves the currently selected text. Handles multiple and rectangular selections, separating them with `buffer.copy_separator`. Virtual space is excluded.

```lua
buffer:get_sel_text()
```

--------------------------------

### textadept.run.run

Source: https://orbitalquark.github.io/textadept/api.html

Prompts the user to run a file using a command from the run_commands table.

```APIDOC
## textadept.run.run

### Description
Prompts the user with the command entry to run a file using an appropriate shell command from the textadept.run.run_commands table.

### Parameters
#### Path Parameters
- **filename** (string) - Optional - String path of the file to run. Defaults to buffer.filename.
```

--------------------------------

### Get Wrapped Line Count

Source: https://orbitalquark.github.io/textadept/api.html

Determines how many display lines are needed to fully show a given document line, considering text wrapping.

```lua
view:wrap_count(_line_)
```

--------------------------------

### Determine fold points in text

Source: https://orbitalquark.github.io/textadept/api.html

Calculates fold levels for a given chunk of text using a specified lexer. The starting line and fold level can be provided.

```lua
lex:fold(...) --> {[1] = 1024, [2] = 9216, [3] = 1025, [4] = 1025, [5] = 1024}
```

--------------------------------

### Quickly Open File from Directory List

Source: https://orbitalquark.github.io/textadept/api.html

Prompts the user to select a file from a list generated by searching specified directories. Supports custom filters for file selection.

```lua
io.quick_open(buffer.filename:match('^(.+)[/\\]')) -- list files in the buffer's directory
```

```lua
io.quick_open(io.get_project_root(), '**/*.{lua,c}') -- list Lua and C project files
```

```lua
io.quick_open(io.get_project_root(), '!build') -- list non-build project files
```

--------------------------------

### Get Buffer Column Map

Source: https://orbitalquark.github.io/textadept/api.html

Accesses a map that translates buffer positions to their corresponding column numbers, correctly handling multi-byte characters and tab expansions.

```lua
buffer.column
```

--------------------------------

### ui.output

Source: https://orbitalquark.github.io/textadept/api.html

Prints to the output buffer, creating it if necessary.

```APIDOC
## ui.output(...)

### Description
Prints to the output buffer, creating it if necessary. The output buffer attempts to understand the error messages and warnings produced by various tools.

### Parameters
#### Request Body
- **...** (String) - Required - Strings to print.

### Response
- **buffer** (userdata) - The output buffer.
```

--------------------------------

### Get Visible Line Number

Source: https://orbitalquark.github.io/textadept/api.html

Converts an actual document line number to its corresponding displayed line number, accounting for wrapping, annotations, and hidden lines.

```lua
view:visible_from_doc_line(_line_)
```

--------------------------------

### Match Keywords with a single string

Source: https://orbitalquark.github.io/textadept/api.html

Use a single string of space-separated words for short, static keyword lists.

```lua
local keyword = lex:tag(lexer.KEYWORD, lexer.word_match('key_1 key_2 ... key_n'))
```

--------------------------------

### Get Line Number from Position

Source: https://orbitalquark.github.io/textadept/api.html

Retrieves the line number containing a given buffer position. Handles out-of-bounds positions by clamping to the nearest valid line.

```lua
buffer:line_from_position(_pos_)
```

--------------------------------

### keys.assign_platform_bindings

Source: https://orbitalquark.github.io/textadept/api.html

Assigns key bindings for the current platform based on a map of commands to lists of their platform-specific key sequences.

```APIDOC
## keys.assign_platform_bindings(keys, bindings)

### Description
Assigns key bindings for the current platform based on a map of commands to lists of their platform-specific key sequences.

### Parameters
#### Path Parameters
- **keys** (Table) - Required - Table to assign key bindings in.
- **bindings** (Table) - Required - Map of Lua functions to tables of key sequences for Windows/Linux/BSD, macOS, and the terminal version, in that order.

### Request Example
keys.assign_platform_bindings{
	[buffer.new] = {'ctrl+n', 'cmd+n', 'ctrl+n'},
	[buffer.line_down] = {'down', {'down', 'ctrl+n'}, 'down'},
}
```

--------------------------------

### Move caret to beginning of wrapped or actual line

Source: https://orbitalquark.github.io/textadept/api.html

Moves the caret to the beginning of the current wrapped line, or to the beginning of the actual line if already at the start of the wrapped line.

```lua
buffer:home_wrap()
```

--------------------------------

### Create a New Lexer

Source: https://orbitalquark.github.io/textadept/api.html

Initializes a new lexer instance, optionally inheriting from an existing lexer.

```lua
lexer.new(..., {inherit = lexer.load('html')}) -- name is 'rhtml' in rhtml.lua file
```

--------------------------------

### textadept.bookmarks.goto_mark

Source: https://orbitalquark.github.io/textadept/api.html

Jumps to the beginning of a bookmarked line.

```APIDOC
## textadept.bookmarks.goto_mark([next])

### Description
Jumps to the beginning of a bookmarked line.

### Parameters
- **next** (boolean) - Optional - Jump to the next bookmarked line in the current buffer instead of the previous one.
```

--------------------------------

### Get Line Length

Source: https://orbitalquark.github.io/textadept/api.html

Calculates the number of bytes on a specific line, including end-of-line characters. For length excluding EOL, use `buffer.line_end_position[line] - buffer.position_from_line(line)`.

```lua
buffer:line_length(_line_)
```

--------------------------------

### Configure Project Test Commands

Source: https://orbitalquark.github.io/textadept/api.html

Map project root paths to their associated test shell command lines or functions. Functions can also specify a working directory and environment.

```lua
textadept.run.test_commands['/path/to/project'] = 'pytest'
```

--------------------------------

### Set Custom Theme with Font and Size Overrides

Source: https://orbitalquark.github.io/textadept/api.html

Applies a custom theme named 'my_theme' while also overriding font and size. The theme file should be located in the Textadept themes directory or specified as an absolute path.

```lua
view:set_theme('my_theme', {font = 'Monospace', size = 12})
```

--------------------------------

### Get Project Root Directory

Source: https://orbitalquark.github.io/textadept/api.html

Returns the root directory of a project recognized by version control systems (Git, Mercurial, SVN, Bazaar, Fossil). Optionally searches from a specific path or submodule.

```lua
io.get_project_root([_path_][, _submodule_ =false])
```

--------------------------------

### Textadept Run Commands API

Source: https://orbitalquark.github.io/textadept/api.html

API for executing compile, run, build, test, and project shell commands.

```APIDOC
## textadept.run.build

### Description
Prompts the user with the command entry to build a project using its shell command from the `textadept.run.build_commands` table.

### Parameters
* **dir** (String) - Path to the project to build. The default value is the current project, which is determined by either the buffer’s filename or the current working directory.

### See also
events.BUILD_OUTPUT

## textadept.run.build_commands

### Description
Map of project root paths and “makefiles” to their associated “build” shell command line strings or functions that return such strings. Functions may also return a working directory and process environment table to operate in. By default, the working directory is the project’s root directory and the environment is Textadept’s environment.

### Usage
```lua
textadept.run.build_commands['CMakeLists.txt'] = 'cmake --build build'
textadept.run.build_commands['/path/to/project'] = 'make -C src'
```

## textadept.run.INDIC_ERROR

### Description
The run or compile error indicator number.

## textadept.run.INDIC_WARNING

### Description
The run or compile warning indicator number.

## textadept.run.MARK_ERROR

### Description
The run or compile error marker number.

## textadept.run.MARK_WARNING

### Description
The run or compile warning marker number.
```

--------------------------------

### Textadept Macros API

Source: https://orbitalquark.github.io/textadept/api.html

API for recording, playing, saving, and loading keyboard macros.

```APIDOC
## textadept.macros.load

### Description
Loads a macro.

### Parameters
* **filename** (String) - Macro file to load. If `nil`, the user is prompted for one. If the filename is a relative path, it will be relative to `~/.textadept/macros/`.

## textadept.macros.play

### Description
Plays a recorded or previously loaded macro.

### Parameters
* **filename** (String) - Filename of a macro to load and play. If the filename is a relative path, it will be relative to `~/.textadept/macros/`.

## textadept.macros.save

### Description
Saves a recorded macro.

### Parameters
* **filename** (String) - Filename to save the recorded macro to. If `nil`, the user is prompted for one. If the filename is a relative path, it will be relative to `~/.textadept/macros/`.

## textadept.macros.record

### Description
Toggles between starting and stopping macro recording.
```

--------------------------------

### Define a Custom Marker Symbol

Source: https://orbitalquark.github.io/textadept/api.html

Assigns a visual symbol to a custom marker number. Marker numbers range from 1 to 32. Use view.new_marker_number() to get a unique number for custom markers.

```lua
view:marker_define(marker, view.MARK_CIRCLE)
```

--------------------------------

### Get Document Line Number from Visible

Source: https://orbitalquark.github.io/textadept/api.html

Converts a displayed line number to its actual document line number, considering wrapping, annotations, and hidden lines. Handles out-of-bounds display lines.

```lua
view:doc_line_from_visible(_display_line_)
```

--------------------------------

### ui.menu

Source: https://orbitalquark.github.io/textadept/api.html

Low-level function for creating a menu.

```APIDOC
## ui.menu(menu_table)

### Description
Low-level function for creating a menu. You probably want to use the higher-level textadept.menu.menubar, textadept.menu.context_menu, or textadept.menu.tab_context_menu tables.

### Parameters
#### Request Body
- **menu_table** (Table) - Required - Ordered list of tables with a string menu item, integer menu ID, and optional keycode and modifier mask.

### Response
- **menu** (userdata) - The created menu.
```

--------------------------------

### Configure Find in Files Filters in Lua

Source: https://orbitalquark.github.io/textadept/manual.html

Customize the files and directories included or excluded from 'Find in Files' searches by modifying the ui.find.find_in_files_filters table in your init.lua. This example restricts searches to specific source directories.

```lua
-- Only search in certain source directories.
ui.find.find_in_files_filters['/path/to/project'] = {'include/**', 'src/**'}

```

--------------------------------

### Spawn child processes with os.spawn

Source: https://orbitalquark.github.io/textadept/api.html

Use os.spawn to execute shell commands. The returned process object allows for interactive communication via write and close methods.

```lua
os.spawn('lua ' .. buffer.filename, print) -- non-interactive
local proc = os.spawn('lua -e "print(io.read())"', print) -- interactive
proc:write('foo\n')
proc:close() -- close stdin, not the process
```

--------------------------------

### Embed Child Lexer in Parent

Source: https://orbitalquark.github.io/textadept/api.html

Embed the loaded child lexer (CSS) into the parent lexer (HTML) using the defined start and end rules. This function call integrates the child lexer's highlighting capabilities.

```lua
lex:embed(css, css_start_rule, css_end_rule)
```

--------------------------------

### Resizing the Window with ui.size

Source: https://orbitalquark.github.io/textadept/api.html

Sets the dimensions of the Textadept window in pixels.

```lua
ui.size = {1000, 625} -- resize window
```