Æsh (Another Extendable SHell) 技术文档

1. 安装指南

1.1 Maven 依赖

要使用 Æsh 库，首先需要在项目的 pom.xml 文件中添加以下依赖：

<dependency>
  <groupId>org.aesh</groupId>
  <artifactId>aesh</artifactId>
  <version>1.7</version>
</dependency>

1.2 Gradle 依赖

如果你使用的是 Gradle，可以在 build.gradle 文件中添加以下依赖：

dependencies {
    compile group: 'org.aesh', name: 'aesh', version: '1.0-SNAPSHOT'
}

2. 项目使用说明

Æsh 是一个用于轻松创建命令的 Java 库。它通过一个定义良好的 API 来处理命令的解析和注入。Æsh 使用 aesh-readline 项目来实现终端/readline 集成。

2.1 创建简单命令

以下是一个简单的示例，展示了如何使用 Æsh 创建一个退出命令：

import org.aesh.command.Command;
import org.aesh.command.CommandDefinition;
import org.aesh.command.CommandException;
import org.aesh.command.CommandResult;
import org.aesh.command.impl.registry.AeshCommandRegistryBuilder;
import org.aesh.command.invocation.CommandInvocation;
import org.aesh.command.parser.CommandLineParserException;
import org.aesh.command.registry.CommandRegistry;
import org.aesh.console.settings.Settings;
import org.aesh.console.settings.SettingsBuilder;
import org.aesh.readline.ReadlineConsole;

import java.io.IOException;

public class SimpleExample {
    public static void main(String[] args) throws CommandLineParserException, IOException {
        CommandRegistry registry = new AeshCommandRegistryBuilder()
                .command(ExitCommand.class)
                .create();
        Settings settings = SettingsBuilder
                .builder()
                .commandRegistry(registry)
                .build();
        ReadlineConsole console = new ReadlineConsole(settings);
        console.setPrompt("[simple@aesh]$ ");
        console.start();
    }

    @CommandDefinition(name = "exit", description = "exit the program", aliases = {"quit"})
    public static class ExitCommand implements Command {
        @Override
        public CommandResult execute(CommandInvocation commandInvocation) throws CommandException, InterruptedException {
            commandInvocation.stop();
            return CommandResult.SUCCESS;
        }
    }
}

2.2 功能特性

Æsh 提供了以下主要功能：

• 易于使用的 API：从简单到复杂的命令都可以轻松创建。
• 支持多种选项和参数：包括列表、组、单个选项等。
• 内置完成器：支持默认值、布尔值和文件的自动完成。
• 支持多级子命令：例如 git rebase/pull 等。
• 自动注入：所有选项值和参数在执行时自动注入。
• 自定义验证器、激活器、完成器、转换器、渲染器和解析器。
• 自动生成帮助/信息文本：基于提供的元数据。
• 运行时添加和删除命令。

3. 项目 API 使用文档

3.1 命令注册

使用 AeshCommandRegistryBuilder 来注册命令：

CommandRegistry registry = new AeshCommandRegistryBuilder()
        .command(ExitCommand.class)
        .create();

3.2 设置配置

使用 SettingsBuilder 来配置终端设置：

Settings settings = SettingsBuilder
        .builder()
        .commandRegistry(registry)
        .build();

3.3 启动终端

使用 ReadlineConsole 启动终端并设置提示符：

ReadlineConsole console = new ReadlineConsole(settings);
console.setPrompt("[simple@aesh]$ ");
console.start();

4. 项目安装方式

Æsh 使用 Maven 作为构建工具。你可以通过以下步骤来构建项目：

1. 克隆项目仓库。
2. 在项目根目录下运行 mvn clean install 命令。

通过以上步骤，你可以在本地构建并安装 Æsh 库。