Buffers are in-memory containers of text. While they are often associated with a specific file on disk, this need not be the case. Instead they simply represent some textual content loaded into memory, available for manipulation within Howl. Buffer manipulation is typically done in one of two ways; it can be done as a result of a user interacting with an Editor displaying a particular buffer, or it can be done programmatically by manipulating the buffer directly.
Buffers can be created directly and used without being associated with a file or an Editor, or without showing up in the buffer list. But if you want the buffer to show up in the buffer list you need to either create it through, or register it with, Application.
See also:
Whether the buffer contains any undo information that can be undo via the undo method. You can assign false to clear any undo information currently available for a particular buffer.
local buffer = Buffer() buffer.text = 'my buffer text!' print(buffer.can_undo) -- => true buffer.can_undo = false print(buffer.can_undo) -- => false
A configuration object that can be used to access and manipulate config variables for a certain buffer. This object is automatically chained to the buffer’s mode’s config property, meaning it will defer to what is set for the mode (and in extension set globally) should a particular configuration variable not be set specifically for the buffer.
A general-purpose table that can be used for storing arbitrary information about a particular buffer. Intended as a way for any Howl code to have a place to assign data with a buffer. Similar to properties but ephemeral, i.e. any data in this table will be lost upon a restart. As this is shared by all Howl code, take care to namespace any specific data properly.
The line ending currently in effect for the buffer. One of:
'\n'
'\r\n'
'\r'
An optional file associated with the current buffer. Assigning to this causes the buffer to be loaded with the file’s contents, provided that the file exists and that the buffer is not currently modified. The buffer’s title is automatically updated from the file’s name.
A timestamp value, as obtained from Lua’s os.time
, specifying when the buffer
was last showing.
The length of the buffer’s text, in code points.
An instance of Lines for the buffer that allows for line based access to the content.
The buffer’s mode. When assigning to this:
buffer-mode-set
signal is emitted.A boolean indicating whether the buffer is modified or not. You can explicitly assign to this to force a particular status.
For a buffer with an associated file, this is a boolean indicating whether the file has changed since its contents was loaded into the buffer. Always false for a buffer without an associated file.
A boolean indicating whether the buffer’s text contains multibyte characters.
A general-purpose table that can be used for storing arbitrary information about a particular buffer. Intended as a way for any Howl code to have a place where to store persistent information for a buffer. The contents of this is automatically serialized and restored with the session. As this is shared by all Howl code, take care to namespace any specific data properly.
A boolean specifying whether the buffer is read-only or not. A read-only buffer can not be modified. Assign to this to control the status.
A boolean indicating whether the buffer is currently showing in any editor.
The size of the buffer’s text, in bytes.
The buffer’s text. Assigning to this causes the entire buffer contents to be replaced with the assigned text.
The buffer’s title. This is automatically set whenever assigning a file
to a buffer, but can be explicitly specified as well. Assigning to this causes
the buffer-title-set
signal to be emitted.
Creates a new buffer, optionally specifying its mode.
Appends text
to the end of the buffer’s current text.
Invokes the function f
, and collects any modifications performed within f
as
one undo group. Calling this, and subsequently calling undo will thus
undo all modifications made within f
.
Returns the byte offset corresponding to the passed char_offset
. Raises an
error if char_offset
is out of bounds.
Returns the character offset corresponding to the passed byte_offset
. Raises
an error if byte_offset
is out of bounds.
Returns a Chunk for the given range.
Returns a Context for the specified position.
Deletes the text between start_pos
and end_pos
, which specify an inclusive
range.
Inserts text
at the position given by pos
, and returns the position right
after newly inserted text. examples.
Lexes the buffer content using the modes lexer, if available. The
content is lexed up until end_pos
.
Redo the last, previously undone, buffer modification.
Reloads the buffer contents from its associated file. Raises an error
if the buffer does not have any associated file. Emits the buffer-reloaded
signal.
Replaces all occurrences of pattern
with replacement
, and returns the number
of replacements made. pattern
can be either a Lua pattern, or a regular
expression.
Saves the buffer’s content to its associated file, if any. Emits the
buffer-saved
signal. As part of saving the content, optionally removes any
trailing white-space and ensures that there’s an eol at the end of the file,
according to the strip_trailing_whitespace
and ensure_newline_at_eof
configuration variables.
Undo the last buffer modification.