Skip to content

Commit 68bd149

Browse files
stalepstalep
committed
further doc improvements
1 parent 369c16c commit 68bd149

26 files changed

Lines changed: 2753 additions & 13 deletions

‎content/_index.md‎

Lines changed: 38 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,40 @@
11
---
2-
date: '2026-01-09T17:15:41+01:00'
3-
draft: true
4-
title: ''
2+
date: '2026-01-11T15:00:00+01:00'
3+
draft: false
4+
title: 'Æsh, Another Extendable SHell'
55
---
6+
7+
Æsh is a collection of Java libraries for building powerful command-line interfaces and console applications.
8+
9+
## Projects
10+
11+
### Æsh
12+
A library to easily create commands through a well-defined API. Æsh handles all parsing, validation, and injection for your commands.
13+
14+
### Æsh Readline
15+
A readline library supporting most GNU Readline features, including line editing, history, completion, masking, and remote connectivity.
16+
17+
## Features
18+
19+
### Æsh
20+
- Easy to use API to create everything from simple to advanced commands
21+
- Support for different types of options (list, group, single) and arguments
22+
- Built-in completors for default values, booleans and files
23+
- Multiple hierarchy of sub commands (eg: `git rebase/pull`)
24+
- Automatic injection of option values and arguments during execution
25+
- Custom validators, activators, completors, converters, renderers and parsers
26+
- Automatically generates help/info text based on metadata
27+
- Add and remove commands during runtime
28+
29+
### Æsh Readline
30+
- Line editing with undo/redo
31+
- History (search, persistence)
32+
- Completion support
33+
- Password masking
34+
- Paste buffer
35+
- Emacs and Vi editing modes
36+
- Cross-platform (POSIX and Windows)
37+
- Configurable history file & buffer size
38+
- Standard out and standard error support
39+
- Redirect, alias, and pipeline support
40+
- Remote connectivity (SSH, Telnet, WebSockets)

‎content/docs/_index.md‎

Lines changed: 46 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,51 @@
11
---
2-
date: '2026-01-09T17:15:50+01:00'
3-
draft: true
4-
title: 'Docs'
2+
date: '2026-01-11T15:00:00+01:00'
3+
draft: false
4+
title: 'Documentation'
55
cascade:
66
type: docs
77
---
88

9-
Here we'll have some information regarding how æsh and æsh-readline works. The details of each of the libraries will go into the aesh and readline doc folder.
9+
Welcome to the Æsh documentation. This site provides comprehensive guides for both Æsh and Æsh Readline libraries.
10+
11+
## Æsh
12+
13+
Æsh is a Java library for creating command-line interfaces with annotations or a builder API. It handles command parsing, option validation, and automatic value injection.
14+
15+
### Getting Started
16+
- [Quick Start](/docs/aesh/getting-started)
17+
- [Installation](/docs/aesh/installation)
18+
19+
### API Reference
20+
- [Command Definition](/docs/aesh/command-definition)
21+
- [Options](/docs/aesh/options)
22+
- [Arguments](/docs/aesh/arguments)
23+
- [Option Lists](/docs/aesh/option-lists)
24+
- [Group Commands](/docs/aesh/group-commands)
25+
26+
### Advanced Topics
27+
- [Validators](/docs/aesh/validators)
28+
- [Converters](/docs/aesh/converters)
29+
- [Completers](/docs/aesh/completers)
30+
- [Activators](/docs/aesh/activators)
31+
- [Renderers](/docs/aesh/renderers)
32+
33+
## Æsh Readline
34+
35+
Æsh Readline provides readline functionality including line editing, history, completion, and remote connectivity.
36+
37+
### Getting Started
38+
- [Quick Start](/docs/readline/getting-started)
39+
- [Installation](/docs/readline/installation)
40+
41+
### API Reference
42+
- [Readline](/docs/readline/readline-api)
43+
- [Terminal](/docs/readline/terminal)
44+
- [Connection](/docs/readline/connection)
45+
- [History](/docs/readline/history)
46+
- [Completion](/docs/readline/completion)
47+
48+
### Advanced Topics
49+
- [Edit Modes](/docs/readline/edit-modes)
50+
- [Key Bindings](/docs/readline/key-bindings)
51+
- [Remote Connectivity](/docs/readline/connectivity)

‎content/docs/aesh/_index.md‎

