Forem: onebitwonder

Building CLIAR — A simple drop-in Java class for parsing command-line arguments (Part 3 of 4)

onebitwonder — Mon, 11 May 2026 21:10:36 +0000

Welcome back to the third part of my rolling blog on building CLIAR, a lightweight, transparent command‑line argument parser for Java.
In the last part, we added support for short options, long options, and key–value pairs.
This chapter focuses on two major improvements:

separating concerns inside the parser

introducing a formal option‑registration system so CLIAR can validate user input

This is the point where CLIAR becomes a real utility rather than a loose collection of parsing rules.
You can find current snapshots of the code on my GitHub page.

Defining rules for option names

Before we can validate user input, we need clear rules for declared option names — the names the developer defines in code.
To keep CLIAR predictable and easy to read:

Short option names must be single alphabetic characters.
Long option names must start with a letter and may contain letters, digits, or hyphens.
Values and positional arguments remain unrestricted. These rules apply only to declared options, not to the raw command‑line arguments.

With naming rules established, we can now look at how CLIAR processes the actual arguments supplied by the user.

Parsing command‑line arguments with dedicated methods

CLIAR does not parse option names directly. It parses arguments, then maps them to declared options.
To keep the logic clean, we delegate parsing to two methods:

parseShortOption(String arg, Cliar cliar)
parseLongOption(String arg, Cliar cliar)

The main loop becomes:

for (String arg : args) {
    if (arg.startsWith("--") && arg.length() > 2) {
        parseLongOption(arg.substring(2), cliar);
    } else if (arg.startsWith("-") && !arg.startsWith("--") && arg.length() > 1) {
        // NOTE: "-" becomes a positional argument
        parseShortOption(arg.substring(1), cliar);
    } else {
        cliar.positionalArguments.add(arg);
    }
}

Parsing Short Options

Short options are simple: each character is a boolean flag.

for (char chr : arg.toCharArray()) {
    if (Character.isLetter(chr)) {
        // ...
    } else {
        throw new IllegalArgumentException(
            String.format("Invalid option '%c' in argument %s.", chr, arg)
        );
    }
}

CLIAR treats grouped flags (-abc) as three separate options.

Parsing Long Options

Long options may include a value:

--verbose
--output=file.txt

We split the argument:

int index = arg.indexOf('=');
String key = arg;
String val = null;

if (index != -1) {
    key = arg.substring(0, index);
    val = arg.substring(index + 1);
}

Then validate the key:

if (key.isEmpty()) {
    throw new IllegalArgumentException("Long option name is empty.");
}

if (!Character.isLetter(key.charAt(0))) {
    throw new IllegalArgumentException("Long option must start with a letter.");
}

for (int i = 1; i < key.length(); i++) {
    char chr = key.charAt(i);

    if (!(Character.isLetter(chr) || Character.isDigit(chr) || chr == '-')) {
        throw new IllegalArgumentException(
            String.format("Illegal character %c in option %s at position %d.", chr, key, i)
        );
    }
}

Declaring Options with the `Option` Class

CLIAR can now parse arguments, but it still doesn’t know which options are allowed.
This information must be declared in code.

We encapsulate a declared option in an inner class:

public static class Option {

    public Option(String shortOption, String longOption, String description,
                  boolean required, boolean expectsValue) { }

    public String getShortOption() { }
    public boolean hasShortOption() { }

    public String getLongOption() { }
    public boolean hasLongOption() { }

    public String getDescription() { }

    public boolean isRequired() { }
    public boolean expectsValue() { }
}

Constructor expectations:

At least one of shortOption or longOption must be provided.
Short options must be a single character.
Short options cannot expect values.
Long options may expect values.

Validation:

if ((shortOption == null || shortOption.isBlank()) &&
    (longOption == null || longOption.isBlank())) {
    throw new IllegalArgumentException("Option requires short or long name.");
}

