Added `textadept.editing.auto_enclose` for auto-enclosing selected text.

3 files changed, 33 insertions, 17 deletions

diff --git a/modules/lua/ta_api b/modules/lua/ta_api
index dff6ecd6..e5706b26 100644
--- a/modules/lua/ta_api
+++ b/modules/lua/ta_api
@@ -5,7 +5,7 @@ ANNOTATION_BOXED view.ANNOTATION_BOXED (number, Read-only)\n
 ANNOTATION_HIDDEN view.ANNOTATION_HIDDEN (number, Read-only)\n
 ANNOTATION_INDENTED view.ANNOTATION_INDENTED (number, Read-only)\n
 ANNOTATION_STANDARD view.ANNOTATION_STANDARD (number, Read-only)\n
-APPLEEVENT_ODOC events.APPLEEVENT_ODOC (string)\nEmitted when Mac OSX tells Textadept to open a file.\nArguments:\n\n* _`uri`_: The UTF-8-encoded URI to open.
+APPLEEVENT_ODOC events.APPLEEVENT_ODOC (string)\nEmitted when macOS tells Textadept to open a file.\nArguments:\n\n* _`uri`_: The UTF-8-encoded URI to open.
 ARG_NONE events.ARG_NONE (string)\nEmitted when no command line arguments are passed to Textadept on startup.
 AUTO_C_CANCELED events.AUTO_C_CANCELED (string)\nEmitted when canceling an autocompletion or user list.
 AUTO_C_CHAR_DELETED events.AUTO_C_CHAR_DELETED (string)\nEmitted after deleting a character while an autocompletion or user list is\nactive.
@@ -65,7 +65,7 @@ DEBUGGER_WATCH_ADDED events.DEBUGGER_WATCH_ADDED (string)\nEmitted when a watch
 DEBUGGER_WATCH_REMOVED events.DEBUGGER_WATCH_REMOVED (string)\nEmitted when a breakpoint is removed.\nThis is only emitted when the debugger is running and paused (e.g. at a\nbreakpoint).\nArguments:\n\n* _`lang`_: The lexer name of the language being debugged.\n* _`expr`_: The expression to stop watching.\n* _`id`_: The expression's ID number.
 DEFAULT lexer.DEFAULT (string)\nThe token name for default tokens.
 DOCUTILS_PATH _M.rest.DOCUTILS_PATH (string)\nThe absolute path to the directory that contains the Python Docutils\nlibrary if it is not in the environment's `PYTHONPATH`.\nThe default value is `nil`, which indicates Docutils is installed.
-DOUBLE_CLICK events.DOUBLE_CLICK (string)\nEmitted after double-clicking the mouse button.\nArguments:\n\n* _`position`_: The position double-clicked.\n* _`line`_: The line number of the position double-clicked.\n* _`modifiers`_: A bit-mask of any modifier keys used: `view.MOD_CTRL`,\n  `view.MOD_SHIFT`, `view.MOD_ALT`, and `view.MOD_META`.\n  On Mac OSX, the Command modifier key is reported as `view.MOD_CTRL` and\n  Ctrl is `view.MOD_META`.\n  Note: If you set `view.rectangular_selection_modifier` to\n  `view.MOD_CTRL`, the "Control" modifier is reported as *both* "Control"\n  and "Alt" due to a Scintilla limitation with GTK.
+DOUBLE_CLICK events.DOUBLE_CLICK (string)\nEmitted after double-clicking the mouse button.\nArguments:\n\n* _`position`_: The position double-clicked.\n* _`line`_: The line number of the position double-clicked.\n* _`modifiers`_: A bit-mask of any modifier keys used: `view.MOD_CTRL`,\n  `view.MOD_SHIFT`, `view.MOD_ALT`, and `view.MOD_META`.\n  On macOS, the Command modifier key is reported as `view.MOD_CTRL` and\n  Ctrl is `view.MOD_META`.\n  Note: If you set `view.rectangular_selection_modifier` to\n  `view.MOD_CTRL`, the "Control" modifier is reported as *both* "Control"\n  and "Alt" due to a Scintilla limitation with GTK.
 DWELL_END events.DWELL_END (string)\nEmitted after `DWELL_START` when the user moves the mouse, presses a key,\nor scrolls the view.\nArguments:\n\n* _`position`_: The position closest to *x* and *y*.\n* _`x`_: The x-coordinate of the mouse in the view.\n* _`y`_: The y-coordinate of the mouse in the view.
 DWELL_START events.DWELL_START (string)\nEmitted when the mouse is stationary for `view.mouse_dwell_time`\nmilliseconds.\nArguments:\n\n* _`position`_: The position closest to *x* and *y*.\n* _`x`_: The x-coordinate of the mouse in the view.\n* _`y`_: The y-coordinate of the mouse in the view.
 EDGE_BACKGROUND view.EDGE_BACKGROUND (number, Read-only)\n
@@ -110,7 +110,7 @@ FOLD_BLANK lexer.FOLD_BLANK (number)\nFlag indicating that the line is blank.
 FOLD_HEADER lexer.FOLD_HEADER (number)\nFlag indicating the line is fold point.
 FUNCTION lexer.FUNCTION (string)\nThe token name for function tokens.
 IDENTIFIER lexer.IDENTIFIER (string)\nThe token name for identifier tokens.
