diff options
Diffstat (limited to 'core')
| -rw-r--r-- | core/._M.luadoc | 51 | ||||
| -rw-r--r-- | core/events.lua | 31 | ||||
| -rw-r--r-- | core/file_io.lua | 30 | ||||
| -rw-r--r-- | core/keys.lua | 67 |
4 files changed, 89 insertions, 90 deletions
diff --git a/core/._M.luadoc b/core/._M.luadoc index 7b459468..9eb70f64 100644 --- a/core/._M.luadoc +++ b/core/._M.luadoc @@ -9,21 +9,21 @@ -- ## Module Guidelines -- -- At the very least, modules consist of a single directory with an *init.lua* --- script. However, the script can load additional Lua files present in the +-- script. However, the script may load additional Lua files present in the -- directory. (For an example, see *modules/textadept/init.lua*.) -- --- Once modules are loaded, regardless of whether they are generic or --- language-specific, they persist in Textadept's Lua State; they are never --- unloaded. Therefore, modules should not set global functions or variables in --- order to avoid polluting the global environment. All functions and variables --- should be contained within the module. +-- Loaded modules, regardless of whether they are generic or language-specific, +-- persist in Textadept's Lua State; Textadept never unloads them. Therefore, +-- modules should define functions or variables within the module itself, not +-- globally. -- -- ### Language-Specific -- -- To fully take advantage of Textadept's features, language-specific modules -- should have at a minimum: a block comment string, run and/or compile --- commands, a buffer property setter function, and if possible, an Adeptsense. --- Optional features are extra snippets and commands and a context menu. +-- commands, an event handler for setting buffer properties like indentation, +-- and if possible, an Adeptsense. Optional features are extra snippets and +-- commands and a context menu. -- -- #### Block Comment -- @@ -51,8 +51,7 @@ -- -- The module should also define error details in -- [`_M.textadept.run.error_detail`][] so double-clicking on compile or runtime --- errors will jump to the error's location. The format for Lua errors looks --- like +-- errors jumps to the error's location. The format for Lua errors looks like -- -- _M.textadept.run.error_detail.lua = { -- pattern = '^lua: (.-):(%d+): (.+)$', @@ -89,7 +88,7 @@ -- -- #### Snippets -- --- [Snippets][] for common language constructs can be useful. Some snippets for +-- [Snippets][] for common language constructs are useful. Some snippets for -- common Lua control structures look like -- -- snippets.lua = { @@ -109,23 +108,15 @@ -- the current line and insert a new line. Both are bound to the `Shift+Enter` -- (`⇧↩` on Mac OSX | `S-Enter` in curses) key for easy access. -- --- function M.try_to_autocomplete_end() --- ... --- end --- --- keys.lua = { --- ['s\n'] = M.try_to_autocomplete_end --- } --- --- --- --- --- keys.cpp = { --- ['s\n'] = function() --- buffer:line_end() --- buffer:add_text(';') --- buffer:new_line() --- end --- } +-- -- In file *lua/init.lua* | -- In file *cpp/init.lua* +-- | +-- function M.try_to_autocomplete_end() | keys.cpp = { +-- ... | ['s\n'] = function() +-- end | buffer:line_end() +-- | buffer:add_text(';') +-- keys.lua = { | buffer:new_line() +-- ['s\n'] = M.try_to_autocomplete_end | end +-- } | } -- -- [Lua]: _M.lua.html -- [C/C++]: _M.cpp.html @@ -133,8 +124,8 @@ -- #### Context Menu -- -- Language-specific [context menus][], accessible by right-clicking inside the --- view, can be useful for accessing module features without using key bindings. --- For Lua this may look like +-- view, are useful for accessing module features without using key bindings. +-- For Lua this might look like -- -- M.context_menu = { -- { _L['_Undo'], buffer.undo }, diff --git a/core/events.lua b/core/events.lua index 02bb81b2..ee058d5b 100644 --- a/core/events.lua +++ b/core/events.lua @@ -8,20 +8,25 @@ local M = {} -- -- ## Overview -- --- Events occur when you do things like create a new buffer, press a key, click --- on a menu, etc. You can even emit events yourself using Lua. Each event has a --- set of event handlers, which are simply Lua functions called in the order --- they were connected to an event. This enables dynamically loaded modules to --- connect to events. +-- Textadept emits events when you do things like create a new buffer, press a +-- key, click on a menu, etc. You can even emit events yourself using Lua. Each +-- event has a set of event handlers, which are simply Lua functions called in +-- the order they were connected to an event. For example, if you created a +-- module that needs to do something each time Textadept creates a new buffer, +-- connect a Lua function to the [BUFFER_NEW](#BUFFER_NEW) event: -- --- Events themselves are nothing special. They do not have to be declared in --- order to be used. They are simply strings containing an arbitrary event name. --- When an event of this name is emitted, either by Textadept or you, all event --- handlers assigned to it are run. Events can be given any number of arguments. --- These arguments will be passed to the event's handler functions. If an event --- handler returns a `true` or `false` boolean value explicitly, no subsequent --- handlers are called. This is useful if you want to stop the propagation of an --- event like a keypress if it has already been handled. +-- events.connect(events.BUFFER_NEW, function() +-- -- Do something here. +-- end) +-- +-- Events themselves are nothing special. You do not have to declare one before +-- using it. Events are simply strings containing arbitrary event names. When +-- either you or Textadept emits an event, Textadept runs all event handlers +-- connected to the event, passing any given arguments to the event's handler +-- functions. If an event handler explicitly returns a `true` or `false` boolean +-- value, Textadept will not call subsequent handlers. This is useful if you +-- want to stop the propagation of an event like a keypress if your event +-- handler handled it. -- -- @field APPLEEVENT_ODOC (string) -- Emitted when Mac OSX tells Textadept to open a document. diff --git a/core/file_io.lua b/core/file_io.lua index 7dd0e354..24fa4a8a 100644 --- a/core/file_io.lua +++ b/core/file_io.lua @@ -6,22 +6,26 @@ -- -- ## Working with UTF-8 -- --- If your filesystem does not use UTF-8-encoded filenames (e.g. Windows), --- conversions to and from that encoding are necessary since all of Textadept's --- internal strings are UTF-8-encoded. When opening and saving files through --- dialogs, these conversions are performed automatically, but if you need to do --- them manually, use [`string.iconv()`][] along with [`_CHARSET`][], your --- filesystem's detected encoding. An example is +-- Textadept encodes all of its filenames, like [`buffer.filename`][], in UTF-8. +-- If you try to use Lua to access the file associated with such a filename, you +-- may not get the right file if your filesystem's encoding is not UTF-8 (e.g. +-- Windows). -- --- <div style="clear: right;"><!-- Clear Table of Contents --></div> +-- -- May not work on non-UTF-8 filesystems. +-- local f = io.open(buffer.filename, 'rb') -- --- events.connect(events.FILE_OPENED, function(utf8_filename) --- local filename = utf8_filename:iconv(_CHARSET, 'UTF-8') --- local f = io.open(filename, 'rb') --- -- process file --- f:close() --- end) +-- You need to convert the filename to the filesystem's encoding using +-- [`string.iconv()`][] along with [`_CHARSET`][]: -- +-- local name = string.iconv(buffer.filename, +-- _CHARSET, 'UTF-8') +-- local f = io.open(name, 'rb') +-- +-- Textadept automatically performs filename conversions for you when opening +-- and saving files through dialogs. You only need to do manual conversions when +-- working with the filesystem directly from Lua. +-- +-- [`buffer.filename`]: buffer.html#filename -- [`string.iconv()`]: string.html#iconv -- [`_CHARSET`]: _G.html#_CHARSET -- @field _G.events.FILE_OPENED (string) diff --git a/core/keys.lua b/core/keys.lua index 60f404a3..fc25b69a 100644 --- a/core/keys.lua +++ b/core/keys.lua @@ -8,21 +8,21 @@ local M = {} -- -- ## Overview -- --- Key bindings are defined in the global table `keys`. Each key-value pair in --- `keys` consists of either a string key sequence and its associated command, --- a string lexer language (from the *lexers/* directory) with a table of key --- sequences and commands, a string key mode with a table of key sequences and --- commands, or a key sequence with a table of more sequences and commands. The --- latter is part of what is called a "key chain", to be discussed below. When --- searching for a command to run based on a key sequence, key bindings in the --- current key mode have priority. If no key mode is active, key bindings in the --- current lexer have priority, followed by the ones in the global table. This --- means if there are two commands with the same key sequence, the one specific --- to the current lexer is run. However, if the command returns the boolean --- value `false`, the lower-priority command is also run. (This is useful for --- language-specific modules to override commands like Adeptsense --- autocompletion, but fall back to word autocompletion if the first command --- fails.) +-- Define key bindings in the global `keys` table in key-value pairs. Each pair +-- consists of either a string key sequence and its associated command, a string +-- lexer language (from the *lexers/* directory) with a table of key sequences +-- and commands, a string key mode with a table of key sequences and commands, +-- or a key sequence with a table of more sequences and commands. The latter is +-- part of what is called a "key chain", to be discussed below. When searching +-- for a command to run based on a key sequence, Textadept considers key +-- bindings in the current key mode to have priority. If no key mode is active, +-- key bindings in the current lexer have priority, followed by the ones in the +-- global table. This means if there are two commands with the same key +-- sequence, Textadept runs the one specific to the current lexer. However, if +-- the command returns the boolean value `false`, Textadept also runs the +-- lower-priority command. (This is useful for language-specific modules to +-- override commands like Adeptsense autocompletion, but fall back to word +-- autocompletion if the first command fails.) -- -- ## Key Sequences -- @@ -39,24 +39,23 @@ local M = {} -- Shift | `'s'` | `'s'` | `'s'` | -- Command | N/A | `'c'` | N/A | -- --- For key values less than 255, their string representation is the character --- that would normally be inserted if the "Control", "Alt", and "Command" +-- The string representation of key values less than 255 is the character that +-- Textadept would normally insert if the "Control", "Alt", and "Command" -- modifiers were not held down. Therefore, a combination of `Ctrl+Alt+Shift+A` -- has the key sequence `caA` on Windows and Linux, but a combination of -- `Ctrl+Shift+Tab` has the key sequence `cs\t`. On a United States English -- keyboard, since the combination of `Ctrl+Shift+,` has the key sequence `c<` --- (`Shift+,` inserts a `<`), the key binding is referred to as `Ctrl+<`. This --- allows key bindings to be language and layout agnostic. For key values --- greater than 255, the [`KEYSYMS`](#KEYSYMS) lookup table is used. Therefore, --- `Ctrl+Right Arrow` has the key sequence `cright`. Uncommenting the `print()` --- statements in *core/keys.lua* will print key sequences to standard out --- (stdout) for inspection. +-- (`Shift+,` inserts a `<`), Textadept recognizes the key binding as `Ctrl+<`. +-- This allows key bindings to be language and layout agnostic. For key values +-- greater than 255, Textadept uses the [`KEYSYMS`](#KEYSYMS) lookup table. +-- Therefore, `Ctrl+Right Arrow` has the key sequence `cright`. Uncommenting the +-- `print()` statements in *core/keys.lua* causes Textadept to print key +-- sequences to standard out (stdout) for inspection. -- -- ## Commands -- --- Commands bound to key sequences can be either Lua functions, or tables --- containing Lua functions with a set of arguments to call the function with. --- Examples are: +-- A command bound to a key sequence is either a Lua function or a table +-- containing a Lua function with a set of arguments to pass. Examples are: -- -- keys['cn'] = buffer.new -- keys['cs'] = buffer.save @@ -66,15 +65,15 @@ local M = {} -- (The function and function table syntax are functionally equivalent. You can -- use either.) -- --- [`buffer`][] references are handled properly in static contexts. +-- Textadept handles [`buffer`][] references properly in static contexts. -- -- [`buffer`]: buffer.html -- -- ## Modes -- --- Sets of key bindings can be grouped together into modes. When a key --- [mode](#MODE) is active, all key bindings defined outside the mode are --- ignored until the mode is unset. Here is a simple vi mode example: +-- You can group together sets of key bindings into modes. When a key +-- [mode](#MODE) is active, Textadept ignores all key bindings defined outside +-- the mode until the mode is unset. Here is a simple vi mode example: -- -- keys.command_mode = { -- ['h'] = buffer.char_left, @@ -95,11 +94,11 @@ local M = {} -- -- ## Key Chains -- --- Key chains are a powerful concept. They allow multiple key bindings to be --- assigned to one key sequence. Language-specific modules +-- Key chains are a powerful concept. They allow you to assign multiple key +-- bindings to one key sequence. Language-specific modules -- [use key chains](#LANGUAGE_MODULE_PREFIX) for their functions. By default, --- the `Esc` (`⎋` on Mac OSX | `Esc` in curses) key cancels a key chain, but it --- can be redefined via [`CLEAR`](#CLEAR). An example key chain looks like: +-- the `Esc` (`⎋` on Mac OSX | `Esc` in curses) key cancels a key chain, but you +-- can redefine it via [`CLEAR`](#CLEAR). An example key chain looks like: -- -- keys['aa'] = { -- a = function1, |