DEV Community: onebitwonder

How to parse configuration files in a type-safe way

onebitwonder — Wed, 27 May 2026 21:32:57 +0000

General thoughts

Storing and retrieving application settings should be simple: just write the setting's value to a file. From a programmer's point of view, reading from and writing to a file is not the complicated part, it is to decide on the use of a binary or human readable file format, each with it's up- and downsides.

A binary file format has the advantage that data-types do not need to be converted to or from a human readable form; the downside is that you have to read data in exactly the same order it was written, and vice versa. This also makes the process application specific.
A text file can easily be designed to be generic and while there are many such formats, the most simple is that of key-value pairs-like the INI file format.
The real challenge here lies converting to and from a string‑encoded value to the strongly typed value the program expects.

In this article, I will show you a simple and extensible way to do exactly that.
You can find the complete code of my configuration arguments reader Confar on my github page.

The conversion mechanism

Since configuration files store everything as text, we need a reliable way to turn those strings into actual typed values. Confar keeps this simple by declaring a generic TypeParser interface with a single job—to convert a raw string into the correct type. If the value can’t be parsed, the function throws an IllegalArgumentException, making the failure explicit and easy to diagnose.

public interface TypeParser<T> {

    public T parse(String raw) throws  IllegalArgumentException;
}

Declaring and storing the setting

Each configuration file entry is represented by a generic Setting class. It stores the setting’s name, its current value, and the TypeParser used to convert the raw string from the file into the appropriate type. Settings may be required or optional: required settings have no default value, while optional ones must define one to avoid NullPointerException in the application. File values override defaults when present. The core of the class is shown below:

public static class Setting<T> {

    public Setting(String name, T defaultValue, TypeParser<T> typeParser) throws IllegalArgumentException {
        if (null == defaultValue) {
            throw new IllegalArgumentException("Default value must not be null");
        }

        this.name = name;
        this.value = defaultValue;
        this.required = false;
        this.typeParser = typeParser;
    }

    public Setting(String name, TypeParser<T> typeParser) throws IllegalArgumentException {
        this.name = name;
        this.required = true;
        this.typeParser = typeParser;
    }

    private final String name;

    public String getName() {
        return name;
    }

    private final boolean required;

    public boolean isRequired() {
        return required;
    }

    private T value = null;

    private void parse(String value) throws IllegalArgumentException {
        this.value = typeParser.parse(value);
    }

    public T get() throws IllegalStateException {
        if (null == value) {
            throw new IllegalStateException("Setting '" + name + "' has no value. Use Confar.load() to initialise settings before calling get() on them");
        }

        return value;
    }

    private final TypeParser<T> typeParser;

    public TypeParser<T> getTypeParser() {
        return typeParser;
    }
}

With the Setting class in place, declaring configuration entries becomes straightforward. A required setting might look like this:

public Setting<Boolean> verbose = new Setting("verbose", StandardTypeParsers.BOOLEAN);

and an optional one with a default value like this:

public Setting<Integer> copies = new Setting("copies", 2, StandardTypeParsers.INTEGER);

Now that the declarations are in place, the next step is retrieving their values from a configuration file.

Confar, the utility class

Because each Setting instance manages its own value, Confar doesn’t need to hold any state. It works purely as a utility class that knows how to load settings from a file and save them back. The load method receives a map of declared settings and fills them with values from the configuration file, while save writes the current values back out.

public class Confar {

    private Confar() {
        ;
    }

    public static void load(File file, Map<String, Setting<?>> declaredSettings) throws IOException, IllegalArgumentException, IllegalStateException {
        // ...
    }

    public static void save(File file, List<Setting<?>> declaredSettings) throws IOException, IllegalStateException {
        // ...
    }
}

With Confar reduced to a simple loader and saver, the only missing piece is the format of the configuration file. Once we know how the file is structured, the logic inside the load method follows almost directly from those rules.

General layout of the file (syntax)

The configuration file format broadly follows the Unix‑style INI convention:

- Each line contains exactly one key-value pair; no line wrapping
- Leading and trailing whitespace is allowed and ignored
- Empty or blank lines are skipped
- Single-line comments are supported
- Comments start with `#` or `;` and are ignored
- Groups improve readability but do not impose structure
- A line starting with `[` begins a new group and must end with `]`;
  the content inside must not be blank

These rules translate directly into the structure of the read loop inside load:

if (null == file) {
    throw new IOException("File must not be null");
}