if (shortOption != null && shortOption.length() != 1) {
    throw new IllegalArgumentException("Short option must be a single character.");
}

if (shortOption != null && expectsValue) {
    throw new IllegalArgumentException("Short options cannot expect values.");
}

Registering Options

To track declared options and parsed arguments, CLIAR maintains four collections:

private final Map<String, Option> shortOptions = new HashMap<>();
private final Map<String, Option> longOptions  = new HashMap<>();
private final Map<Option, String> parsedOptions = new HashMap<>();
private final List<String> positionalArguments = new ArrayList<>();

and the factory method now accepts a list of declared options:

Cliar cliar = new Cliar();

for (Option opt : options) {
    if (opt == null) {
        throw new IllegalArgumentException("Option must not be null.");
    }

    if (opt.hasShortOption()) {
        String key = opt.getShortOption();
        if (cliar.shortOptions.containsKey(key)) {
            throw new IllegalArgumentException("Duplicate short option: -" + key);
        }
        cliar.shortOptions.put(key, opt);
    }

    if (opt.hasLongOption()) {
        String key = opt.getLongOption();
        if (cliar.longOptions.containsKey(key)) {
            throw new IllegalArgumentException("Duplicate long option: --" + key);
        }
        cliar.longOptions.put(key, opt);
    }
}

This ensures CLIAR knows exactly which options are valid.

Validating Parsed Options

This is where argument parsing and option validation meet: each parsed argument is checked against the set of declared options, and only valid, non‑duplicate options are accepted.

For short options, each character (or each character in a grouped short option) is looked up in the map of declared short options:

for (char chr : arg.toCharArray()) {
    if (Character.isLetter(chr)) {
        Option opt = cliar.shortOptions.get(String.valueOf(chr));

        if (opt == null) {
            throw new IllegalArgumentException(
                String.format("Invalid option '%c' in argument %s.", chr, arg)
            );
        }

        if (cliar.parsedOptions.containsKey(opt)) {
            throw new IllegalArgumentException("Duplicate short option: -" + opt.getShortOption());
        }

        cliar.parsedOptions.put(opt, null);
    } else {
        throw new IllegalArgumentException(
            String.format("Invalid option '%c' in argument %s.", chr, arg)
        );
    }
}

And similarly for long options, where the parser validates the option name, checks whether a value is required, and ensures no duplicates are supplied:

Option opt = cliar.longOptions.get(key);

if (opt == null) {
    throw new IllegalArgumentException(String.format("Invalid option '%s'.", key));
}

if (opt.expectsValue() && (index == -1 || val.isBlank())) {
    throw new IllegalArgumentException(String.format("Option '%s' requires a value.", key));
}

if (cliar.parsedOptions.containsKey(opt)) {
    throw new IllegalArgumentException("Duplicate long option: --" + opt.getLongOption());
}

cliar.parsedOptions.put(opt, val);

Many frustrations come from unspoken expectations

At this stage, CLIAR has verified that all supplied arguments correspond to declared options — but it has not yet checked whether all required options were actually provided. This final validation step happens after parsing and ensures that every option marked as required is present:

for (Option opt : options) {
    if (opt.isRequired() && !cliar.parsedOptions.containsKey(opt)) {
        String name = opt.hasLongOption()
            ? "--" + opt.getLongOption()
            : "-" + opt.getShortOption();

        throw new IllegalArgumentException(
            String.format("Missing required option %s.", name)
        );
    }
}

with this, CLIAR contains:

all valid parsed options
all positional arguments
and has rejected any invalid or missing required options

Conclusion

In this chapter, we turned CLIAR into a structured, declarative command‑line parser.
We introduced:

- dedicated parsing methods
- strict naming rules
- the Option class
- option registration
- duplicate detection
- required‑option enforcement

With these foundations in place, CLIAR is now robust and predictable.

In the fourth and last part, we will expose the parsed options to the consumer, refine the API and suggest a few improvements for a future revision of CLIAR.

