Interface History

  • All Superinterfaces:
    java.lang.Iterable<History.Entry>
    All Known Implementing Classes:
    DefaultHistory

    public interface History
    extends java.lang.Iterable<History.Entry>
    Console command history management interface.

    The History interface provides functionality for storing, retrieving, and navigating through previously entered commands. It allows users to recall and reuse commands they've typed before, which is a fundamental feature of interactive command-line interfaces.

    History implementations typically support:

    • Adding new entries as commands are executed
    • Navigating backward and forward through history
    • Persisting history to a file for use across sessions
    • Filtering or ignoring certain commands based on patterns

    Each history entry contains the command text along with metadata such as the timestamp when it was executed.

    The default implementation is DefaultHistory.

    Since:
    2.3
    See Also:
    LineReader.getHistory(), LineReaderBuilder.history(History)
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Interface Description
      static interface  History.Entry
      Represents a single history entry containing a command line and its metadata.
    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      default void add​(java.lang.String line)  
      void add​(java.time.Instant time, java.lang.String line)
      Adds a new item to the history with the specified timestamp.
      void append​(java.nio.file.Path file, boolean incremental)
      Append history to the file.
      void attach​(LineReader reader)
      Initialize the history for the given reader.
      java.lang.String current()
      Return the content of the current buffer.
      int first()
      Returns the index of the first element in the history.
      java.lang.String get​(int index)
      Returns the history item at the specified index.
      int index()
      Returns the current index in the history.
      default boolean isEmpty()
      Checks if the history is empty.
      default boolean isPersistable​(History.Entry entry)
      Check if an entry should be persisted or not.
      default java.util.ListIterator<History.Entry> iterator()  
      java.util.ListIterator<History.Entry> iterator​(int index)
      Returns a list iterator over the history entries starting at the specified index.
      int last()
      Returns the index of the last element in the history.
      void load()
      Load history.
      boolean moveTo​(int index)
      Move to the specified index in the history
      void moveToEnd()
      Move to the end of the history buffer.
      boolean moveToFirst()
      Moves the history index to the first entry.
      boolean moveToLast()
      This moves the history to the last entry.
      boolean next()
      Move the pointer to the next element in the buffer.
      boolean previous()
      Move the pointer to the previous element in the buffer.
      void purge()
      Purge history.
      void read​(java.nio.file.Path file, boolean checkDuplicates)
      Read history from the file.
      void resetIndex()
      Reset index after remove
      default java.util.Iterator<History.Entry> reverseIterator()  
      default java.util.Iterator<History.Entry> reverseIterator​(int index)  
      void save()
      Save history.
      int size()
      Returns the number of items in the history.
      void write​(java.nio.file.Path file, boolean incremental)
      Write history to the file.
      • Methods inherited from interface java.lang.Iterable

        forEach, spliterator
    • Method Detail

      • attach

        void attach​(LineReader reader)
        Initialize the history for the given reader.
        Parameters:
        reader - the reader to attach to
      • load

        void load()
           throws java.io.IOException
        Load history.
        Throws:
        java.io.IOException - if a problem occurs
      • save

        void save()
           throws java.io.IOException
        Save history.
        Throws:
        java.io.IOException - if a problem occurs
      • write

        void write​(java.nio.file.Path file,
                   boolean incremental)
            throws java.io.IOException
        Write history to the file. If incremental only the events that are new since the last incremental operation to the file are added.
        Parameters:
        file - History file
        incremental - If true incremental write operation is performed.
        Throws:
        java.io.IOException - if a problem occurs
      • append

        void append​(java.nio.file.Path file,
                    boolean incremental)
             throws java.io.IOException
        Append history to the file. If incremental only the events that are new since the last incremental operation to the file are added.
        Parameters:
        file - History file
        incremental - If true incremental append operation is performed.
        Throws:
        java.io.IOException - if a problem occurs
      • read

        void read​(java.nio.file.Path file,
                  boolean checkDuplicates)
           throws java.io.IOException
        Read history from the file. If checkDuplicates is true only the events that are not contained within the internal list are added.
        Parameters:
        file - History file
        checkDuplicates - If true, duplicate history entries will be discarded
        Throws:
        java.io.IOException - if a problem occurs
      • purge

        void purge()
            throws java.io.IOException
        Purge history.
        Throws:
        java.io.IOException - if a problem occurs
      • size

        int size()
        Returns the number of items in the history.
        Returns:
        the number of history items
      • isEmpty

        default boolean isEmpty()
        Checks if the history is empty.
        Returns:
        true if the history contains no items
      • index

        int index()
        Returns the current index in the history.
        Returns:
        the current index
      • first

        int first()
        Returns the index of the first element in the history.
        Returns:
        the index of the first history item
      • last

        int last()
        Returns the index of the last element in the history.
        Returns:
        the index of the last history item
      • get

        java.lang.String get​(int index)
        Returns the history item at the specified index.
        Parameters:
        index - the index of the history item to retrieve
        Returns:
        the history item at the specified index
      • add

        default void add​(java.lang.String line)
      • add

        void add​(java.time.Instant time,
                 java.lang.String line)
        Adds a new item to the history with the specified timestamp.
        Parameters:
        time - the timestamp for the history item
        line - the line to add to the history
      • isPersistable

        default boolean isPersistable​(History.Entry entry)
        Check if an entry should be persisted or not.
        Parameters:
        entry - the entry to check
        Returns:
        true if the given entry should be persisted, false otherwise
      • iterator

        java.util.ListIterator<History.Entry> iterator​(int index)
        Returns a list iterator over the history entries starting at the specified index.
        Parameters:
        index - the index to start iterating from
        Returns:
        a list iterator over the history entries
      • iterator

        default java.util.ListIterator<History.Entry> iterator()
        Specified by:
        iterator in interface java.lang.Iterable<History.Entry>
      • reverseIterator

        default java.util.Iterator<History.Entry> reverseIterator()
      • reverseIterator

        default java.util.Iterator<History.Entry> reverseIterator​(int index)
      • current

        java.lang.String current()
        Return the content of the current buffer.
        Returns:
        the content of the current buffer
      • previous

        boolean previous()
        Move the pointer to the previous element in the buffer.
        Returns:
        true if we successfully went to the previous element
      • next

        boolean next()
        Move the pointer to the next element in the buffer.
        Returns:
        true if we successfully went to the next element
      • moveToFirst

        boolean moveToFirst()
        Moves the history index to the first entry.
        Returns:
        Return false if there are no iterator in the history or if the history is already at the beginning.
      • moveToLast

        boolean moveToLast()
        This moves the history to the last entry. This entry is one position before the moveToEnd() position.
        Returns:
        Returns false if there were no history iterator or the history index was already at the last entry.
      • moveTo

        boolean moveTo​(int index)
        Move to the specified index in the history
        Parameters:
        index - The index to move to.
        Returns:
        Returns true if the index was moved.
      • moveToEnd

        void moveToEnd()
        Move to the end of the history buffer. This will be a blank entry, after all of the other iterator.
      • resetIndex

        void resetIndex()
        Reset index after remove