if ((null == declaredSettings) || declaredSettings.isEmpty()) {
    throw new IllegalArgumentException("Settings list must not be null or empty");
}

try (BufferedReader configFile = new BufferedReader(new InputStreamReader(new FileInputStream(file)))) {

    int lines = 0;
    String currentLine;
    String group = "";
    List<String> parsedSettings = new ArrayList<>();

    while (null != (currentLine = configFile.readLine())) {
        lines++;

        currentLine = currentLine.trim();

        if (currentLine.startsWith("[")) {

            if (!line.endsWith("]")) {
                // throw exception
            }

            // ...

        } else if (currentLine.isBlank()) {
            continue;
        } else if (currentLine.startsWith("#")) {
            continue;
        } else if (currentLine.startsWith(";")) {
            continue;
        } else {
            // ...
        }
    }

    // ...
}

Here, lines helps produce meaningful error messages, currentLine carries the trimmed content of each line, group reflects the currently active section, and parsedSettings ensures we don’t process the same setting twice.

Grouping setting

To keep configuration files readable, we allow settings to be grouped under headers like [network] or [ui]. When a setting appears under such a header, it should remember that group. Every setting starts out in the empty group—the implicit group at the top of the file before any header is encountered. Since [ ] isn’t a valid group, this empty group is never written explicitly. Supporting this only requires a small addition to the Setting class:

private static final String DEFAULT_GROUP  = "";

private String group = DEFAULT_GROUP;

private String getGroup() {
    return group;
}

private void setGroup(String name) {
    group = name;
}

Processing and assigning groups

Group headers may contain leading or trailing whitespace, but the actual name must not be empty. Because groups are purely cosmetic, the parsing logic stays simple:

group = currentLine.substring(1, currentLine.length() - 1).trim();

if (group.isBlank()) {
    throw new IllegalArgumentException("Invalid group name in line " + lines);
}

continue;

Here we extract the text between the brackets, trim it, validate it, and remember it as the active group for the settings that follow.

Parsing settings

A setting is defined by a key‑value pair separated by =. Whitespace around both parts is ignored, and everything after the = belongs to the value. With that in mind, the parsing logic becomes straightforward:

int index = currentLine.indexOf('=');

if (-1 == index) {
    throw new IllegalArgumentException("Invalid line " + lines + ": expected key=value");
}

String key = currentLine.substring(0, index).trim();
String val = currentLine.substring(index + 1).trim();

if (parsedSettings.contains(key)) {
    throw new IllegalStateException("Duplicate setting '" + key + "' at line " + lines);
}

Setting setting = declaredSettings.get(key);

if (null == setting) {
    throw new IllegalArgumentException("Unknown setting '" + key + "' at line " + lines);
}

setting.parse(val);
setting.setGroup(group); // soft setting, no hard mapping

parsedSettings.add(key);

We split the line, ensure the setting hasn’t already been declared, and confirm that the key is valid. The value is then parsed using the setting’s TypeParser, which either produces a typed value or throws an exception if the input is invalid. Only after successful parsing do we assign the group and mark the setting as processed.

One last check

After parsing the file and validating each entry, there’s one last thing to verify: did the user provide all required settings?

for (String key : declaredSettings.keySet()) {
    if (!parsedSettings.contains(key) && declaredSettings.get(key).isRequired()) {
        throw new IllegalStateException("Missing required setting '" + key + "'");
    }
}

This final pass ensures that every required setting has a value—either from the file or from its default—so accessing it through get won’t cause surprises later.

Storing settings

Settings aren’t static—applications often need to update them and persist those changes. To support this, each Setting exposes a setter that validates the new value before storing it:

public void set(T value) {
    if (null == value) {
        throw new IllegalStateException("Setting '" + name + "' cannot be assigned a value of 'null'");
    }

    this.value = value;
}

Before saving the configuration, we sort the settings into their groups so the output file stays tidy and easy to read. The grouping logic is straightforward:

if (null == file) {
    throw new IOException("File must not be null");
}

if ((null == declaredSettings) || declaredSettings.isEmpty()) {
    throw new IllegalArgumentException("Settings list must not be null or empty");
}

Map<String, List<Setting<?>>> groupedSettings = new LinkedHashMap<>();

for (Setting setting : declaredSettings) {

    List<Setting<?>> groupedSetting = groupedSettings.get(setting.getGroup());

    if (null == groupedSetting) {
        groupedSetting = new ArrayList<>();
        groupedSettings.put(setting.getGroup(), groupedSetting);
    }

    groupedSetting.add(setting);
}

