diff options
Diffstat (limited to 'core')
| -rw-r--r-- | core/.buffer.luadoc | 326 | ||||
| -rw-r--r-- | core/.ui.dialogs.luadoc | 108 | ||||
| -rw-r--r-- | core/events.lua | 14 | ||||
| -rw-r--r-- | core/file_io.lua | 22 | ||||
| -rw-r--r-- | core/init.lua | 6 | ||||
| -rw-r--r-- | core/lfs_ext.lua | 16 | ||||
| -rw-r--r-- | core/ui.lua | 6 |
7 files changed, 231 insertions, 267 deletions
diff --git a/core/.buffer.luadoc b/core/.buffer.luadoc index 087fd8a3..69d63338 100644 --- a/core/.buffer.luadoc +++ b/core/.buffer.luadoc @@ -35,10 +35,11 @@ -- @field anchor (number) -- The anchor's position. -- @field annotation_lines (table, Read-only) --- Table of the number of annotation lines for line numbers starting from +-- Table of the number of annotation text lines for line numbers starting from -- zero. -- @field annotation_style (table) --- Table of style numbers for annotations for line numbers starting from zero. +-- Table of style numbers for annotation text for line numbers starting from +-- zero. -- Only some style attributes are active in annotations: font, -- size/size_fractional, bold/weight, italics, fore, back, and character_set. -- @field annotation_style_offset (number) @@ -127,7 +128,7 @@ -- The default value is `buffer.ORDER_PRESORTED`. -- @field auto_c_separator (number) -- The byte value of the character that separates autocompletion and user list --- items. +-- list items. -- The default value is `32` (' '). -- @field auto_c_type_separator (number) -- The character byte that separates autocompletion and user list items and @@ -149,7 +150,7 @@ -- @field call_tip_fore_hlt (number, Write-only) -- The call tip's highlighted text foreground color, in "0xBBGGRR" format. -- @field call_tip_position (boolean) --- Display the call tip above instead of below the text. +-- Display the call tip above the current line instead of below it. -- The default value is `false`. -- @field call_tip_use_style (number) -- The pixel width of tab characters in call tips. @@ -225,9 +226,10 @@ -- -- The default value is `buffer.CURSORNORMAL`. -- @field edge_colour (number) --- The color, in "0xBBGGRR" format, marking long lines. +-- The color, in "0xBBGGRR" format, of the edge or background for long lines +-- based on `buffer.edge_mode`. -- @field edge_column (number) --- The column number to start marking long lines at. +-- The column number to mark long lines at. -- @field edge_mode (number) -- The long line mark mode. -- @@ -237,7 +239,7 @@ -- Draw a vertical line whose color is [`buffer.edge_colour`](#edge_colour) -- at column [`buffer.edge_column`](#edge_column). -- * `buffer.EDGE_BACKGROUND` --- Change the background color of characters after column +-- Change the background color of text after column -- [`buffer.edge_column`](#edge_column) to -- [`buffer.edge_colour`](#edge_colour). -- @field encoding (string or nil) @@ -248,10 +250,12 @@ -- Disable scrolling past the last line. -- The default value is `true`. -- @field end_styled (number, Read-only) --- The last correctly styled character's position. +-- The current styling position or the last correctly styled character's +-- position. -- @field eol_mode (number) --- The current end of line mode. Changing the mode does not convert existing --- line endings. Use [`buffer:convert_eols()`](#convert_eols) to do so. +-- The current end of line mode. Changing the current mode does not convert +-- existing line endings. Use [`buffer:convert_eols()`](#convert_eols) to do +-- so. -- -- * `buffer.EOL_CRLF` -- Carriage return with line feed ("\r\n"). @@ -263,17 +267,17 @@ -- The default value is `buffer.EOL_CRLF` on Windows platforms, -- `buffer.EOL_LF` otherwise. -- @field extra_ascent (number) --- The amount of pixel padding above line text. +-- The amount of pixel padding above lines. -- The default value is `0`. -- @field extra_descent (number) --- The amount of pixel padding below line text. +-- The amount of pixel padding below lines. -- The default is `0`. -- @field filename (string) -- The absolute file path associated with the buffer. -- @field first_visible_line (number) -- The line number of the line at the top of the view, starting from zero. -- @field fold_expanded (table) --- Table of flags indicating whether or not folds are expanded for line +-- Table of flags indicating whether or not fold points are expanded for line -- numbers starting from zero. -- Setting expanded fold states does not toggle folds; it only updates fold -- margin markers. Use [`buffer:toggle_fold()`](#toggle_fold) instead. @@ -293,7 +297,7 @@ -- @field fold_level (table) -- Table of fold level bit-masks for line numbers starting from zero. -- Fold level masks comprise of an integer level combined with any of the --- following bits: +-- following bit flags: -- -- * `buffer.FOLDLEVELBASE` -- The initial fold level. @@ -302,8 +306,7 @@ -- * `buffer.FOLDLEVELHEADERFLAG` -- The line is a header, or fold point. -- @field fold_parent (table, Read-only) --- Table of parent line numbers (fold points) for child line numbers starting --- from zero. +-- Table of fold point line numbers for child line numbers starting from zero. -- A line number of `-1` means no line was found. -- @field h_scroll_bar (bool) -- Display the horizontal scroll bar. @@ -333,7 +336,7 @@ -- * `buffer.IV_LOOKFORWARD` -- Draw guides beyond the current line up to the next non-empty line's -- level, but with an additional level if the previous non-empty line is a --- fold header. +-- fold point. -- * `buffer.IV_LOOKBOTH` -- Draw guides beyond the current line up to either the level of the -- previous or next non-empty line, whichever is greater. @@ -424,9 +427,8 @@ -- Table of column indentation amounts, for line numbers starting from zero. -- @field line_state (table) -- Table of integer line states for line numbers starting from zero. --- Line states are used for storing longer lived parse states per line. They --- are available in addition to the 8 bits of styling information per --- character. +-- Line states are unaffected by changes in styling and are available in +-- addition to the 8 bits of styling information per character. -- @field line_visible (table, Read-only) -- Table of flags indicating whether or not lines are visible for line numbers -- starting from zero. @@ -449,8 +451,8 @@ -- The pixel size of the left margin of the buffer text. -- The default value is `1`. -- @field margin_mask_n (table) --- Table of bit-masks of markers that symbol margins can display for margin --- numbers from zero to four. +-- Table of bit-masks of markers whose symbols marker symbol margins can +-- display for margin numbers from zero to four. -- Bit-masks are 32-bit values whose bits correspond to the 32 available -- markers. -- The default values are `0`, `bit32.bnot(buffer.MASK_FOLDERS)`, `0`, `0`, @@ -494,14 +496,14 @@ -- Table of margin types for margin numbers from zero to four. -- -- * `buffer.MARGIN_SYMBOL` --- A symbol margin. +-- A marker symbol margin. -- * `buffer.MARGIN_NUMBER` -- A line number margin. -- * `buffer.MARGIN_BACK` --- A symbol margin whose background color matches the default text +-- A marker symbol margin whose background color matches the default text -- background color. -- * `buffer.MARGIN_FORE` --- A symbol margin whose foreground color matches the default text +-- A marker symbol margin whose foreground color matches the default text -- foreground color. -- * `buffer.MARGIN_TEXT` -- A text margin. @@ -560,8 +562,8 @@ -- @field punctuation_chars (string) -- The string set of characters recognized as punctuation characters. -- Set this only after setting [`buffer.word_chars`](#word_chars). --- The default value is a string containing all characters not considered to --- be whitespace or word characters. +-- The default value is a string containing all non-word and non-whitespace +-- characters. -- @field read_only (bool) -- Whether or not the buffer is read-only. -- The default value is `false`. @@ -574,7 +576,7 @@ -- @field rectangular_selection_caret_virtual_space (number) -- The amount of virtual space for the rectangular selection's caret. -- @field rectangular_selection_modifier (number) --- The modifier key used in combination with a mouse drag to create a +-- The modifier key used in combination with a mouse drag in order to create a -- rectangular selection. -- -- * `buffer.MOD_CTRL` @@ -587,17 +589,17 @@ -- -- The default value is `buffer.MOD_CTRL`. -- @field rgba_image_height (number) --- The height for the RGBA image to be defined using +-- The height of the RGBA image to be defined using -- [`buffer:marker_define_rgba_image()`](#marker_define_rgba_image). -- @field rgba_image_scale (number) --- The scale factor in percent for the RGBA image to be defined using +-- The scale factor in percent of the RGBA image to be defined using -- [`buffer:marker_define_rgba_image()`](#marker_define_rgba_image). -- This is useful on OSX with a retina display where each display unit is 2 -- pixels: use a factor of `200` so that each image pixel is displayed using a -- screen pixel. The default scale, `100`, will stretch each image pixel to -- cover 4 screen pixels on a retina display. -- @field rgba_image_width (number) --- The width for the RGBA image to be defined using +-- The width of the RGBA image to be defined using -- [`buffer:marker_define_rgba_image()`](#marker_define_rgba_image) and -- [`buffer:register_rgba_image()`](#register_rgba_image). -- @field scroll_width (number) @@ -609,8 +611,8 @@ -- [`buffer.scroll_width_tracking`](#scroll_width_tracking). -- The default value is `2000`. -- @field scroll_width_tracking (bool) --- Continuously update the scroll width to match the maximum width of a --- displayed line beyond [`buffer.scroll_width`](#scroll_width). +-- Continuously update the horizontal scrolling width to match the maximum +-- width of a displayed line beyond [`buffer.scroll_width`](#scroll_width). -- The default value is `false`. -- @field search_flags (number) -- The bit-mask of search flags used by @@ -714,15 +716,14 @@ -- @field style_at (table, Read-only) -- Table of style numbers at positions starting from zero. -- @field style_back (table) --- Table of background colors, in "0xBBGGRR" format, of text within styles for --- style numbers from `0` to `255`. +-- Table of background colors, in "0xBBGGRR" format, of text for style numbers +-- from `0` to `255`. -- @field style_bold (table) --- Table of flags indicating whether or not text within styles has a bold font --- face for style numbers from `0` to `255`. +-- Table of flags indicating whether or not text is bold for style numbers +-- from `0` to `255`. -- The default values are `false`. -- @field style_case (table) --- Table of letter case modes of text within styles for style numbers from `0` --- to `255`. +-- Table of letter case modes of text for style numbers from `0` to `255`. -- -- * `buffer.CASE_MIXED` -- Display text in normally. @@ -733,8 +734,8 @@ -- -- The default values are `buffer.CASE_MIXED`. -- @field style_changeable (table) --- Table of flags indicating whether or not text within styles is changeable --- for style numbers from `0` to `255`. +-- Table of flags indicating whether or not text is changeable for style +-- numbers from `0` to `255`. -- The default values are `true`. -- Currently, read-only styles do not allow the caret into the range of text, -- but ranges containing read-only text are deletable. @@ -744,34 +745,32 @@ -- margin for style numbers from `0` to `255`. -- The default values are `false`. -- @field style_font (table) --- Table of string font faces of text within styles for style numbers from --- `0` to `255`. +-- Table of string font names of text for style numbers from `0` to `255`. -- @field style_fore (table) --- Table of foreground colors, in "0xBBGGRR" format, of text within styles for --- style numbers from `0` to `255`. +-- Table of foreground colors, in "0xBBGGRR" format, of text for style numbers +-- from `0` to `255`. -- @field style_hot_spot (table) --- Table of flags indicating whether or not text within styles is clickable --- for style numbers from `0` to `255`. +-- Table of flags indicating whether or not text is clickable for style +-- numbers from `0` to `255`. -- The default values are `false`. -- @field style_italic (table) --- Table of flags indicating whether or not text within styles has an italic --- font face for style numbers from `0` to `255`. +-- Table of flags indicating whether or not text is italic for style numbers +-- from `0` to `255`. -- The default values are `false`. -- @field style_name (table, Read-only) -- Table of style names for style numbers from `0` to `255`. -- @field style_size (table) --- Table of font sizes of text within styles for style numbers from `0` to --- `255`. +-- Table of font sizes of text for style numbers from `0` to `255`. -- @field style_underline (table) --- Table of flags indicating whether or not text within styles has an --- underlined font face for style numbers from `0` to `255`. +-- Table of flags indicating whether or not text is underlined for style +-- numbers from `0` to `255`. -- The default values are `false`. -- @field style_visible (table) --- Table of flags indicating whether or not text within styles is visible for --- style numbers from `0` to `255`. +-- Table of flags indicating whether or not text is visible for style numbers +-- from `0` to `255`. -- The default values are `true`. -- @field tab_indents (bool) --- Tabbing indents within indentation. +-- Indent text when tabbing within indentation. -- The default value is `false`. -- @field tab_label (string) -- The buffer's tab label in the tab bar. @@ -779,7 +778,7 @@ -- The number of space characters represented by a tab character. -- The default value is `8`. -- @field tag (table, Read-only) --- List of values for tag match numbers from a regular expression search. +-- List of capture text for capture numbers from a regular expression search. -- @field target_end (number) -- The position of the end of the target range. -- This is also set by a successful @@ -800,8 +799,8 @@ -- the undo buffer with the buffer text. -- The default value is `true`. -- @field use_tabs (bool) --- Use tabs instead of spaces in indentation. Changing the setting does not --- convert existing indentation. Use +-- Use tabs instead of spaces in indentation. Changing the current setting +-- does not convert existing indentation. Use -- [`textadept.editing.convert_indentation()`][] to do so. -- The default value is `true`. -- @field v_scroll_bar (bool) @@ -811,14 +810,14 @@ -- Display end of line characters. -- The default value is `false`. -- @field view_ws (number) --- The whitespace character visibility mode. +-- The whitespace visibility mode. -- -- * `buffer.WS_INVISIBLE` -- Whitespace is invisible. -- * `buffer.WS_VISIBLEALWAYS` --- Display all whitespace as dots and arrows. +-- Display all space characters as dots and tab characters as arrows. -- * `buffer.WS_VISIBLEAFTERINDENT` --- Display only non-indentation whitespace as dots and arrows. +-- Display only non-indentation spaces and tabs as dots and arrows. -- -- The default value is `buffer.WS_INVISIBLE`. -- @field virtual_space_options (number) @@ -831,8 +830,8 @@ -- * `buffer.VS_USERACCESSIBLE` -- Enable virtual space. -- --- When virtual space is enabled, the caret may move into the space past the --- ends of lines. +-- When virtual space is enabled, the caret may move into the space past end +-- of line characters. -- The default value is `buffer.VS_NONE`. -- @field whitespace_chars (string) -- The string set of characters recognized as whitespace characters. @@ -853,9 +852,9 @@ -- * `buffer.WRAPINDENT_FIXED` -- Indent wrapped lines by [`buffer.wrap_start_indent`](#wrap_start_indent). -- * `buffer.WRAPINDENT_SAME` --- Indent wrapped lines the same as the first line. +-- Indent wrapped lines the same amount as the first line. -- * `buffer.WRAPINDENT_INDENT` --- Indent wrapped lines one more level than the first line. +-- Indent wrapped lines one more level than the level of the first line. -- -- The default value is `buffer.WRAPINDENT_FIXED`. -- @field wrap_mode (number) @@ -891,7 +890,7 @@ -- The wrapped line visual flag drawing mode. -- -- * `buffer.WRAPVISUALFLAGLOC_DEFAULT` --- Draw the visual flag near the right border. +-- Draw the visual flag near the view's right margin. -- * `buffer.WRAPVISUALFLAGLOC_END_BY_TEXT` -- Draw the visual flag near text at the end of the line. -- * `buffer.WRAPVISUALFLAGLOC_START_BY_TEXT` @@ -899,7 +898,7 @@ -- -- The default value is `buffer.WRAPVISUALFLAGLOC_DEFAULT`. -- @field x_offset (number) --- The horizontal scroll position in pixels. +-- The horizontal scroll pixel position. -- A value of `0` is the normal position with the first text column visible at -- the left of the view. -- @field zoom (number) @@ -952,7 +951,7 @@ function annotation_clear_all(buffer) end function append_text(buffer, text) end --- --- Returns whether or not the autocompletion or user list is visible. +-- Returns whether or not an autocompletion or user list is visible. -- @param buffer The buffer. -- @return bool function auto_c_active(buffer) end @@ -976,11 +975,10 @@ function auto_c_pos_start(buffer) end --- -- Selects the first item in the autocompletion or user list that starts with --- *string*, considering case sensitiveness based on --- `buffer.auto_c_ignore_case`. +-- string *prefix*, using case sensitivity setting `buffer.auto_c_ignore_case`. -- @param buffer The buffer. --- @param string The item in the list to select. -function auto_c_select(buffer, string) end +-- @param prefix The item in the list to select. +function auto_c_select(buffer, prefix) end --- -- Displays an autocompletion list constructed from string *item_list*, whose @@ -1075,7 +1073,7 @@ function call_tip_active(buffer) end function call_tip_cancel(buffer) end --- --- Returns the position where the call tip displayed at. +-- Returns the call tip's display position. -- @param buffer The buffer. -- @return number function call_tip_pos_start(buffer) end @@ -1091,8 +1089,8 @@ function call_tip_set_hlt(buffer, start_pos, end_pos) end --- -- Displays a call tip containing string *text* for the word behind position -- *pos*. --- Any "\001" or "\002" bytes in *text* are replaced by arrow visuals, --- indicating the word has more than one call tip. +-- Any "\001" or "\002" bytes in *text* are replaced by up or down arrow +-- visuals, respectively, indicating the word has more than one call tip. -- @param buffer The buffer. -- @param pos The position in *buffer* to show the call tip at. -- @param text The call tip text to show. @@ -1111,14 +1109,14 @@ function can_redo(buffer) end function can_undo(buffer) end --- --- Cancels the active call tip, autocompletion or user list, selection mode, +-- Cancels the active selection mode, autocompletion or user list, call tip, -- etc. -- @param buffer The buffer. function cancel(buffer) end --- -- Instructs the lexer to reprocess the range of text between *start_pos* and --- *end_pos*. +-- *end_pos* due to a change in state. -- @param buffer The buffer. -- @param start_pos The start position of the range of text in *buffer* to -- reprocess. @@ -1144,23 +1142,6 @@ function char_left_extend(buffer) end function char_left_rect_extend(buffer) end --- --- Returns the position closest to view coordinates *x* and *y*. --- @param buffer The buffer. --- @param x The x-coordinate in the view to use. --- @param y The y-coordinate in the view to use. --- @return number -function char_position_from_point(buffer, x, y) end - ---- --- Returns the position closest to view coordinates *x* and *y*, or `-1` if the --- point is outside the window or not close to any text. --- @param buffer The buffer. --- @param x The x-coordinate in the view to use. --- @param y The y-coordinate in the view to use. --- @return number -function char_position_from_point_close(buffer, x, y) end - ---- -- Moves the caret right one character. -- @param buffer The buffer. function char_right(buffer) end @@ -1222,8 +1203,8 @@ function clear_selections(buffer) end function colourise(buffer, start_pos, end_pos) end --- --- Returns the line number of the next contracted fold header line starting at --- *line_start*, or `-1`. +-- Returns the line number of the next contracted fold point starting at line +-- number *line_start*, or `-1`. -- @param buffer The buffer. -- @param line_start The line number in *buffer* to start at. -- @return number @@ -1266,7 +1247,8 @@ function copy_range(buffer, start_pos, end_pos) end function copy_text(buffer, text) end --- --- Returns the number of whole characters between positions *start_pos* and +-- Returns the number of whole characters, taking multi-byte characters into +-- account, between positions *start_pos* and -- *end_pos*. -- @param buffer The buffer. -- @param start_pos The start position of the range of text in *buffer* to start @@ -1382,31 +1364,20 @@ function empty_undo_buffer(buffer) end function end_undo_action(buffer) end --- --- Ensures line number *line* is visible by expanding any fold header lines --- hiding it. +-- Ensures line number *line* is visible by expanding any fold points hiding it. -- @param buffer The buffer. -- @param line The line number in *buffer* to ensure visible. function ensure_visible(buffer, line) end --- --- Ensures line number *line* is visible by expanding any fold header lines --- hiding it and applies the vertical caret policy set with +-- Ensures line number *line* is visible by expanding any fold points hiding it +-- based on the vertical caret policy previously defined in -- `buffer:set_visible_policy()`. -- @param buffer The buffer. -- @param line The line number in *buffer* to ensure visible. function ensure_visible_enforce_policy(buffer, line) end --- --- Expands the fold states of the fold header on line number *line* and its --- children with fold level *level*. --- @param buffer The buffer. --- @param line The line number in *buffer* to expand the folds for. --- @param level The previous fold level of *line*, not the current one. This is --- because this function is used to respond to changes in a line's fold level --- or fold header status, so a new fold level has already been set. -function expand_children(buffer, line, level) end - ---- -- Returns the position of column number *column* on line number *line*, taking -- tab and multi-byte characters into account, or the position at the end of -- line *line*. @@ -1416,9 +1387,8 @@ function expand_children(buffer, line, level) end function find_column(buffer, line, column) end --- --- Expands, contracts, or toggles the fold states of all fold headers, depending --- on *action*. --- When toggling, the state of the first fold header determines whether to +-- Expands, contracts, or toggles all fold points, depending on *action*. +-- When toggling, the state of the first fold point determines whether to -- expand or contract. -- @param buffer The buffer. -- @param action The fold action to perform. Valid values are: @@ -1428,8 +1398,8 @@ function find_column(buffer, line, column) end function fold_all(buffer, action) end --- --- Expands, contracts, or toggles the fold states of the fold header on line --- number *line* and its children, depending on *action*. +-- Expands, contracts, or toggles the fold point on line number *line* as well +-- as all of its children, depending on *action*. -- @param buffer The buffer. -- @param line The line number in *buffer* to set the fold states for. -- @param action The fold action to perform. Valid values are: @@ -1439,8 +1409,8 @@ function fold_all(buffer, action) end function fold_children(buffer, line, action) end --- --- Expands, contracts, or toggles the fold state of the fold header on line --- number *line*, depending on *action*. +-- Expands, contracts, or toggles the fold point on line number *line*, +-- depending on *action*. -- @param buffer The buffer. -- @param line The line number in *buffer* to set the fold state for. -- @param action The fold action to perform. Valid values are: @@ -1475,8 +1445,8 @@ function get_hotspot_active_fore(buffer) end --- -- Returns the line number of the last line after line number *start_line* whose --- fold level is greater than *level* or the level of *start_line* if *level* is --- `-1`. +-- fold level is greater than *level* or, if *level* is `-1`, the level of +-- *start_line*. -- @param buffer The buffer. -- @param start_line The line number in *buffer* of a header line. -- @param level The fold level, or `-1` for the level of *start_line*. @@ -1629,8 +1599,8 @@ function indicator_fill_range(buffer, pos, fill_length) end function indicator_start(buffer, indicator, pos) end --- --- Inserts string *text* at position *pos* or the caret position if *pos* is --- `-1`, removing any selections. +-- Inserts string *text* at position *pos*, removing any selections. +-- If *pos* is `-1`, inserts *text* at the caret position. -- If the caret is after the *pos*, it is moved appropriately, but not scrolled -- into view. -- @param buffer The buffer. @@ -1717,7 +1687,7 @@ function line_end_wrap(buffer) end function line_end_wrap_extend(buffer) end --- --- Returns the line number containing position *pos*. +-- Returns the line number of the line containing position *pos*. -- Returns `0` if *pos* is less than 0 or `buffer.line_count` if *pos* is -- greater than `buffer.length`. -- @param buffer The buffer. @@ -1726,7 +1696,7 @@ function line_end_wrap_extend(buffer) end function line_from_position(buffer, pos) end --- --- Returns the number of characters on line number *line*, including end of line +-- Returns the number of bytes on line number *line*, including end of line -- characters. -- To get line length excluding end of line characters, use -- `buffer.line_end_position[line] - buffer:position_from_line(line)`. @@ -1736,7 +1706,7 @@ function line_from_position(buffer, pos) end function line_length(buffer, line) end --- --- Scroll right *columns* columns and down *lines* lines. +-- Scrolls the buffer right *columns* columns and down *lines* lines. -- Negative values are allowed. -- @param buffer The buffer. -- @param columns The number of columns to scroll horizontally. @@ -1744,12 +1714,12 @@ function line_length(buffer, line) end function line_scroll(buffer, columns, lines) end --- --- Scroll the buffer down one line, keeping the caret visible. +-- Scrolls the buffer down one line, keeping the caret visible. -- @param buffer The buffer. function line_scroll_down(buffer) end --- --- Scroll the buffer up one line, keeping the caret visible. +-- Scrolls the buffer up one line, keeping the caret visible. -- @param buffer The buffer. function line_scroll_up(buffer) end @@ -1794,7 +1764,7 @@ function lines_split(buffer, pixel_width) end function lower_case(buffer) end --- --- Clears the text in text margins on all lines. +-- Clears all text in text margins. -- @param buffer The buffer. function margin_text_clear_all(buffer) end @@ -1810,8 +1780,8 @@ function margin_text_clear_all(buffer) end function marker_add(buffer, line, marker_num) end --- --- Adds the markers specified in the marker bit-mask *marker_mask* to line --- number *line*. +-- Adds the markers specified in marker bit-mask *marker_mask* to line number +-- *line*. -- The first bit is set to add marker number 0, the second bit for marker number -- 1, and so on up to marker number 31. -- @param buffer The buffer. @@ -1821,9 +1791,9 @@ function marker_add(buffer, line, marker_num) end function marker_add_set(buffer, line, marker_mask) end --- --- Associates marker number *marker_num*, in the range of `0` to `31`, with --- symbol *marker_symbol*. --- *marker_symbol* is shown in symbol margins next to lines marked with +-- Assigns marker symbol *marker_symbol* to marker number *marker_num*, in the +-- range of `0` to `31`. +-- *marker_symbol* is shown in marker symbol margins next to lines marked with -- *marker_num*. -- @param buffer The buffer. -- @param marker_num The marker number in the range of `0` to `31` to set @@ -1835,8 +1805,9 @@ function marker_define(buffer, marker_num, marker_symbol) end --- -- Associates marker number *marker_num*, in the range of `0` to `31`, with XPM -- image *pixmap*. --- The `buffer.MARK_PIXMAP` symbol must be associated with *marker_num*. --- The image is shown in symbol margins next to lines marked with *marker_num*. +-- The `buffer.MARK_PIXMAP` marker symbol must be assigned to *marker_num*. +-- The image is shown in marker symbol margins next to lines marked with +-- *marker_num*. -- @param buffer The buffer. -- @param marker_num The marker number in the range of `0` to `31` to define -- pixmap *pixmap* for. @@ -1850,7 +1821,7 @@ function marker_define_pixmap(buffer, marker_num, pixmap) end -- `buffer.rgba_image_height`, must have already been defined. *pixels* is a -- sequence of 4 byte pixel values (red, blue, green, and alpha) defining the -- image line by line starting at the top-left pixel. --- The `buffer.MARK_RGBAIMAGE` symbol must be associated with *marker_num*. +-- The `buffer.MARK_RGBAIMAGE` marker symbol must be assigned to *marker_num*. -- The image is shown in symbol margins next to lines marked with *marker_num*. -- RGBA image markers use the `buffer.MARK_RGBAIMAGE` marker symbol. -- @param buffer The buffer. @@ -1915,7 +1886,7 @@ function marker_get(buffer, line) end function marker_line_from_handle(buffer, handle) end --- --- Returns the first line number starting at line number *start_line* that has +-- Returns the first line number, starting at line number *start_line*, that has -- had all of the markers represented by marker bit-mask *marker_mask* added to -- it, or `-1` if no line was found. -- Bit 0 is set if marker 0 is set, bit 1 for marker 1, etc., up to marker 31. @@ -1927,7 +1898,7 @@ function marker_line_from_handle(buffer, handle) end function marker_next(buffer, start_line, marker_mask) end --- --- Returns the last line number before or on line number *start_line* that has +-- Returns the last line number, before or on line number *start_line*, that has -- had all of the markers represented by marker bit-mask *marker_mask* added to -- it, or `-1` if no line was found. -- Bit 0 is set if marker 0 is set, bit 1 for marker 1, etc., up to marker 31. @@ -1939,7 +1910,7 @@ function marker_next(buffer, start_line, marker_mask) end function marker_previous(buffer, start_line, marker_mask) end --- --- Returns the symbol defined for marker number *marker_num*, in the range of +-- Returns the symbol assigned to marker number *marker_num*, in the range of -- `0` to `31`, used in `buffer:marker_define()`, -- `buffer:marker_define_pixmap()`, or `buffer:marker_define_rgba_image()`. -- @param buffer The buffer. @@ -2035,22 +2006,8 @@ function para_up_extend(buffer) end function paste(buffer) end --- --- Returns the x-coordinate in the view of position *pos*. --- @param buffer The buffer. --- @param pos The position in *buffer* to get the x-coordinate in the view of. --- @return number -function point_x_from_position(buffer, pos) end - ---- --- Returns the y-coordinate in the view of position *pos*. --- @param buffer The buffer. --- @param pos The position in *buffer* to get the y-coordinate in the view of. --- @return number -function point_y_from_position(buffer, pos) end - ---- -- Returns the position of the next character after position *pos*, taking --- multi-byte characters into account, or `buffer.length - 1`. +-- multi-byte characters into account, or `buffer.length`. -- @param buffer The buffer. -- @param pos The position in *buffer* to get the position after from. function position_after(buffer, pos) end @@ -2110,8 +2067,8 @@ function release_all_extended_styles(buffer) end function replace_sel(buffer, text) end --- --- Replaces the text in the target range with string *text* without modifying --- any selections or scrolling the view. +-- Replaces the text in the target range with string *text* sans modifying any +-- selections or scrolling the view. -- Setting the target and calling this function with an empty string is another -- way to delete text. -- @param buffer The buffer. @@ -2121,7 +2078,7 @@ function replace_target(buffer, text) end --- -- Replaces the text in the target range with string *text* but first replaces --- any "\d" sequences with the value of tag match number *d* from the regular +-- any "\d" sequences with the text of capture number *d* from the regular -- expression (or the entire match for *d* = 0), and then returns the -- replacement text's length. -- @param buffer The buffer. @@ -2135,7 +2092,7 @@ function replace_target_re(buffer, text) end function rotate_selection(buffer) end --- --- Scrolls the caret into view based on the policies set with +-- Scrolls the caret into view based on the policies previously defined in -- `buffer:set_x_caret_policy()` and `buffer:set_y_caret_policy()`. -- @param buffer The buffer. -- @see set_x_caret_policy @@ -2231,7 +2188,8 @@ function set_chars_default(buffer) end function set_empty_selection(buffer, pos) end --- --- Overrides the fold margin's default color with *color*, in "0xBBGGRR" format, +-- Overrides the fold margin's default color with color *color*, in "0xBBGGRR" +-- format, -- if *use_setting* is `true`. -- @param buffer The buffer. -- @param use_setting Whether or not to use *color*. @@ -2239,7 +2197,7 @@ function set_empty_selection(buffer, pos) end function set_fold_margin_colour(buffer, use_setting, color) end --- --- Overrides the fold margin's default highlight color with *color*, in +-- Overrides the fold margin's default highlight color with color *color*, in -- "0xBBGGRR" format, if *use_setting* is `true`. -- @param buffer The buffer. -- @param use_setting Whether or not to use *color*. @@ -2247,16 +2205,16 @@ function set_fold_margin_colour(buffer, use_setting, color) end function set_fold_margin_hi_colour(buffer, use_setting, color) end --- --- Overrides the default background color of active hotspots with *color*, in --- "0xBBGGRR" format, if *use_setting* is `true`. +-- Overrides the default background color of active hotspots with color *color*, +-- in "0xBBGGRR" format, if *use_setting* is `true`. -- @param buffer The buffer. -- @param use_setting Whether or not to use *color*. -- @param color The color in "0xBBGGRR" format. function set_hotspot_active_back(buffer, use_setting, color) end --- --- Overrides the default foreground color of active hotspots with *color*, in --- "0xBBGGRR" format, if *use_setting* is `true`. +-- Overrides the default foreground color of active hotspots with color *color*, +-- in "0xBBGGRR" format, if *use_setting* is `true`. -- @param buffer The buffer. -- @param use_setting Whether or not to use *color*. -- @param color The color in "0xBBGGRR" format. @@ -2279,7 +2237,7 @@ function set_save_point(buffer) end function set_sel(buffer, start_pos, end_pos) end --- --- Overrides the selection's default background color with *color*, in +-- Overrides the selection's default background color with color *color*, in -- "0xBBGGRR" format, if *use_setting* is `true`. -- @param buffer The buffer. -- @param use_setting Whether or not to use *color*. @@ -2287,7 +2245,7 @@ function set_sel(buffer, start_pos, end_pos) end function set_sel_back(buffer, use_setting, color) end --- --- Overrides the selection's default foreground color with *color*, in +-- Overrides the selection's default foreground color with color *color*, in -- "0xBBGGRR" format, if *use_setting* is `true`. -- @param buffer The buffer. -- @param use_setting Whether or not to use *color*. @@ -2319,9 +2277,9 @@ function set_styling(buffer, length, style) end function set_text(buffer, text) end --- --- Sets the visible policy bit-mask *visible_policy* for displaying lines using --- `buffer:ensure_visible_enforce_policy()` to *visible_slop* number of lines --- from the bottom of the view. +-- Sets the visible policy bit-mask *visible_policy* to *visible_slop* number of +-- lines away from the vertical margins when redisplaying hidden or folded lines +-- using `buffer:ensure_visible_enforce_policy()`. -- It is similar in operation to `buffer:set_y_caret_policy()`. -- @param buffer The buffer. -- @param visible_policy The combination of `buffer.VISIBLE_SLOP` and @@ -2330,16 +2288,16 @@ function set_text(buffer, text) end function set_visible_policy(buffer, visible_policy, visible_slop) end --- --- Overrides the background color of whitespace with *color*, in "0xBBGGRR" --- format, if *use_setting* is `true`. +-- Overrides the background color of whitespace with color *color*, in +-- "0xBBGGRR" format, if *use_setting* is `true`. -- @param buffer The buffer. -- @param use_setting Whether or not to use *color*. -- @param color The color in "0xBBGGRR" format. function set_whitespace_back(buffer, use_setting, color) end --- --- Overrides the foreground color of whitespace with *color*, in "0xBBGGRR" --- format, if *use_setting* is `true`. +-- Overrides the foreground color of whitespace with color *color*, in +-- "0xBBGGRR" format, if *use_setting* is `true`. -- @param use_setting Whether or not to use *color*. -- @param color The color in "0xBBGGRR" format. function set_whitespace_fore(buffer, use_setting, color) end @@ -2449,16 +2407,16 @@ function text_height(buffer, line) end function text_width(buffer, style_num, text) end --- --- Cycles between caret sticky option settings `buffer.CARETSTICKY_ON`, +-- Cycles between `buffer.caret_sticky` option settings `buffer.CARETSTICKY_ON`, -- `buffer.CARETSTICKY_WHITESPACE`, and `buffer.CARETSTICKY_OFF`. -- @param buffer The buffer. -- @see caret_sticky function toggle_caret_sticky(buffer) end --- --- Toggles the fold state of the fold header on line number *line* between --- expanded, where all of its child lines are displayed, and contracted, where --- all of its child lines are hidden. +-- Toggles the fold point on line number *line* between expanded, where all of +-- its child lines are displayed, and contracted, where all of its child lines +-- are hidden. -- @param buffer The buffer. -- @param line The line number in *buffer* to toggle the fold on. function toggle_fold(buffer, line) end @@ -2652,7 +2610,8 @@ function word_right_extend(buffer) end function word_start_position(buffer, pos, only_word_chars) end --- --- Returns the number of wrapped lines needed to display line number *line*. +-- Returns the number of wrapped lines needed to fully display line number +-- *line*. -- @param buffer The buffer. -- @param line The line number in *buffer* to use. -- @return number @@ -2703,8 +2662,8 @@ function text_range(buffer, start_pos, end_pos) end function get_lexer(buffer, current) end --- --- Associates lexer name *lexer* or auto-detected lexer name with the buffer and --- then loads the appropriate language module if the module exists. +-- Associates lexer name *lexer* or the auto-detected lexer name with the buffer +-- and then loads the appropriate language module if the module exists. -- @param buffer The buffer. -- @param lexer Optional string lexer name to set. If `nil`, attempts to -- auto-detect the buffer's lexer. @@ -2766,6 +2725,8 @@ function set_lexer(buffer, lexer) end -- * allocate_sub_styles+ -- * assign_cmd_key -- * can_paste +-- * char_position_from_point +-- * char_position_from_point_close -- * clear_cmd_key -- * clear_all_cmd_keys -- * create_document @@ -2773,6 +2734,7 @@ function set_lexer(buffer, lexer) end -- * describe_key_word_sets -- * describe_property -- * encoded_from_utf8 +-- * expand_children -- * find_indicator_flash -- * find_indicator_hide -- * find_indicator_show @@ -2785,6 +2747,8 @@ function set_lexer(buffer, lexer) end -- * indicator_value_at -- * load_lexer_library -- * null +-- * point_x_from_position +-- * point_y_from_position -- * position_from_point -- * position_from_point_close -- * private_lexer_call diff --git a/core/.ui.dialogs.luadoc b/core/.ui.dialogs.luadoc index 67c36b2f..91ea5e4c 100644 --- a/core/.ui.dialogs.luadoc +++ b/core/.ui.dialogs.luadoc @@ -27,14 +27,14 @@ module('ui.dialogs') -- * `button3`: The left-most button's label. This option requires `button2` -- to be set. -- * `string_output`: Return the selected button's label or the dialog's exit --- status instead of the button's index or the exit code. The default value --- is `false`. +-- status instead of the button's index or the dialog's exit code. The +-- default value is `false`. -- * `width`: The dialog's pixel width. -- * `height`: The dialog's pixel height. -- * `float`: Show the dialog on top of all desktop windows. The default value -- is `false`. --- * `timeout`: The number of seconds the dialog waits for the user to select --- a button before timing out. Dialogs do not time out by default. +-- * `timeout`: The integer number of seconds the dialog waits for the user to +-- select a button before timing out. Dialogs do not time out by default. -- @return selected button or exit code -- @usage ui.dialogs.msgbox{title = 'EOL Mode', text = 'Which EOL?', -- icon = 'gtk-dialog-question', button1 = 'CRLF', button2 = 'CR', @@ -61,14 +61,14 @@ function msgbox(options) end -- * `no_cancel`: Do not display the "Cancel" button. The default value is -- `false`. -- * `string_output`: Return the selected button's label or the dialog's exit --- status instead of the button's index or the exit code. The default value --- is `false`. +-- status instead of the button's index or the dialog's exit code. The +-- default value is `false`. -- * `width`: The dialog's pixel width. -- * `height`: The dialog's pixel height. -- * `float`: Show the dialog on top of all desktop windows. The default value -- is `false`. --- * `timeout`: The number of seconds the dialog waits for the user to select --- a button before timing out. Dialogs do not time out by default. +-- * `timeout`: the integer number of seconds the dialog waits for the user to +-- select a button before timing out. Dialogs do not time out by default. -- @return selected button or exit code function ok_msgbox(options) end @@ -92,14 +92,14 @@ function ok_msgbox(options) end -- * `no_cancel`: Do not display the "Cancel" button. The default value is -- `false`. -- * `string_output`: Return the selected button's label or the dialog's exit --- status instead of the button's index or the exit code. The default value --- is `false`. +-- status instead of the button's index or the dialog's exit code. The +-- default value is `false`. -- * `width`: The dialog's pixel width. -- * `height`: The dialog's pixel height. -- * `float`: Show the dialog on top of all desktop windows. The default value -- is `false`. --- * `timeout`: The number of seconds the dialog waits for the user to select --- a button before timing out. Dialogs do not time out by default. +-- * `timeout`: the integer number of seconds the dialog waits for the user to +-- select a button before timing out. Dialogs do not time out by default. -- @return selected button or exit code function yesno_msgbox(options) end @@ -121,14 +121,14 @@ function yesno_msgbox(options) end -- * `button3`: The left-most button's label. This option requires `button2` -- to be set. -- * `string_output`: Return the selected button's label or the dialog's exit --- status instead of the button's index or the exit code. The default value --- is `false`. +-- status instead of the button's index or the dialog's exit code. The +-- default value is `false`. -- * `width`: The dialog's pixel width. -- * `height`: The dialog's pixel height. -- * `float`: Show the dialog on top of all desktop windows. The default value -- is `false`. --- * `timeout`: The number of seconds the dialog waits for the user to select --- a button before timing out. Dialogs do not time out by default. +-- * `timeout`: the integer number of seconds the dialog waits for the user to +-- select a button before timing out. Dialogs do not time out by default. -- @return selected button or exit code, input text -- @usage ui.dialogs.inputbox{title = 'Goto Line', informative_text = 'Line:', -- text = '1'} @@ -150,14 +150,14 @@ function inputbox(options) end -- * `no_cancel`: Do not display the "Cancel" button. The default value is -- `false`. -- * `string_output`: Return the selected button's label or the dialog's exit --- status instead of the button's index or the exit code. The default value --- is `false`. +-- status instead of the button's index or the dialog's exit code. The +-- default value is `false`. -- * `width`: The dialog's pixel width. -- * `height`: The dialog's pixel height. -- * `float`: Show the dialog on top of all desktop windows. The default value -- is `false`. --- * `timeout`: The number of seconds the dialog waits for the user to select --- a button before timing out. Dialogs do not time out by default. +-- * `timeout`: the integer number of seconds the dialog waits for the user to +-- select a button before timing out. Dialogs do not time out by default. -- @return selected button or exit code, input text function standard_inputbox(options) end @@ -179,14 +179,14 @@ function standard_inputbox(options) end -- * `button3`: The left-most button's label. This option requires `button2` -- to be set. -- * `string_output`: Return the selected button's label or the dialog's exit --- status instead of the button's index or the exit code. The default value --- is `false`. +-- status instead of the button's index or the dialog's exit code. The +-- default value is `false`. -- * `width`: The dialog's pixel width. -- * `height`: The dialog's pixel height. -- * `float`: Show the dialog on top of all desktop windows. The default value -- is `false`. --- * `timeout`: The number of seconds the dialog waits for the user to select --- a button before timing out. Dialogs do not time out by default. +-- * `timeout`: the integer number of seconds the dialog waits for the user to +-- select a button before timing out. Dialogs do not time out by default. -- @return selected button or exit code, input text function secure_inputbox(options) end @@ -206,14 +206,14 @@ function secure_inputbox(options) end -- * `no_cancel`: Do not display the "Cancel" button. The default value is -- `false`. -- * `string_output`: Return the selected button's label or the dialog's exit --- status instead of the button's index or the exit code. The default value --- is `false`. +-- status instead of the button's index or the dialog's exit code. The +-- default value is `false`. -- * `width`: The dialog's pixel width. -- * `height`: The dialog's pixel height. -- * `float`: Show the dialog on top of all desktop windows. The default value -- is `false`. --- * `timeout`: The number of seconds the dialog waits for the user to select --- a button before timing out. Dialogs do not time out by default. +-- * `timeout`: the integer number of seconds the dialog waits for the user to +-- select a button before timing out. Dialogs do not time out by default. -- @return selected button or exit code, input text function secure_standard_inputbox(options) end @@ -256,12 +256,11 @@ function filesave(options) end --- -- Prompts the user with a multiple-line textbox dialog defined by dialog --- options table *options*, returning the selected button's index along with the --- textbox text if *options*.`editable` is `true` or, if --- *options*.`string_output` is `true`, the selected button's label along with --- the textbox text if *options*.`editable` is also `true`. --- If the dialog timed out, returns `0` or `"timeout"`. If the user canceled the --- dialog, returns `-1` or `"delete"`. +-- options table *options*, returning the selected button's index or, if +-- *options*.`string_output` is `true`, the selected button's label. If +-- *options*.`editable` is `true`, also returns the textbox text. If the dialog +-- timed out, returns `0` or `"timeout"`. If the user canceled the dialog, +-- returns `-1` or `"delete"`. -- @param options Table of key-value option pairs for the dialog. -- -- * `title`: The dialog's title text. @@ -274,25 +273,26 @@ function filesave(options) end -- * `button2`: The middle button's label. -- * `button3`: The left-most button's label. This option requires `button2` -- to be set. --- * `editable`: Allows the user to edit the text in the textbox. The default +-- * `editable`: Allows the user to edit the textbox's text. The default value +-- is `false`. +-- * `focus_textbox`: Focus the textbox instead of the buttons. The default -- value is `false`. --- * `focus_textbox`: Focus the textbox instead of the dialog buttons. The --- default value is `false`. -- * `scroll_to`: Where to scroll the textbox text when it is not all visible. -- The available values are `"top"` and `"bottom"`. The default value is -- `"top"`. --- * `selected`: Select all textbox text. The default value is `false`. +-- * `selected`: Select all of the textbox's text. The default value is +-- `false`. -- * `monospaced_font`: Use a monospaced font in the textbox instead of a -- proportional one. The default value is `false`. -- * `string_output`: Return the selected button's label or the dialog's exit --- status instead of the button's index or the exit code. The default value --- is `false`. +-- status instead of the button's index or the dialog's exit code. The +-- default value is `false`. -- * `width`: The dialog's pixel width. -- * `height`: The dialog's pixel height. -- * `float`: Show the dialog on top of all desktop windows. The default value -- is `false`. --- * `timeout`: The number of seconds the dialog waits for the user to select --- a button before timing out. Dialogs do not time out by default. +-- * `timeout`: the integer number of seconds the dialog waits for the user to +-- select a button before timing out. Dialogs do not time out by default. -- @return selected button or exit code, textbox text -- @usage ui.dialogs.textbox{title = 'License Agreement', -- informative_text = 'You agree to:', text_from_file = _HOME..'/LICENSE'} @@ -323,14 +323,14 @@ function textbox(options) end -- value is `1`. -- * `string_output`: Return the selected button's label or the dialog's exit -- status along with the selected item's text instead of the button's index --- or the exit code along with the item's index. The default value is --- `false`. +-- or the dialog's exit code along with the item's index. The default value +-- is `false`. -- * `width`: The dialog's pixel width. -- * `height`: The dialog's pixel height. -- * `float`: Show the dialog on top of all desktop windows. The default value -- is `false`. --- * `timeout`: The number of seconds the dialog waits for the user to select --- a button before timing out. Dialogs do not time out by default. +-- * `timeout`: the integer number of seconds the dialog waits for the user to +-- select a button before timing out. Dialogs do not time out by default. -- @return selected button or exit code, selected item -- @usage ui.dialogs.dropdown{title = 'Select Encoding', width = 200, -- items = io.encodings, string_output = true} @@ -359,14 +359,14 @@ function dropdown(options) end -- value is `1`. -- * `string_output`: Return the selected button's label or the dialog's exit -- status along with the selected item's text instead of the button's index --- or the exit code along with the item's index. The default value is --- `false`. +-- or the dialog's exit code along with the item's index. The default value +-- is `false`. -- * `width`: The dialog's pixel width. -- * `height`: The dialog's pixel height. -- * `float`: Show the dialog on top of all desktop windows. The default value -- is `false`. --- * `timeout`: The number of seconds the dialog waits for the user to select --- a button before timing out. Dialogs do not time out by default. +-- * `timeout`: the integer number of seconds the dialog waits for the user to +-- select a button before timing out. Dialogs do not time out by default. -- @return selected button or exit code, selected item function standard_dropdown(options) end @@ -401,14 +401,14 @@ function standard_dropdown(options) end -- contain at least *n* column names. -- * `string_output`: Return the selected button's label or the dialog's exit -- status along with the selected item's text instead of the button's index --- or the exit code along with the item's index. The default value is --- `false`. +-- or the dialog's exit code along with the item's index. The default value +-- is `false`. -- * `width`: The dialog's pixel width. -- * `height`: The dialog's pixel height. -- * `float`: Show the dialog on top of all desktop windows. The default value -- is `false`. --- * `timeout`: The number of seconds the dialog waits for the user to select --- a button before timing out. Dialogs do not time out by default. +-- * `timeout`: the integer number of seconds the dialog waits for the user to +-- select a button before timing out. Dialogs do not time out by default. -- @return selected button or exit code, selected item or list of selected items -- @usage ui.dialogs.filteredlist{title = 'Title', columns = {'Foo', 'Bar'}, -- items = {'a', 'b', 'c', 'd'}} diff --git a/core/events.lua b/core/events.lua index 796c027d..babc9f0d 100644 --- a/core/events.lua +++ b/core/events.lua @@ -71,7 +71,7 @@ local M = {} -- -- * _`byte`_: The text character's byte. -- @field COMMAND_ENTRY_KEYPRESS (string) --- Emitted when pressing a key in the Command Entry. +-- Emitted when pressing a key in the command entry. -- If any handler returns `true`, the key is not inserted into the entry. -- Arguments: -- @@ -141,8 +141,8 @@ local M = {} -- `buffer.MOD_CTRL`, the "Control" modifier is reported as *both* "Control" -- and "Alt" due to a Scintilla limitation with GTK+. -- @field HOTSPOT_RELEASE_CLICK (string) --- Emitted after releasing the mouse after clicking on text that was in a --- style with the hotspot attribute set. +-- Emitted when releasing the mouse after clicking on text that is in a style +-- with the hotspot attribute set. -- Arguments: -- -- * _`position`_: The clicked text's position. @@ -199,13 +199,13 @@ local M = {} -- Emitted to replace selected (found) text. -- Arguments: -- --- * _`text`_: The text to replace the selected text with. +-- * _`text`_: The replacement text. -- @field REPLACE_ALL (string) -- Emitted to replace all occurrences of found text. -- Arguments: -- -- * _`find_text`_: The text to search for. --- * _`repl_text`_: The text to replace found text with. +-- * _`repl_text`_: The replacement text. -- @field RESET_AFTER (string) -- Emitted after resetting the Lua state. -- Emitted by [`reset()`][]. @@ -220,12 +220,12 @@ local M = {} -- Emitted when buffer content, styling, selection, or scroll position -- changes. -- @field URI_DROPPED (string) --- Emitted after dragging and dropping a URI into the view. +-- Emitted after dragging and dropping a URI into a view. -- Arguments: -- -- * _`text`_: The UTF-8-encoded URI dropped. -- @field USER_LIST_SELECTION (string) --- Emitted after selecting an item in a user list. +-- Emitted after selecting an item in the user list. -- Arguments: -- -- * _`list_type`_: The *list_type* from [`buffer:user_list_show()`][]. diff --git a/core/file_io.lua b/core/file_io.lua index cfd0967f..3353f962 100644 --- a/core/file_io.lua +++ b/core/file_io.lua @@ -4,7 +4,7 @@ --- -- Extends Lua's `io` library with Textadept functions for working with files. -- @field _G.events.FILE_OPENED (string) --- Emitted when opening a file in a new buffer. +-- Emitted after opening a file in a new buffer. -- Emitted by [`open_file()`](#open_file). -- Arguments: -- @@ -91,8 +91,8 @@ io.boms = { io.encodings = {'UTF-8', 'ASCII', 'ISO-8859-1', 'MacRoman'} --- --- Opens *filenames*, a string filename or table of provided or user-selected --- filenames. +-- Opens *filenames*, a string filename or list of filenames, or the +-- user-selected filenames. -- Emits a `FILE_OPENED` event. -- @param filenames Optional string filename or table of filenames to open. If -- `nil`, the user is prompted with a fileselect dialog. @@ -229,7 +229,7 @@ function io.save_file() end --- --- Saves the current buffer to file *filename* or user-specified filename. +-- Saves the current buffer to file *filename* or the user-specified filename. -- Emits a `FILE_SAVED_AS` event. -- @param filename Optional new filepath to save the buffer to. If `nil`, the -- user is prompted for one. @@ -280,8 +280,8 @@ function io.close_buffer() end --- --- Closes all open buffers, prompting the user to continue with unsaved buffers, --- and returning `true` if the user did not cancel. +-- Closes all open buffers, prompting the user to continue if there are unsaved +-- buffers, and returns `true` if the user did not cancel. -- No buffers are saved automatically. They must be saved manually. -- @return `true` if user did not cancel. -- @see io.close_buffer @@ -343,19 +343,19 @@ end --- -- Prompts the user to select files to open from *paths*, a string directory --- path or table of directory paths, using a filtered list dialog. +-- path or list of directory paths, using a filtered list dialog. -- Files shown in the dialog do not match any pattern in string or table -- *filter*, and, unless *exclude_FILTER* is `true`, `lfs.FILTER` as well. A -- filter table contains Lua patterns that match filenames to exclude, an --- optional `folders` sub-table that contains patterns matching folders to +-- optional `folders` sub-table that contains patterns matching directories to -- exclude, and an optional `extensions` sub-table that contains raw file -- extensions to exclude. Any patterns starting with '!' exclude files and --- folders that do not match the pattern that follows. The number of files in --- the list is capped at `SNAPOPEN_MAX`. +-- directories that do not match the pattern that follows. The number of files +-- in the list is capped at `SNAPOPEN_MAX`. -- *opts* is an optional table of additional options for -- `ui.dialogs.filteredlist()`. -- @param paths String directory path or table of directory paths to search. --- @param filter Optional filter for files and folders to exclude. +-- @param filter Optional filter for files and directories to exclude. -- @param exclude_FILTER Optional flag indicating whether or not to exclude the -- default filter `lfs.FILTER` in the search. If `false`, adds `lfs.FILTER` to -- *filter*. diff --git a/core/init.lua b/core/init.lua index e38b031a..7314ae01 100644 --- a/core/init.lua +++ b/core/init.lua @@ -113,9 +113,9 @@ local quit local reset --- --- Calls function *f* with the given arguments after *interval* seconds and then --- repeatedly while *f* returns `true`. A `nil` or `false` return value stops --- repetition. +-- Calls function *f* with the given arguments after number *interval* seconds +-- and then repeatedly while *f* returns `true`. A `nil` or `false` return value +-- stops repetition. -- @param interval The interval in seconds to call *f* after. -- @param f The function to call. -- @param ... Additional arguments to pass to *f*. diff --git a/core/lfs_ext.lua b/core/lfs_ext.lua index 633aee50..1c19e389 100644 --- a/core/lfs_ext.lua +++ b/core/lfs_ext.lua @@ -7,7 +7,7 @@ module('lfs')]] --- -- The filter table containing common binary file extensions and version control --- folders to exclude when iterating over files and directories using +-- directories to exclude when iterating over files and directories using -- `dir_foreach` when its `exclude_FILTER` argument is `false`. -- @see dir_foreach -- @class table @@ -41,18 +41,18 @@ end --- -- Iterates over all files and sub-directories in directory *dir*, calling --- function *f* on each file found. --- Files *f* is called on do not match any pattern in string or table *filter*, +-- function *f* with each file found. +-- Files passed to *f* do not match any pattern in string or table *filter*, -- and, unless *exclude_FILTER* is `true`, `FILTER` as well. A filter table -- contains Lua patterns that match filenames to exclude, an optional `folders` --- sub-table that contains patterns matching folders to exclude, and an optional --- `extensions` sub-table that contains raw file extensions to exclude. Any --- patterns starting with '!' exclude files and folders that do not match the --- pattern that follows. +-- sub-table that contains patterns matching directories to exclude, and an +-- optional `extensions` sub-table that contains raw file extensions to exclude. +-- Any patterns starting with '!' exclude files and directories that do not +-- match the pattern that follows. -- @param dir The directory path to iterate over. -- @param f Function to call with each full file path found. If *f* returns -- `false` explicitly, iteration ceases. --- @param filter Optional filter for files and folders to exclude. +-- @param filter Optional filter for files and directories to exclude. -- @param exclude_FILTER Optional flag indicating whether or not to exclude the -- default filter `FILTER` in the search. If `false`, adds `FILTER` to -- *filter*. diff --git a/core/ui.lua b/core/ui.lua index 03a0adcf..201ed1ea 100644 --- a/core/ui.lua +++ b/core/ui.lua @@ -140,7 +140,7 @@ end -- Switches to the buffer whose filename is *filename* in an existing view, -- otherwise splitting the current view if *split* is `true` or shifting to the -- next or *preferred_view* view instead of staying in the current one. --- *sloppy* indicates whether or not only the last part of *filename* is matched +-- *sloppy* indicates whether or not to only match the last part of *filename* -- to a buffer's `filename`. -- @param filename The filename of the buffer to go to. -- @param split Optional flag indicating whether or not to open the buffer in a @@ -177,7 +177,7 @@ function ui.goto_file(filename, split, preferred_view, sloppy) end --- --- Switches the editor theme to name *name* and optionally assigns the +-- Switches the editor theme to string *name* and optionally assigns the -- properties contained in table *props*. -- User themes override Textadept's default themes when they have the same name. -- If *name* contains slashes, it is assumed to be an absolute path to a theme @@ -406,7 +406,7 @@ The functions below are Lua C functions. local dialog --- --- Returns the current split view structure. +-- Returns a split table containing Textadept's current split view structure. -- This is primarily used in session saving. -- @return table of split views. Each split view entry is a table with 4 -- fields: `1`, `2`, `vertical`, and `size`. `1` and `2` have values of either |