Lines changed: 20 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,22 @@
11
---
2-
date: '2026-01-09T17:17:45+01:00'
3-
draft: true
4-
title: 'Aesh'
2+
date: '2026-01-11T15:00:00+01:00'
3+
draft: false
4+
title: 'Æsh'
55
---
6+
7+
Æsh is a Java library to easily create commands through a well-defined API.
8+
9+
## Overview
10+
11+
Æsh takes care of all parsing and injection for your commands. It uses annotations as the default way of adding metadata for commands, but also provides a builder API if that is preferred.
12+
13+
## Key Features
14+
15+
- Easy to use API to create everything from simple to advanced commands
16+
- Supports different types of options (list, group, single) and arguments
17+
- Built-in completors for default values, booleans and files
18+
- Multiple hierarchy of sub commands (e.g., `git rebase/pull`)
19+
- Automatic injection of option values and arguments during execution
20+
- Custom validators, activators, completors, converters, renderers and parsers
21+
- Automatically generates help/info text based on provided metadata
22+
- Add and remove commands during runtime

‎content/docs/aesh/activators.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
---
2+
date: '2026-01-11T15:00:00+01:00'
3+
draft: false
4+
title: 'Activators'
5+
---
6+
7+
Activators control whether options, arguments, or entire commands are available/enabled.
8+
9+
## OptionActivator
10+
11+
Enable or disable an option based on conditions:
12+
13+
```java
14+
public class SslOptionActivator implements OptionActivator {
15+
16+
@Override
17+
public boolean isActivated(CompleterInvocation invocation) {
18+
MyCommand cmd = (MyCommand) invocation.getCommand();
19+
// SSL options only active if secure mode is enabled
20+
return cmd.secureMode;
21+
}
22+
}
23+
```
24+
25+
Usage:
26+
27+
```java
28+
@CommandDefinition(name = "server")
29+
public class ServerCommand implements Command<CommandInvocation> {
30+
31+
@Option(name = "secure", hasValue = false, description = "Enable secure mode")
32+
private boolean secureMode = false;
33+
34+
@Option(
35+
name = "cert",
36+
activator = SslOptionActivator.class,
37+
description = "SSL certificate (only in secure mode)"
38+
)
39+
private String certPath;
40+
41+
@Option(
42+
name = "key",
43+
activator = SslOptionActivator.class,
44+
description = "SSL private key (only in secure mode)"
45+
)
46+
private String keyPath;
47+
48+
@Override
49+
public CommandResult execute(CommandInvocation invocation) {
50+
return CommandResult.SUCCESS;
51+
}
52+
}
53+
```
54+
55+
## CommandActivator
56+
57+
Control whether a command is visible/available:
58+
59+
```java
60+
public class AdminCommandActivator implements CommandActivator {
61+
62+
@Override
63+
public boolean isActivated(CommandInvocation invocation) {
64+
// Only show admin commands if user is admin
65+
return isAdmin(invocation);
66+
}
67+
68+
private boolean isAdmin(CommandInvocation invocation) {
69+
// Check if user has admin privileges
70+
// This could check environment variables, config files, etc.
71+
return System.getProperty("user.role", "user").equals("admin");
72+
}
73+
}
74+
```
75+
76+
Usage:
77+
78+
```java
79+
@CommandDefinition(
80+
name = "shutdown",
81+
description = "Shutdown the server",
82+
activator = AdminCommandActivator.class
83+
)
84+
public class ShutdownCommand implements Command<CommandInvocation> {
85+
86+
@Override
87+
public CommandResult execute(CommandInvocation invocation) {
88+
invocation.println("Shutting down...");
89+
return CommandResult.SUCCESS;
90+
}
91+
}
92+
```
93+
94+
## Conditional Validation
95+
96+
Use activators to conditionally require options:
97+
98+
```java
99+
public class OutputFileActivator implements OptionActivator {
100+
101+
@Override
102+
public boolean isActivated(CompleterInvocation invocation) {
103+
MyCommand cmd = (MyCommand) invocation.getCommand();
104+
// Output file option only active when not verbose
105+
return !cmd.verbose;
106+
}
107+
}
108+
109+
@CommandDefinition(name = "process")
110+
public class ProcessCommand implements Command<CommandInvocation> {
111+
112+
@Option(name = "verbose", hasValue = false, description = "Verbose output")
113+
private boolean verbose = false;
114+
115+
@Option(
116+
name = "output",
117+
activator = OutputFileActivator.class,
118+
required = true,
119+
description = "Output file (required unless verbose)"
120+
)
121+
private String outputFile;
122+
123+
@Override
124+
public CommandResult execute(CommandInvocation invocation) {
125+
return CommandResult.SUCCESS;
126+
}
127+
}
128+
```
129+
130+
When `--verbose` is used, the `--output` option is hidden and not required.
131+
132+
## Accessing Runtime Context
133+
134+
Activators can access the Aesh context:
135+
136+
```java
137+
public class ContextAwareActivator implements OptionActivator {
138+
139+
@Override
140+
public boolean isActivated(CompleterInvocation invocation) {
141+
AeshContext context = invocation.getAeshContext();
142+
// Access runtime context for more complex conditions
143+
return context.someCondition();
144+
}
145+
}
146+
```

