Getting started


Since Æsh is created to be extended and used by other applications it doesn't do much on its own. However, it is very easy to get started with a simple application.
Let's start with a simple demonstration: 
public class AeshExample {
    public static void main(String[] args) {

        Settings settings = new SettingsBuilder().logging(true).create();
        AeshConsole aeshConsole = new AeshConsoleBuilder().settings(settings)
                .prompt(new Prompt("[aesh@rules]$ "))
                .command(ExitCommand.class)
                .command(LsCommand.class)
                .create();

        aeshConsole.start();
    }

    @CommandDefinition(name="exit", description = "exit the program")
    public static class ExitCommand implements Command {
        @Override
        public CommandResult execute(AeshConsole console, ControlOperator operator) throws IOException {
            console.stop();
            return CommandResult.SUCCESS;
        }
    }

    @CommandDefinition(name="ls", description = "fooing")
    public static class LsCommand implements Command {
        @Option
        private String color;

        @Arguments
        private List<File> files;

        @Override
        public CommandResult execute(AeshConsole console, ControlOperator operator) throws IOException {
            if(files != null) {
              for(File f : files)
                console.out().print(f.toString());
            }
            return CommandResult.SUCCESS;
        }
    }
}

Here we create a small program that only have two methods; ls and exit. All the command line parsing, population of the option values are all done by æsh. The annotation used to specify the command is identical to what is used in the Command Line Parser page. The only addition is the Command interface that needs to be implemented as well. Using this API is the easiest way to get you started and should suffice for most cases.


Console API

The original public api was targeted around the Console is still supported and have been steadily improved. The biggest change compared to earlier version is that Console now reads from the inputstream in a separate thread. This opens up a lot of possibilities, but also require some changes to the api. The Console.readLine(..) method is gone and now Console provides a callback to handle the input sent from the terminal (an example will be shown below). The way you send data to the out/error streams have also changed a bit. Instead of directly calling a method on Console you now fetch a PrintWriter for either out/error and print to it. - just remember that there is not automatically flushing of the print statements only when using println.

Here is a very short code that will start Æsh using the Console API: 
import org.jboss.aesh.console.*;
public class Example {
  
  Console console = new Console(new SettingsBuilder().create());
  
  final ConsoleCallback consoleCallback = new ConsoleCallback() {
    @Override
    public int readConsoleOutput(ConsoleOperation operation) throws IOException{
        console.out().println("======>\"" + operation.getBuffer());
        if (operation.getBuffer().equals("quit") || operation.getBuffer().equals("exit")) {
            console.stop();
        }
    }
  };
  console.setCallback(consoleCallback);
  console.start();
}

As you notice this example doesnt do much other than registrering the given input and printing it again.

Interact with Æsh

As mentioned the two different APIs provides two different ways of interacting with Æsh. The more high level API when using

AeshConsole enforce you to interact with in the Command execute method and the Completer API. For most CLI programs this would be sufficient and should handle most usecases.
If you need to support a more "unconventional" option/value syntax or parser strategy you might have to use the low level API.

ConsoleCallback

When using the Console API the way you receive user input is with a ConsoleCallback. The registered ConsoleCallback is called each time a user press enter and it is possible to change the registered callback when needed.
The data object thats sent from the Console is a ConsoleOperation object:
  • buffer: user input
  • redirectOrPipe: if either piping or redirecting is used, this is set to true.

Piping and Redirecting

Æsh supports piping and redirecting similar to who it works in various Unix shells. Read more here.

Settings

In addition to the settings a user can define in the init file the developer can also define a lot of settings in Æsh. Read more about settings here.

Provided Examples

As mentioned above, Æsh provides two simple examples that you can use as a quick intro to the API. There is on example each for the two different APIs.
Example.java show how to use the low level API. To run it, simply do; java -cp aesh-{version}.jar Example
AeshExample.java show how to use the high level API. To run it, simply do; java -cp aesh-{version}.jar AeshExample
back to top