JLine: Интерактивная Java Console в стиле Quake

Каждому программисту в жизни приходилось писать небольшие консольные утилитки. Обычно это выглядит как бесконечный цикл чтения строки, парсинга её и выполнение. Но визуально это всегда выглядит не очень, да и пользоваться трудно. Но мне как-то пришлось писать такую консольную утилитку, с которой должны работать нормальные люди :) поэтому задумался (после соответсвующего пинка :))) над её усовершенствованием в стиле Quake, т.е. сделать такую консольку более интерактивной. Конечно же писать самостоятельно в 2011 году наверно глупо. Немного поискав, остановился на наилучшем, на мой взгляд, варианте: JLine. Перечислю те вещи, за которые она мне больше всего приглянулась:

• История команд, по которой можно легко перемещаться с помощью стрелочек.
• Редактирование строки. В стандартном java console приложении невозможно отредактировать символ внутри уже набранной строки, приходится удалять весь хвост.
• Автодополнение команд с помощью tab. Легко настраиваемое, но при этом с хорошим стандартным набором

В этом посте я набросаю простенькую консоль, поддерживающую команды, которые можно легко будет добавлять (для этого задействуем Google Guice).

Для начала объявим базовый интерфейс для всех команд. Главный метод execute, который что-то делает :) Остальные методы возвращают метаданные, не очень красиво выглядит, возможно через аннотации было бы лучше сделать, но я пока не придумал как.

public interface Command {

    String getName();

    String getDescription();

    String execute(final String[] args) throws InterruptedException;

    String[] getArgs();

    Completor[] getArgCompletors();

}

Буду останавливаться только на главных моментах (где остальной код можно будет увидеть см. в конце поста).

Первые два пункта jline поддерживает практически без нашего участия. А вот с автодополнением придёться ему помочь. Как можно заметить каждая команда обладает методом getArgCompletors. Он возвращает массив jline интерфейсов Completor. Это достаточно простой интерфейс

public interface Completor {
   int complete(String buffer, int cursor, List candidates);
}

Тут всё просто. Передаётся строка, позиция курсора. В список candidates метод должен поместить возможные варианты автодополнения. В составе библиотеки идут несколько стандартных реализаций.

• SimpleCompletor хранит список строк и предлагает варианты из этого списка.
• FileNameCompletor динамически подсказывает имена доступных файлов и папок.
• NullCompletor ничего не подсказывает :).
• ArgumentCompletor композитный Completor. Хороший пример несколько идущих аргументов подряд с разделителем. Для каждого из таких аргументов можно задать свой Completor.

Есть и другие, но это те, что будут использованы в моём приложении. К сожалению конкретного того, что мне надо в списке не оказалось. Мне нужна по сути усовершенствованная версия ArgumentCompletor. Каждая строка содержит имя команды, а вслед за ней через пробел идут аргументы. Очень похоже на ArgumentCompletor. Но в зависимости от первой команды, дальше для аргументов могут быть разные дополнители. Поэтому я написал свой Completor. Он очень простой. В начале подбирается команда с помощью SimpleCompletor. И когда команда известна, подбирается для неё свой ArgumentCompletor из тех, что предоставляет интерфейс команды.

public class CommandsCompletor implements Completor {

    private final ArgumentCompletor.ArgumentDelimiter delim;

    private final Completor commandCompletor;
    private final Map argumentsCompletors;

    @Inject
    public CommandsCompletor(final Map commands) {
        delim = new ArgumentCompletor.WhitespaceArgumentDelimiter();

        String[] commandNames = new String[commands.size()];
        commandNames = commands.keySet().toArray(commandNames);
        commandCompletor = new SimpleCompletor(commandNames);
        argumentsCompletors = new HashMap();
        for (Map.Entry commandEntry : commands.entrySet()) {
            String commandName = commandEntry.getKey();
            Command command = commandEntry.getValue();
            Completor[] baseArgumentsCompletors = command.getArgCompletors();
            int baseLength = baseArgumentsCompletors == null ? 0 :
                            baseArgumentsCompletors.length;
            Completor[] commandArgumentCompletors = 
                           new Completor[baseLength + 2];

            commandArgumentCompletors[0] = commandCompletor;
            if (baseLength > 0) {
                arraycopy(baseArgumentsCompletors, 0, 
                              commandArgumentCompletors, 1, baseLength);
            }
            commandArgumentCompletors[baseLength + 1] = new NullCompletor();

            Completor argumentCompletor = 
                         new ArgumentCompletor(commandArgumentCompletors);
            argumentsCompletors.put(commandName, argumentCompletor);
        }
    }

    @Override
    public int complete(final String buffer, final int cursor, 
                             final List candidates) {
        ArgumentCompletor.ArgumentList list = delim.delimit(buffer, cursor);
        int argIndex = list.getCursorArgumentIndex();

        if (argIndex < 0) {
            return -1;
        }

        if (argIndex > 0) {
            String commandName = list.getArguments()[0];
            if (!argumentsCompletors.containsKey(commandName)) {
                return -1;
            }
            return argumentsCompletors.get(commandName).
                     complete(buffer, cursor, candidates);
        } else {
            return commandCompletor.complete(buffer, cursor, candidates);
        }
    }

}

Несколько замечаний.

