Module textredux.core.buffer

Textredux buffers wrap Textadept buffers and extend them with support for custom styling, buffer specific key bindings and hotspot support.

Usage

You create a new Textredux buffer by calling new, passing the buffer title. You specify an on_refresh handler for the buffer, which is responsible for actually inserting the content in the buffer, along with any custom styles and hotspot handlers. Custom key bindings are specified using keys. In the on_refresh handler, you add the actual text using any of the extended text insertion functions (reduxbuffer:add_text, reduxbuffer:append_text, reduxbuffer:insert_text). You invoke reduxbuffer:show to show the buffer, and respond to any interactions using the provided callbacks.

local textredux = require('textredux')
local reduxbuffer = textredux.core.buffer.new('Example buffer')
reduxbuffer.on_refresh = function(buf)
  buf:add_text('Textredux!')
end
reduxbuffer:show()

If you need to test whether a Textadept buffer is used as a Textredux buffer you can check for the _textredux field.

events.connect(events.BUFFER_AFTER_SWITCH, function()
  local buffer = buffer
  if buffer._textredux then
    -- …
  end
end)

How it works

When you work with a Textredux buffer, it will nearly always seem just like an ordinary Textadept buffer (but with benefits, such as support for custom styling and easy callbacks, etc.). But where a Textadept buffer is volatile, and might cease to exists at any time (for example being closed by a user) a Textredux buffer is persistent.

When we say that a Textredux buffer “wraps” a Textadept buffer, there's more to it than just adding additional methods to the Textadept buffer API. A Textredux buffer will always exist, but the corresponding Textadept buffer, named target hereafter, may not. When the target buffer exists, a Textredux buffer will expose all the functions and attributes of the Textadept buffer, making it possible to use the Textredux buffer in just the same way as you would a Textadept buffer (i.e. invoking any of the ordinary buffer methods, setting attributes, etc.). Textredux takes care of creating the target buffer automatically if needed whenever you invoke reduxbuffer:show. When the target buffer does not exist, for instance as the result of the user closing it, any attempt to invoke any of the ordinary buffer methods will raise an error. You can check explicitly whether the target buffer exists by using the reduxbuffer:is_attached function. However, this is not something you will have to worry much about in practice, since you'll typically interact with the buffer as part of a refresh, key press, etc., where the target buffer will always exist.

In short, you don't have to worry about creating buffers, detecting whether the buffer was closed, etc., as long as you remember to invoke reduxbuffer:show and perform your work within the callbacks.

Functions

new (title) Creates and returns a new Textredux buffer.
reduxbuffer:show () Shows the buffer.
reduxbuffer:close () Closes the buffer.
reduxbuffer:update (callback) Performs an update of the buffer contents.
reduxbuffer:refresh () Refreshes the buffer.
reduxbuffer:set_title (title) Updates the title of the buffer.
reduxbuffer:is_attached () Checks whether a target buffer currently exists.
reduxbuffer:is_showing () Checks whether the buffer is currently showing in any view.
reduxbuffer:is_active () Checks whether the buffer is currently active, i.e.
reduxbuffer:add_hotspot (start_pos, end_pos, command) Adds a hotspot for the given text range.
reduxbuffer:add_text (text, style, command, indicator) Override for buffer:add_text which accepts optional style, command and indicator parameters.
reduxbuffer:append_text (text, style, command, indicator) Override for buffer:append_text which accepts optional style, command and indicator parameters.
reduxbuffer:insert_text (pos, text, style, command, indicator) Override for buffer:insert_text which accepts optional style, command and indicator parameters.

Instance fields

reduxbuffer.read_only Whether the buffer should be marked as read only.
reduxbuffer.on_deleted Callback invoked whenever the target buffer is deleted.
reduxbuffer.on_refresh Callback invoked whenever the buffer should refresh.
reduxbuffer.on_char_added Callback invoked when a CHAR_ADDED event is fired.
reduxbuffer.keys A table of key commands for the buffer.
reduxbuffer.data A general purpose table that can be used for storing state associated with the buffer.
reduxbuffer.target The target buffer, if any.
reduxbuffer.origin_buffer The buffer open when a Textredux buffer was shown.


Functions

new (title)
Creates and returns a new Textredux buffer. The buffer will not be attached upon the return.

Parameters:

  • title The title of the buffer. This will be displayed as the buffer's title in Textadept's top bar.
