diff options
30 files changed, 1491 insertions, 724 deletions
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.<br /> +-- * 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.<br /> +-- * -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.<br /> +-- * 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.<br /> +-- * 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.<br /> +-- * 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.<br /> +-- * 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.<br /> +-- * 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.<br /> +-- * 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.<br /> +-- * 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.<br /> +-- * 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.<br /> +-- * 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. +-- <br /> +-- * 0: None +-- * 1: End +-- * 2: Start +-- * `wrap_visual_flags_location`: The location of visual flags for wrapped +-- lines.<br /> +-- * 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)<br /> +-- Called when an ordinary text character is added to the buffer. +-- - ch: the ASCII representation of the character. +-- * **save\_point\_reached** ()<br /> +-- Called when a save point is entered. +-- * **save\_point\_left** ()<br /> +-- Called when a save point is left. +-- * **double\_click** (position, line)<br /> +-- 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** ()<br /> +-- Called when the text or styling of the buffer has changed or the selection +-- range has changed. +-- * **margin\_click** (margin, modifiers, position)<br /> +-- 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)<br /> +-- 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)<br /> +-- 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)<br /> +-- 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)<br /> +-- 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** ()<br /> +-- Called when a new [buffer][buffer] is created. +-- * **buffer\_deleted** ()<br /> +-- Called when a [buffer][buffer] has been deleted. +-- * **buffer\_before\_switch** ()<br /> +-- Called right before another [buffer][buffer] is switched to. +-- * **buffer\_after\_switch** ()<br /> +-- Called right after a [buffer][buffer] was switched to. +-- * **view\_new** ()<br /> +-- Called when a new [view][view] is created. +-- * **view\_before\_switch** ()<br /> +-- Called right before another [view][view] is switched to. +-- * **view\_after\_switch** ()<br /> +-- Called right after [view][view] was switched to. +-- * **quit** ()<br /> +-- Called when quitting Textadept.<br /> +-- 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)<br /> +-- Called when a key is pressed. +-- - code: the key code (according to `<gdk/gdkkeysyms.h>`). +-- - 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. +-- <br /> +-- Note: The Alt-Option key in Mac OSX is not available. +-- * **menu\_clicked** (menu\_id)<br /> +-- 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)<br /> +-- 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)<br /> +-- 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)<br /> +-- 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)<br /> +-- 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** ()<br /> +-- Called when the [PM][PM] view is filled with data. +-- * **find** (text, next)<br /> +-- 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)<br /> +-- 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)<br /> +-- 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)<br /> +-- Called when a key is pressed in the Command Entry. +-- - code: the key code (according to `<gdk/gdkkeysyms.h>`). +-- +-- [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)<br /> +-- Replacement for [`buffer:set_lexer_language()`][buffer_set_lexer_language].<br /> +-- 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.<br /> +-- 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) <br /> +-- Called when a file has been opened in a new buffer. +-- - filename: the filename encoded in UTF-8. +-- * **file\_before\_save** (filename) <br /> +-- Called right before a file is saved to disk. +-- - filename: the filename encoded in UTF-8. +-- * **file\_saved_as** (filename) <br /> +-- 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 mitchell<att>caladbolg.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 diff --git a/doc/manual/1_Introduction.md b/doc/manual/1_Introduction.md new file mode 100644 index 00000000..57a16cb0 --- /dev/null +++ b/doc/manual/1_Introduction.md @@ -0,0 +1,84 @@ +# Introduction + +## Purpose + +This manual is not intended to be completely comprehensive. + +## Textadept's Philosophy + +Textadept is a text editor for programmers. + +In a world where code bloat is commonplace and application speed is second to +its number of features, Textadept breaks that trend, aiming to stay minimalist +and fast, but at the same time being ridiculously extensible. At its core lies +less than 2000 lines of C code, and that's how it always will be. While other +editors rely on recordable macros to speed up workflow, shell scripts to quickly +transform text, and static side panes to manage your documents, files, and more, +Textadept takes it to the extreme: it gives you complete control over the entire +application using the embedded [Lua][Lua] language. Lua is nearly as fast as C, +and has a very small footprint. In fact, most of Textadept is written in Lua. +Its incredibly fast startup time and operation attest to Lua's worthiness. + +Tired of all those features you never use in other editors? With Textadept you +can disable or remove anything you dislike or do not need. Wish you had an +additional feature? Chances are you can add it yourself. + +Annoyed of recording complicated macros in other editors, only to find yourself +re-recording them over and over with little changes each time? You may be +surprised to find you can write the same commands in Lua, from moving the caret +to replacing text, performing searches, and much more! + +Worried that your existing shell scripts for transforming text in other editors +will not be compatible with Lua or Textadept? No need to be. You can tell Lua to +run them in your shell. + +Wish that you could add a feature to another editor's document/file browser/etc. +side pane? Textadept allows you to create as many different kinds of browsers +for heirarchical data as you want. + +These are just some of Textadept's strengths. Textadept is not about +constraining the user to a certain set of features while allowing minimal +custimization and/or extensibility. Textadept is about allowing that +customization and extensibility from the get-go; the features come after that. + +[Lua]: http://lua.org + +## Help + +Textadept has a [mailing list][mailing_list] and a [wiki][wiki]. You can also +join us on IRC via [freenode.net][freenode] in `#textadept`. + +[mailing_list]: http://groups.google.com/group/textadept +[wiki]: http://caladbolg.net/textadeptwiki +[freenode]: http://freenode.net + +## Screenshots + +<div style="float: left;"> +Main window.<br /> +<a href="http://caladbolg.net/images/textadept/window.png"><img src="http://caladbolg.net/images/textadept/window_t.png" alt="Main" /></a> +</div> +<div style="float: left; margin-left: 50px;"> +Open Buffers.<br /> +<a href="http://caladbolg.net/images/textadept/buffers.png"><img src="http://caladbolg.net/images/textadept/buffers_t.png" alt="Buffers" /></a> +</div> +<div style="margin-left: 400px;"> +Lua Commands.<br /> +<a href="http://caladbolg.net/images/textadept/command.png"><img src="http://caladbolg.net/images/textadept/command_t.png" alt="Command" /></a> +</div> +<div style="float: left;"> +Project Manager.<br /> +<a href="http://caladbolg.net/images/textadept/project.png"><img src="http://caladbolg.net/images/textadept/project_t.png" alt="PM" /></a> +</div> +<div style="margin-left: 200px;"> +Extras.<br /> +<a href="http://caladbolg.net/images/textadept/extra.png"><img src="http://caladbolg.net/images/textadept/extra_t.png" alt="Extras" /></a> +</div> +<div style="float: left;"> +Windows OS.<br /> +<a href="http://caladbolg.net/images/textadept/win32.png"><img src="http://caladbolg.net/images/textadept/win32_t.png" alt="Win32" /></a> +</div> +<div style="margin-left: 200px;"> +Linux OS.<br /> +<a href="http://caladbolg.net/images/textadept/linux.png"><img src="http://caladbolg.net/images/textadept/linux_t.png" alt="Linux" /></a> +</div> diff --git a/doc/manual/2_Installation.md b/doc/manual/2_Installation.md new file mode 100644 index 00000000..e83805d8 --- /dev/null +++ b/doc/manual/2_Installation.md @@ -0,0 +1,49 @@ +# Installation
+
+## Requirements
+
+In its bid for minimalism, Textadept also needs very little to run. In fact, the
+only thing it needs is [GTK+ 2.0][GTK2]. It has it's own version of Lua compiled
+in.
+
+#### Linux
+
+Most Linux systems already have GTK+ installed. If not, it is probably available
+through your package manager. Otherwise, compile and install it from the
+[GTK+ website][GTK-Linux].
+
+#### Mac OSX
+
+There is a GTK+ [Mac OSX Framework][GTK-OSX] available in contrast to using GTK+
+from Fink or DarwinPorts/MacPorts in conjuction with X11. You will need to get
+the [latest TESTING framework][GTK-OSX-Latest] that supports versioning. Note
+that Textadept is designed for Intel Leopard Macs.
+
+#### Windows
+
+Windows systems need the [GTK+ 2.0 Runtime][GTK-Runtime] installed.
+
+[GTK2]: http://gtk.org
+[GTK-Linux]: http://www.gtk.org/download-linux.html
+[GTK-OSX]: http://gtk-osx.org
+[GTK-OSX-Latest]: http://people.imendio.com/richard/stuff/Gtk-Framework-2.14.3-2-test1.dmg
+[GTK-Runtime]: http://sourceforge.net/projects/gtk-win/
+
+## Download
+
+Textadept can be downloaded from the [project page][Download]. Select the
+appropriate package for your platform.
+
+[Download]: http://textadept.googlecode.com/
+
+## Installation
+
+#### Linux and Windows
+
+For Linux and Windows machines, simply unpack the archive anywhere and you are
+ready to go.
+
+#### Mac OSX
+
+For Mac OSX machines, unpack the archive and move `textadept.app` to your user
+or system `Applications` directory like any other application.
diff --git a/doc/manual/3_Compiling.md b/doc/manual/3_Compiling.md new file mode 100644 index 00000000..acd874d3 --- /dev/null +++ b/doc/manual/3_Compiling.md @@ -0,0 +1,86 @@ +# Compiling + +## Requirements + +The requirements for building Textadept are not quite so minimal. + +#### Linux + +Linux systems will need the GTK+ development libraries. Your package manager +should allow you to install them. For Debian-based distributions, the package is +typically called `gtk2.0-dev`. Otherwise, compile and install it from the +[GTK+ website][GTK-Linux]. Additionally you will need the [GNU C compiler][GCC] +(`gcc`) and [GNU Make][Make] (`make`). Both should be available for your Linux +distribution through its package manager. + +#### Mac OSX + +[XCode][XCode] is needed for Mac OSX as well as the +[GTK-OSX Framework][GTK-OSX-Latest]. + +#### Windows + +Compiling Textadept on Windows is no longer supported. If you wish to do so +however, you will need a C compiler that supports the C99 standard (Microsoft's +does not) and the [GTK+ for Windows bundle][GTK-Win32] and win_iconv libraries. + +The preferred way to compile for Windows is cross-compiling from Linux. To do +so, in addition to the GTK+ development libraries mentioned above, you will need +[MinGW][MinGW] with the Windows header files and the Windows [bundle][GTK-Win32] +along with win_iconv. The former should be available from your package manager. +The latter you will have to download manually. + +[GTK-Linux]: http://www.gtk.org/download-linux.html +[GCC]: http://gcc.gnu.org +[Make]: http://www.gnu.org/software/make/ +[XCode]: http://developer.apple.com/TOOLS/xcode/ +[GTK-OSX-Latest]: http://people.imendio.com/richard/stuff/Gtk-Framework-2.14.3-2-test1.dmg +[GTK-Win32]: http://www.gtk.org/download-windows.html +[MinGW]: http://mingw.org + +## Download + +Download the `textadept_x.x.src.zip`, regardless of what platform you are on. + +## Compiling + +#### Linux + +For Linux systems, simply run `make` in the `src/` directory. The `textadept` +executable will be created in the root directory. You can make a symlink from +it to `/usr/bin/` or elsewhere in your `PATH`. + +#### Mac OSX + +In Mac OSX, open `xcode/textadept.xcodeproj` in XCode, change the active build +configuration combo box from `Debug` to `Release` (if necessary), click `Build`, +and copy the resulting `xcode/build/Release/textadept.app` to your user or +system `Applications` folder. + + +#### Windows (Cross-Compiling from Linux) + +When cross-compiling from within Linux, first unzip the GTK+ for Windows bundle +into a new `src/win32gtk` directory. Then rename all the +`src/win32gtk/lib/*.dll.a` files to `src/win32/gtk/lib/*.a`, removing the `.dll` +part of the filename. Finally, modify the `CC`, `CPP`, and `WINDRES` variables +in the `WIN32` block of `src/Makefile` to match your MinGW installation and run +`make WIN32=1` to build `../textadept.exe`. + +## Problems + +#### Mac OSX + +In Mac OSX, if the build fails because of a + + `redefinition of 'struct Sci_TextRange'` + +error, you will need to open `src/scintilla-st/include/Scintilla.h` and comment +out the following lines (put `//` at the start of the line): + + #define CharacterRange Sci_CharacterRange + #define TextRange Sci_TextRange + #define TextToFind Sci_TextToFind + +`src/scintilla-st/src/LexLPeg.cxx` may need to have `TextRange tr` changed to +`Sci_TextRange tr` as well. diff --git a/doc/manual/4_UserInterface.md b/doc/manual/4_UserInterface.md new file mode 100644 index 00000000..60ed9a18 --- /dev/null +++ b/doc/manual/4_UserInterface.md @@ -0,0 +1,38 @@ +# User Interface + +Textadept's user interface was designed to be simple. It consists of an optional +menubar, left-hand side pane, editor view, and initially hidden dialogs for +find/replace and command entry. Below are brief descriptions of these features. +More in-depth discussion about each of them is provided later in the manual. + +## Menubar + +The completely customizable (and optional!) menubar typically provides access to +all of Textadept's features. + +## Side Pane + +From the beginning, the side pane has been called the Project Manager, or PM. +This is a deceptive name though, as it can hold any hierarchical, treeview-based +data structure, not just a list of files in a project. By default, Textadept can +show opened buffers, a filesystem, and a list of Lua modules. (These can be seen +in `core/ext/pm/`.) If you choose, you can resize and/or hide the PM. + +## Editor View + +The editor view is where you will spend most of your time in Textadept. It +supports unlimited split views and is completely controllable by Lua. + +## Find/Replace Dialog + +This compact dialog is a great way to slice and dice through your document or +directory of files. You can even find and replace text using Lua patterns. It is +available when you need it and quickly gets out of your way when you do not, +minimizing distractions. + +## Command Entry + +The versitile command entry functions as both a place to execute Lua commands +with the internal Lua state and find text incrementally. You can extend it to do +even more if you would like. Like the find/replace dialog, the command entry +pops in and out as you wish. diff --git a/doc/manual/5_FolderStructure.md b/doc/manual/5_FolderStructure.md new file mode 100644 index 00000000..7cb0f4b3 --- /dev/null +++ b/doc/manual/5_FolderStructure.md @@ -0,0 +1,41 @@ +# Folder Structure + +Because Textadept is mostly written in Lua, these Lua files have to be stored in +an organized folder structure. + +## Core + +Textadept's core Lua modules are contained in `core/`. These are absolutely +necessary in order for Textadept to run. They are responsible for Textadept's +Lua to C interface, event structure, file input/output, and localization. + +## Core Extension + +Core extension Lua modules are in `core/ext/`. These are optional and not +required, but are stored in `core/` because they could be considered "core +functionality". They are responsible for PM functionality and features like +find/replace and the handling of key commands, menus, and file types. + +## Lexers + +Lexer Lua modules are responsible for the syntax highlighting of source code. +They are located in `lexers/`. + +## Modules + +Editor Lua modules are contained in `modules/`. These provide advanced text +editing capabilities and can be available for all programming languages or +targeted at specific ones. + +## Themes + +Built-in themes to customize the look and behavior of Textadept are located in +`themes/`. + +## User + +User Lua modules are contained in a `.textadept` folder in your home directory. +In Linux and Mac OSX, your home directory is the location specified by the +`HOME` environment variable (typically `/home/username` and `/Users/username` +respectively). In Windows, it is the `USERPROFILE` environment variable. This +directory will be denoted as `~/.textadept` from now on in the manual. diff --git a/doc/manual/6_Startup.md b/doc/manual/6_Startup.md new file mode 100644 index 00000000..c9103782 --- /dev/null +++ b/doc/manual/6_Startup.md @@ -0,0 +1,33 @@ +# Startup Process + +Textadept starts up ridiculously fast. On most computers it starts up around as +fast as you can blink. + +## Core (`core/init.lua`) + +The key to Textadept's lightning fast start time is that it loads only its core +modules before showing the window. + +#### Themes + +Textadept loads its theme during the Core startup process. Each theme is its +own folder with three files: `buffer.lua`, `lexer.lua`, and `view.lua`. The +buffer theme sets default buffer properties like tabs and indentation. The view +theme sets default view properties like caret color and current line background +color. Lexer themes set the color and style definitions used by most lexers. By +default the `'light'` theme is used. A `'scite'` theme is provided for users +accustomed to SciTE. + +To use a different theme, create a `~/.textadept/theme` file containing the +name of the built-in theme you would like. If you have a custom theme, use the +path to its directory instead. Any errors are printed to standard out. + +## Post-Core (`init.lua`) + +After loading the core modules, Textadept begins loading additional modules. +It first checks for a `~/.textadept/init.lua` user module. If the module is +found, it is run and skips loading the default modules specified in `init.lua`. +Otherwise a mixture of core extension and generic modules are loaded. + +After loading the additional modules, Textadept parses command line arguments, +or if none are specified, reloads the last saved session. diff --git a/doc/manual/7_LuaInterface.md b/doc/manual/7_LuaInterface.md new file mode 100644 index 00000000..f1e343d9 --- /dev/null +++ b/doc/manual/7_LuaInterface.md @@ -0,0 +1,27 @@ +# Lua Interface + +After startup, Textadept relinquishes control to Lua. At this point, having a +Manual is pointless since all of Textadept's functionality is dynamic from here +on out. This is where the most important resource for help comes in: the +[LuaDoc][LuaDoc]. It contains not only documentation for Textadept's Lua API, +but documentation for all of its modules and features as well. It is more up to +date than a manual like this could ever be. + +[LuaDoc]: ../index.html + +## Global Variables + +The following global variables not mentioned in the LuaDoc are available in +Textadept's Lua state: + +* `arg`: Table containing the command line arguments passed to Textadept. +* `_HOME`: Path to the directory containing Textadept. +* `WIN32`: If Textadept is running on Windows, this flag is `true`. +* `MAC`: If Textadept is running on Mac OSX, this flag is `true`. +* `_CHARSET`: The character set encoding of the filesystem. This is used in + [File I/O][file_io]. +* `RESETTING`: If [`textadept.reset()`][textadept_reset] has been called, this + flag is `true` while the Lua state is being re-initialized. + +[file_io]: ../modules/textadept.io.html +[textadept_reset]: ../modules/textadept.html#reset diff --git a/doc/sidebar.md b/doc/sidebar.md new file mode 100644 index 00000000..1c258ca9 --- /dev/null +++ b/doc/sidebar.md @@ -0,0 +1,31 @@ + + +# Manual + +* [Introduction](manual/1_Introduction.html) +* [Installation](manual/2_Installation.html) +* [Compiling](manual/3_Compiling.html) +* [User Interface](manual/4_UserInterface.html) +* [Folder Structure](manual/5_FolderStructure.html) +* [Startup](manual/6_Startup.html) +* [Lua Interface](manual/7_LuaInterface.html) + +# Links + +* [Caladbolg.net](http://caladbolg.net) +* [LuaDoc](index.html) +* [Download](http://code.google.com/p/textadept/downloads/list) +* [Mailing List](http://groups.google.com/group/textadept) +* [Mercurial Repository](http://code.google.com/p/textadept/source/browse) +* [Wiki](http://caladbolg.net/textadeptwiki) + +# Donate + +<form action="https://www.paypal.com/cgi-bin/webscr" method="post"> +<input type="hidden" name="cmd" value="_s-xclick"> +<input type="hidden" name="hosted_button_id" value="3165962"> +<input type="image" src="https://www.paypal.com/en_US/i/btn/btn_donateCC_LG.gif" border="0" name="submit" alt=""> +<img alt="" border="0" src="https://www.paypal.com/en_US/i/scr/pixel.gif" width="1" height="1"> +</form> + +Do you like Textadept? Please consider a $5 or more donation. diff --git a/modules/textadept/bookmarks.lua b/modules/textadept/bookmarks.lua index 3fdca987..a94c56db 100644 --- a/modules/textadept/bookmarks.lua +++ b/modules/textadept/bookmarks.lua @@ -5,15 +5,22 @@ local locale = _G.locale --- -- Bookmarks for the textadept module. --- There are several option variables used: --- MARK_BOOKMARK: The integer mark used to identify a bookmarked line. --- MARK_BOOKMARK_COLOR: The Scintilla color used for a bookmarked line. module('_m.textadept.bookmarks', package.seeall) --- options -local MARK_BOOKMARK = 1 -local MARK_BOOKMARK_COLOR = 0xC08040 --- end options +-- Markdown: +-- ## Settings +-- +-- * `MARK_BOOKMARK`: The unique integer mark used to identify a bookmarked +-- line. +-- * `MARK_BOOKMARK_COLOR`: The [Scintilla color][scintilla_color] used for a +-- bookmarked line. +-- +-- [scintilla_color]: http://scintilla.org/ScintillaDoc.html#colour + +-- settings +MARK_BOOKMARK = 1 +MARK_BOOKMARK_COLOR = 0xC08040 +-- end settings --- -- Adds a bookmark to the current line. diff --git a/modules/textadept/editing.lua b/modules/textadept/editing.lua index d1d2c4a2..97ac9baa 100644 --- a/modules/textadept/editing.lua +++ b/modules/textadept/editing.lua @@ -7,6 +7,25 @@ local locale = _G.locale -- Editing commands for the textadept module. module('_m.textadept.editing', package.seeall) +-- Markdown: +-- ## Settings +-- +-- * `AUTOPAIR`: Flag indicating whether or not when an opening `(`, `[`, `[`, +-- `"`, or `'` is typed, its closing complement character is automatically +-- inserted. +-- * `HIGHLIGHT_BRACES`: Flag indicating whether or not when the caret is over a +-- brace character (any of the following: `()[]{}<>`), its matching complement +-- brace is highlighted. +-- * `AUTOINDENT`: Flag indicating whether or not when the enter key is pressed, +-- the inserted line has is indented to match the level of indentation of the +-- previous line. + +-- settings +AUTOPAIR = true +HIGHLIGHT_BRACES = true +AUTOINDENT = true +-- end settings + -- The kill-ring. -- @field maxn The maximum size of the kill-ring. local kill_ring = { pos = 1, maxn = 10 } @@ -53,11 +72,14 @@ local comment_strings = { ruby = '#~', } +if AUTOPAIR then textadept.events.add_handler('char_added', function(c) -- matches characters specified in char_matches if char_matches[c] then buffer:insert_text(-1, char_matches[c]) end end) +end +if HIGHLIGHT_BRACES then textadept.events.add_handler('update_ui', function() -- highlights matching braces local buffer = buffer @@ -74,7 +96,9 @@ textadept.events.add_handler('update_ui', buffer:brace_bad_light(-1) end end) +end +if AUTOINDENT then textadept.events.add_handler('char_added', function(char) -- auto-indent on return if char ~= 10 then return end @@ -101,6 +125,7 @@ textadept.events.add_handler('char_added', buffer:set_sel(anchor, caret) end end) +end -- local functions local insert_into_kill_ring, scroll_kill_ring diff --git a/modules/textadept/lsnippets.lua b/modules/textadept/lsnippets.lua index 3d4c73fa..5eeb14e1 100644 --- a/modules/textadept/lsnippets.lua +++ b/modules/textadept/lsnippets.lua @@ -5,80 +5,130 @@ local locale = _G.locale --- -- Provides Lua-centric snippets for Textadept. --- Snippets are basically pieces of text inserted into a document, but can --- execute code, contain placeholders a user can enter in dynamic text for, and --- make transformations on that text. This is much more powerful than standard --- text templating. --- There are several option variables used: --- MARK_SNIPPET: The integer mark used to identify the line that marks the --- end of a snippet. --- MARK_SNIPPET_COLOR: The Scintilla color used for the line --- that marks the end of the snippet. --- module('_m.textadept.lsnippets', package.seeall) --- Usage: --- Snippets are defined in the global table 'snippets'. Keys in that table are --- snippet trigger words, and values are the snippet's text to insert. The --- exceptions are language names and style names. Language names have table --- values of either snippets or style keys with table values of snippets. --- 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: --- snippets = { --- file = '%(buffer.filename)', --- lua = { --- f = 'function %1(name)(%2(args))\n %0\nend', --- string = { [string-specific snippets here] } +-- Markdown: +-- ## Settings +-- +-- * `MARK_SNIPPET`: The unique integer mark used to identify the line that +-- marks the end of a snippet. +-- * `MARK_SNIPPET_COLOR`: The [Scintilla color][scintilla_color] used for the +-- line that marks the end of the snippet. +-- +-- [scintilla_color]: http://scintilla.org/ScintillaDoc.html#colour +-- +-- ## Overview +-- +-- Snippets are basically pieces of text inserted into a document, but can +-- execute code, contain placeholders you can enter dynamic text for, and +-- perform transformations on that text. This is much more powerful than +-- standard text templating. +-- +-- Snippets are defined in the global table `snippets`. Each key-value pair in +-- `snippets` consist of either: +-- +-- * A string snippet trigger word and its expanded text. +-- * A string language name and its associated `snippets`-like table. +-- * A string style name and its associated `snippets`-like table. +-- +-- 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`. +-- +-- ## Snippet Precedence +-- +-- When searching for a snippet to expand in the `snippets` table, snippets in +-- the current style have priority, followed by the ones in the current lexer, +-- and finally the ones in the global table. +-- +-- ## Snippet Syntax +-- +-- A snippet to insert may contain any of the following: +-- +-- #### Plain Text +-- +-- Any plain text characters may be used with the exception of `%` and `. +-- These are special characters and must be "escaped" by prefixing one with a +-- `%`. As an example, `%%` inserts a single `%` in the snippet. +-- +-- #### Lua and Shell Code +-- +-- %(lua_code) +-- `shell_code` +-- +-- The code is executed the moment the snippet is inserted. +-- +-- For Lua code, the global Lua state is available as well as a `selected_text` +-- variable (containing the current selection in the buffer) for convenience. +-- Only the return value of the code execution is inserted, not standard out. +-- Therefore any `print()` statements are meaningless. +-- +-- Shell code is run via Lua's [`io.popen()`][io_popen]. +-- +-- [io_popen]: http://www.lua.org/manual/5.1/manual.html#pdf-io.popen +-- +-- #### Tab Stops and Mirrors +-- +-- %num +-- +-- These are visited in numeric order (1, 2, 3, etc.) with %0 being the final +-- position of the caret, or the end of the snippet if %0 is not specified. If +-- there is a placeholder (described below) with the specified `num`, its text +-- is mirrored here. +-- +-- #### Placeholders +-- +-- %num(text) +-- +-- These are also visited in numeric order, but have precedence over tab stops, +-- and insert the specified `text` at the current position upon entry. `text` +-- can contain Lua code executed at run-time: +-- +-- %num(#(lua_code)) +-- +-- The global Lua state is available as well as a `selected_text` variable +-- (containing the current selection in the buffer) for convenience. +-- +-- `#`'s will have to be escaped with `%` for plain text. Any mis-matched `)`'s +-- must also be escaped, but balanced `()`'s need not be. +-- +-- #### Transformations +-- +-- %num(pattern|replacement) +-- +-- These act like mirrors, but transform the text that would be inserted using +-- a given [Lua pattern][lua_pattern] and replacement. Like in placeholders, +-- `replacement` can contain Lua code executed at run-time as well as the +-- standard Lua capture sequences: `%n` where 1 <= `n` <= 9. +-- +-- [lua_pattern]: http://www.lua.org/manual/5.1/manual.html#5.4.1 +-- +-- Any `|`'s after the first one do not need to be escaped. +-- +-- ## Example +-- +-- snippets = { +-- file = '%(buffer.filename)', +-- lua = { +-- f = 'function %1(name)(%2(args))\n %0\nend', +-- string = { [string-specific snippets here] } +-- } -- } --- } --- Style and lexer insensitive snippets should be placed in the lexer and --- snippets tables respectively. --- --- When searching for a snippet to expand in the snippets table, snippets in the --- current style have priority, then the ones in the current lexer, and finally --- the ones in the global table. --- --- As mentioned, snippets are key-value pairs, the key being the trigger word --- and the value being the snippet text: ['trigger'] = 'text'. --- Snippet text however can contain more than just text. --- --- Insert-time Lua and shell code: %(lua_code), `shell_code` --- The code is executed the moment the snippet is inserted. For Lua code, the --- result of the code execution is inserted, so print statements are useless. --- All global variables and a 'selected_text' variable are available. --- --- Tab stops/Mirrors: %num --- These are visited in numeric order with %0 being the final position of the --- caret, the end of the snippet if not specified. If there is a placeholder --- (described below) with the specified num, its text is mirrored here. --- --- Placeholders: %num(text) --- These are also visited in numeric order, having precedence over tab stops, --- and inserting the specified text. If no placeholder is available, the tab --- stop is visited instead. The specified text can contain Lua code executed --- at run-time: #(lua_code). --- --- Transformations: %num(pattern|replacement) --- These act like mirrors, but transform the text that would be inserted using --- a given Lua pattern and replacement. The replacement can contain Lua code --- executed at run-time: #(lua_code), as well as the standard Lua capture --- sequences: %n where 1 <= n <= 9. --- See the Lua documentation for using patterns and replacements. --- --- To escape any of the special characters '%', '`', ')', '|', or '#', prepend --- the standard Lua escape character '%'. Note: --- * Only '`' needs to be escaped in shell code. --- * '|'s after the first in transformations do not need to be escaped. --- * Only unmatched ')'s need to be escaped. Nested ()s are ignored. +-- +-- The first snippet is global and runs the Lua code to determine the current +-- buffer's filename and inserts it. The other snippets apply only in the `lua` +-- lexer. Any snippets in the `string` table are available only when the current +-- style is `string` in the `lua` lexer. -local MARK_SNIPPET = 4 -local MARK_SNIPPET_COLOR = 0x4D9999 +-- settings +MARK_SNIPPET = 4 +MARK_SNIPPET_COLOR = 0x4D9999 +-- end settings --- -- Global container that holds all snippet definitions. -- @class table --- @name snippets +-- @name _G.snippets _G.snippets = {} _G.snippets.file = "%(buffer.filename)" diff --git a/modules/textadept/mlines.lua b/modules/textadept/mlines.lua index daddf4b5..6d4d866b 100644 --- a/modules/textadept/mlines.lua +++ b/modules/textadept/mlines.lua @@ -5,21 +5,25 @@ local locale = _G.locale --- -- Multiple line editing for the textadept module. --- There are several option variables used: --- MARK_MLINE: The integer mark used to identify an MLine marked line. --- MARK_MLINE_COLOR: The Scintilla color used for an MLine marked line. module('_m.textadept.mlines', package.seeall) --- options -local MARK_MLINE = 2 -local MARK_MLINE_COLOR = 0x4D994D --- end options +-- Markdown: +-- ## Settings +-- +-- * `MARK_MLINE`: The unique integer mark used to identify an MLine marked +-- line. +-- * `MARK_MLINE_COLOR`: The [Scintilla color][scintilla_color] used for an +-- MLine marked line. +-- +-- [scintilla_color]: http://scintilla.org/ScintillaDoc.html#colour ---- --- [Local table] Contains all MLine marked lines with the column index to edit --- with respect to for each specific line. --- @class table --- @name mlines +-- settings +MARK_MLINE = 2 +MARK_MLINE_COLOR = 0x4D994D +-- end settings + +-- Contains all MLine marked lines with the column index to edit with respect to +-- for each specific line. local mlines = {} local mlines_most_recent diff --git a/modules/textadept/run.lua b/modules/textadept/run.lua index d6fa0a24..fcdb6a43 100644 --- a/modules/textadept/run.lua +++ b/modules/textadept/run.lua @@ -20,7 +20,7 @@ function execute(command) local filedir, filename = filepath:match('^(.+[/\\])([^/\\]+)$') local filename_noext = filename:match('^(.+)%.') command = command:gsub('%%%b()', { - ['%(filepath)'] = filepath, _CHARSET, 'UTF-8', + ['%(filepath)'] = filepath, ['%(filedir)'] = filedir, ['%(filename)'] = filename, ['%(filename_noext)'] = filename_noext, diff --git a/modules/textadept/session.lua b/modules/textadept/session.lua index a464da68..ba98a728 100644 --- a/modules/textadept/session.lua +++ b/modules/textadept/session.lua @@ -5,11 +5,16 @@ local locale = _G.locale --- -- Session support for the textadept module. --- There are several option variables used: --- DEFAULT_SESSION: The path to the default session file. module('_m.textadept.session', package.seeall) -local DEFAULT_SESSION = _USERHOME..'/session' +-- Markdown: +-- ## Settings +-- +-- * `DEFAULT_SESSION`: The path to the default session file. + +-- settings +DEFAULT_SESSION = _USERHOME..'/session' +-- end settings --- -- Loads a Textadept session file. diff --git a/scripts/update_doc b/scripts/update_doc new file mode 100755 index 00000000..c3360e43 --- /dev/null +++ b/scripts/update_doc @@ -0,0 +1,104 @@ +#!/usr/bin/lua +-- Copyright 2007-2009 Mitchell mitchell<att>caladbolg.net. See LICENSE. + +-- Generate LuaDoc. +os.execute('rm -rf ../doc/modules/') +os.execute('cd ../; luadoc -d doc/ --nofiles modules/ core/ lexers/lexer.lua') + +-- Insert Markdown in modules into LuaDoc. +local p = io.popen('grep -r "\\-\\- Markdown:" ../*') +for file in p:lines() do + local module + + -- Open the Lua file and extract the Markdown lines. + local f = io.open(file:match('^[^:]+')) + local markdown, flag = {}, false + for line in f:lines() do + if flag and line:match('^%-%-') then + local match = line:match('^%-%- ([^\n]+)') + markdown[#markdown + 1] = match or '' + elseif flag then -- markdown ended + break + elseif line:match('^%-%- Markdown:') then + flag = true + elseif line:match('^module') then + module = line:match("^module%('([^']+)") + end + end + f:close() + + -- Convert the Markdown into HTML. + markdown = table.concat(markdown, '\n') + f = io.open('tmp', 'w') + f:write(markdown) + f:close() + f = io.popen('perl ../doc/Markdown.pl tmp') + markdown = f:read('*all') + f:close() + os.execute('rm tmp') + + -- Insert the Marked down HTML in the LuaDoc HTML file. + local filename = '../doc/modules/'..module..'.html' + f = io.open(filename) + local contents = f:read('*all') + f:close() + local s = contents:find('<h2>Functions</h2>') + if not s then s = contents:find('<h2>Tables</h2>') end + contents = contents:sub(1, s - 1)..markdown..contents:sub(s) + f = io.open(filename, 'w') + f:write(contents) + f:close() +end +p:close() + +-- Generate the Manual. +p = io.popen('ls -1 ../doc/manual/*.md') +for mdfile in p:lines() do + local htmlfile = mdfile:match('^(.+).md$')..'.html' + html = [[ + <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> + <html> + <head> + <title>Textadept Manual</title> + <base href="http://caladbolg.net/luadoc/textadept/" /> + <link rel="stylesheet" href="luadoc.css" type="text/css" /> + </head> + + <body> + <div id="container"> + <div id="main"> + <div id="navigation"> + + %sidebar% + + </div> + <div id="content"> + + %content% + + </div> + </div> + <div id="about"> + <p><a href="http://validator.w3.org/check?uri=referer"><img src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0!" height="31" width="88" /></a></p> + </div> + </div> + </body> + </html> + ]] + + local sidebar_md = io.popen('../doc/Markdown.pl ../doc/sidebar.md') + html = html:gsub('%%sidebar%%', sidebar_md:read('*all')) + sidebar_md:close() + local content_md = io.popen('../doc/Markdown.pl '..mdfile) + html = html:gsub('%%content%%', content_md:read('*all')) + content_md:close() + + local f = io.open(htmlfile, 'w') + f:write(html) + f:close() +end +p:close() + +os.execute("sed -i 's/pre.example/pre, pre.example/;' ../doc/luadoc.css") +os.execute('cd ../; doxygen Doxyfile') |