howl.clipboard
Overview
The clipboard module keeps track of copied text in Howl, and handles synchronization with the system clipboard and primary selection. It provides two ways of remembering clipboard items: As a list of anynomous clips that is automatically updated with each copy/delete/cut operation, and within named registers.
Clipboard items
A clipboard item is a simple Lua table. The simplest and most common type of
item contains only one field, text
, that contains the text of the item. There
is no real restriction on what additional fields can be available for a
clipboard item (the fields can be specified when doing a push), but so
far one specific field is in use; The whole_lines
field, when set to true
,
indicates that the text should be considered a block of stand-alone lines,
rather than a simple chunk of text.
See also:
- The spec for clipboard
Properties
clips
A table (list) of clipboard items available on the clipboard, with the most
recent item being at index 1 in the table. The maximum number of clipboard items
is controlled by the clipboard_max_items
config variable. clips
is
automatically updated whenever a new item is push()ed, prepending the
new item and removing older items as necessary.
current
The most recent anynomous clipboard item available on the clipboard.
primary
The primary
object is used for synchronization with the systems primary
selection (i.e. the one used for middle button action). It has a .text
property that can be used to fetch or store the contents of the primary
selection, as well as a clear
method that can be used for clearing the
selection. In contrast to the ordinary clipboard it’s possible to set virtual
content for the primary clipboard, via the use of a provider function. Such a
function would be called on-demand as necessary to provide the content.
Example:
primary = howl.clipboard.primary primary.text = 'direct' print primary.text -- => 'direct' primary.text = -> 'on-demand' print primary.text -- => 'on-demand' primary\clear!
registers
A table containing named clipboard items. As an example, suppose a clipboard
item containing the text “hello” has been push()ed to the abc
register. In that case the registers
table would look like the following:
{ abc = { text: 'hello' } }
Functions
push (item, options = {})
Pushes the specified item
to the clipboard. item
can either be table
containing a text
field, along with optional additional fields, or it can be a
string in which case a clipboard item table is automatically constructed.
The optional options
table allows for specifying a named register where to
store the item. The to
field specifies the register name to use for storing
the clip in this case.
The pushed item is made available to the system clipboard automatically, except
when pushing to a named register using the to
field in options
.
Examples:
-- Push some text to the clipboard howl.clipboard.push('my text') -- Push a clipboard item with additional fields howl.clipboard.push({text = 'my text', whole_lines = true}) -- Push some text to the register 'a' howl.clipboard.push('my text', { to = 'a' } )