By collecting settings under their group names, we preserve both readability and clean output formatting.

With the settings grouped, the final step is to write them back to the file. We begin with the empty group—settings that weren’t under any explicit header—and then move on to the named groups:

try (BufferedWriter configFile = new BufferedWriter (new OutputStreamWriter(new FileOutputStream(file)))) {

    List<Setting<?>> defaultGroup = groupedSettings.get("");

    if (null != defaultGroup) {
        for (Setting setting : defaultGroup) {
            configFile.write(setting.getName());
            configFile.write('=');
            configFile.write(setting.get().toString());
            configFile.newLine();
        }
    }

    for (String group : groupedSettings.keySet()) {

        if (!group.isBlank()) {
            configFile.write('[');
            configFile.write(group);
            configFile.write(']');
            configFile.newLine();

            List<Setting<?>> settings = groupedSettings.get(group);

            for (Setting setting : settings) {
                configFile.write(setting.getName());
                configFile.write('=');
                configFile.write(setting.get().toString());
                configFile.newLine();
            }

            configFile.newLine();
        }
    }

}

The empty group is written first to preserve the natural top‑of‑file layout.

Things to watch out for (and a small convenience tip)

Although settings can be declared anywhere, they must not be accessed before being loaded—unless they have a default value. Passing an incomplete list of settings to load can also lead to confusing errors later, when required settings turn out to be missing. This makes the correct order of operations important and not always intuitive for first‑time users.
Another drawback is that comments in the configuration file are lost when saving.

So far, the actual mechanic underlying the type-save reading has only been hinted at when showcasing settings declaration earlier on.
To make Confar easier to use, it’s helpful to provide a set of ready‑made parsers for common types:

public static class StandardTypeParsers {

    public static final TypeParser<Boolean> BOOLEAN = new TypeParser<>(){
        @Override public Boolean parse(String raw) throws IllegalArgumentException {
            return Boolean.valueOf(raw);
        }
    };

    // ...
}

You would define similar parsers for:

Byte
Short
Integer
Long
Float
Double and
String

Note that for String, the parser should simply return the raw value unchanged.

Conclusion

We began with the simple goal not to overthink configuration files and we end the same way — with a tiny tool that reads what you wrote, writes what you meant, and politely avoids doing anything clever behind your back.
As a bonus, the generic nature of Setting allows users to extend the allowed setting types, e.g. ip-addresses, lists of ; seperated values-whatever you want. Just stay in line ;)

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 (Final part of 4)

onebitwonder — Sun, 17 May 2026 13:56:39 +0000

Welcome to the final part of my rolling blog series. In this installment, we’ll add the remaining methods needed to access parsed command‑line arguments, along with a small but useful feature: automatically generating a formatted help message from the declared options.
To wrap things up, I’ll also highlight a few limitations of CLIAR and outline how it could evolve in a future revision.

You can find the previous part here and current snapshots of the code on my GitHub page.

Retrieving option names

Throughout the implementation, CLIAR frequently needs to refer to an option by name. Since an option may define a short name, a long name, or both, it’s helpful to centralize this logic. To avoid repeating the same formatting code everywhere, we add a getName() method to the Option class:

public String getName() {
    if (hasShortOption() && hasLongOption()) {
        return String.format("-%s/--%s", getShortOption(), getLongOption());
    } else if (hasLongOption()) {
        return String.format("--%s", getLongOption());
    } else {
        return String.format("-%s", getShortOption());
    }
}

With this small addition in place, we can finally turn to the part of CLIAR that motivated the entire project in the first place.

User access to option values

So far, CLIAR has accepted options declared at compile time and validated them against the supplied command‑line arguments at runtime. Now it’s time to bridge those two worlds by exposing accessor methods that let users retrieve the parsed values.

To begin with, we add a convenience method that checks whether a particular option was supplied:

public boolean has(Option name) {
    return parsedOptions.containsKey(name);
}

For positional arguments, we provide two methods: one to retrieve the number of parsed positional arguments, and one to access them by index:

public int getNumArguments() {
    return positionalArguments.size();
}

public String getArgument(int index) throws IndexOutOfBoundsException {
    return positionalArguments.get(index);
}

Next, we implement a family of getter methods—one for each primitive type plus String.
Each method accepts a default value (used when the option is optional and not present) and performs a simple validation to ensure the option’s value expectations match the accessor being used:

public boolean getBoolean(Option name, boolean defaultValue) throws IllegalStateException{
    if (name.expectsValue()) {
        throw new IllegalStateException(String.format("Option \'%s\' expects a value and cannot be used as a boolean.", name.getName()));
    }

    String val = parsedOptions.get(name);

    return null == val ? defaultValue : Boolean.parseBoolean(val);
}

public byte getByte(Option name, byte defaultValue) throws IllegalStateException, NumberFormatException {
    if (!name.expectsValue()) {
        throw new IllegalStateException(String.format("Option \'%s\' does not expect a value.", name.getName()));
    }

    String val = parsedOptions.get(name);

    return null == val ? defaultValue : Byte.parseByte(val);
}

// ...

And likewise for:

- short
- int
- long
- float
- double
- String

With these accessors in place, CLIAR is now fully functional.

Helping the hopeless

Since people regularly ignore the RTFM principle, we want CLIAR to be at least somewhat self‑explanatory. That means providing a simple, formatted listing of all declared options along with their descriptions. To keep things straightforward, we won’t implement line‑wrapping for long descriptions; instead, we’ll simply align the short option, long option, and description columns.

public String help() {
    int maxLen = 0;

    for (Option opt : declaredOptions) {
        if (null != opt.getLongOption()) {
            int len = opt.getLongOption().length();
            maxLen = len > maxLen ? len : maxLen;
        }
    }

    StringBuilder helpString = new StringBuilder();

    for (Option opt: declaredOptions) {
        String shortOption = null != opt.getShortOption() ? "-" + opt.getShortOption() : "  ";
        String longOption = null != opt.getLongOption() ? "--" + opt.getLongOption() : "";

        helpString.append(String.format("%s %-" + maxLen + "s %s\n", shortOption, longOption, opt.getDescription()));
    }

    return helpString.toString();
}

Now CLIAR is not only functional but also helpful.

Theory without practice is useless

Below is a short example of how CLIAR can be used inside an application:

public class Main {

    private final Option verbose = new Option("v", "verbose", "Enable verbose output", false, false);

    private final Option color = new Option(null, "color", "Set output color", false, true);

    private final Option input = new Option(null, "input", "Input file", true, true);

    private void init(String[] args) {

        Cliar cliar = null;

        try {
            cliar = Cliar.from(args, new Cliar.Option[] {
                verbose,
                color,
                input
            });

            // ...

            if (cliar.getBoolean(verbose, false)) {
                // ...
            }

        } catch (IllegalArgumentException ex) {
            System.err.println(ex.getMessage());

            if (null != cliar) {
                System.err.println(cliar.help());
            }

            System.exit(-1);
        }
    }

    public static void main(String[] args) {
        Main myApp = new Main();

        myApp.init(args);

        // ...
    }
}

Instead of declaring fields of primitive types such as private boolean verbose or private int color, each declared Option effectively is such a field. It connects directly to the supplied command‑line arguments without any reflection magic, making CLIAR suitable even for legacy applications or environments running on older JVMs or JDKs.

What could be done better in a future revision

While CLIAR is intentionally minimal, several areas could be improved in a future revision.
Right now, options are represented as individual fields rather than being grouped into a dedicated configuration class, which limits how cleanly they can be passed around. Options also do not carry explicit types; instead, the caller chooses the appropriate getter, which works but leaves room for type‑safe improvements. Positional arguments are stored as raw strings, meaning any further parsing must be done manually. And finally, the generated help text is intentionally simple: it lists the available options, but it does not show the expected command syntax or provide a high‑level summary of the application.

Conclusion

CLIAR comes in at just about 220 lines of real code — small enough to read in one sitting, yet complete enough to use in real applications.
It provides a functional, transparent, dependency‑free command‑line parser that you can drop into almost any Java project.

I hope you enjoyed this series, and I’d be happy to have you along for the next one as well.

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 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.

DEV Community: onebitwonder

How to parse configuration files in a type-safe way

General thoughts

The conversion mechanism

Declaring and storing the setting

Confar, the utility class

General layout of the file (syntax)

Grouping setting

Processing and assigning groups

Parsing settings

One last check

Storing settings

Things to watch out for (and a small convenience tip)

Conclusion

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

Retrieving option names

User access to option values

Helping the hopeless

Theory without practice is useless

What could be done better in a future revision

Conclusion

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