This article was written with the help of an LLM for structuring and wording. All technical content reflects my own understanding and decisions.

Building CLIAR — A simple drop-in Java class for parsing command-line arguments (Part 2 of 4)

onebitwonder — Fri, 03 Apr 2026 11:51:56 +0000

Welcome to the second part of my rolling blog, where I start building CLIAR from the ground up-starting with the simplest possible parser—and see where it breaks.
You can find the first part here and current snapshots of the code on my GitHub page.

Getting started with Short Options

To keep the interface simple, we start with a factory method:

public static Cliar from(String[] args) { ... }

With that in place, we can begin parsing the simplest possible arguments: single-character options.

for (String arg : args) {
    if (arg.startsWith("-") && !arg.startsWith("--")) {
        char option = arg.charAt(1);
        // ...
    }
}

This allows basic usage like:

myApp -a
myApp -a -b -c

However, passing each option separately is verbose. A common convention is to group them:

myApp -abc

This requires only a small change:

for (String arg : args) {
    if (arg.startsWith("-") && !arg.startsWith("--")) {
        for (char chr : arg.substring(1).toCharArray()) {
            // ...
        }
    }
}

Long Options for Clarity

An option character should reflect its meaning, like -a for all or -v for verbose. But what if you have options that start with the same letter, like cut and copy?
For reasons like this—and for better readability—we introduce long options. To distinguish them from short options, they start with a double hyphen --:

for (String arg : args) {
    if (arg.startsWith("-") && !arg.startsWith("--")) {
        // ...
    } else if (arg.startsWith("--") && (2 < arg.length())) {
        arg = arg.substring(2);
        // ...
    }
}

However a long option also starts with -, so the second branch will never be reached.
We therefore need to check for long options first:

for (String arg : args) {
    if (arg.startsWith("--") && (2 < arg.length())) {
        arg = arg.substring(2);
        // ...
    } else if (arg.startsWith("-") && !arg.startsWith("--")) {
        // ...
    }
}

Even something as simple as checking prefixes already introduces subtle edge cases.

Not everything is optional

Options, as the name implies, do not have to be passed to a program—but certain information must be, and it may not follow a format we can easily validate.
These required arguments are not prefixed, and their meaning is determined by the order in which they are passed to the program.

for (String arg : args) {
    if (arg.startsWith("--") && (2 < arg.length())) {
        arg = arg.substring(2);
        // ...
    } else if (arg.startsWith("-") && !arg.startsWith("--")) {
        // ...
    } else {
        // TODO: process positional arguments
    }
}

Parameterized options

So far, all options are simple flags—they are either present or not. But what if an option needs a value?

For example, we might want to specify a color:

myApp --color red

With our current approach, red would be treated as a positional argument, introducing ambiguity: is it a value for --color, or just the next positional parameter?
One way to solve this is to enforce ordering rules—but that would make the interface less flexible.
Instead, we can make the relationship explicit:

myApp --color=red

By using =, we clearly separate option and value, and parsing becomes straightforward: everything before = is the option, everything after is the value.
This works well for long options—but what about short options? For single-character options it might work, but short options can be grouped (-abc), making it unclear which option a value belongs to.

To keep the parser simple, we introduce a rule:

Only long options can have values.

This keeps the implementation predictable while still supporting common use cases.

for (String arg : args) {
    if (arg.startsWith("--") && (2 < arg.length())) {
        int index = arg.indexOf("=");
        if (-1 != index) {
            String key = arg.substring(0, index);
            String val = arg.substring(index + 1);
            // ...
        } else {
            // ...
        }
    } else if (arg.startsWith("-") && !arg.startsWith("--")) {
        // ...
    } else {
        // TODO: process positional arguments
    }
}

All Arguments Are Equal, but Some Are More Equal

Some tools treat - as a special positional argument representing standard input, and -- as a marker for the end of options.
We will ignore these cases for now—they will return once our parser is more complete.

