https://github.com/sigpwned/just-args-java
Simple CLI argument parsing library
https://github.com/sigpwned/just-args-java
args args-parser cli cli-parameters cli-parser java java-8
Last synced: 11 months ago
JSON representation
Simple CLI argument parsing library
- Host: GitHub
- URL: https://github.com/sigpwned/just-args-java
- Owner: sigpwned
- License: unlicense
- Created: 2025-01-04T20:41:24.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-03-01T01:36:26.000Z (11 months ago)
- Last Synced: 2025-03-01T02:26:44.933Z (11 months ago)
- Topics: args, args-parser, cli, cli-parameters, cli-parser, java, java-8
- Language: Java
- Homepage: https://github.com/sigpwned/just-args-java
- Size: 32.2 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# Just Args for Java [](https://github.com/sigpwned/just-args-java/actions/workflows/tests.yml) [](https://central.sonatype.com/artifact/com.sigpwned/just-args) [](https://javadoc.io/doc/com.sigpwned/just-args)
Just Args is a small, simple library for Java that provides command-line argument parsing support and nothing else.
## Goals
Just Args should...
* **Parse arguments**. The library parses valid command-line arguments into a structured and useful model.
* **Be very small**. The JAR file is currently less than 10KB compressed, under 25KB uncompressed.
* **Be very simple**. Users only need one method to parse arguments: `JustArgs.parseArgs`.
* **Be flexible**. Supports options, flags, and positional arguments, as well as advanced configurations.
* **Be open source**. Released under Unlicense, so you don't have to worry about copyright.
* **Work out of the box**. Designed to handle common argument parsing use cases with minimal configuration.
## Non-Goals
Just Args should not...
* **Validate command-line usage**. The library is not a strict validator and assumes you know how your CLI should behave.
* **Provide advanced features**. The library intentionally avoids dependencies, complex argument validation, and advanced frameworks.
## Installation
Just Args is available in Maven Central. You can add it to your project using the following Maven dependency:
```xml
com.sigpwned
just-args
0.0.0
```
Just Args is a single Java file with no dependencies, so you can also just copy/paste it into your project, in a pinch.
## Quickstart
### Basic Usage
To parse a list of command-line arguments:
```java
import com.sigpwned.just.args.JustArgs;
List args = List.of("--xray", "value1", "-f", "positional1");
Map shortOptionNames = Map.of('x', "xray");
Map longOptionNames = Map.of("xray", "xray");
Map shortPositiveFlagNames = Map.of('f', "flag");
Map longPositiveFlagNames = Map.of();
Map shortNegativeFlagNames = Map.of();
Map longNegativeFlagNames = Map.of();
JustArgs.ParsedArgs result = JustArgs.parseArgs(
args,
shortOptionNames, longOptionNames,
shortPositiveFlagNames, longPositiveFlagNames,
shortNegativeFlagNames, longNegativeFlagNames);
System.out.println(result.getArgs()); // [positional1]
System.out.println(result.getOptions()); // {xray=[value1]}
System.out.println(result.getFlags()); // {flag=[true]}
```
### Features
Just Args supports:
* **Options**: Arguments with values, e.g., `-k value`, `--key value` or `--key=value`.
* **Flags**: Boolean arguments, e.g., `-f` or `--flag`.
* **Short Flag Batches**: Multiple short flags grouped together, e.g., `-abc` is equivialent to `-a -b -c`
* **Positional Arguments**: Unlabeled arguments.
* **Separator Token `--`**: Marks all subsequent arguments as positional.
---
## Advanced Usage
### Handling Syntax Errors
Just Args throws a `JustArgs.IllegalSyntaxException` when it encounters invalid syntax. This is a subclass of `IllegalArgumentException` for simplicity.
```java
try {
JustArgs.parseArgs(...);
} catch (JustArgs.IllegalSyntaxException e) {
System.err.println("Syntax error at index " + e.getIndex() + ": " + e.getMessage());
}
```
### Customizing Argument Names
You can configure short and long names for options and flags, and assign them to the same logical bucket in the result:
```java
Map shortOptionNames = Map.of('o', "output");
Map longOptionNames = Map.of("output", "output");
Map shortPositiveFlagNames = Map.of('v', "verbose");
Map longPositiveFlagNames = Map.of("verbose", "verbose");
```
---
## FAQ
### Why Another Argument Parsing Library?
Most libraries are either too large, too complex, or depend on external frameworks. Just Args is small, simple, and dependency-free—perfect for lightweight projects.
### What About Error Messages?
Just Args focuses on simplicity. Error messages are provided through exceptions, leaving full control to the user.
### Can You Add Feature X?
Feel free to ask, but probably not. Just Args is intentionally minimal. If you need advanced features, consider a more fully-featured library like Apache Commons CLI or Picocli.
---
## A Note on Development
Just Args was built with simplicity and clarity in mind. The library is intentionally small and avoids external dependencies to make it easy to embed in any project.
---