From 033416a15fe60fe10387119e0e63bb9ed9e8aedd Mon Sep 17 00:00:00 2001 From: mitchell <70453897+667e-11@users.noreply.github.com> Date: Sat, 25 Jul 2009 23:34:13 -0400 Subject: Documentation overhaul. --- core/._m.lua | 84 ++++--- core/.browser.lua | 12 +- core/.buffer.lua | 558 ++++++++++++++++++++-------------------------- core/.command_entry.lua | 38 +++- core/.find.lua | 61 +++-- core/.pm.lua | 56 ++--- core/.textadept.lua | 34 ++- core/.view.lua | 16 +- core/events.lua | 258 +++++++++++++-------- core/ext/key_commands.lua | 100 ++++++++- core/ext/keys.lua | 71 +----- core/ext/mime_types.lua | 78 +++++-- core/file_io.lua | 59 ++++- core/locale.conf | 4 +- core/locale.lua | 24 +- 15 files changed, 818 insertions(+), 635 deletions(-) (limited to 'core') diff --git a/core/._m.lua b/core/._m.lua index 36f2f25c..47afeab3 100644 --- a/core/._m.lua +++ b/core/._m.lua @@ -4,36 +4,64 @@ --- -- A table of loaded modules. --- [Dummy file] module('_m') --- Usage: --- Modules utilize the Lua 5.1 package model. --- --- There are two kinds of modules: generic and language-specific. Both are just --- single directories full of Lua scripts and maybe additional files. Each --- module has an init.lua script that loads all of the functionality provided by --- the module. --- --- Generic modules are loaded on startup (/init.lua) and available all the time. --- --- Language-specific modules are loaded when a file with a specific extension is --- opened or saved and available to that kind of file only. Adding or modifying --- a language is done in /core/ext/mime_types.lua. Add your language and its --- associated lexer to the languages table, the language's file extension and --- associated language to the extensions table, and optionally shebang words --- with their associated language to the shebangs table. --- Each module contains the init.lua script, and typically a commands.lua and --- snippets.lua script. Sometimes .api files can be used by a module. To do so, --- set an 'api' variable to textadept.io.read_api_file(path, word_chars)'s --- return value. It will be used for displaying calltips and autocomplete lists --- by default. --- You can use the 'modules' Project Manager browser to create and manage --- language-specific modules. --- --- When assigning key commands to module functions, do not forget to do so AFTER --- the function has been defined. Typically key commands are placed at the end --- of files, like commands.lua in language-specific modules. +-- Markdown: +-- ## Overview +-- +-- Modules utilize the Lua 5.1 package model. It is recommended to put all +-- modules in the `modules/` Textadept directory. A module consists of a single +-- directory with an `init.lua` script to load any additional Lua files +-- (typically in the same location). Essentially there are two classes of +-- modules: generic and language-specific. +-- +-- ## Generic Modules +-- +-- This class of modules is usually available globally for programming in all +-- languages. An example is the [`_m.textadept`][m_textadept] module which adds +-- a wide variety of text editing capabilities to Textadept. +-- +-- [m_textadept]: ../modules/_m.textadept.html +-- +-- ## Language-specific Modules +-- +-- Each module of this class of modules is named after a language lexer in +-- `lexers/` and is usually available only for editing code in that particular +-- programming language. Examples are the [`_m.cpp`][m_cpp] and +-- [`_m.lua`][m_lua] modules which provide special editing features for the +-- C/C++ and Lua languages respectively. +-- +-- [m_cpp]: ../modules/_m.cpp.html +-- [m_lua]: ../modules/_m.lua.html +-- +-- Note: While language-specific modules can only be used by files of that +-- language, they persist in Textadept's Lua state. Because of this, it is not +-- recommended to set global functions or variables and depend on them, as they +-- may be inadvertantly overwritten. Keep these inside the module. +-- +-- ## Loading Modules +-- +-- Generic modules can be loaded using `require`: +-- +-- require 'module_name' +-- +-- Language-specific modules are automatically loaded when a file of that +-- language is loaded or a buffer's lexer is set to that language. +-- +-- ## Managing Modules +-- +-- Modules are easy to create and edit in the filesystem, but you can use the +-- `modules` PM browser to create Language-specific modules from a generic +-- template, or manage all available modules. +-- +-- ## Modules and Key Commands +-- +-- When assigning [key commands][key_commands] to module functions, do not +-- forget to do so AFTER the function has been defined. Typically key commands +-- are placed at the end of files, like `commands.lua` in language-specific +-- modules. +-- +-- [key_commands]: ../modules/textadept.keys.html --- -- This module contains no functions. diff --git a/core/.browser.lua b/core/.browser.lua index a9bb2ac1..486d9557 100644 --- a/core/.browser.lua +++ b/core/.browser.lua @@ -3,9 +3,6 @@ --- -- A model browser for the Textadept project manager. --- It can be loaded by adding to the browsers table in core/ext/pm.lua or by --- 'require'ing it elsewhere. --- [Dummy file] module('textadept.pm.browser') --- @@ -40,8 +37,8 @@ function get_contents_for(full_path, expanding) --- -- Performs an action based on the selected treeview item. -- This function is called internally and shouldn't be called by a script. --- @param selected_item Identical to 'full_path' in pm.get_contents_for. --- @see pm.get_contents_for +-- @param selected_item Identical to 'full_path' in get_contents_for. +-- @see get_contents_for function perform_action(selected_item) --- @@ -54,15 +51,14 @@ function perform_action(selected_item) -- 'gtk-*' - a stock menu item is created based on the GTK stock-id. -- 'separator' - a menu separator item is created. -- Otherwise a regular menu item with a mnemonic is created. --- @see pm.get_contents_for function get_context_menu(selected_item) --- -- Performs an action based on the selected menu item. -- This function is called internally and shouldn't be called by a script. -- @param menu_id The numeric ID of the menu item. --- @param selected_item Identical to 'full_path' in pm.get_contents_for. --- @see pm.get_contents_for +-- @param selected_item Identical to 'full_path' in get_contents_for. +-- @see get_contents_for function perform_menu_action(menu_id, selected_item) --- diff --git a/core/.buffer.lua b/core/.buffer.lua index af1221b9..549761e3 100644 --- a/core/.buffer.lua +++ b/core/.buffer.lua @@ -5,369 +5,267 @@ --- -- The current buffer in the currently focused view. -- It also represents the structure of any buffer table in 'buffers'. --- [Dummy file] module('buffer') ---- --- The current buffer in the currently focused view. --- It also represents the structure of any buffer table in 'buffers'. --- @class table --- @name buffer --- @field doc_pointer The pointer to the document associated with this buffer. +-- Markdown: +-- ## Fields +-- +-- * `doc_pointer`: The pointer to the document associated with this buffer. -- (Used internally; read-only) --- @field dirty Flag indicating whether or not the buffer has been modified --- since it was last saved. --- @field filename The absolute path to the file associated with this buffer. --- It is encoded in UTF-8. Use 'textadept.iconv()' for charset conversions. --- @field encoding The encoding of the file on the hard disk. It will be nil if +-- * `dirty`: Flag indicating whether or not the buffer has been modified since +-- it was last saved. +-- * `filename`: The absolute path to the file associated with this buffer. It +-- is encoded in UTF-8. Use [`textadept.iconv()`][textadept_iconv] for +-- charset conversions. +-- * `encoding`: The encoding of the file on the hard disk. It will be nil if -- the file is a binary file. --- @field encoding_bom The byte-order mark of the file encoding (if any). --- @field anchor The position of the opposite end of the selection to the --- caret. --- @field auto_c_auto_hide Flag indicating whether or not autocompletion is --- hidden automatically when nothing matches. --- @field auto_c_cancel_at_start Flag indicating whether or not autocompletion +-- * `encoding_bom`: The byte-order mark of the file encoding (if any). +-- * `anchor`: The position of the opposite end of the selection to the caret. +-- * `auto_c_auto_hide`: Flag indicating whether or not autocompletion is hidden +-- automatically when nothing matches. +-- * `auto_c_cancel_at_start`: Flag indicating whether or not autocompletion -- should be cancelled if the user backspaces to a position before where it -- was created. --- @field auto_c_choose_single Flag indicating whether or not a single item in +-- * `auto_c_choose_single`: Flag indicating whether or not a single item in -- autocompletion should be chosen automatically. --- @field auto_c_drop_rest_of_word Flag indicating whether or not autocompletion +-- * `auto_c_drop_rest_of_word`: Flag indicating whether or not autocompletion -- deletes any word characters after the inserted text upon completion. --- @field auto_c_fill_ups A string of characters that when typed will cause the +-- * `auto_c_fill_ups`: A string of characters that when typed will cause the -- autocompletion to choose the selected item. --- @field auto_c_ignore_case Flag indicating whether or not case is significant +-- * `auto_c_ignore_case`: Flag indicating whether or not case is significant -- when performing autocompletion searches. --- @field auto_c_max_height The maximum height in rows of autocompletion and --- user lists. Default is 5. --- @field auto_c_max_width The maximum width in characters of autocompletion and +-- * `auto_c_max_height`: The maximum height in rows of autocompletion and user +-- lists. Default is 5. +-- * `auto_c_max_width`: The maximum width in characters of autocompletion and -- user lists. --- @field auto_c_type_separator The (integer) type separator character in the +-- * `auto_c_type_separator`: The (integer) type separator character in the -- string setting up an autocompletion list. --- @field back_space_un_indents Flag indicating whether or not a backspace press +-- * `back_space_un_indents`: Flag indicating whether or not a backspace press -- when the caret is within indentation unindents. --- @field buffered_draw Flag indicating whether or not text is drawn into a --- buffer first or directly onto the screen. --- @field call_tip_back The background color for the call tip. (Write-only) --- @field call_tip_fore The foreground color for the call tip. (Write-only) --- @field call_tip_fore_hlt The foreground color for the highlighted part of the --- call tip. --- @field call_tip_use_style Call tip tab size in pixels. (Enables --- STYLE_CALLTIP) --- @field caret_fore The foreground color of the caret. --- @field caret_line_back The color of the background of the line containing the --- caret. --- @field caret_line_back_alpha The background alpha of the caret line. --- @field caret_line_visible Flag indicating whether or not the background of --- the line containing the caret is a different color. --- @field caret_period The time in milliseconds that the caret is on and off. 0 --- is a steady on. --- @field caret_sticky Flag indicating whether or not the caret preferred x +-- * `buffered_draw`: Flag indicating whether or not text is drawn into a buffer +-- first or directly onto the screen. +-- * `call_tip_back`: The background [color][color] for the call tip. +-- (Write-only) +-- * `call_tip_fore`: The foreground [color][color] for the call tip. +-- (Write-only) +-- * `call_tip_fore_hlt`: The foreground [color][color] for the highlighted part +-- of the call tip. +-- * `call_tip_use_style`: Call tip tab size in pixels. (Enables +-- `STYLE_CALLTIP`.) +-- * `caret_fore`: The foreground [color][color] of the caret. +-- * `caret_line_back`: The [color][color] of the background of the line +-- containing the caret. +-- * `caret_line_back_alpha`: The background alpha of the caret line. +-- * `caret_line_visible`: Flag indicating whether or not the background of the +-- line containing the caret is a different color. +-- * `caret_period`: The time in milliseconds that the caret is on and off. 0 is +-- a steady on. +-- * `caret_sticky`: Flag indicating whether or not the caret preferred x -- position can only be changed by explicit movement commands. --- @field caret_style The style of the caret to be drawn. 0: invisible, 1: line, --- 2: block. --- @field caret_width The width of the insert mode caret in pixels. --- @field char_at The character byte at given index position. (Read-only) --- @field code_page The code page used to interpret the bytes of the document as +-- * `caret_style`: The style of the caret to be drawn.
+-- * 0: invisible +-- * 1: line +-- * 2: block +-- * `caret_width`: The width of the insert mode caret in pixels. +-- * `char_at`: The character byte at given index position. (Read-only) +-- * `code_page`: The code page used to interpret the bytes of the document as -- characters. --- @field column The column number of an index position, taking tab width into +-- * `column`: The column number of an index position, taking tab width into -- account. --- @field control_char_symbol The character used to display control characters. +-- * `control_char_symbol`: The character used to display control characters. -- (< 32 uses that control character) --- @field current_pos The position of the caret. --- @field cursor The cursor type. -1: normal, 4: wait. --- @field direct_function buffer:The pointer to a function buffer:that processes messages for +-- * `current_pos`: The position of the caret. +-- * `cursor`: The cursor type.
+-- * -1: normal +-- * 4: wait. +-- * `direct_function`: The pointer to a function that processes messages for -- this Scintilla. (Read-only) --- @field direct_pointer The pointer value to use as the first function buffer:argument --- when calling the function buffer:returned by direct_function. --- @field eol_mode The end of line mode. 0: CRLF, 1: CR, 2: LF. --- @field edge_colour The color used in edge indication. --- @field edge_column The column number which text should be kept within. --- @field edge_mode The edge highlight mode. 0: none, 1: line, 2: background. --- @field end_at_last_line Flag indicating whether or not the maximum scroll +-- * `direct_pointer`: The pointer value to use as the first function argument +-- when calling the function returned by direct_function. +-- * `eol_mode`: The end of line mode.
+-- * 0: `CRLF` +-- * 1: `CR` +-- * 2: `LF` +-- * `edge_colour`: The [color][color] used in edge indication. +-- * `edge_column`: The column number which text should be kept within. +-- * `edge_mode`: The edge highlight mode.
+-- * 0: None +-- * 1: Line +-- * 2: Background +-- * `end_at_last_line`: Flag indicating whether or not the maximum scroll -- position has the last line at the bottom of the view. Default is true. --- @field end_styled The position of the last correctly styled character. +-- * `end_styled`: The position of the last correctly styled character. -- (Read-only) --- @field first_visible_line The display line at the top of the display. +-- * `first_visible_line`: The display line at the top of the display. -- (Read-only) --- @field focus The internal focus flag. --- @field fold_expanded Flag indicating whether or not an indexed (header) line +-- * `focus`: The internal focus flag. +-- * `fold_expanded`: Flag indicating whether or not an indexed (header) line -- has been expanded. --- @field fold_level The fold level of an indexed line. 0x400: base, 0x1000: --- white, 0x2000: header, 0x4000: box header, 0x8000: box footer, 0x10000: --- contracted, 0x20000: unindent, 0x0FFF: number mask. --- @field fold_parent The parent line of indexed (child) line. (Read-only) --- @field h_scroll_bar Flag indicating whether or not the horizontal scroll bar --- is visible. --- @field highlight_guide The highlighted indentation guide column. --- @field hotspot_active_underline Flag indicating whether or not active --- hotspots are underlined. --- @field hotspot_single_line Flag indicating whether or not hotspots are --- limited to a single line so hotspots on two lines don't merge. --- @field indent The indentation size. --- @field indentation_guides Flag indicating whether or not indentation --- guides are visible. --- @field indic_fore The foreground color of an indexed indicator. --- @field indic_style The style of an indexed indicator. 0: plain, 1: squiggle --- 2: TT, 3: diagonal, 4: strike, 5: hidden, 6: box, 7: roundbox. --- @field indic_under Flag indicating whether or not an indexed indicator is --- drawn over text. Default is true. --- @field indicator_current The indicator used for indicator_fill_range and --- indicator_clear_range. --- @field indicator_value The value used for indicator_fill_range. --- @field key_words Unused. --- @field layout_cache The degree of caching of layout information. --- @field length The number of characters in the document. (Read-only). --- @field lexer The lexxing language of the document. --- @field line_count The number of lines in the document (>= 1). (Read-only). --- @field line_end_position The position after the last visible character on --- an index line. (Read-only) --- @field line_indent_position The position before the first non-indentation +-- * `fold_level`: The fold level of an indexed line.
+-- * 0x400: Base +-- * 0x1000: White +-- * 0x2000: Header +-- * 0x0FFF: Number mask +-- * `fold_parent`: The parent line of indexed (child) line. (Read-only) +-- * `h_scroll_bar`: Flag indicating whether or not the horizontal scroll bar is +-- visible. +-- * `highlight_guide`: The highlighted indentation guide column. +-- * `hotspot_active_underline`: Flag indicating whether or not active hotspots +-- are underlined. +-- * `hotspot_single_line`: Flag indicating whether or not hotspots are limited +-- to a single line so hotspots on two lines do not merge. +-- * `indent`: The indentation size. +-- * `indentation_guides`: Flag indicating whether or not indentation guides are +-- visible. +-- * `indic_fore`: The foreground [color][color] of an indexed indicator. +-- * `indic_style`: The style of an indexed indicator.
+-- * 0: Plain +-- * 1: Squiggle +-- * 2: TT +-- * 3: Diagonal +-- * 4: Strike +-- * 5: Hidden +-- * 6: Box +-- * 7: Roundbox. +-- * `indic_under`: Flag indicating whether or not an indexed indicator is drawn +-- over text. Default is `true`. +-- * `indicator_current`: The indicator used for `indicator_fill_range` and +-- `indicator_clear_range`. +-- * `indicator_value`: The value used for `indicator_fill_range`. +-- * `key_words`: Unused. +-- * `layout_cache`: The degree of caching of layout information. +-- * `length`: The number of characters in the document. (Read-only). +-- * `lexer`: The (integer) lexing language of the document. +-- * `line_count`: The number of lines in the document (>= 1). (Read-only). +-- * `line_end_position`: The position after the last visible character on an +-- index line. (Read-only) +-- * `line_indent_position`: The position before the first non-indentation -- character on an indexed line. (Read-only) --- @field line_indentation The number of columns an indexed line is indented. --- @field line_state Extra styling information of an indexed line. --- @field line_visible Flag indicating whether or not the indexed line is --- visible. (Read-only) --- @field lines_on_screen The number of lines completely visible. (Read-only) --- @field margin_left The size in pixels of the left margin. --- @field margin_mask_n The marker mask of an indexed margin. --- @field margin_right The size in pixels of the right margin. --- @field margin_sensitive_n Flag indicating whether or not the indexed margin --- is sensitive to mouse clicks. --- @field margin_type_n The type of an indexed margin. 0: symbolic, 1: numeric. --- @field margin_width_n The width of an indexed margin in pixels. --- @field max_line_state The last line number that has a line state. --- (Read-only). --- @field mod_event_mask Mask of modification events sent to the container. --- @field modify Flag indicating whether or not the document is different from +-- * `line_indentation`: The number of columns an indexed line is indented. +-- * `line_state`: Extra styling information of an indexed line. +-- * `line_visible`: Flag indicating whether or not the indexed line is visible. +-- (Read-only) +-- * `lines_on_screen`: The number of lines completely visible. (Read-only) +-- * `margin_left`: The size in pixels of the left margin. +-- * `margin_mask_n`: The marker mask of an indexed margin. +-- * `margin_right`: The size in pixels of the right margin. +-- * `margin_sensitive_n`: Flag indicating whether or not the indexed margin is +-- sensitive to mouse clicks. +-- * `margin_type_n`: The type of an indexed margin.
+-- * 0: Symbolic +-- * 1: Numeric +-- * `margin_width_n`: The width of an indexed margin in pixels. +-- * `max_line_state`: The last line number that has a line state. (Read-only). +-- * `mod_event_mask`: Mask of modification events sent to the container. +-- * `modify`: Flag indicating whether or not the document is different from -- when it was last saved. --- @field mouse_down_captures Flag indicating whether or not the mouse is +-- * `mouse_down_captures`: Flag indicating whether or not the mouse is -- captured when its button is pressed. --- @field mouse_dwell_time The time in milliseconds the mouse must sit still to +-- * `mouse_dwell_time`: The time in milliseconds the mouse must sit still to -- generate a mouse dwell event. --- @field overtype Flag indicating whether or not overtype mode is active. --- @field paste_convert_endings Flag indicating whether or not line endings are +-- * `overtype`: Flag indicating whether or not overtype mode is active. +-- * `paste_convert_endings`: Flag indicating whether or not line endings are -- converted when pasting text. --- @field position_cache The number of entries in the position cache. --- @field print_colour_mode The print color mode. 0: normal, 1: invert the light --- value of each style, 2: force black on white, 3: force background to be --- white, 4: only default background is forced to be white. --- @field print_magnification The print magnification added to the point size. --- @field print_wrap_mode Wrap mode. 0: none, 1: word. --- @field property The (string) value for a given (string) key index. --- @field property_int The (integer) value for a given (string) key index. +-- * `position_cache`: The number of entries in the position cache. +-- * `print_colour_mode`: The print color mode.
+-- * 0: Normal +-- * 1: Invert the light value of each style +-- * 2: Force black on white +-- * 3: Force background to be white +-- * 4: Only default background is forced to be white +-- * `print_magnification`: The print magnification added to the point size. +-- * `print_wrap_mode`: Wrap mode.
+-- * 0: None +-- * 1: Word +-- * `property`: The (string) value for a given (string) key index. +-- * `property_int`: The (integer) value for a given (string) key index. -- (Read-only) --- @field read_only Flag indicating whether or not the document is read-only. --- @field scroll_width The document width assumed for scrolling. --- @field scroll_width_tracking Flag indicating whether or not the maximum width +-- * `read_only`: Flag indicating whether or not the document is read-only. +-- * `scroll_width`: The document width assumed for scrolling. +-- * `scroll_width_tracking`: Flag indicating whether or not the maximum width -- line displayed is used to set the scroll width. --- @field search_flags The search flags used by search_in_target. --- @field sel_alpha The alpha of the selection. --- @field sel_eol_filled Flag indicating whether or not the selection end of --- line is filled. --- @field selection_end The position that ends the selection. (current_pos) --- @field selection_is_rectangle Flag indicating whether or not the selection is +-- * `search_flags`: The search flags used by `search_in_target`. +-- * `sel_alpha`: The alpha of the selection. +-- * `sel_eol_filled`: Flag indicating whether or not the selection end of line +-- is filled. +-- * `selection_end`: The position that ends the selection. (current_pos) +-- * `selection_is_rectangle`: Flag indicating whether or not the selection is -- rectangular. (Read-only) --- @field selection_mode The mode of the current selection. 0: stream, 1: --- rectangle, 2: lines. --- @field selection_start The position that starts the selection. (anchor) --- @field status error status. 0: OK. --- @field style_at The style byte at the index position. (Read-only) --- @field style_back The background color of an indexed style. --- @field style_bits The number of bits in style bytes. --- @field style_bits_needed The number of bits the current lexer needs for +-- * `selection_mode`: The mode of the current selection.
+-- * 0: Stream +-- * 1: Rectangle +-- * 2: Lines +-- * `selection_start`: The position that starts the selection. (anchor) +-- * `status`: error status. 0: OK. +-- * `style_at`: The style byte at the index position. (Read-only) +-- * `style_back`: The background [color][color] of an indexed style. +-- * `style_bits`: The number of bits in style bytes. +-- * `style_bits_needed`: The number of bits the current lexer needs for -- styling. (Read-only) --- @field style_bold Flag indicating whether or not the indexed style is bold. --- @field style_case The case of an indexed style. 0: mixed, 1: upper, 2: lower. --- @field style_changeable Flag indicating whether or not the indexed style is +-- * `style_bold`: Flag indicating whether or not the indexed style is bold. +-- * `style_case`: The case of an indexed style.
+-- * 0: Mixed +-- * 1: Upper +-- * 2: Lower +-- * `style_changeable`: Flag indicating whether or not the indexed style is -- changeable. --- @field style_character_set The character set of the font in the indexed --- style. --- @field style_eol_filled Flag indicating whether or not the indexed style's --- end of line is filled. --- @field style_font The font of the indexed style. --- @field style_fore The foreground color of the indexed style. --- @field style_hot_spot Flag indicating whether or not the indexed style is a +-- * `style_character_set`: The character set of the font in the indexed style. +-- * `style_eol_filled`: Flag indicating whether or not the indexed style's end +-- of line is filled. +-- * `style_font`: The font of the indexed style. +-- * `style_fore`: The foreground [color][color] of the indexed style. +-- * `style_hot_spot`: Flag indicating whether or not the indexed style is a -- hotspot. --- @field style_italic Flag indicating whether or not the indexed style is --- italic. --- @field style_size The font size of the indexed style. --- @field style_underline Flag indicating whether or not the indexed style is +-- * `style_italic`: Flag indicating whether or not the indexed style is italic. +-- * `style_size`: The font size of the indexed style. +-- * `style_underline`: Flag indicating whether or not the indexed style is -- underlined. --- @field style_visible Flag indicating whether or not the indexed style is +-- * `style_visible`: Flag indicating whether or not the indexed style is -- visible. --- @field tab_indents Flag indicating whether or not a tab press when the caret +-- * `tab_indents`: Flag indicating whether or not a tab press when the caret -- is within indentation indents. --- @field tab_width The visible size of a tab in multiples of the width of a --- space character. --- @field target_end The position that ends the target which is used for +-- * `tab_width`: The visible size of a tab in multiples of the width of a space +-- character. +-- * `target_end`: The position that ends the target which is used for updating +-- the document without affecting the scroll position. +-- * `target_start`: The position that starts the target which is used for -- updating the document without affecting the scroll position. --- @field target_start The position that starts the target which is used for --- updating the document without affecting the scroll position. --- @field text_length The number of characters in the document. (Read-only) --- @field two_phase_draw Flag indicating whether or not drawing is performed in +-- * `text_length`: The number of characters in the document. (Read-only) +-- * `two_phase_draw`: Flag indicating whether or not drawing is performed in -- two phases: background and then foreground. --- @field undo_collection Flag indicating whether or not an undo history is --- being collected. --- @field use_palette Flag indicating whether or not Scintilla uses the env's +-- * `undo_collection`: Flag indicating whether or not an undo history is being +-- collected. +-- * `use_palette`: Flag indicating whether or not Scintilla uses the env's -- palette calls to display more colors. --- @field use_tabs Flag indicating whether or not indentation uses tabs and --- spaces or just spaces. --- @field v_scroll_bar Flag indicating whether or not the vertical scroll bar is --- visible. --- @field view_eol Flag indicating whether or not end of line characters are +-- * `use_tabs`: Flag indicating whether or not indentation uses tabs and spaces +-- or just spaces. +-- * `v_scroll_bar`: Flag indicating whether or not the vertical scroll bar is -- visible. --- @field view_ws Flag indicating whether or not whitespace characters are +-- * `view_eol`: Flag indicating whether or not end of line characters are -- visible. --- @field whitespace_chars The set of characters making up whitespace when --- moving or selecting by word. Should be called after setting word_chars. +-- * `view_ws`: Flag indicating whether or not whitespace characters are visible. +-- * `whitespace_chars`: The set of characters making up whitespace when moving +-- or selecting by word. Should be called after setting word_chars. -- (Write-only) --- @field word_chars The set of characters making up words when moving or +-- * `word_chars`: The set of characters making up words when moving or -- selecting by word. (Write-only) --- @field wrap_mode Flag indicating whether or not text is word wrapped. --- @field wrap_start_indent The start indent for wrapped lines. --- @field wrap_visual_flags The display mode of visual flags for wrapped lines. --- 0: none, 1: end, 2: start. --- @field wrap_visual_flags_location The location of visual flags for wrapped --- lines. 0: default, 1: end by text, 2: start by text. --- @field x_offset The horizontal scroll position. --- @field zoom The zoom level added to all font sizes. +: magnify, -: reduce. -buffer = { - doc_pointer = nil, dirty = nil, filename = nil, - encoding = nil, encoding_bom = nil, - anchor = nil, - auto_c_auto_hide = nil, - auto_c_cancel_at_start = nil, - auto_c_choose_single = nil, - auto_c_drop_rest_of_word = nil, - auto_c_fill_ups = nil, - auto_c_ignore_case = nil, - auto_c_max_height = nil, - auto_c_max_width = nil, - auto_c_separator = nil, - auto_c_type_separator = nil, - back_space_un_indents = nil, - buffered_draw = nil, - call_tip_back = nil, - call_tip_fore = nil, - call_tip_fore_hlt = nil, - call_tip_use_style = nil, - caret_fore = nil, - caret_line_back = nil, - caret_line_back_alpha = nil, - caret_line_visible = nil, - caret_period = nil, - caret_sticky = nil, - caret_style = nil, - caret_width = nil, - char_at = nil, - code_page = nil, - column = nil, - control_char_symbol = nil, - current_pos = nil, - cursor = nil, - direct_function buffer:= nil, - direct_pointer = nil, - doc_pointer = nil, - eol_mode = nil, - edge_colour = nil, - edge_column = nil, - edge_mode = nil, - end_at_last_line = nil, - end_styled = nil, - first_visible_line = nil, - focus = nil, - fold_expanded = nil, - fold_level = nil, - fold_parent = nil, - h_scroll_bar = nil, - highlight_guide = nil, - hotspot_active_underline = nil, - hotspot_single_line = nil, - indent = nil, - indentation_guides = nil, - indic_fore = nil, - indic_style = nil, - indic_under = nil, - indicator_current = nil, - indicator_value = nil, - key_words = nil, - layout_cache = nil, - length = nil, - lexer = nil, - line_count = nil, - line_end_position = nil, - line_indent_position = nil, - line_indentation = nil, - line_state = nil, - line_visible = nil, - lines_on_screen = nil, - margin_left = nil, - margin_mask_n = nil, - margin_right = nil, - margin_sensitive_n = nil, - margin_type_n = nil, - margin_width_n = nil, - max_line_state = nil, - mod_event_mask = nil, - modify = nil, - mouse_down_captures = nil, - mouse_dwell_time = nil, - overtype = nil, - paste_convert_endings = nil, - position_cache = nil, - print_colour_mode = nil, - print_magnification = nil, - print_wrap_mode = nil, - property = nil, - property_int = nil, - read_only = nil, - scroll_width = nil, - scroll_width_tracking = nil, - search_flags = nil, - sel_alpha = nil, - sel_eol_filled = nil, - selection_end = nil, - selection_is_rectangle = nil, - selection_mode = nil, - selection_start = nil, - status = nil, - style_at = nil, - style_back = nil, - style_bits = nil, - style_bits_needed = nil, - style_bold = nil, - style_case = nil, - style_changeable = nil, - style_character_set = nil, - style_eol_filled = nil, - style_font = nil, - style_fore = nil, - style_hot_spot = nil, - style_italic = nil, - style_size = nil, - style_underline = nil, - style_visible = nil, - tab_indents = nil, - tab_width = nil, - target_end = nil, - target_start = nil, - text_length = nil, - two_phase_draw = nil, - undo_collection = nil, - use_palette = nil, - use_tabs = nil, - v_scroll_bar = nil, - view_eol = nil, - view_ws = nil, - whitespace_chars = nil, - word_chars = nil, - wrap_mode = nil, - wrap_start_indent = nil, - wrap_visual_flags = nil, - wrap_visual_flags_location = nil, - x_offset = nil, - zoom = nil, -} +-- * `wrap_mode`: Flag indicating whether or not text is word wrapped. +-- * `wrap_start_indent`: The start indent for wrapped lines. +-- * `wrap_visual_flags`: The display mode of visual flags for wrapped lines. +--
+-- * 0: None +-- * 1: End +-- * 2: Start +-- * `wrap_visual_flags_location`: The location of visual flags for wrapped +-- lines.
+-- * 0: Default +-- * 1: End by text +-- * 2: Start by text +-- * `x_offset`: The horizontal scroll position. +-- * `zoom`: The zoom level added to all font sizes. +: magnify, -: reduce. +-- +-- [textadept_iconv]: ../modules/textadept.html#iconv +-- [color]: http://scintilla.org/ScintillaDoc.html#colour --- -- Gets a range of text from the current buffer. @@ -463,7 +361,7 @@ function buffer:clear_all_cmd_keys() function buffer:clear_document_style() --- Clears all the registered XPM images. function buffer:clear_registered_images() ---- Colorizes a segment of the document using the current lexxing language. +--- Colorizes a segment of the document using the current lexing language. function buffer:colourise(start_pos, end_pos) --- Converts all line endings in the document to one mode. -- @param mode The line ending mode. 0: CRLF, 1: CR, 2: LF. @@ -529,7 +427,7 @@ function buffer:get_hotspot_active_back() function buffer:get_hotspot_active_fore() --- Returns the last child line of a header line. function buffer:get_last_child(header_line, level) ---- Returns the name of the lexxing language used by the document. +--- Returns the name of the lexing language used by the document. function buffer:get_lexer_language() --- Returns the contents of a line. function buffer:get_line(line) @@ -918,3 +816,19 @@ function buffer:wrap_count(line) function buffer:zoom_in() --- Makes the displayed text smaller by decreasing the font sizes by 1 point. function buffer:zoom_out() + +--- +-- @see textadept.io.reload +function buffer:reload() +--- +-- @see textadept.io.set_encoding +function buffer:set_encoding() +--- +-- @see textadept.io.save +function buffer:save() +--- +-- @see textadept.io.save_as +function buffer:save_as() +--- +-- @see textadept.io.close +function buffer:close() diff --git a/core/.command_entry.lua b/core/.command_entry.lua index c1a06f45..09622b8d 100644 --- a/core/.command_entry.lua +++ b/core/.command_entry.lua @@ -3,16 +3,38 @@ -- global textadept.command_entry table. --- --- Textadept's Lua command entry. --- [Dummy file] +-- Textadept's Command entry. module('textadept.command_entry') ---- --- Textadept's Lua command entry table. --- @class table --- @name textadept.command_entry --- @field entry_text The text in the entry. -command_entry = { entry_text = nil } +-- Markdown: +-- ## Fields +-- +-- * `entry_text`: The text in the entry. +-- +-- ## Overview +-- +-- Access to the Lua state is available through this command entry. It is useful +-- for debugging, inspecting, and entering buffer or view commands. If you try +-- cause instability in Textadept's Lua state, you might very well succeed. Be +-- careful. +-- +-- Tab-completion for functions, variables, tables, etc. is available. Press the +-- `Tab` key to display a list of available completions. Use the arrow keys to +-- make a selection and press `Enter` to insert it. +-- +-- Note: Use [`textadept.print()`][textadept_print] instead of the global +-- `print()` function. The former prints to a new buffer, the latter to standard +-- out (`STDOUT`). +-- +-- [textadept_print]: ../modules/textadept.html#print +-- +-- ## Extending +-- +-- You can extend the command entry to do more than enter Lua commands. An +-- example of this is [incremental search][inc_search]. See `core/ext/find.lua` +-- for the implementation. +-- +-- [inc_search]: ../modules/textadept.find.html#incremental --- Focuses the command entry. function focus() end diff --git a/core/.find.lua b/core/.find.lua index a773f603..cf64a1e5 100644 --- a/core/.find.lua +++ b/core/.find.lua @@ -4,14 +4,30 @@ --- -- Textadept's integrated find/replace dialog. --- [Dummy file] module('textadept.find') --- Usage: +-- Markdown: +-- ## Fields +-- +-- * `find_entry_text`: The text in the find entry. +-- * `replace_entry_text`: The text in the replace entry. +-- * `match_case`: Flag indicating whether or not case-sensitive search is +-- performed. +-- * `whole_word`: Flag indicating whether or not only whole-word matches are +-- allowed in searches. +-- * `lua`: Flag indicating whether or not the text to find in a search is a Lua +-- pattern. +-- * `in_files`: Flag indicating whether or not to search for the text in a list +-- of files. +-- +-- ## Overview +-- -- In addition to offering standard find and replace, Textadept allows you to --- find with Lua patterns and replace with Lua captures and even Lua code! Lua --- captures (%n) are available for a Lua pattern search and embedded Lua code --- enclosed in %() is always available. +-- find with [Lua patterns][lua_patterns] and replace with Lua captures and even +-- Lua code! Lua captures (`%n`) are only available from a Lua pattern search, +-- but embedded Lua code enclosed in `%()` is always available. +-- +-- [lua_patterns]: http://www.lua.org/manual/5.1/manual.html#5.4.1 -- -- If any block of text is selected for 'Replace All', only matches found in -- that block are replaced. @@ -22,32 +38,15 @@ module('textadept.find') -- Files first, and then 'Replace All' for each file a result is found in. -- The 'Match Case', 'Whole Word', and 'Lua pattern' flags still apply. -- --- Customizing look and feel: --- Like the project manager, there are no function calls to make that --- customize the look and feel of the find dialog. Instead you can manipulate --- it via GTK rc files. The find and replace entries widget names of --- 'textadept-find-entry' and 'textadept-replace-entry' respectively. --- Resource file documentation can be found at --- http://library.gnome.org/devel/gtk/unstable/gtk-Resource-Files.html. - ---- --- Textadept's find table. --- @class table --- @name find --- @field find_entry_text The text in the find entry. --- @field replace_entry_text The text in the replace entry. --- @field match_case Flag indicating whether or not case-sensitive search is --- performed. --- @field whole_word Flag indicating whether or not only whole-word matches are --- allowed in searches. --- @field lua Flag indicating whether or not the text to find in a search is a --- Lua pattern. --- @field in_files Flag indicating whether or not to search for the text in a --- list of files. -find = { - find_entry_text = nil, replace_entry_text = nil, - match_case = nil, whole_word = nil, lua = nil, in_files = nil -} +-- Incremental search uses the Command Entry. +-- +-- ## Customizing Look and Feel +-- +-- There is no way to theme the dialog from within Textadept. Instead you can +-- use [GTK Resource files][gtkrc]. The find and replace entries have widget +-- names of `textadept-find-entry` and `textadept-replace-entry` respectively. +-- +-- [gtkrc]: http://library.gnome.org/devel/gtk/unstable/gtk-Resource-Files.html. --- Displays and focuses the find/replace dialog. function focus() end diff --git a/core/.pm.lua b/core/.pm.lua index 5371d286..ee9bde66 100644 --- a/core/.pm.lua +++ b/core/.pm.lua @@ -4,26 +4,40 @@ --- -- Textadept's project manager. --- [Dummy file] module('textadept.pm') --- Usage: --- Interactive search: --- Typing text into the project manager view begins the interactive search. --- If the text matches ANY part of an item in the view (case sensitively), the --- item is highlighted and subsequent matches can be navigated to using the --- up/down arrow keys. +-- Markdown: +-- ## Fields -- --- Customizing look and feel: --- There are no function calls to make that customize the look and feel of the --- project manager. Instead you can manipulate it via GTK rc files. The pm --- entry and view have widget names of 'textadept-pm-entry' and --- 'textadept-pm-view' respectively. Resource file documentation can be found --- at http://library.gnome.org/devel/gtk/unstable/gtk-Resource-Files.html. --- My rc file is something like this: +-- * `entry_text`: The text in the entry. +-- * `width`: The width of the project manager. +-- * `cursor`: The cursor in the project manager (string representation of +-- current `GtkTreePath`). -- --- pixmap_path "/usr/share/icons/Tango/:/home/mitchell/.icons/prog/" +-- ## Overview +-- +-- The PM uses different [browsers][browsers] to display heirarchical data. +-- +-- [browsers]: ../modules/textadept.pm.browser.html +-- +-- ## Interactive Search +-- +-- Typing text into the project manager view begins the interactive search. +-- If the text matches ANY part of an item in the view (case sensitively), the +-- item is highlighted and subsequent matches can be navigated to using the +-- up/down arrow keys. +-- +-- ## Customizing Look and Feel +-- +-- There is no way to theme the dialog from within Textadept. Instead you can +-- use [GTK Resource files][gtkrc]. The pm entry and view have widget names of +-- `textadept-pm-entry` and `textadept-pm-view` respectively. -- +-- [gtkrc]: http://library.gnome.org/devel/gtk/unstable/gtk-Resource-Files.html. +-- +-- My RC file looks something like this: +-- +-- pixmap_path "/usr/share/icons/Tango/:/home/mitchell/.icons/prog/" -- style "textadept-pm-display-style" { -- fg[NORMAL] = "#AAAAAA" # treeview arrows foreground -- fg[PRELIGHT] = "#AAAAAA" # treeview arrows hover foreground @@ -34,7 +48,6 @@ module('textadept.pm') -- text[NORMAL] = "#AAAAAA" # entry, treeview text foreground -- text[ACTIVE] = "#AAAAAA" # treeview unfocused selection text -- text[SELECTED] = "#DDDDDD" # entry, treeview selection text foreground --- -- stock["gtk-directory"] = {{ "16x16/places/stock_folder.png", LTR }} -- stock["gtk-folder-new"] = {{ "16x16/actions/folder_new.png", LTR }} -- stock["prog-class"] = {{ "class.png", LTR }} @@ -47,20 +60,9 @@ module('textadept.pm') -- stock["prog-reference"] = {{ "reference.png", LTR }} -- stock["prog-struct"] = {{ "struct.png", LTR }} -- } --- -- widget "*textadept-pm-entry" style "textadept-pm-display-style" -- widget "*textadept-pm-view" style "textadept-pm-display-style" ---- --- Textadept's project manager table. --- @class table --- @name textadept.pm --- @field entry_text The text in the entry. --- @field width The width of the project manager. --- @field cursor The cursor in the project manager (string representation of --- current GtkTreePath). -pm = { entry_text = nil, width = nil, cursor = nil } - --- Requests the project manager to get its contents based on its entry text. function activate() end diff --git a/core/.textadept.lua b/core/.textadept.lua index d0247f60..c1c40699 100644 --- a/core/.textadept.lua +++ b/core/.textadept.lua @@ -4,27 +4,23 @@ --- -- The core textadept table. --- [Dummy file] module('textadept') ---- --- The core textadept table. --- @class table --- @name textadept --- @field title The title of the Textadept window. --- @field focused_doc_pointer The pointer to the document associated with the --- buffer of the currently focused view. (Used internally; read-only) --- @field menubar A table of GTK menus defining a menubar (write-only). --- @field context_menu A GTK menu defining the editor's context menu. --- @field clipboard_text The text on the clipboard (read-only). --- @field statusbar_text The text displayed by the statusbar (write-only). --- @field docstatusbar_text The text displayed by the doc statusbar --- (write-only). --- @field size The size of the Textadept window ({ width, height}). -textadept = { - title = nil, focused_doc_pointer = nil, clipboard_text = nil, menubar = nil, - context_menu = nil, statusbar_text = nil, docstatusbar_text = nil, size = nil -} +-- Markdown: +-- ## Fields +-- +-- * `title`: The title of the Textadept window. +-- * `focused_doc_pointer`: The pointer to the document associated with the +-- buffer of the currently focused view. (Used internally; read-only.) +-- * `menubar`: A table of GTK menus defining a menubar (write-only). +-- * `context_menu`: A GTK menu defining the editor's context menu. +-- * `clipboard_text`: The text on the clipboard (read-only). +-- * `statusbar_text`: The text displayed by the statusbar (write-only). +-- * `docstatusbar_text`: The text displayed by the doc statusbar (write-only). +-- * `size`: The size of the Textadept window (`{ width, height}`). +-- * `constants`: Table containing Scintilla constants. +-- * `buffer_functions`: Table containing Scintilla functions. +-- * `buffer_properties`: Table containing Scintilla set/get functions. --- -- A numerically indexed table of open buffers in Textadept. diff --git a/core/.view.lua b/core/.view.lua index 6cdb4336..ea576265 100644 --- a/core/.view.lua +++ b/core/.view.lua @@ -5,19 +5,15 @@ --- -- The currently focused view. -- It also represents the structure of any view table in 'views'. --- [Dummy file] module('view') ---- --- The currently focused view. --- It also represents the structure of any view table in 'views'. --- @class table --- @name view --- @field doc_pointer The pointer to the document associated with this view's +-- Markdown: +-- ## Fields +-- +-- * `doc_pointer`: The pointer to the document associated with this view's -- buffer. (Used internally; read-only) --- @field size The integer position of the split resizer (if this view is part --- of a split view). -view = { doc_pointer = nil, size = nil } +-- * `size`: The integer position of the split resizer (if this view is part of +-- a split view). --- -- Splits the indexed view vertically or horizontally and focuses the new view. diff --git a/core/events.lua b/core/events.lua index 61ebd3ea..2b3db461 100644 --- a/core/events.lua +++ b/core/events.lua @@ -4,109 +4,173 @@ local textadept = _G.textadept local locale = _G.locale --- --- Module that handles Scintilla and Textadept notifications/events. --- Most of Textadept's functionality comes through handlers. Scintilla --- notifications, Textadept's own events, and user-defined events can all be --- handled. +-- Textadept's core event structure and handlers. module('textadept.events', package.seeall) --- Usage: --- Each event can have multiple handlers, which are simply Lua functions that --- are called in the sequence they are added as handler functions. Sometimes it --- is useful to have a handler run under a specific condition(s). If this is the --- case, place a conditional in the function that returns if it isn't met. +-- Markdown: +-- ## Overview -- --- If a handler returns either true or false explicitly, all subsequent handlers --- are not called. This is useful for something like a 'keypress' event where if --- the key is handled, true should be returned so as to not propagate the event. +-- Textadept is very event-driven. Most of its functionality comes through event +-- handlers. Events occur when you create a new buffer, press a key, click on a +-- menu, etc. You can even make an event occur with Lua code. Instead of having +-- a single event handler however, each event can have a set of handlers. These +-- handlers are simply Lua functions that are called in the order they were +-- added to an event. This enables dynamically loaded modules to add their own +-- handlers to events. -- --- Events need not be declared. A handler can simply be added for an event name, --- and 'handle'd when necessary. As an example, you can create a handler for a --- custom 'my_event' and call "textadept.events.handle('my_event')" to envoke --- it. +-- Events themselves are nothing special. They do not have to be declared in +-- order to be used. They are simply strings containing an arbitrary event name. +-- When an event of this name occurs, either generated by Textadept or you, all +-- event handlers assigned to it are run. -- --- For reference, events will be shown in 'event(arguments)' format, but in --- reality, the event is handled as 'handle(event, arguments)'. +-- Events can be given any number of arguments. These arguments will be passed +-- to the event's handler functions. If a handler returns either true or false +-- explicitly, all subsequent handlers are not called. This is useful if you +-- want to stop the propagation of an event like a keypress. -- --- Scintilla notifications: --- char_added(ch) --- ch: the (integer) character added. --- save_point_reached() --- save_point_left() --- double_click(position, line) --- position: the position of the beginning of the line clicked. --- line: the line clicked. --- update_ui() --- margin_click(margin, modifiers, position) --- margin: the margin number. --- modifiers: mouse modifiers. --- position: the position of the beginning of the line at the point clicked. --- user_list_selection(wParam, text) --- wParam: the user list ID. --- text: the text of the selected item. --- uri_dropped(text) --- text: the URI dropped. --- call_tip_click(position) --- position: 1 or 2 if the up or down arrow was clicked; 0 otherwise. --- auto_c_selection(lParam, text) --- lParam: the start position of the word being completed. --- text: the text of the selected item. +-- ## Textadept Events -- --- Textadept events: --- buffer_new() --- buffer_deleted() --- buffer_before_switch() --- buffer_after_switch() --- view_new() --- view_before_switch() --- view_after_switch() --- quit() --- Note: when adding a quit handler, it must be inserted at index 1 because --- the default quit handler returns true, which ignores all subsequent --- handlers. --- keypress(code, shift, control, alt) --- code: the key code. --- shift: flag indicating whether or not shift is pressed. --- control: flag indicating whether or not control is pressed. --- alt: flag indicating whether or not alt is pressed. --- menu_clicked(menu_id) --- menu_id: the numeric ID of the menu item. --- pm_contents_request(full_path, expanding) --- full_path: a numerically indexed table of treeview item parents. The --- first index contains the text of pm_entry. Subsequent indexes contain --- the ID's of parents of the child requested for expanding (if any). --- expanding: indicates if the contents of a parent are being requested. --- pm_item_selected(selected_item, gdkevent) --- selected_item: identical to 'full_path' for 'pm_contents_request' event. --- gdkevent: the GDK event associated with the request. It must be passed to --- pm.show_context_menu() --- pm_context_menu_request(selected_item) --- selected_item: identical to 'full_path' for 'pm_contents_request' event. --- pm_menu_clicked(menu_id, selected_item) --- menu_id: the numeric ID for the menu item. --- selected_item: identical to 'full_path' for 'pm_contents_request' event. --- pm_view_filled() --- find(text, next) --- text: the text to find. --- next: flag indicating whether or not the search direction is forward. --- replace(text) --- text: the text to replace the current selection with. It can contain both --- Lua capture items (%n where 1 <= n <= 9) for Lua pattern searches and %() --- sequences for embedding Lua code for any search. --- replace_all(find_text, repl_text) --- find_text: the text to find. --- repl_text: the text to replace found text with. --- find_keypress(code) --- code: the key code. --- command_entry_completions_request() --- command_entry_keypress(code) --- code: the key code. +-- The following is a list of all Scintilla events generated by Textadept in +-- `event_name(arguments)` format: +-- +-- * **char\_added** (ch)
+-- Called when an ordinary text character is added to the buffer. +-- - ch: the ASCII representation of the character. +-- * **save\_point\_reached** ()
+-- Called when a save point is entered. +-- * **save\_point\_left** ()
+-- Called when a save point is left. +-- * **double\_click** (position, line)
+-- Called when the mouse button is double-clicked. +-- - position: the text position the click occured at. +-- - line: the line number the click occured at. +-- * **update\_ui** ()
+-- Called when the text or styling of the buffer has changed or the selection +-- range has changed. +-- * **margin\_click** (margin, modifiers, position)
+-- Called when the mouse is clicked inside a margin. +-- - margin: the margin number that was clicked. +-- - modifiers: the appropriate combination of `SCI_SHIFT`, `SCI_CTRL`, +-- and `SCI_ALT` to indicate the keys that were held down at the time of +-- the margin click. +-- - position: The position of the start of the line in the buffer that +-- corresponds to the margin click. +-- * **user\_list\_selection** (wParam, text)
+-- Called when the user has selected an item in a user list. +-- - wParam: the list_type parameter from +-- [`buffer:user_list_show()`][buffer_user_list_show]. +-- - text: the text of the selection. +-- * **uri\_dropped** (text)
+-- Called when the user has dragged a URI such as a file name or web address +-- into Textadept. +-- - text: URI text. +-- * **call\_tip\_click** (position)
+-- Called when the user clicks on a calltip. +-- - position: 1 if the click is in an up arrow, 2 if in a down arrow, and +-- 0 if elsewhere. +-- * **auto\_c\_selection** (lParam, text)
+-- Called when the user has selected an item in an autocompletion list. +-- - lParam: the start position of the word being completed. +-- - text: the text of the selection. +-- +-- [buffer_user_list_show]: ../modules/buffer.html#buffer:user_list_show +-- +-- The following is a list of all Textadept events generated in +-- `event_name(arguments)` format: +-- +-- * **buffer\_new** ()
+-- Called when a new [buffer][buffer] is created. +-- * **buffer\_deleted** ()
+-- Called when a [buffer][buffer] has been deleted. +-- * **buffer\_before\_switch** ()
+-- Called right before another [buffer][buffer] is switched to. +-- * **buffer\_after\_switch** ()
+-- Called right after a [buffer][buffer] was switched to. +-- * **view\_new** ()
+-- Called when a new [view][view] is created. +-- * **view\_before\_switch** ()
+-- Called right before another [view][view] is switched to. +-- * **view\_after\_switch** ()
+-- Called right after [view][view] was switched to. +-- * **quit** ()
+-- Called when quitting Textadept.
+-- Note: Any quit handlers added must be inserted at index 1 because the +-- default quit handler in `core/events.lua` returns `true`, which ignores all +-- subsequent handlers. +-- * **keypress** (code, shift, control, alt)
+-- Called when a key is pressed. +-- - code: the key code (according to ``). +-- - shift: flag indicating whether or not the Shift key is pressed. +-- - control: flag indicating whether or not the Control key is pressed. +-- - alt: flag indicating whether or not the Alt/Apple key is pressed. +--
+-- Note: The Alt-Option key in Mac OSX is not available. +-- * **menu\_clicked** (menu\_id)
+-- Called when a menu item is selected. +-- - menu\_id: the numeric ID of the menu item set in +-- [`textadept.gtkmenu()`][textadept_gtkmenu]. +-- * **pm\_contents\_request** (full\_path, expanding)
+-- Called when the [PM][PM] requests data to display. +-- - full\_path: a numerically indexed table of treeview item parents. The +-- first index contains the text of the PM entry. Subsequent indices +-- contain the ID's of parents of the child (if any). +-- - expanding: indicates if the contents of a parent are being requested. +-- * **pm\_item\_selected** (selected\_item)
+-- Called when an item in the [PM][PM] is double-clicked or activated. +-- - selected\_item: identical to `full_path` in the `pm_contents_request` +-- event. +-- * **pm\_context\_menu\_request** (selected\_item, gdkevent)
+-- Called when the context menu for an item in the [PM][PM] is requested. +-- - selected\_item: identical to `full_path` in the `pm_contents_request` +-- event. +-- - gdkevent: the GDK event associated with the request. It must be +-- passed to [`textadept.pm.show_context_menu()`][pm_show_menu]. +-- * **pm\_menu\_clicked** (menu\_id, selected\_item)
+-- Called when a [PM][PM] context menu item is selected. +-- - menu\_id: the numeric ID of the context menu item set in +-- [`textadept.gtkmenu()`][textadept_gtkmenu]. +-- - selected\_item: identical to `full_path` in the `pm_contents_request` +-- event. +-- * **pm\_view\_filled** ()
+-- Called when the [PM][PM] view is filled with data. +-- * **find** (text, next)
+-- Called when attempting to finding text via the Find dialog box. +-- - text: the text to search for. +-- - next: flat indicating whether or not the search direction is forward. +-- * **replace** (text)
+-- Called when the found text is selected and asked to be replaced. +-- - text: the text to replace the selected text with. +-- * **replace\_all** (find\_text, repl\_text)
+-- Called when all occurances of found text are to be replaced. +-- - find\_text: the text to search for. +-- - repl\_text: the text to replace found text with. +-- * **command\_entry\_keypress** (code)
+-- Called when a key is pressed in the Command Entry. +-- - code: the key code (according to ``). +-- +-- [buffer]: ../modules/buffer.html +-- [view]: ../modules/view.html +-- [textadept_gtkmenu]: ../modules/textadept.html#gtkmenu +-- [PM]: ../modules/textadept.pm.html +-- [pm_show_menu]: ../modules/textadept.pm.html#show_context_menu +-- +-- ## Example +-- +-- The following Lua code generates and handles a custom `my_event` event: +-- +-- function my_event_handler(message) +-- textadept.print(message) +-- end +-- +-- textadept.events.add_handler('my_event', my_event_handler) +-- textadept.events.handle('my_event', 'my message') local events = textadept.events --- -- Adds a handler function to an event. --- @param event The string event name. +-- @param event The string event name. It is arbitrary and need not be defined +-- anywhere. -- @param f The Lua function to add. -- @param index Optional index to insert the handler into. function add_handler(event, f, index) @@ -121,12 +185,13 @@ function add_handler(event, f, index) end --- --- Calls every handler function added to an event in sequence. --- If true or false is returned by any handler, the iteration ceases. Normally --- this function is called by the system when necessary, but it can be called --- in scripts to handle user-defined events. +-- Calls all handlers for the given event in sequence (effectively "generating" +-- the event). +-- If true or false is explicitly returned by any handler, the event is not +-- propagated any further; iteration ceases. -- @param event The string event name. --- @param ... Arguments to the handler. +-- @param ... Arguments passed to the handler. +-- @return true or false if any handler explicitly returned such; nil otherwise. function handle(event, ...) local plural = event..'s' local handlers = events[plural] @@ -155,6 +220,7 @@ local scnnotifications = { --- -- Handles Scintilla notifications. -- @param n The Scintilla notification structure as a Lua table. +-- @return true or false if any handler explicitly returned such; nil otherwise. function notification(n) local f = scnnotifications[n.code] if f then diff --git a/core/ext/key_commands.lua b/core/ext/key_commands.lua index 9a98612c..26c1d929 100644 --- a/core/ext/key_commands.lua +++ b/core/ext/key_commands.lua @@ -5,10 +5,97 @@ local locale = _G.locale --- -- Defines the key commands used by the Textadept key command manager. --- For non-ascii keys, see textadept.keys for string aliases. -- This set of key commands is pretty standard among other text editors. module('textadept.key_commands', package.seeall) +-- Markdown: +-- ## Overview +-- +-- Key commands are defined in the global table `keys`. Each key-value pair in +-- `keys` consists of either: +-- +-- * A string representing a key command and an associated action table. +-- * A string language name and its associated `keys`-like table. +-- * A string style name and its associated `keys`-like table. +-- * A string representing a key command and its associated `keys`-like table. +-- (This is a keychain sequence.) +-- +-- A key command string is built from a combination of the `CTRL`, `SHIFT`, +-- `ALT`, and `ADD` constants as well as the pressed key itself. The value of +-- `ADD` is inserted between each of `CTRL`, `SHIFT`, `ALT`, and the key. +-- For example: +-- +-- -- keys.lua: +-- CTRL = 'Ctrl' +-- SHIFT = 'Shift' +-- ALT = 'Alt' +-- ADD = '+' +-- -- pressing control, shift, alt and 'a' yields: 'Ctrl+Shift+Alt+a' +-- +-- For key values less than 255, Lua's [`string.char()`][string_char] is used to +-- determine the key's string representation. Otherwise, the `KEYSYMS` lookup +-- table in [`textadept.keys`][textadept_keys] is used. +-- +-- [string_char]: http://www.lua.org/manual/5.1/manual.html#pdf-string.char +-- [textadept_keys]: ../modules/textadept.keys.html +-- +-- An action table is a table consisting of either: +-- +-- * A Lua function followed by a list of arguments to pass to that function. +-- * A string representing a [buffer][buffer] or [view][view] function followed +-- by its respective `'buffer'` or `'view'` string and then any arguments to +-- pass to the resulting function. +-- +-- `buffer.`_`function`_ by itself cannot be used because at the time of +-- evaluation, `buffer.`_`function`_ would apply only to the current +-- buffer, not for all buffers. By using this string reference system, the +-- correct `buffer.`_`function`_ will be evaluated every time. The same +-- applies to `view`. +-- +-- [buffer]: ../modules/buffer.html +-- [view]: ../modules/view.html +-- +-- Language names are the names of the lexer files in `lexers/` such as `cpp` +-- and `lua`. Style names are different lexer styles, most of which are in +-- `lexers/lexer.lua`; examples are `whitespace`, `comment`, and `string`. +-- +-- Key commands can be chained like in Emacs using keychain sequences. By +-- default, the `Esc` key cancels the current keychain, but it can be redefined +-- by setting the `keys.clear_sequence` field. Naturally, the clear sequence +-- cannot be chained. +-- +-- ## Key Command Precedence +-- +-- When searching for a key command to execute in the `keys` table, key commands +-- in the current style have priority, followed by the ones in the current lexer, +-- and finally the ones in the global table. +-- +-- ## Example +-- +-- keys = { +-- ['ctrl+f'] = { 'char_right', 'buffer' }, +-- ['ctrl+b'] = { 'char_left', 'buffer' }, +-- lua = { +-- ['ctrl+c'] = { 'add_text', 'buffer', '-- ' }, +-- whitespace = { +-- ['ctrl+f'] = { function() print('whitespace') end } +-- } +-- } +-- } +-- +-- The first two key commands are global and call `buffer:char_right()` and +-- `buffer:char_left()` respectively. The last two commands apply only in the +-- Lua lexer with the very last one only being available in Lua's `whitespace` +-- style. If `ctrl+f` is pressed when the current style is `whitespace` in the +-- `lua` lexer, the global key command with the same shortcut is overriden and +-- `whitespace` is printed to standard out. +-- +-- ## Problems +-- +-- All Lua functions must be defined BEFORE they are reference in key commands. +-- Therefore, any module containing key commands should be loaded after all +-- other modules, whose functions are being referenced, have been loaded. + -- Windows and Linux key commands are listed in the first block. -- Mac OSX key commands are listed in the second block. @@ -16,6 +103,12 @@ local keys = _G.keys local b, v = 'buffer', 'view' local t = textadept +-- CTRL = 'c' +-- SHIFT = 's' +-- ALT = 'a' +-- ADD = '' +-- Control, Shift, Alt, and 'a' = 'csaa' + if not MAC then -- Windows and Linux key commands. @@ -410,3 +503,8 @@ else keys.cd = { 'clear', b } keys.cad = { 'del_word_right', b } end + +--- +-- This module has no functions. +function no_functions() end +no_functions = nil -- undefine diff --git a/core/ext/keys.lua b/core/ext/keys.lua index 5a27f36a..d89a08a0 100644 --- a/core/ext/keys.lua +++ b/core/ext/keys.lua @@ -7,76 +7,27 @@ local locale = _G.locale -- Manages key commands in Textadept. -- Default key commands should be defined in a separate file and loaded after -- all modules. --- There are several option variables used: --- SCOPES_ENABLED: Flag indicating whether scopes/styles can be used for key --- commands. --- CTRL: The string representing the Control key. --- SHIFT: The string representing the Shift key. --- ALT: The string representing the Alt key (the Apple key on Mac OSX). --- ADD: The string representing used to join together a sequence of Control, --- Shift, or Alt modifier keys. --- module('textadept.keys', package.seeall) --- Usage: --- Keys are defined in the global table 'keys'. Keys in that table are key --- sequences, and values are tables of Lua functions and arguments to execute. --- The exceptions are language names, style names, and keychains (discussed --- later). Language names have table values of either key commands or style keys --- with table values of key commands. See /lexers/lexer.lua for some default --- style names. Each lexer's 'add_style' function adds additional styles, the --- string argument being the style's name. For example: --- keys = { --- ['ctrl+f'] = { 'char_right', 'buffer' }, --- ['ctrl+b'] = { 'char_left', 'buffer' }, --- lua = { --- ['ctrl+c'] = { 'add_text', 'buffer', '-- ' }, --- whitespace = { function() print('whitespace') end } --- } --- } --- Style and lexer insensitive key commands should be placed in the lexer and --- keys tables respectively. --- --- When searching for a key command to execute in the keys table, key commands --- in the current style have priority, then ones in the current lexer, and --- finally the ones in the global table. --- --- As mentioned, key commands are key-value pairs, the key being the key --- sequence compiled from the CTRL, SHIFT, ALT, and ADD options (discussed --- below) as well as the key pressed and the value being a table of a function --- to call and its arguments. For the table, the first item can be either a Lua --- function or a string (representing a function name). If it is a function, all --- table items after it are used as arguments. If the first item is a string, --- the next string is checked to be either 'buffer' or 'view' and the current --- buffer or view is used as the table with the function name as a field, --- indexing a function. The current buffer or view is then used as the first --- argument to that function, with all items after the second following as --- additional ones. Basically in Lua: {buffer|view}:{first_item}(...) --- --- As noted previously, key sequences can be compiled differently via the CTRL, --- SHIFT, ALT, and ADD options. The first three indicate the text for each --- respective modifier key and ADD is the text inserted between modifiers. --- --- Key commands can be chained like in Emacs. Instead of a key sequence having --- a table of a function and its arguments, it has a table of key commands (much --- like lexer or style specific key commands). My default, the 'escape' key --- cancels the current keychain, but it can be redefined by setting the --- 'clear_sequence' key in the global keys table. It cannot be chained however. +-- Markdown: +-- ## Settings -- --- Keys that have values higher than 255 cannot be represented by a string, but --- can have a string representation defined in the KEYSYMS table. +-- * `SCOPES_ENABLED`: Flag indicating whether scopes/styles can be used for key +-- commands. +-- * `CTRL`: The string representing the Control key. +-- * `SHIFT`: The string representing the Shift key. +-- * `ALT`: The string representing the Alt key (the Apple key on Mac OSX). +-- * `ADD`: The string representing used to join together a sequence of Control, +-- Shift, or Alt modifier keys. -- --- Keep in mind that all Lua functions used in key commands must be defined --- BEFORE the key command references it. Therefore the module containing key --- commands should be loaded LAST, after all other modules have been loaded. --- options +-- settings local SCOPES_ENABLED = true local ADD = '' local CTRL = 'c'..ADD local SHIFT = 's'..ADD local ALT = 'a'..ADD --- end options +-- end settings --- -- Global container that holds all key commands. diff --git a/core/ext/mime_types.lua b/core/ext/mime_types.lua index e6412884..e16ecf6b 100644 --- a/core/ext/mime_types.lua +++ b/core/ext/mime_types.lua @@ -3,9 +3,63 @@ local textadept = _G.textadept local locale = _G.locale ---- Handles file-specific settings (based on file extension). +--- +-- Handles file-specific settings. module('textadept.mime_types', package.seeall) +-- Markdown: +-- ## Overview +-- +-- Files can be recognized and associated with programming language lexers in +-- three ways: +-- +-- * By file extension. +-- * By keywords in the file's shebang (`#!/path/to/exe`) line. +-- * By a pattern that matches the file's first line. +-- +-- If a lexer is not associated with a file you open, first make sure the lexer +-- exists in `lexers/`. If it does not, you will need to write one. Consult the +-- [lexer][lexer] module for a tutorial. +-- +-- [lexer]: ../modules/lexer.html +-- +-- ## Configuration File +-- +-- `core/ext/mime_types.conf` is the configuration file for mime-type detection. +-- +-- #### Detection by File Extension +-- +-- file_ext lexer +-- +-- Note: `file_ext` should not start with a `.` (period). +-- +-- #### Detection by Shebang Keywords +-- +-- #shebang_word lexer +-- +-- Examples of `shebang_word`'s are `lua`, `ruby`, `python`. +-- +-- #### Detection by Pattern +-- +-- /pattern lexer +-- +-- Only the last space, the one separating the pattern from the lexer, is +-- significant. No spaces in the pattern need to be escaped. +-- +-- ## Extras +-- +-- This module adds an extra function to `buffer`: +-- +-- * **buffer:set\_lexer** (language)
+-- Replacement for [`buffer:set_lexer_language()`][buffer_set_lexer_language].
+-- Sets a buffer._lexer field so it can be restored without querying the +-- mime-types tables. Also if the user manually sets the lexer, it should be +-- restored.
+-- Loads the language-specific module if it exists. +-- - lang: The string language to set. +-- +-- [buffer_set_lexer_language]: buffer.html#buffer:set_lexer_language + --- -- File extensions with their associated lexers. -- @class table @@ -43,17 +97,26 @@ if f then f:close() end ---- +-- -- Replacement for buffer:set_lexer_language(). -- Sets a buffer._lexer field so it can be restored without querying the -- mime-types tables. Also if the user manually sets the lexer, it should be -- restored. +-- Loads the language-specific module if it exists. -- @param buffer The buffer to set the lexer language of. -- @param lang The string language to set. -- @usage buffer:set_lexer('language_name') local function set_lexer(buffer, lang) buffer._lexer = lang buffer:set_lexer_language(lang) + if buffer.filename then + local ret, err = pcall(require, lang) + if ret then + _m[lang].set_buffer_properties() + elseif not ret and not err:find("^module '"..lang.."' not found:") then + error(err) + end + end end textadept.events.add_handler('buffer_new', function() buffer.set_lexer = set_lexer end) @@ -83,17 +146,6 @@ local function handle_new() end end buffer:set_lexer(lexer or 'container') - if buffer.filename then - local lang = extensions[buffer.filename:match('[^/\\.]+$')] - if lang then - local ret, err = pcall(require, lang) - if ret then - _m[lang].set_buffer_properties() - elseif not ret and not err:find("^module '"..lang.."' not found:") then - error(err) - end - end - end end -- Sets the buffer's lexer based on filename, shebang words, or diff --git a/core/file_io.lua b/core/file_io.lua index aedecbd3..499aea72 100644 --- a/core/file_io.lua +++ b/core/file_io.lua @@ -5,14 +5,56 @@ local locale = _G.locale --- -- Provides file input/output routines for Textadept. --- Opens and saves files and reads API files. --- --- Events (all filenames are encoded in UTF-8): --- file_opened(filename) --- file_before_save(filename) --- file_saved_as(filename) module('textadept.io', package.seeall) +-- Markdown: +-- ## Overview +-- +-- Textadept represents all characters and strings internally as UTF-8. You will +-- not notice any difference for working with files containing ASCII text since +-- UTF-8 is compatible with it. Problems may arise for files with more exotic +-- encodings that may not be detected properly, if at all. When opening a file, +-- the list of encodings tried before throwing a `conversion failed` error is in +-- `core/file_io.lua`'s [`try_encodings`](#try_encodings). Textadept respects the +-- detected encoding when saving the file. +-- +-- New files are saved as UTF-8 by default. +-- +-- ## Converting Filenames to and from UTF-8 +-- +-- If your filesystem does not use UTF-8 encoded filenames, conversions to and +-- from that encoding will be necessary. When opening and saving files through +-- dialogs, Textadept takes care of these conversions for you, but if you need +-- to do them manually, use [`textadept.iconv()`][textadept_iconv] along with +-- `_CHARSET`, your filesystem's detected encoding. +-- +-- Example: +-- +-- textadept.events.add_handler('file_opened', +-- function(utf8_filename) +-- local filename = textadept.iconv(utf8_filename, _CHARSET, 'UTF-8') +-- local f = io.open(filename, 'rb') +-- -- process file +-- f:close() +-- end) +-- +-- [textadept_iconv]: ../modules/textadept.html#iconv +-- +-- ## Events +-- +-- The following is a list of all File I/O events generated in +-- `event_name(arguments)` format: +-- +-- * **file\_opened** (filename)
+-- Called when a file has been opened in a new buffer. +-- - filename: the filename encoded in UTF-8. +-- * **file\_before\_save** (filename)
+-- Called right before a file is saved to disk. +-- - filename: the filename encoded in UTF-8. +-- * **file\_saved_as** (filename)
+-- Called when a file is saved under another filename. +-- - filename: the other filename encoded in UTF-8. + local lfs = require 'lfs' --- @@ -56,8 +98,11 @@ local function detect_encoding(text) return nil end +--- -- List of encodings to try to decode files as after UTF-8. -local try_encodings = { +-- @class table +-- @name try_encodings +try_encodings = { 'UTF-8', 'ASCII', 'ISO-8859-1', diff --git a/core/locale.conf b/core/locale.conf index 00300a6b..4298b390 100644 --- a/core/locale.conf +++ b/core/locale.conf @@ -712,8 +712,8 @@ PM_BROWSER_FILE_INFO_OK "OK" PM_BROWSER_FILE_SHOW_DOT_FILES "Show _Dot Files" % core/ext/pm/modules_browser.lua -% "_New Module" -PM_BROWSER_MODULE_NEW "_New Module" +% "_New Language Module" +PM_BROWSER_MODULE_NEW "_New Language Module" % core/ext/pm/modules_browser.lua % "_Delete Module" diff --git a/core/locale.lua b/core/locale.lua index 306bb64d..be37499d 100644 --- a/core/locale.lua +++ b/core/locale.lua @@ -1,11 +1,24 @@ -- Copyright 2007-2009 Mitchell mitchellcaladbolg.net. See LICENSE. --- --- This module loads all messages used by Textadept for localization. --- Localized strings are contained in 'core/locale.conf'. Please see this file --- for more information. +-- Contains all messages used by Textadept for localization. module('locale', package.seeall) +-- Markdown: +-- ## Overview +-- +-- All Textadept messages displayed are located in `core/locale.conf`. To change +-- the language, simply replace that file with a similar file containing the +-- translated messages. See `core/locale.conf` for more information. +-- +-- Feel free to translate Textadept and send your modified `locale.conf` files +-- to me. I will put them up on the site where they can be accessed. +-- +-- ## Fields +-- +-- Each message ID in `core/locale.conf` is accessible as a field in this +-- module. + local escapes = { ['\\n'] = '\n', ['\\r'] = '\r', ['\\t'] = '\t' } local f = io.open(_HOME..'/core/locale.conf', 'rb') @@ -17,3 +30,8 @@ for line in f:lines() do end end f:close() + +--- +-- This module contains no functions. +function no_functions() end +no_functions = nil -- undefine -- cgit v1.2.3