15. Overview of the Ring Package

In this lesson, we will explore the fundamentals of the built-in ring package, which is useful for managing histories. We will leverage this package to implement a the prompt history feature of chatgpt.el package.

With the ring package, we can efficiently add or remove elements and, given any element, easily access its previous or next neighbor.

Creating Rings and Inserting Elements¶

In this section, we demonstrate two methods to create rings and two methods for inserting elements.

First, we create a ring variable r with a size of 3 using the make-ring function:

(setq r (make-ring 3)) ;; (0 0 . [nil nil nil])

We confirm that the ring is empty by checking:

(ring-empty-p r) ;;

Next, we insert three elements into the ring using the ring-insert function:

(ring-insert r "foo-1") ;; "foo-1"
(ring-insert r "foo-2") ;; "foo-2"
(ring-insert r "foo-3") ;; "foo-3"

To view the elements in the ring, we can use the ring-elements function. For our ring r, it returns the following list, "foo-1" being the oldest element and "foo-3" the newest:

(ring-elements r) ;; ("foo-3" "foo-2" "foo-1")

Next, we insert a fourth element, "foo-4", into this full ring:

(ring-insert r "foo-4")

Listing the elements again, we can observe that the oldest element "foo-1" has been removed, the ring rotated, and "foo-4" is now the newest element:

(ring-elements r) ;; ("foo-4" "foo-3" "foo-2")

Now, let's explore another approach for creating rings and inserting elements that allows for ring enlargement without dropping the oldest element.

We initialize the ring r with three elements using ring-convert-sequence-to-ring, which converts a sequence into a ring:

(setq r (ring-convert-sequence-to-ring '("foo-3" "foo-2" "foo-1")))

We can list r elements:

(ring-elements r) ;; ("foo-3" "foo-2" "foo-1")

Now, we use ring-insert+extend to insert "foo-4" while enlarging the ring instead of discarding the oldest element:

(ring-insert+extend r "foo-4" t) ;; "foo-4"

The updated elements in ring r now show that the oldest element remains the same, and the ring has been enlarged:

(ring-elements r) ;; ("foo-4" "foo-3" "foo-2" "foo-1")

Accessing Ring Elements¶

In this section, we learn how to access elements in a ring.

First, we define the ring r again with three elements:

(setq r (ring-convert-sequence-to-ring '("foo-3" "foo-2" "foo-1")))

We can confirm the elements in ring r as follows:

(ring-elements r) ;; ("foo-3" "foo-2" "foo-1")

Now, we use the ring-ref function to access elements by their index:

(ring-ref r 0) ;; "foo-3"
(ring-ref r 1) ;; "foo-2"

To retrieve the next or previous element for a given value, we use the ring-next and ring-previous functions:

(ring-next r "foo-2") ;; "foo-1"
(ring-previous r "foo-2") ;; "foo-3"

If we attempt to get the next element of the oldest entry, ring-next wraps back to the newest element:

(ring-next r "foo-1") ;; "foo-3"

Conversely, attempting to get the previous element of the newest entry wraps back to the oldest:

(ring-previous r "foo-3") ;; "foo-1"

Lastly, note that trying to access the next or previous element of a non-existent item raises an error:

(ring-next r "not-in-r")
 ;; ring-next: Item is not in the ring: ‘not-in-r’

In the subsequent lesson, we will apply the concepts from this lesson and the previous one to implement the prompt history feature.