eldritch

Rationale

Why. argumentative's Arguments keeps every argument a line wrote, duplicates included, and leaves counting them to the caller.

Key Concepts

TypedArguments

Role. A command line's arguments, each read by its type: required, optional, oneOf and has check the arity its kind declares. Implementing args() is all it takes.

Pattern. Template Method

Invocation

Role. The seam between a command's work and what runs it, a main method or a ToolProvider: TypedArguments, with emitProgress to report on err, and complain to report on err and make the run exit 1 without stopping the work.

How It Works

Guarantees. A Required left out, or any argument written twice, is refused with an IllegalArgumentException naming its long option: --root is required. A oneOf with no leg written, or more than one, is refused naming every leg: exactly one of (--left | --right) is written, and this line writes 0. Reading an argument the command does not accept is an IllegalStateException: a defect in the command, never in its line.

Lane

Purpose. Turning a command line's strings into typed arguments, refused where they are read.

Alternative. argumentative's Arguments alone, streamed, when a command counts its own arguments.

Usage

Without eldritch: the caller counts each argument

final List<Root> roots = StreamSupport.stream(arguments.spliterator(), false)
        .filter(Root.class::isInstance).map(Root.class::cast).toList();
if (roots.size() != 1) {
    throw new IllegalArgumentException("--root is required, once");
}
final Path root = roots.get(0).value();

With eldritch: each argument is read by its type, and the work reports how it goes

final Path root = invocation.required(Root.class);
if (invocation.has(Verbose.class)) {
    invocation.emitProgress("reading " + root);
}

Dependencies

• software.visionary:argumentative:2026.10.13 at Compile
• software.visionary:junit-closure:2026.09.17 at Testing

Views

Drawn from the release. A link in a view opens its source at the release tag.