-INDICATOR_CLICK events.INDICATOR_CLICK (string)\nEmitted when clicking the mouse on text that has an indicator present.\nArguments:\n\n* _`position`_: The clicked text's position.\n* _`modifiers`_: A bit-mask of any modifier keys used: `view.MOD_CTRL`,\n  `view.MOD_SHIFT`, `view.MOD_ALT`, and `view.MOD_META`.\n  On Mac OSX, the Command modifier key is reported as `view.MOD_CTRL` and\n  Ctrl is `view.MOD_META`.\n  Note: If you set `view.rectangular_selection_modifier` to\n  `view.MOD_CTRL`, the "Control" modifier is reported as *both* "Control"\n  and "Alt" due to a Scintilla limitation with GTK.
+INDICATOR_CLICK events.INDICATOR_CLICK (string)\nEmitted when clicking the mouse on text that has an indicator present.\nArguments:\n\n* _`position`_: The clicked text's position.\n* _`modifiers`_: A bit-mask of any modifier keys used: `view.MOD_CTRL`,\n  `view.MOD_SHIFT`, `view.MOD_ALT`, and `view.MOD_META`.\n  On macOS, the Command modifier key is reported as `view.MOD_CTRL` and\n  Ctrl is `view.MOD_META`.\n  Note: If you set `view.rectangular_selection_modifier` to\n  `view.MOD_CTRL`, the "Control" modifier is reported as *both* "Control"\n  and "Alt" due to a Scintilla limitation with GTK.
 INDICATOR_MAX buffer.INDICATOR_MAX (number, Read-only)\n
 INDICATOR_RELEASE events.INDICATOR_RELEASE (string)\nEmitted when releasing the mouse after clicking on text that has an\nindicator present.\nArguments:\n\n* _`position`_: The clicked text's position.
 INDIC_ADDITION file_diff.INDIC_ADDITION (number)\nThe indicator number for text added within lines.
@@ -149,7 +149,7 @@ IV_LOOKBOTH view.IV_LOOKBOTH (number, Read-only)\n
 IV_LOOKFORWARD view.IV_LOOKFORWARD (number, Read-only)\n
 IV_NONE view.IV_NONE (number, Read-only)\n
 IV_REAL view.IV_REAL (number, Read-only)\n
-KEYPRESS events.KEYPRESS (string)\nEmitted when pressing a key.\nIf any handler returns `true`, the key is not inserted into the buffer.\nArguments:\n\n* _`code`_: The numeric key code.\n* _`shift`_: The "Shift" modifier key is held down.\n* _`ctrl`_: The "Control" modifier key is held down.\n* _`alt`_: The "Alt"/"Option" modifier key is held down.\n* _`cmd`_: The "Command" modifier key on Mac OSX is held down.\n* _`caps_lock`_: The "Caps Lock" modifier is on.
+KEYPRESS events.KEYPRESS (string)\nEmitted when pressing a key.\nIf any handler returns `true`, the key is not inserted into the buffer.\nArguments:\n\n* _`code`_: The numeric key code.\n* _`shift`_: The "Shift" modifier key is held down.\n* _`ctrl`_: The "Control" modifier key is held down.\n* _`alt`_: The "Alt"/"Option" modifier key is held down.\n* _`cmd`_: The "Command" modifier key on macOS is held down.\n* _`caps_lock`_: The "Caps Lock" modifier is on.
 KEYSYMS keys.KEYSYMS (table)\nLookup table for string representations of key codes higher than 255.\nKey codes can be identified by temporarily uncommenting the `print()`\nstatements in *core/keys.lua*.
 KEYWORD lexer.KEYWORD (string)\nThe token name for keyword tokens.
 LABEL lexer.LABEL (string)\nThe token name for label tokens.
@@ -162,7 +162,7 @@ LUA_GENERATOR ctags.LUA_GENERATOR (string)\nPlaceholder value that indicates Tex
 MARGINOPTION_NONE view.MARGINOPTION_NONE (number, Read-only)\n
 MARGINOPTION_SUBLINESELECT view.MARGINOPTION_SUBLINESELECT (number, Read-only)\n
 MARGIN_BACK view.MARGIN_BACK (number, Read-only)\n
-MARGIN_CLICK events.MARGIN_CLICK (string)\nEmitted when clicking the mouse inside a sensitive margin.\nArguments:\n\n* _`margin`_: The margin number clicked.\n* _`position`_: The beginning position of the clicked margin's line.\n* _`modifiers`_: A bit-mask of any modifier keys used: `view.MOD_CTRL`,\n  `view.MOD_SHIFT`, `view.MOD_ALT`, and `view.MOD_META`.\n  On Mac OSX, the Command modifier key is reported as `view.MOD_CTRL` and\n  Ctrl is `view.MOD_META`.\n  Note: If you set `view.rectangular_selection_modifier` to\n  `view.MOD_CTRL`, the "Control" modifier is reported as *both* "Control"\n  and "Alt" due to a Scintilla limitation with GTK.
+MARGIN_CLICK events.MARGIN_CLICK (string)\nEmitted when clicking the mouse inside a sensitive margin.\nArguments:\n\n* _`margin`_: The margin number clicked.\n* _`position`_: The beginning position of the clicked margin's line.\n* _`modifiers`_: A bit-mask of any modifier keys used: `view.MOD_CTRL`,\n  `view.MOD_SHIFT`, `view.MOD_ALT`, and `view.MOD_META`.\n  On macOS, the Command modifier key is reported as `view.MOD_CTRL` and\n  Ctrl is `view.MOD_META`.\n  Note: If you set `view.rectangular_selection_modifier` to\n  `view.MOD_CTRL`, the "Control" modifier is reported as *both* "Control"\n  and "Alt" due to a Scintilla limitation with GTK.
 MARGIN_COLOR view.MARGIN_COLOR (number, Read-only)\n
 MARGIN_FORE view.MARGIN_FORE (number, Read-only)\n
 MARGIN_NUMBER view.MARGIN_NUMBER (number, Read-only)\n