• Я использую WhitespaceArgumentDelimiter, чтобы раздробить строку на аргументы. И если курсор показывает на первый аргумент, значит мы дополняем имя команды и для этого используем простой SimpleCompletor со списком всех команд.
• Первым дополнителем во всех ArgumentCompletor передаётся наш дополнитель для команды. Это сделано для упрощения кода, так как строка для построения ему передаётся в том виде как она пришла к нам, поэтому в качестве аргумента должно быть имя команды.
• ArgumentCompletor обладает интересным поведением. Дополнителей, переданных ему может быть меньше чем аргументов в строке, тогда он для каждого последующего использует последний в списке Completor. Мы последним передаём NullCompletor, чтобы больше ничего не дополнялось.
• Не обращайте внимание на аннотацию Inject, это от Guice и об этом будет позже.

А теперь сделаем нашу консольку с бесконечным циклом чтения новых команд. Чтобы использовать все плюшки описанные выше, необходимо использовать ConsoleReader, который позволяет прочитать строку со всеми плюшками.

public class Console {

    private final ConsoleReader reader;

    private final Executor executor;
    private final String helpCommandName;

    @Inject
    public Console(final Executor executor, final Completor commandsCompletor) throws IllegalStateException {
        this.executor = executor;
        try {
            this.reader = new ConsoleReader();
        } catch (IOException e) {
            throw new IllegalStateException("Couldn't create console reader: " + e.getMessage(), e);
        }
        reader.setBellEnabled(false);
        reader.addCompletor(commandsCompletor);
        this.helpCommandName = "help";
    }

    public void run() throws IOException {
        String line;
        while ((line = reader.readLine(">>> ")) != null) {
            try {
                String result;
                try {
                    result = executor.execute(line);
                } catch (InterruptedException e) {
                    out.println("exit");
                    break;
                }
                if (isNotBlank(result)) {
                    out.println(result);
                }
            } catch (UnsupportedCommand e) {
                err.println("Unsupported command: " + e.getCommandName());
                try {
                    out.println(executor.execute(helpCommandName));
                } catch (InterruptedException e1) {
                    err.println("help command was interrupted");
                }
            }
        }
    }
}

Надеюсь достаточно просто. Есть правда Executor, если интересно можете посмотреть его код, но ничего там интересного нету. Он просто парсит строку и выбирает команду для выполнения и запускает её.

Теперь поговорим о расширяемости. Всюду в конструкторах натыканы @Inject. Это для Guice, чтобы он при создании этих объектов передавал из своего контейнера соответсвующие реализации ожидаемых интерфейсов. Например в консоль мы передаём интерфейс Completor, а не его реализацию. Но что более интересно это Map commands. За его формирование будет отвечать так же Guice, но нам надо будет ему помочь. Для этого я буду использовать MapBinder. Что мне всегда нравилось в Guice, это отсутствие xml. Поэтому можно сделать отличный абстрактный модуль, который описывает все зависимости.

public abstract class AbstractConsoleModule extends AbstractModule {

    @Override
    protected final void configure() {
        List commands = new ArrayList();
        MapBinder commandsBinder = MapBinder.newMapBinder(binder(), String.class, Command.class);

        ExitCommand exitCommand = new ExitCommand();
        commandsBinder.addBinding("exit").toInstance(exitCommand);
        HelpCommand helpCommand = new HelpCommand();
        commandsBinder.addBinding("help").toInstance(helpCommand);

        Command[] futureCommands = getCommands();
        for (Command command : futureCommands) {
            commandsBinder.addBinding(command.getName()).toInstance(command);
        }
        commands.add(exitCommand);
        commands.add(helpCommand);
        commands.addAll(asList(futureCommands));
        helpCommand.init(commands);

        bind(Completor.class).to(CommandsCompletor.class);
    }

    protected abstract Command[] getCommands();

}

Т.о. если нужны новые команды достаточно их вернуть в getCommands и с помощью MapBinder они попадут во все классы ожидающие список команд, как например CommandsCompletor или Executor. Так же вместо Completor передастся наша реализация.

Есть две стандартные команды:

• help выводить справку обо всех доступных командах
• exit завершает работу

Но чтобы это происходило динамически, имя класса реализующего AbstractConsoleModule можно передать первым аргументом приложения. Вот такой метод main получился.

    public static void main(final String[] args) {
        AbstractConsoleModule consoleModule;
        if (args == null || args.length == 0) {
            consoleModule = new ConsoleModule();
        } else {
            consoleModule = createModule(args[0]);
        }
        Injector injector = Guice.createInjector(consoleModule);
        Console console = injector.getInstance(Console.class);
        try {
            console.run();
        } catch (IOException e) {
            err.println(e.getMessage());
        }
    }

createModule очень забавный метод, который с помощью reflection строит объект реализации AbstractConsoleModule по имени. А интересен он тем, что размер полезного кода раза в три меньше чем череда catch'ей :)

И для примера был реализован такой модуль с двумя командами.

• HelloCommand с одним аргументом и выводит результирующую строку. В качестве дополнение подсказывает слово world ;)
• CutCommand показывает содержимое выбранного файла и использует FileNameCompletor.

public class ConsoleModule extends AbstractConsoleModule {

    @Override
    protected Command[] getCommands() {
        return new Command[]{new HelloCommand(), new CutCommand()};
    }

}

Скриншоты как-то глупо атачить, поэтому снял видео =D

И как обещал. Решил выкладывать примеры в проект blog-examples на GitHub, чтобы не потерялись, да и смотреть исходники удобнее, качать непонятные архивы не надо и код говорит больше чем слова :)