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

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)

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.