Settings Configuration

The Settings class provides comprehensive configuration for Æsh console applications. It controls behavior for history, aliases, editing modes, logging, and many other aspects of the shell environment.

Overview

Settings are configured using the builder pattern and passed to either AeshConsoleRunner or AeshRuntimeRunner:

import org.aesh.command.settings.Settings;
import org.aesh.command.settings.SettingsBuilder;

Settings settings = SettingsBuilder.builder()
        .enableHistory(true)
        .historyFile(new File(".myapp_history"))
        .historySize(500)
        .enableAlias(true)
        .build();

AeshConsoleRunner.builder()
        .settings(settings)
        .command(MyCommand.class)
        .start();

SettingsBuilder API

Creating a Builder

// Default settings
SettingsBuilder builder = SettingsBuilder.builder();

// Copy from existing settings
SettingsBuilder builder = SettingsBuilder.builder(existingSettings);

Building Settings

Settings settings = builder.build();

Configuration Options

History Configuration

enableHistory(boolean)

Enables or disables command history. Default: true

SettingsBuilder.builder()
        .enableHistory(true)
        .build();

historyFile(File)

Sets the file for persisting command history. Default: null (in-memory only)

SettingsBuilder.builder()
        .historyFile(new File(System.getProperty("user.home"), ".myapp_history"))
        .build();

historySize(int)

Sets the maximum number of history entries. Default: 500

SettingsBuilder.builder()
        .historySize(1000)
        .build();

historyPersistent(boolean)

Controls whether history is persisted to file. Default: true (if historyFile is set)

SettingsBuilder.builder()
        .historyPersistent(true)
        .build();

historyDisabled(boolean)

Completely disables history functionality. Default: false

SettingsBuilder.builder()
        .historyDisabled(false)
        .build();

Alias Configuration

enableAlias(boolean)

Enables command aliases. Default: false

SettingsBuilder.builder()
        .enableAlias(true)
        .build();

aliasFile(File)

Sets the file for persisting aliases. Default: null

SettingsBuilder.builder()
        .aliasFile(new File(System.getProperty("user.home"), ".myapp_aliases"))
        .build();

persistAlias(boolean)

Controls whether aliases are persisted to file. Default: true (if aliasFile is set)

SettingsBuilder.builder()
        .persistAlias(true)
        .build();

Export Configuration

enableExport(boolean)

Enables export functionality for environment variables. Default: false

SettingsBuilder.builder()
        .enableExport(true)
        .build();

exportFile(File)

Sets the file for persisting exported variables. Default: null

SettingsBuilder.builder()
        .exportFile(new File(System.getProperty("user.home"), ".myapp_exports"))
        .build();

persistExport(boolean)

Controls whether exports are persisted to file. Default: true (if exportFile is set)

SettingsBuilder.builder()
        .persistExport(true)
        .build();

Editing Mode

mode(EditMode.Mode)

Sets the editing mode (Emacs or Vi). Default: EditMode.Mode.EMACS

import org.aesh.readline.editing.EditMode;

SettingsBuilder.builder()
        .mode(EditMode.Mode.EMACS)  // or EditMode.Mode.VI
        .build();

Logging

logging(boolean)

Enables internal logging. Default: false

SettingsBuilder.builder()
        .logging(true)
        .build();

logFile(String)

Sets the log file path. Default: null

SettingsBuilder.builder()
        .logging(true)
        .logFile("/var/log/myapp/aesh.log")
        .build();

Command Registry

commandRegistry(CommandRegistry)

Sets a custom command registry.

import org.aesh.command.registry.MutableCommandRegistry;

MutableCommandRegistry registry = new MutableCommandRegistry();
registry.addCommand(MyCommand.class);

SettingsBuilder.builder()
        .commandRegistry(registry)
        .build();

Connection and Terminal

connection(Connection)

Sets a custom connection for terminal I/O.

SettingsBuilder.builder()
        .connection(myConnection)
        .build();

inputStream(InputStream)

Sets the input stream. Default: System.in

SettingsBuilder.builder()
        .inputStream(new FileInputStream("input.txt"))
        .build();

outputStream(PrintStream)

Sets the output stream. Default: System.out

SettingsBuilder.builder()
        .outputStream(new PrintStream(new FileOutputStream("output.txt")))
        .build();

outputStreamError(PrintStream)

Sets the error output stream. Default: System.err

SettingsBuilder.builder()
        .outputStreamError(new PrintStream(new FileOutputStream("error.txt")))
        .build();

Operators and Redirection

enableOperatorParser(boolean)

Enables parsing of command operators (|, >, >>, &&, ||, ;). Default: true

SettingsBuilder.builder()
        .enableOperatorParser(true)
        .build();

setPipe(boolean)

Enables pipe (|) operator support. Default: true

SettingsBuilder.builder()
        .setPipe(true)
        .build();