@@ -241,7 +241,7 @@ OPERATOR lexer.OPERATOR (string)\nThe token name for operator tokens.
 ORDER_CUSTOM buffer.ORDER_CUSTOM (number, Read-only)\n
 ORDER_PERFORMSORT buffer.ORDER_PERFORMSORT (number, Read-only)\n
 ORDER_PRESORTED buffer.ORDER_PRESORTED (number, Read-only)\n
-OSX _G.OSX (bool)\nWhether or not Textadept is running on Mac OSX as a GUI application.
+OSX _G.OSX (bool)\nWhether or not Textadept is running on macOS as a GUI application.
 PREPROCESSOR lexer.PREPROCESSOR (string)\nThe token name for preprocessor tokens.
 QUIT events.QUIT (string)\nEmitted when quitting Textadept.\nWhen connecting to this event, connect with an index of 1 if the handler\nneeds to run before Textadept closes all open buffers. If a handler returns\n`true`, Textadept does not quit. It is not recommended to return `false`\nfrom a quit handler, as that may interfere with Textadept's normal shutdown\nprocedure.\nEmitted by `quit()`.
 REGEX lexer.REGEX (string)\nThe token name for regex tokens.
@@ -273,7 +273,7 @@ STYLE_INDENTGUIDE view.STYLE_INDENTGUIDE (number, Read-only)\n
 STYLE_LINENUMBER view.STYLE_LINENUMBER (number, Read-only)\n
 STYLE_MAX view.STYLE_MAX (number, Read-only)\n
 SUSPEND events.SUSPEND (string)\nEmitted when suspending Textadept. If any handler returns `true`, Textadept\ndoes not suspend.\nThis event is only emitted by the terminal version.
-TAB_CLICKED events.TAB_CLICKED (string)\nEmitted when the user clicks on a buffer tab.\nWhen connecting to this event, connect with an index of 1 if the handler\nneeds to run before Textadept switches between buffers.\nNote that Textadept always displays a context menu on right-click.\nArguments:\n\n* _`index`_: The numeric index of the clicked tab.\n* _`button`_: The mouse button number that was clicked, either `1` (left\n  button), `2` (middle button), `3` (right button), `4` (wheel up), or `5`\n (wheel down).\n* _`shift`_: The "Shift" modifier key is held down.\n* _`ctrl`_: The "Control" modifier key is held down.\n* _`alt`_: The "Alt"/"Option" modifier key is held down.\n* _`cmd`_: The "Command" modifier key on Mac OSX is held down.
+TAB_CLICKED events.TAB_CLICKED (string)\nEmitted when the user clicks on a buffer tab.\nWhen connecting to this event, connect with an index of 1 if the handler\nneeds to run before Textadept switches between buffers.\nNote that Textadept always displays a context menu on right-click.\nArguments:\n\n* _`index`_: The numeric index of the clicked tab.\n* _`button`_: The mouse button number that was clicked, either `1` (left\n  button), `2` (middle button), `3` (right button), `4` (wheel up), or `5`\n (wheel down).\n* _`shift`_: The "Shift" modifier key is held down.\n* _`ctrl`_: The "Control" modifier key is held down.\n* _`alt`_: The "Alt"/"Option" modifier key is held down.\n* _`cmd`_: The "Command" modifier key on macOS is held down.
 TD_LONGARROW view.TD_LONGARROW (number, Read-only)\n
 TD_STRIKEOUT view.TD_STRIKEOUT (number, Read-only)\n
 TIME_FOREVER view.TIME_FOREVER (number, Read-only)\n
