howl.Buffer

howl.Buffer

Overview

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:

Properties

can_undo

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

config

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.

data

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.

eol

The line ending currently in effect for the buffer. One of:

file

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.

last_shown

A timestamp value, as obtained from Lua’s os.time, specifying when the buffer was last showing.

length

The length of the buffer’s text, in code points.

lines

An instance of Lines for the buffer that allows for line based access to the content.

mode

The buffer’s mode. When assigning to this:

modified

A boolean indicating whether the buffer is modified or not. You can explicitly assign to this to force a particular status.

modified_on_disk

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.

multibyte

A boolean indicating whether the buffer’s text contains multibyte characters.

properties

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.

read_only

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.

showing

A boolean indicating whether the buffer is currently showing in any editor.

size

The size of the buffer’s text, in bytes.

text

The buffer’s text. Assigning to this causes the entire buffer contents to be replaced with the assigned text.

title

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.

Functions

Buffer(mode = {})

Creates a new buffer, optionally specifying its mode.

Methods

append(text)

Appends text to the end of the buffer’s current text.

as_one_undo(f)

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.

byte_offset(char_offset)

Returns the byte offset corresponding to the passed char_offset. Raises an error if char_offset is out of bounds.

char_offset(byte_offset)

Returns the character offset corresponding to the passed byte_offset. Raises an error if byte_offset is out of bounds.

chunk(start_pos, end_pos)

Returns a Chunk for the given range.

context_at(pos)

Returns a Context for the specified position.

delete(start_pos, end_pos)

Deletes the text between start_pos and end_pos, which specify an inclusive range.

insert(text, pos)

Inserts text at the position given by pos, and returns the position right after newly inserted text. examples.

lex(end_pos)

Lexes the buffer content using the modes lexer, if available. The content is lexed up until end_pos.

redo()

Redo the last, previously undone, buffer modification.

reload()

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.

replace(pattern, replacement)

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.

save()

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()

Undo the last buffer modification.