JLine3 History

JLine3のHistoryのメモ。

概要

Historyは、JLine3でユーザーが入力した文字列の履歴を扱うクラス（インターフェース）。

import org.jline.reader.History;

HistoryはLineReaderで保持される。
デフォルトではDefaultHistoryというクラスが使われる。
LineReaderのreadLineメソッドで読み込まれた文字列がHistoryに登録される。

デフォルトでは、カーソルキーの上で過去に入力した文字列が表示される。下を押すとその履歴より後の文字列が表示される。
Ctrl+Rで、文字列の先頭を入力してそれにマッチする履歴だけを表示できる。

これらのキーバインドはLineReaderImplで定義されている。
（デフォルトはemacsバインドになっていて、viバインドにも変更できる模様）

	bind(emacs, DOWN_LINE_OR_HISTORY,	ctrl('N'));
	bind(emacs, UP_LINE_OR_HISTORY,  	ctrl('P'));

	bind(emacs, HISTORY_INCREMENTAL_SEARCH_BACKWARD,	ctrl('R'));
	bind(emacs, HISTORY_INCREMENTAL_SEARCH_FORWARD, 	ctrl('S'));

Historyは、入力された履歴をファイルへ読み書き（保存）する機能を備えている。
→履歴をファイルに保存する例

履歴を取得する例

履歴の取得に関係するHistoryのメソッドは何種類かある。

    History history = lineReader.getHistory();
    System.out.println(history.get(history.last()));

HistoryはIterableを実装しているので、iteratorメソッドやfor文が使用できる。

    for (History.Entry entry : history) {
        System.out.println(entry.index());
        System.out.println(ZonedDateTime.ofInstant(entry.time(), ZoneId.of("Asia/Tokyo")));
        System.out.println(entry.line()); // 履歴の文字列
    }

履歴を追加する例

履歴はHistoryのaddメソッドで追加する。

    History history = lineReader.getHistory();
    history.add("abc");

内部的には、現在時刻も一緒に登録するようになっている。

履歴をファイルに保存する例

ユーザーが入力した文字列の履歴をファイルに読み書きするHistoryのメソッドは何種類かある。

import java.nio.file.Path;

    var path = Path.of(System.getProperty("java.io.tmpdir"), "jline-example-history.txt");
    lineReader.setVariable(LineReader.HISTORY_FILE, path);
    lineReader.setOpt(Option.HISTORY_TIMESTAMPED);

//  History history = lineReader.getHistory();
//  history.attach(lineReader); // attachの中でloadされる（LineReaderImpl.readLine()内でattachされるので、明示的にattachする必要は無い）
//  history.load();

    for (;;) {
        String line = lineReader.readLine("jline> ");
        if (line.equals("exit")) {
            break;
        }
        if (line.equals("history")) {
            System.out.println("history=" + history);
        }

        terminal.writer().println(line);
    }

//  history.save();

LineReader.HISTORY_FILEで履歴ファイルのパスを設定しておけば、履歴は（LineReaderImpl.readLine()内で）自動的に読み込まれる （loadされる）。
また、デフォルトでは（Option.HISTORY_INCREMENTALがtrueなので）readLine()で1行入力する毎に履歴ファイルに保存される（saveされる）。

ちなみに、履歴ファイルは1行にひとつの履歴が入ったテキストファイル（UTF-8）。
（複数行の文字列でも、改行コードが「\r」や「\n」にエスケープされて必ず1行になる）

$TMP/jline-example-history.txtの例

1663663742270:aaa
1663663744867:bbb
1663663746476:abc

各行の形式は2通りある。デフォルトは「タイムスタンプ:文字列」という形式。
→Option.HISTORY_TIMESTAMPED

Historyのオプション

LineReaderのオプションで履歴関連の設定が出来る。

History関連のオプションをLineReaderでセットする仕様はいただけないと思うが＾＾；
オプションをセットする機構がLineReaderにあるので、それを利用している形かなぁ…。

import org.jline.reader.LineReader;
import org.jline.reader.LineReader.Option;

import java.nio.file.Path;

    Path path = Path.of(System.getProperty("java.io.tmpdir"), "jline-example-history.txt");
    lineReader.setVariable(LineReader.HISTORY_FILE, path);
    lineReader.setOpt(Option.HISTORY_IGNORE_DUPS);

//  lineReader.getHistory().attach(lineReader);

LineReaderで定義されている定数を使って設定する場合はLineReader#setVariable()（あるいはvariable()）を使う。
LineReader.Optionで定義されている定数を使って設定する場合はLineReader#setOpt()やunsetOpt()（あるいはoption()）を使う。

それから、History（DefaultHistory）の中でLineReaderの設定を参照する為に、HistoryにLineReaderをアタッチする必要がある。
ただし、LineReaderImpl.readLine()の中でアタッチされるので、自分で明示的にsave/loadを実行したい場合以外はattachメソッドを呼ぶ必要は無い。
（attachメソッドを呼ぶと、内部でload（履歴ファイルの読み込み）が実行される）

特定の履歴をファイルに保存しない例

HistoryのisPersistableメソッドをオーバーライドすると、特定の履歴（文字列）だけファイルに保存しないということが出来る。

import org.jline.reader.impl.history.DefaultHistory;

public class MyHistory extends DefaultHistory {

    @Override
    public boolean isPersistable(Entry entry) {
        String line = entry.line();
        if (line.startsWith(":") || line.startsWith("\\")) {
            // :や\で始まる文字列は履歴ファイルに保存しない
            return false;
        }
        return true;
    }
}

    LineReader lineReader = LineReaderBuilder.builder()
        .history(new MyHistory())
        .build();

ちなみに、LineReader.HISTORY_IGNOREという設定値もあるが、これは履歴ファイルへ保存しないものではなく、履歴自体へ登録しないパターンを設定する。
（ちなみにそれもmatchPatternsメソッドをオーバーライドすれば、自由に変更できる）