@@ -327,7 +327,7 @@ _L _G._L (module)\nMap of all messages used by Textadept to their localized form
 _M _G._M (module)\nA table of loaded Textadept language modules.\n\nLanguage modules are a special kind of module that Textadept automatically\nloads when editing source code in a particular programming language. The only\nthing "special" about them is they are named after a lexer. Otherwise they\nare plain Lua modules. The *~/.textadept/modules/* directory houses language\nmodules (along with other modules).\n\nA language module is designed to provide extra functionality for a single\nprogramming language. Some examples of what language modules can do:\n\n  * Specify block comment syntax for lines of code\n  * Define compile and run commands for source files\n  * Set language-specific editor properties like indentation rules\n  * Specify code autocompletion routines\n  * Declare snippets\n  * Define commands and key bindings for them\n  * Add to the top-level menu or right-click editor context menu\n\nExamples of these features are described in the sections below.
 _RELEASE _G._RELEASE (string)\nThe Textadept release version string.
 _SCINTILLA _G._SCINTILLA (module)\nScintilla constants, functions, and properties.\nDo not modify anything in this module. Doing so will have unpredictable\nconsequences.
-_USERHOME _G._USERHOME (string)\nThe path to the user's *~/.textadept/* directory, where all preferences and\nuser-data is stored.\nOn Windows machines *~/* is the value of the "USERHOME" environment\nvariable (typically *C:\Users\username\\* or\n*C:\Documents and Settings\username\\*). On Linux, BSD, and Mac OSX\nmachines *~/* is the value of "$HOME" (typically */home/username/* and\n*/Users/username/* respectively).
+_USERHOME _G._USERHOME (string)\nThe path to the user's *~/.textadept/* directory, where all preferences and\nuser-data is stored.\nOn Windows machines *~/* is the value of the "USERHOME" environment\nvariable (typically *C:\Users\username\\* or\n*C:\Documents and Settings\username\\*). On Linux, BSD, and macOS\nmachines *~/* is the value of "$HOME" (typically */home/username/* and\n*/Users/username/* respectively).
 _VIEWS _G._VIEWS (table)\nTable of all views in Textadept.\nNumeric keys have view values and view keys have their associated numeric\nkeys.\n@see _G.view
 _print ui._print(buffer_type, ...)\nPrints the given string messages to the buffer of string type *buffer_type*.\nOpens a new buffer for printing messages to if necessary. If the message\nbuffer is already open in a view, the message is printed to that view.\nOtherwise the view is split (unless `ui.tabs` is `true`) and the message\nbuffer is displayed before being printed to.\n@param buffer_type String type of message buffer.\n@param ... Message strings.\n@usage ui._print(_L['[Message Buffer]'], message)
 abspath lfs.abspath(filename, prefix)\nReturns the absolute path to string *filename*.\n*prefix* or `lfs.currentdir()` is prepended to a relative filename. The\nreturned path is not guaranteed to exist.\n@param filename The relative or absolute path to a file.\n@param prefix Optional prefix path prepended to a relative filename.\n@return string absolute path
@@ -391,6 +391,7 @@ auto_c_separator buffer.auto_c_separator (number)\nThe byte value of the charact
 auto_c_show buffer.auto_c_show(buffer, len_entered, items)\nDisplays an autocompletion list constructed from string *items* (whose items\nare delimited by `buffer.auto_c_separator` characters) using *len_entered*\nnumber of characters behind the caret as the prefix of the word to be\nautocompleted.\nThe sorted order of *items* (`buffer.auto_c_order`) must have already been\ndefined.\n@param buffer A buffer.\n@param len_entered The number of characters before the caret used to provide\n  the context.\n@param items The sorted string of words to show, separated by\n  `buffer.auto_c_separator` characters (initially spaces).\n@see auto_c_separator\n@see auto_c_order
 auto_c_stops buffer.auto_c_stops(buffer, chars)\nAllows the user to type any character in string set *chars* in order to\ncancel an autocompletion or user list.\nThe default set is empty.\n@param buffer A buffer.\n@param chars The string of characters that cancel autocompletion. This string\n  is empty by default.
 auto_c_type_separator buffer.auto_c_type_separator (number)\nThe character byte that separates autocompletion and user list items and\ntheir image types.\nAutocompletion and user list items can display both an image and text.\nRegister images and their types using `view.register_image()` or\n`view.register_rgba_image()` before appending image types to list\nitems after type separator characters.\nThe default value is 63 ('?').
+auto_enclose textadept.editing.auto_enclose (bool)\nWhether or not to auto-enclose selected text when typing a punctuation\ncharacter, taking `textadept.editing.auto_pairs` into account.\nThe default value is `false`.
 auto_indent textadept.editing.auto_indent (bool)\nMatch the previous line's indentation level after inserting a new line.\nThe default value is `true`.
 auto_pairs textadept.editing.auto_pairs (table)\nMap of auto-paired characters like parentheses, brackets, braces, and quotes.\nThe ASCII values of opening characters are assigned to strings that contain\ncomplement characters. The default auto-paired characters are "()", "[]",\n"{}", "''", and """".
 autocomplete textadept.editing.autocomplete(name)\nDisplays an autocompletion list provided by the autocompleter function\nassociated with string *name*, and returns `true` if completions were found.\n@param name The name of an autocompleter function in the `autocompleters`\n  table to use for providing autocompletions.\n@see autocompleters
@@ -410,7 +411,7 @@ brace_highlight_indicator view.brace_highlight_indicator(view, use_indicator, in
 brace_match buffer.brace_match(buffer, pos, max_re_style)\nReturns the position of the matching brace for the brace character at\nposition *pos*, taking nested braces into account, or `-1`.\nThe brace characters recognized are '(', ')', '[', ']', '{', '}', '<', and\n'>' and must have the same style.\n@param buffer A buffer.\n@param pos The position of the brace in *buffer* to match.\n@param max_re_style Must be `0`. Reserved for expansion.\n@return number
 brace_matches textadept.editing.brace_matches (table)\nTable of brace characters to highlight.\nThe ASCII values of brace characters are keys and are assigned non-`nil`\nvalues. The default brace characters are '(', ')', '[', ']', '{', and '}'.
 browser export.browser (string)\nPath to or the name of the browser executable to show exported HTML files\nin.\nThe default value is 'firefox'.
-buffer _G.buffer (module)\nA Textadept buffer object.\nConstants are documented in the fields they apply to.\nWhile you can work with individual buffer instances, it is really only useful\nto work with the global one.\nMany of these functions and fields are derived from buffer-specific\nfunctionality of the Scintilla editing component, and additional information\ncan be found on the Scintilla website:\nhttp://scintilla.org/ScintillaDoc.html.\nNote that with regard to Scintilla-specific functionality, this API is a\n_suggestion_, not a hard requirement. All of that functionality also exists\nin `view`, even if undocumented.
+buffer _G.buffer (module)\nA Textadept buffer object.\nConstants are documented in the fields they apply to.\nWhile you can work with individual buffer instances, it is really only useful\nto work with the global one.\nMany of these functions and fields are derived from buffer-specific\nfunctionality of the Scintilla editing component, and additional information\ncan be found on the Scintilla website:\nhttp://scintilla.org/ScintillaDoc.html.\nNote that with regard to Scintilla-specific functionality, this API is a\n_suggestion_, not a hard requirement. All of that functionality also exists\nin `view`, even if undocumented.\nAny buffer fields set on startup (e.g. in *~/.textadept/init.lua*) will be\nthe default, initial values for all buffers.
 buffer _G.buffer (table)\nThe current buffer in the current view.
 buffer view.buffer (table)\nThe buffer the view currently contains. (Read-only)
 buffer_statusbar_text ui.buffer_statusbar_text (string, Write-only)\nThe text displayed in the buffer statusbar.
@@ -531,7 +532,7 @@ empty_undo_buffer buffer.empty_undo_buffer(buffer)\nDeletes the undo and redo hi
 enable_listening history.enable_listening()\nEnables recording of edit locations.
 enclose textadept.editing.enclose(left, right)\nEncloses the selected text or the current word within strings *left* and\n*right*, taking multiple selections into account.\n@param left The left part of the enclosure.\n@param right The right part of the enclosure.
 encoding buffer.encoding (string or nil)\nThe string encoding of the file, or `nil` for binary files.
-encodings io.encodings (table)\nList of encodings to attempt to decode files as.\nYou should add to this list if you get a "Conversion failed" error when\ntrying to open a file whose encoding is not recognized. Valid encodings are\nGNU iconv's encodings and include:\n\n  * European: ASCII, ISO-8859-{1,2,3,4,5,7,9,10,13,14,15,16}, KOI8-R, KOI8-U,\n    KOI8-RU, CP{1250,1251,1252,1253,1254,1257}, CP{850,866,1131},\n    Mac{Roman,CentralEurope,Iceland,Croatian,Romania},\n    Mac{Cyrillic,Ukraine,Greek,Turkish}, Macintosh.\n  * Semitic: ISO-8859-{6,8}, CP{1255,1256}, CP862, Mac{Hebrew,Arabic}.\n  * Japanese: EUC-JP, SHIFT_JIS, CP932, ISO-2022-JP, ISO-2022-JP-2,\n    ISO-2022-JP-1.\n  * Chinese: EUC-CN, HZ, GBK, CP936, GB18030, EUC-TW, BIG5, CP950,\n    BIG5-HKSCS, BIG5-HKSCS:2004, BIG5-HKSCS:2001, BIG5-HKSCS:1999,\n    ISO-2022-CN, ISO-2022-CN-EXT.\n  * Korean: EUC-KR, CP949, ISO-2022-KR, JOHAB.\n  * Armenian: ARMSCII-8.\n  * Georgian: Georgian-Academy, Georgian-PS.\n  * Tajik: KOI8-T.\n  * Kazakh: PT154, RK1048.\n  * Thai: ISO-8859-11, TIS-620, CP874, MacThai.\n  * Laotian: MuleLao-1, CP1133.\n  * Vietnamese: VISCII, TCVN, CP1258.\n  * Unicode: UTF-8, UCS-2, UCS-2BE, UCS-2LE, UCS-4, UCS-4BE, UCS-4LE, UTF-16,\n    UTF-16BE, UTF-16LE, UTF-32, UTF-32BE, UTF-32LE, UTF-7, C99, JAVA.
+encodings io.encodings (table)\nList of encodings to attempt to decode files as.\nYou should add to this list if you get a "Conversion failed" error when\ntrying to open a file whose encoding is not recognized. Valid encodings are\nGNU iconv's encodings and include:\n\n  * European: ASCII, ISO-8859-{1,2,3,4,5,7,9,10,13,14,15,16}, KOI8-R, KOI8-U,\n    KOI8-RU, CP{1250,1251,1252,1253,1254,1257}, CP{850,866,1131},\n    Mac{Roman,CentralEurope,Iceland,Croatian,Romania},\n    Mac{Cyrillic,Ukraine,Greek,Turkish}, Macintosh.\n  * Unicode: UTF-8, UCS-2, UCS-2BE, UCS-2LE, UCS-4, UCS-4BE, UCS-4LE, UTF-16,\n    UTF-16BE, UTF-16LE, UTF-32, UTF-32BE, UTF-32LE, UTF-7, C99, JAVA.
 end_at_last_line view.end_at_last_line (bool)\nDisable scrolling past the last line.\nThe default value is `true`.
 end_styled buffer.end_styled (number, Read-only)\nThe current styling position or the last correctly styled character's\nposition.
 end_undo_action buffer.end_undo_action(buffer)\nEnds a sequence of actions to be undone or redone as a single action.\n@param buffer A buffer.
@@ -559,7 +560,7 @@ file_types textadept.file_types (module)\nHandles file type detection for Textad
 filename buffer.filename (string)\nThe absolute file path associated with the buffer.
 filesave ui.dialogs.filesave(options)\nPrompts the user with a file save dialog defined by dialog options table\n*options*, returning the string file chosen.\nIf the user canceled the dialog, returns `nil`.\n@param options Table of key-value option pairs for the dialog.\n\n  * `title`: The dialog's title text.\n  * `with_directory`: The initial filesystem directory to show.\n  * `with_file`: The initially chosen filename. This option requires\n    `with_directory` to be set.\n  * `with_extension`: The list of extensions selectable files must have.\n  * `no_create_directories`: Prevent the user from creating new directories.\n    The default value is `false`.\n@return filename or nil
 fileselect ui.dialogs.fileselect(options)\nPrompts the user with a file selection dialog defined by dialog options\ntable *options*, returning the string file selected.\nIf *options*.`select_multiple` is `true`, returns the list of files selected.\nIf the user canceled the dialog, returns `nil`.\n@param options Table of key-value option pairs for the dialog.\n\n  * `title`: The dialog's title text.\n  * `with_directory`: The initial filesystem directory to show.\n  * `with_file`: The initially selected filename. This option requires\n    `with_directory` to be set.\n  * `with_extension`: The list of extensions selectable files must have.\n  * `select_multiple`: Allow the user to select multiple files. The default\n    value is `false`.\n  * `select_only_directories`: Only allow the user to select directories. The\n    default value is `false`.\n@usage ui.dialogs.fileselect{title = 'Open C File', with_directory = _HOME,\n  with_extension = {'c', 'h'}, select_multiple = true}\n@return filename, list of filenames, or nil
-filter_through textadept.editing.filter_through(command)\nPasses the selected text or all buffer text to string shell command *command*\nas standard input (stdin) and replaces the input text with the command's\nstandard output (stdout). *command* may contain shell pipes ('|').\nStandard input is as follows:\n\n1. If no text is selected, the entire buffer is used.\n2. If text is selected and spans a single line, only the selected text is\nused.\n3. If text is selected and spans multiple lines, all text on the lines that\nhave text selected is passed as stdin. However, if the end of the selection\nis at the beginning of a line, only the line ending delimiters from the\nprevious line are included. The rest of the line is excluded.\n@param command The Linux, BSD, Mac OSX, or Windows shell command to filter\n  text through. May contain pipes.
+filter_through textadept.editing.filter_through(command)\nPasses the selected text or all buffer text to string shell command *command*\nas standard input (stdin) and replaces the input text with the command's\nstandard output (stdout). *command* may contain shell pipes ('|').\nStandard input is as follows:\n\n1. If no text is selected, the entire buffer is used.\n2. If text is selected and spans a single line, only the selected text is\nused.\n3. If text is selected and spans multiple lines, all text on the lines that\nhave text selected is passed as stdin. However, if the end of the selection\nis at the beginning of a line, only the line ending delimiters from the\nprevious line are included. The rest of the line is excluded.\n@param command The Linux, BSD, macOS, or Windows shell command to filter text\n  through. May contain pipes.
 filteredlist ui.dialogs.filteredlist(options)\nPrompts the user with a filtered list item selection dialog defined by dialog\noptions table *options*, returning the selected button's index along with the\nindex or indices of the selected item or items (depending on whether or not\n*options*.`select_multiple` is `true`).\nIf *options*.`string_output` is `true`, returns the selected button's label\nalong with the text of the selected item or items.\nIf the dialog timed out, returns `0` or `"timeout"`. If the user canceled the\ndialog, returns `-1` or `"delete"`.\nSpaces in the filter text are treated as wildcards.\n@param options Table of key-value option pairs for the filtered list dialog.\n\n  * `title`: The dialog's title text.\n  * `informative_text`: The dialog's main message text.\n  * `text`: The dialog's initial input text.\n  * `columns`: The list of string column names for list rows.\n  * `items`: The list of string items to show in the filtered list.\n  * `button1`: The right-most button's label. The default value is\n    `_L['OK']`.\n  * `button2`: The middle button's label.\n  * `button3`: The left-most button's label. This option requires `button2`\n    to be set.\n  * `select_multiple`: Allow the user to select multiple items. The default\n    value is `false`.\n  * `search_column`: The column number to filter the input text against. The\n    default value is `1`. This option requires `columns` to be set and\n    contain at least *n* column names.\n  * `output_column`: The column number to use for `string_output`. The\n    default value is `1`. This option requires `columns` to be set and\n    contain at least *n* column names.\n  * `string_output`: Return the selected button's label (instead of its\n    index) and the selected item's text (instead of its index). If no item\n    was selected, returns the dialog's exit status (instead of its exit\n    code). The default value is `false`.\n  * `width`: The dialog's pixel width. The default width stretches nearly the\n    width of Textadept's window.\n  * `height`: The dialog's pixel height.\n  * `float`: Show the dialog on top of all desktop windows. The default value\n    is `false`.\n  * `timeout`: The integer number of seconds the dialog waits for the user to\n    select a button before timing out. Dialogs do not time out by default.\n@usage ui.dialogs.filteredlist{title = 'Title', columns = {'Foo', 'Bar'},\n  items = {'a', 'b', 'c', 'd'}}\n@return selected button or exit code, selected item or list of selected items
 find ui.find (module)\nTextadept's Find & Replace pane.
 find_column buffer.find_column(buffer, line, column)\nReturns the position of column number *column* on line number *line* (taking\ntab and multi-byte characters into account), or the position at the end of\nline *line*.\n@param buffer A buffer.\n@param line The line number in *buffer* to use.\n@param column The column number to use.
@@ -601,7 +602,7 @@ get_default_fold_display_text view.get_default_fold_display_text(view)\nReturns
 get_last_child buffer.get_last_child(buffer, line, level)\nReturns the line number of the last line after line number *line* whose fold\nlevel is greater than *level*.\nIf *level* is `-1`, returns the level of *line*.\n@param buffer A buffer.\n@param line The line number in *buffer* of a header line.\n@param level The fold level, or `-1` for the level of *line*.
 get_lexer buffer.get_lexer(buffer, current)\nReturns the buffer's lexer name.\nIf *current* is `true`, returns the name of the lexer under the caret in\na multiple-language lexer.\n@param buffer A buffer.\n@param current Whether or not to get the lexer at the current caret position\n  in multi-language lexers. The default is `false` and returns the parent\n  lexer.
 get_line buffer.get_line(buffer, line)\nReturns the text on line number *line*, including end of line characters.\n@param buffer A buffer.\n@param line The line number in *buffer* to use.\n@return string, number
-get_project_root io.get_project_root(path)\nReturns the root directory of the project that contains filesystem path\n*path*.\nIn order to be recognized, projects must be under version control. Recognized\nVCSes are Bazaar, Git, Mercurial, and SVN.\n@param path Optional filesystem path to a project or a file contained within\n  a project. The default value is the buffer's filename or the current\n  working directory.\n@return string root or nil
+get_project_root io.get_project_root(path)\nReturns the root directory of the project that contains filesystem path\n*path*.\nIn order to be recognized, projects must be under version control. Recognized\nVCSes are Bazaar, Fossil, Git, Mercurial, and SVN.\n@param path Optional filesystem path to a project or a file contained within\n  a project. The default value is the buffer's filename or the current\n  working directory.\n@return string root or nil
 get_rule lexer.get_rule(lexer, id)\nReturns the rule identified by string *id*.\n@param lexer The lexer to fetch a rule from.\n@param id The id of the rule to fetch.\n@return pattern
 get_sel_text buffer.get_sel_text(buffer)\nReturns the selected text.\nMultiple selections are included in order with no delimiters. Rectangular\nselections are included from top to bottom with end of line characters.\nVirtual space is not included.\n@param buffer A buffer.\n@return string, number
 get_split_table ui.get_split_table()\nReturns a split table that contains Textadept's current split view structure.\nThis is primarily used in session saving.\n@return table of split views. Each split view entry is a table with 4\n  fields: `1`, `2`, `vertical`, and `size`. `1` and `2` have values of either\n  nested split view entries or the views themselves; `vertical` is a flag\n  that indicates if the split is vertical or not; and `size` is the integer\n  position of the split resizer.
@@ -900,7 +901,7 @@ rest _G.snippets.rest (table)\nContainer for reST-specific snippets.
 rest _M.rest (module)\nThe reST module.\nIt provides utilities for editing reST and Sphinx documents.
 restart debugger.restart(...)\nRestarts debugger execution from the beginning.\nEmits a `DEBUGGER_PAUSE` event, passing along any additional arguments given.
 rgba_image_height view.rgba_image_height (number)\nThe height of the RGBA image to be defined using\n`view.marker_define_rgba_image()`.
-rgba_image_scale view.rgba_image_scale (number)\nThe scale factor in percent of the RGBA image to be defined using\n`view.marker_define_rgba_image()`.\nThis is useful on OSX with a retina display where each display unit is 2\npixels: use a factor of `200` so that each image pixel is displayed using a\nscreen pixel. The default scale, `100`, will stretch each image pixel to\ncover 4 screen pixels on a retina display.
+rgba_image_scale view.rgba_image_scale (number)\nThe scale factor in percent of the RGBA image to be defined using\n`view.marker_define_rgba_image()`.\nThis is useful on macOS with a retina display where each display unit is 2\npixels: use a factor of `200` so that each image pixel is displayed using a\nscreen pixel. The default scale, `100`, will stretch each image pixel to\ncover 4 screen pixels on a retina display.
 rgba_image_width view.rgba_image_width (number)\nThe width of the RGBA image to be defined using\n`view.marker_define_rgba_image()` and\n`view.register_rgba_image()`.
 rotate_selection buffer.rotate_selection(buffer)\nDesignates the next additional selection to be the main selection.\n@param buffer A buffer.
 ruby _G.keys.ruby (table)\nContainer for Ruby-specific key bindings.
@@ -964,7 +965,7 @@ set_encoding buffer.set_encoding(buffer, encoding)\nConverts the current buffer'
 set_fold_margin_color view.set_fold_margin_color(view, use_setting, color)\nOverrides the fold margin's default color with color *color*, in "0xBBGGRR"\nformat,\nif *use_setting* is `true`.\n@param view A view.\n@param use_setting Whether or not to use *color*.\n@param color The color in "0xBBGGRR" format.
 set_fold_margin_hi_color view.set_fold_margin_hi_color(view, use_setting, color)\nOverrides the fold margin's default highlight color with color *color*, in\n"0xBBGGRR" format, if *use_setting* is `true`.\n@param view A view.\n@param use_setting Whether or not to use *color*.\n@param color The color in "0xBBGGRR" format.
 set_frame debugger.set_frame()\nPrompts the user to select a stack frame to switch to from the current\ndebugger call stack, unless the debugger is executing (e.g. not at a\nbreakpoint).\nEmits a `DEBUGGER_SET_FRAME` event.
-set_lexer buffer.set_lexer(buffer, name)\nAssociates string lexer name *name* or the auto-detected lexer name with the \nbuffer and then loads the appropriate language module if that module exists.\n@param buffer A buffer.\n@param name Optional string lexer name to set. If `nil`, attempts to\n  auto-detect the buffer's lexer.\n@usage buffer:set_lexer('lexer_name')
+set_lexer buffer.set_lexer(buffer, name)\nAssociates string lexer name *name* or the auto-detected lexer name with the\nbuffer and then loads the appropriate language module if that module exists.\n@param buffer A buffer.\n@param name Optional string lexer name to set. If `nil`, attempts to\n  auto-detect the buffer's lexer.\n@usage buffer:set_lexer('lexer_name')
 set_save_point buffer.set_save_point(buffer)\nIndicates the buffer has no unsaved changes.\n@param buffer A buffer.
 set_sel buffer.set_sel(buffer, start_pos, end_pos)\nSelects the range of text between positions *start_pos* and *end_pos*,\nscrolling the selected text into view.\n@param buffer A buffer.\n@param start_pos The start position of the range of text in *buffer* to\n  select. If negative, it means the end of the buffer.\n@param end_pos The end position of the range of text in *buffer* to select.\n  If negative, it means remove any selection (i.e. set the `anchor` to the\n  same position as `current_pos`).
 set_sel_back view.set_sel_back(view, use_setting, color)\nOverrides the selection's default background color with color *color*, in\n"0xBBGGRR" format, if *use_setting* is `true`.\nOverwrites any existing `view.additional_sel_back` color.\n@param view A view.\n@param use_setting Whether or not to use *color*.\n@param color The color in "0xBBGGRR" format.
@@ -1100,7 +1101,7 @@ vc_home_rect_extend buffer.vc_home_rect_extend(buffer)\nLike `buffer.vc_home()`,
 vc_home_wrap buffer.vc_home_wrap(buffer)\nMoves the caret to the first visible character on the current wrapped line\nor, if already there, to the beginning of the actual line.\n@param buffer A buffer.
 vc_home_wrap_extend buffer.vc_home_wrap_extend(buffer)\nLike `buffer.vc_home_wrap()`, but extends the selected text to the new\nposition.\n@param buffer A buffer.
 vertical_center_caret view.vertical_center_caret(view)\nCenters current line in the view.\n@param view A view.
-view _G.view (module)\nA Textadept view object.\nConstants are documented in the fields they apply to.\nWhile you can work with individual view instances, it is often useful to work\nwith just the global one.\nMany of these functions and fields are derived from view-specific\nfunctionality the Scintilla editing component, and additional information can\nbe found on the Scintilla website:\nhttp://scintilla.org/ScintillaDoc.html\nNote that with regard to Scintilla-specific functionality, this API is a\n_suggestion_, not a hard requirement. All of that functionality also exists\nin `buffer`, even if undocumented.
+view _G.view (module)\nA Textadept view object.\nConstants are documented in the fields they apply to.\nWhile you can work with individual view instances, it is often useful to work\nwith just the global one.\nMany of these functions and fields are derived from view-specific\nfunctionality the Scintilla editing component, and additional information can\nbe found on the Scintilla website:\nhttp://scintilla.org/ScintillaDoc.html\nNote that with regard to Scintilla-specific functionality, this API is a\n_suggestion_, not a hard requirement. All of that functionality also exists\nin `buffer`, even if undocumented.\nAny view fields set on startup (e.g. in *~/.textadept/init.lua*) will be the\ndefault, initial values for all views.
 view _G.view (table)\nThe current view.
 view_eol view.view_eol (bool)\nDisplay end of line characters.\nThe default value is `false`.
 view_ws view.view_ws (number)\nThe whitespace visibility mode.\n\n* `view.WS_INVISIBLE`\n  Whitespace is invisible.\n* `view.WS_VISIBLEALWAYS`\n  Display all space characters as dots and tab characters as arrows.\n* `view.WS_VISIBLEAFTERINDENT`\n  Display only non-indentation spaces and tabs as dots and arrows.\n* `view.WS_VISIBLEONLYININDENT`\n  Display only indentation spaces and tabs as dots and arrows.\n\nThe default value is `view.WS_INVISIBLE`.
diff --git a/modules/lua/ta_tags b/modules/lua/ta_tags
index de411830..f34164b5 100644
--- a/modules/lua/ta_tags
+++ b/modules/lua/ta_tags
@@ -399,6 +399,7 @@ auto_c_separator	_HOME/core/.buffer.luadoc	/^module('buffer')$/;"	F	class:buffer
 auto_c_show	_HOME/core/.buffer.luadoc	/^function auto_c_show(buffer, len_entered, items) end$/;"	f	class:buffer
 auto_c_stops	_HOME/core/.buffer.luadoc	/^function auto_c_stops(buffer, chars) end$/;"	f	class:buffer
 auto_c_type_separator	_HOME/core/.buffer.luadoc	/^module('buffer')$/;"	F	class:buffer
+auto_enclose	_HOME/modules/textadept/editing.lua	/^module('textadept.editing')]]$/;"	F	class:textadept.editing
 auto_indent	_HOME/modules/textadept/editing.lua	/^module('textadept.editing')]]$/;"	F	class:textadept.editing
 auto_pairs	_HOME/modules/textadept/editing.lua	/^M.auto_pairs = {[40] = ')', [91] = ']', [123] = '}', [39] = "'", [34] = '"'}$/;"	t	class:textadept.editing
 autocomplete	_HOME/modules/textadept/editing.lua	/^function M.autocomplete(name)$/;"	f	class:textadept.editing
diff --git a/modules/textadept/editing.lua b/modules/textadept/editing.lua
index 4af9d5cc..0e59e7a4 100644
--- a/modules/textadept/editing.lua
+++ b/modules/textadept/editing.lua
@@ -26,6 +26,10 @@ local M = {}
 --     Do not automatically highlight words.
 --
 --   The default value is `textadept.editing.HIGHLIGHT_NONE`.
+-- @field auto_enclose (bool)
+--   Whether or not to auto-enclose selected text when typing a punctuation
+--   character, taking [`textadept.editing.auto_pairs`]() into account.
+--   The default value is `false`.
 -- @field INDIC_BRACEMATCH (number)
 --   The matching brace highlight indicator number.
 -- @field INDIC_HIGHLIGHT (number)
@@ -37,6 +41,7 @@ M.strip_trailing_spaces = false
 M.autocomplete_all_words = false
 M.HIGHLIGHT_NONE, M.HIGHLIGHT_CURRENT, M.HIGHLIGHT_SELECTED = 1, 2, 3
 M.highlight_words = M.HIGHLIGHT_NONE
+M.auto_enclose = false
 M.INDIC_BRACEMATCH = _SCINTILLA.next_indic_number()
 M.INDIC_HIGHLIGHT = _SCINTILLA.next_indic_number()
 
@@ -477,6 +482,15 @@ function M.enclose(left, right)
   buffer:end_undo_action()
 end
 
+-- Enclose selected text in punctuation or auto-paired characters.
+events.connect(events.KEYPRESS, function(code)
+  if not M.auto_enclose or buffer.selection_empty or code >= 256 then return end
+  local char = string.char(code)
+  if char:find('^%P') then return end -- not punctuation
+  M.enclose(char, M.auto_pairs[code] or char)
+  return true -- prevent typing
+end, 1)
+
 ---
 -- Selects the text between strings *left* and *right* that enclose the caret.
 -- If that range is already selected, toggles between selecting *left* and
@@ -602,8 +616,8 @@ end
 -- have text selected is passed as stdin. However, if the end of the selection
 -- is at the beginning of a line, only the line ending delimiters from the
 -- previous line are included. The rest of the line is excluded.
--- @param command The Linux, BSD, Mac OSX, or Windows shell command to filter
---   text through. May contain pipes.
+-- @param command The Linux, BSD, macOS, or Windows shell command to filter text
+--   through. May contain pipes.
 -- @name filter_through
 function M.filter_through(command)
   assert(not (WIN32 and CURSES), 'not implemented in this environment')