‎content/docs/aesh/arguments.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
---
2+
date: '2026-01-11T15:00:00+01:00'
3+
draft: false
4+
title: 'Arguments'
5+
---
6+
7+
The `@Argument` annotation defines positional command-line arguments.
8+
9+
## Properties
10+
11+
| Property | Type | Default | Description |
12+
|----------|------|---------|-------------|
13+
| `description` | `String` | `""` | Help description |
14+
| `required` | `boolean` | `false` | Is argument required? |
15+
| `defaultValue` | `String[]` | `{}` | Default values |
16+
| `askIfNotSet` | `boolean` | `false` | Prompt user if not set |
17+
| `overrideRequired` | `boolean` | `false` | Override required validation |
18+
| `converter` | `Class<? extends Converter>` | `NullConverter.class` | Custom value converter |
19+
| `completer` | `Class<? extends OptionCompleter>` | `NullOptionCompleter.class` | Custom completer |
20+
| `validator` | `Class<? extends OptionValidator>` | `NullValidator.class` | Custom validator |
21+
| `activator` | `Class<? extends OptionActivator>` | `NullActivator.class` | Custom activator |
22+
| `renderer` | `Class<? extends OptionRenderer>` | `NullOptionRenderer.class` | Custom renderer |
23+
| `parser` | `Class<? extends OptionParser>` | `AeshOptionParser.class` | Custom parser |
24+
25+
## Basic Example
26+
27+
```java
28+
@CommandDefinition(name = "echo")
29+
public class EchoCommand implements Command<CommandInvocation> {
30+
31+
@Argument(description = "Text to echo")
32+
private String text;
33+
34+
@Override
35+
public CommandResult execute(CommandInvocation invocation) {
36+
invocation.println(text);
37+
return CommandResult.SUCCESS;
38+
}
39+
}
40+
```
41+
42+
Usage: `echo Hello World`
43+
44+
## Multiple Arguments with @Arguments
45+
46+
For multiple values, use `@Arguments` (plural) with a `Collection`:
47+
48+
```java
49+
@CommandDefinition(name = "sum")
50+
public class SumCommand implements Command<CommandInvocation> {
51+
52+
@Arguments(description = "Numbers to sum")
53+
private List<Integer> numbers;
54+
55+
@Override
56+
public CommandResult execute(CommandInvocation invocation) {
57+
int sum = numbers.stream().mapToInt(Integer::intValue).sum();
58+
invocation.println("Sum: " + sum);
59+
return CommandResult.SUCCESS;
60+
}
61+
}
62+
```
63+
64+
Usage: `sum 1 2 3 4 5`
65+
66+
## Required Argument
67+
68+
```java
69+
@Argument(required = true, description = "Required file")
70+
private String file;
71+
```
72+
73+
## Default Value
74+
75+
```java
76+
@Argument(defaultValue = "output.txt", description = "Output file")
77+
private String outputFile;
78+
```
79+
80+
## Combined with Options
81+
82+
Arguments and options can be used together:
83+
84+
```java
85+
@CommandDefinition(name = "copy")
86+
public class CopyCommand implements Command<CommandInvocation> {
87+
88+
@Argument(required = true, description = "Source file")
89+
private String source;
90+
91+
@Option(shortName = 'd', description = "Destination directory")
92+
private String destination = ".";
93+
94+
@Option(shortName = 'v', hasValue = false, description = "Verbose")
95+
private boolean verbose;
96+
97+
@Override
98+
public CommandResult execute(CommandInvocation invocation) {
99+
// implementation
100+
return CommandResult.SUCCESS;
101+
}
102+
}
103+
```
104+
105+
Usage: `copy myfile.txt -d /tmp -v`

0 commit comments

Comments
 (0)