howl.breadcrumbs

Overview

The breadcrumbs module keeps track of previously visited locations within Howl, and provides functions for remembering a specific location as well as for navigating forward and backward in the breadcrumb trail.

Structure of a breadcrumb

Each crumb describes a previously visited location, and has the following fields:

As can be seen above, a crumb has a file reference, or a buffer reference via the buffer_marker field, or both at the same time. In the case where a marker is available that should be used for determining the correct position, as pos could be stale in those cases, due to later editing or modifications. crumb_pos can be used for correctly determining the up-to-date position of a given crumb.


Related:

Properties

location

The current location in the trail. As the user edits this will typically point to an uninitialized crumb, as it points to the position that will be next used for storing a crumb using drop.

next

The next crumb in the trail, if any. This will be non-nil only if the user has navigated back in the breadcrumb trail.

previous

The previous crumb in the trail, if any, or nil.

trail

The table of breadcrumbs.

Functions

clear ()

Clears all current breadcrumbs. After this location would be 1, and trail would have a size of 0.

crumb_pos (crumb)

Returns the position of crumb. Note that this can potentially return nil, if the crumb in question have become stale, meaning that it referred to a buffer that has disappeared.

drop (opts)

Inserts a crumb at the current location based on on the value in opts, if provided, or otherwise on the current edit location. opts can contain the following fields:

If opts is provided, then pos must be present, and at least one of buffer and file. If opts is nil then a breadcrumb based on the current editing location.

go_back ()

This moves backwards in the breadcrumb trail, if possible. Note that as part of moving backwards, a new crumb is first inserted at the current location.

go_forward ()

This moves forward in the breadcrumb trail, if possible. Note that as part of moving forward, a new crumb is first inserted at the current location.