setRedirection(boolean)

Enables redirection (>, >>, <) support. Default: true

SettingsBuilder.builder()
        .setRedirection(true)
        .build();

Command Invocation

commandInvocationProvider(CommandInvocationProvider)

Sets a custom CommandInvocation provider for dependency injection.

SettingsBuilder.builder()
        .commandInvocationProvider(new MyCommandInvocationProvider())
        .build();

See Custom Command Invocation for details.

Completion

completionHandler(CompletionHandler)

Sets a custom completion handler.

SettingsBuilder.builder()
        .completionHandler(new MyCompletionHandler())
        .build();

Additional Options

readInputrc(boolean)

Controls whether to read the .inputrc file for readline configuration. Default: true

SettingsBuilder.builder()
        .readInputrc(true)
        .build();

parseOperators(boolean)

Controls operator parsing. Default: true

SettingsBuilder.builder()
        .parseOperators(true)
        .build();

echoCtrl(boolean)

Controls whether control characters are echoed. Default: true

SettingsBuilder.builder()
        .echoCtrl(true)
        .build();

Complete Example

import org.aesh.command.settings.Settings;
import org.aesh.command.settings.SettingsBuilder;
import org.aesh.readline.editing.EditMode;
import java.io.File;

public class ConfiguredConsole {
    public static void main(String[] args) {
        String userHome = System.getProperty("user.home");
        
        Settings settings = SettingsBuilder.builder()
                // History configuration
                .enableHistory(true)
                .historyFile(new File(userHome, ".myapp_history"))
                .historySize(1000)
                .historyPersistent(true)
                
                // Alias configuration
                .enableAlias(true)
                .aliasFile(new File(userHome, ".myapp_aliases"))
                
                // Export configuration
                .enableExport(true)
                .exportFile(new File(userHome, ".myapp_exports"))
                
                // Editing mode
                .mode(EditMode.Mode.EMACS)
                
                // Logging
                .logging(true)
                .logFile("/tmp/myapp-aesh.log")
                
                // Operators
                .enableOperatorParser(true)
                .setPipe(true)
                .setRedirection(true)
                
                .build();
        
        AeshConsoleRunner.builder()
                .settings(settings)
                .command(MyCommand.class)
                .command(OtherCommand.class)
                .addExitCommand()
                .prompt("[myapp]$ ")
                .start();
    }
}

Accessing Settings at Runtime

Commands can access settings through the CommandInvocationConfiguration:

@Override
public CommandResult execute(CommandInvocation invocation) {
    CommandInvocationConfiguration config = invocation.getConfiguration();
    // Access configuration properties...
    return CommandResult.SUCCESS;
}

Settings Summary Table

Setting	Type	Default	Description
`enableHistory`	`boolean`	`true`	Enable command history
`historyFile`	`File`	`null`	History persistence file
`historySize`	`int`	`500`	Maximum history entries
`historyPersistent`	`boolean`	`true`	Persist history to file
`historyDisabled`	`boolean`	`false`	Completely disable history
`enableAlias`	`boolean`	`false`	Enable command aliases
`aliasFile`	`File`	`null`	Alias persistence file
`persistAlias`	`boolean`	`true`	Persist aliases to file
`enableExport`	`boolean`	`false`	Enable environment exports
`exportFile`	`File`	`null`	Export persistence file
`persistExport`	`boolean`	`true`	Persist exports to file
`mode`	`EditMode.Mode`	`EMACS`	Editing mode (EMACS or VI)
`logging`	`boolean`	`false`	Enable internal logging
`logFile`	`String`	`null`	Log file path
`enableOperatorParser`	`boolean`	`true`	Parse command operators
`setPipe`	`boolean`	`true`	Enable pipe operator
`setRedirection`	`boolean`	`true`	Enable redirection operators
`readInputrc`	`boolean`	`true`	Read .inputrc configuration
`echoCtrl`	`boolean`	`true`	Echo control characters

Best Practices

Always set history file - For production applications, always configure a history file so users don’t lose their command history between sessions.
Use user home for config files - Store configuration files in the user’s home directory following platform conventions.
Enable aliases for power users - Aliases let users create shortcuts for frequently used commands.
Consider Vi mode - Some users prefer Vi editing mode. Consider making this configurable.
Log during development - Enable logging during development to debug issues.
Disable operators when not needed - If your application doesn’t support piping or redirection, disable them to prevent confusion.

// Development settings
Settings devSettings = SettingsBuilder.builder()
        .logging(true)
        .logFile("aesh-debug.log")
        .build();

// Production settings
Settings prodSettings = SettingsBuilder.builder()
        .enableHistory(true)
        .historyFile(new File(System.getProperty("user.home"), ".myapp_history"))
        .historySize(1000)
        .enableAlias(true)
        .build();

Examples and Tutorials Extensions Library