shell-java

A custom POSIX-style shell implementation in Java, built from scratch.

Builtins · I/O redirection · pipelines · job control · history · variable expansion · aliases · tab completion

Features · Requirements · Building · Usage · Architecture · Testing · Releases · License

A custom POSIX-style shell implementation in Java, built from scratch with support for builtin commands, I/O redirection, pipelines, tab completion, job control, command history, variable expansion, and aliases.

• I/O Redirection — >, >>, 2>, 2>>
• Pipelines — cmd1 | cmd2 | cmd3
• Background execution — command &
• Variable expansion — $VAR, ${VAR}, $?, $$, $!
• Variable assignment — VAR=value
• History expansion — !!, !n, !prefix
• Tab completion — builtins, PATH executables, files, directories, aliases
• Command history — persistent via ~/.shell_java_history
• Aliases — recursive expansion with self-reference protection
• Quote handling — single quotes, double quotes, backslash escaping

• Java 17+
• Maven 3.6+

mvn package

This produces target/shell-java-<version>.jar.

java -jar target/shell-java-1.0.0.jar

# Basic commands
$ echo "hello world"
hello world

$ ls
src  target  pom.xml

# I/O redirection
$ echo hello > out.txt
$ cat out.txt
hello

$ echo world >> out.txt
$ cat out.txt
hello
world

# Pipelines
$ echo hello world | cat
hello world

# Variable expansion
$ NAME=world
$ echo "hello $NAME"
hello world

$ echo $?
0

# Background jobs
$ ping -n 10 127.0.0.1 &
[1] 12345
$ jobs
[1]+  Running                 ping -n 10 127.0.0.1 &

# Aliases
$ alias ll='ls'
$ ll
src  target  pom.xml

# History
$ history
    1  echo hello
    2  ls
    3  history

$ !!
history

src/main/java/
├── Main.java
├── Shell.java
├── alias/
│   └── AliasManager.java
├── command/
│   ├── CommandRegistry.java
│   ├── Executable.java
│   ├── ExternalCommand.java
│   ├── ProcessBuilderFactory.java
│   └── builtin/
│       ├── Builtin.java
│       ├── BuiltinFactory.java
│       ├── AliasBuiltin.java
│       ├── CatBuiltin.java
│       ├── CdBuiltin.java
│       ├── ClearBuiltin.java
│       ├── CompleteBuiltin.java
│       ├── DeclareBuiltin.java
│       ├── EchoBuiltin.java
│       ├── ExitBuiltin.java
│       ├── ExportBuiltin.java
│       ├── FcBuiltin.java
│       ├── HistoryBuiltin.java
│       ├── JobsBuiltin.java
│       ├── LsBuiltin.java
│       ├── MkdirBuiltin.java
│       ├── PwdBuiltin.java
│       ├── RmdirBuiltin.java
│       ├── TouchBuiltin.java
│       ├── TypeBuiltin.java
│       ├── UnaliasBuiltin.java
│       └── UnsetBuiltin.java
├── completer/
│   ├── CandidateCollector.java
│   └── SystemBinaryCompleter.java
├── history/
│   └── HistoryManager.java
├── jobs/
│   ├── Job.java
│   ├── JobManager.java
│   └── JobStatus.java
├── pipe/
│   ├── Pipeline.java
│   └── PipelineResult.java
├── redirect/
│   ├── OutputWriter.java
│   ├── Redirect.java
│   └── RedirectType.java
└── util/
    ├── Environment.java
    ├── ParseResult.java
    ├── PathResolver.java
    ├── Tokenizer.java
    └── UnterminatedQuoteException.java

mvn test

Unit tests cover:

• Tokenizer — quoting, escaping, pipes, variable expansion, redirects
• PathResolver — PATH scanning, PATHEXT extension matching
• HistoryManager — HISTSIZE, HISTCONTROL, persistence
• JobManager — job tracking, reaping, numbering
• AliasManager — expansion, recursion, self-reference protection
• Environment — variable management, exit codes
• OutputWriter — stdout, file, append, stderr redirection
• CommandRegistry — builtin registration and lookup

MIT — see LICENSE for details.