reduxbuffer:show ()
Shows the buffer. If the target buffer doesn't exist, due to it either not having been created yet or having been deleted, it is automatically created. Upon the return, the buffer is showing and set as the global buffer.
reduxbuffer:close ()
Closes the buffer.
reduxbuffer:update (callback)
Performs an update of the buffer contents. You invoke this with a callback that will do the actual update. This function takes care of ensuring that the target is writable, and handles setting the save point, etc.

Parameters:

  • callback The callback to invoke to perform the update. The callback will receive the buffer instance as its sole parameter.
reduxbuffer:refresh ()
Refreshes the buffer. A refresh works by ensuring that it's possible to write to the buffer and invoking the on_refresh handler. After the refresh is complete, the read_only state is reset to whatever it was before the refresh, and a save point is set.

Please note that a refresh will clear all content, along with hotspots, etc. If you want to perform smaller updates please use the buffer:update function instead.

reduxbuffer:set_title (title)
Updates the title of the buffer.

Parameters:

  • title
reduxbuffer:is_attached ()
Checks whether a target buffer currently exists.

Returns:

    true if the target buffer exists and false otherwise
reduxbuffer:is_showing ()
Checks whether the buffer is currently showing in any view.

Returns:

    true if the buffer is showing and false otherwise
reduxbuffer:is_active ()
Checks whether the buffer is currently active, i.e. the current buffer.

Returns:

    true if the buffer is active and false otherwise
reduxbuffer:add_hotspot (start_pos, end_pos, command)
Adds a hotspot for the given text range. Hotspots allows you to specify what happens when the user selects a text range. Besides using this function directly, it's also possible and in many cases more convenient to add a hotspot when using any of the text insertion functions (buffer:add_text, buffer:append_text, buffer:insert_text). Note that the range given is interpreted as being half closed, i.e. [start_pos, end_pos).

Note that all hotspots are cleared as part of a refresh.

Parameters:

  • start_pos The start position
  • end_pos The end position. The end position itself is not part of the hotspot.
  • command The command to execute. Similarily to keys, the command can be either a function or a table. When the command is a function, it will be passed the buffer instance as a parameter.
reduxbuffer:add_text (text, style, command, indicator)
Override for buffer:add_text which accepts optional style, command and indicator parameters.

Parameters:

reduxbuffer:append_text (text, style, command, indicator)
Override for buffer:append_text which accepts optional style, command and indicator parameters.

Parameters:

reduxbuffer:insert_text (pos, text, style, command, indicator)
Override for buffer:insert_text which accepts optional style, command and indicator parameters.

Parameters:

  • pos The position to insert text at or -1 for the current position.
  • text The text to insert.
  • style The style to use for the text, as defined using textredux.core.style.
  • command The command to run if the user "selects" this text. See buffer:add_hotspot for more information.
  • indicator Optional textredux.core.indicator to use for the inserted text.

Instance fields

These can be set for a buffer instance, and not globally for the module.
reduxbuffer.read_only
Whether the buffer should be marked as read only. The default is true but can be changed on a buffer to buffer basis. Any call to buffer:refresh will automatically take care of setting the buffer to write mode before invoking the on_refresh handler, and will restore the read_only state afterwards.
reduxbuffer.on_deleted
Callback invoked whenever the target buffer is deleted. The callback has the following with the following parameters: buffer
reduxbuffer.on_refresh
Callback invoked whenever the buffer should refresh. This should be set for each buffer. This callback is responsible for actually inserting any content into the buffer. Before this callback is invoked, any previous buffer content will be cleared. The callback will be invoked with the buffer as the sole parameter.

See also:

reduxbuffer.on_char_added
Callback invoked when a CHAR_ADDED event is fired. Receives the char as an argument. This can be used to handle keypresses in a buffer in read-only mode.
reduxbuffer.keys
A table of key commands for the buffer. This is simply a textadept.keys mode, which is set whenever the Textredux buffer is active. The format for specifying keys is the same as for textadept.keys, thus the values assigned can be either functions or tables.
reduxbuffer.data
A general purpose table that can be used for storing state associated with the buffer. The data table is will automatically be cleared whenever the target buffer is closed.
reduxbuffer.target
The target buffer, if any. This holds a reference to the target buffer, when present.
reduxbuffer.origin_buffer
The buffer open when a Textredux buffer was shown. Stored to be able to go back to after closing the Textredux buffer.