Anything Goes? Not Quite.

So far, we have defined how command-line arguments are parsed, but not what valid arguments actually look like.

Thus:

---
-?*/
--n00p
-3
--color=(&3

are all valid options, but none of them are sensible.
It is common to restrict option names to letters only, while keeping values more flexible.

So far, all parsing logic is handled inside a single loop—and it continues to accumulate responsibilities.

As the number of cases grows, this approach becomes harder to maintain and extend.

In the next part, we will start to separate concerns and delegate specific tasks—such as parsing short options, long options, and values—to dedicated methods.

This article was written with the help of an LLM for structuring and wording. All technical content reflects my own understanding and decisions.

Building CLIAR — A simple drop-in Java class for parsing command-line arguments (Part 1 of 4)

onebitwonder — Tue, 24 Mar 2026 19:25:37 +0000

Welcome to the first part of my rolling blog, where I explore the need to pass command-line arguments to an application, how existing tools handle them, and why there is still value in writing a small, custom solution in Java.

Why Programs Need Command-Line Arguments

Every program solves a specific problem. Take a tool that outputs the binary content of a file as hexadecimal values. Hardcoding the input file would require recompilation for every use. Moving such values into a configuration file doesn’t help either—these are not persistent settings, but parameters that change on every run.

This is exactly where command-line arguments come in:
they allow you to pass dynamic input to your program at runtime.

From Raw Arguments to Structured Input

At its simplest, a program receives command-line arguments as a list of tokens:

myProgram arg1 arg2 ...

In Java, these are exposed as:

public static void main(String[] args) {
    // args[0], args[1], ...
}

The program processes them in exactly the order they were provided. This works—as long as the structure is fixed. But as soon as arguments become optional or reorderable, this approach breaks down. Relying on positions like args[0] or args[1] leads to fragile code, bugs, and unclear usage.

The core issue is simple:

Not all arguments are the same—but this model treats them as if they were.

What vs Where: Understanding CLI Argument Types

Command-line tools typically distinguish between different types of arguments:

Options (the what) — describe meaning, independent of position, e.g. gpg --generate-key foo, ls -l, rmdir --ignore-fail
Positional arguments (the where) — defined by order, e.g. mv currentname.txt newname.txt
Subcommands — structure commands into actions, e.g. git commit -m "message"

There is no strict standard, but these conventions are widely used.

Why Not Just Use a Library?

The Java ecosystem already provides mature solutions like

These libraries are powerful and well-designed. For many applications, they are the right choice. However, they are also general-purpose frameworks. For small tools, this can feel like overkill—introducing additional dependencies, abstractions, and configuration.

What if all you need is a simple, transparent solution that you can drop into any project?

This is the motivation behind CLIAR.

In the next part, we’ll start with the simplest possible parser—and see where it breaks.

This article was written with the help of an LLM for structuring and wording. All technical content reflects my own understanding and decisions.

Forem: onebitwonder

Building CLIAR — A simple drop-in Java class for parsing command-line arguments (Part 3 of 4)

Defining rules for option names

Parsing command‑line arguments with dedicated methods

Parsing Short Options

Parsing Long Options

Declaring Options with the Option Class

Registering Options

Validating Parsed Options

Many frustrations come from unspoken expectations

Conclusion

Building CLIAR — A simple drop-in Java class for parsing command-line arguments (Part 2 of 4)

Getting started with Short Options

Long Options for Clarity

Not everything is optional

Parameterized options

All Arguments Are Equal, but Some Are More Equal

Anything Goes? Not Quite.

Building CLIAR — A simple drop-in Java class for parsing command-line arguments (Part 1 of 4)

Why Programs Need Command-Line Arguments

From Raw Arguments to Structured Input

What vs Where: Understanding CLI Argument Types

Why Not Just Use a Library?

Declaring Options with the `Option` Class