# cthulu

`software.visionary:cthulu:2026.10.13` · https://codeberg.org/Kompuwiz/cthulu

Visionary Software Solutions Cthulu: a command line made into a Ritual, the Command that is also the Invocation its work asks

A command line made into a Ritual: one Command that is also the Invocation its work asks.

## Rationale

**Why.** A Command has no arguments, and a program launched from a command line has nothing but.

**Problem.** A launcher that must know how each program reads its arguments can run only the programs it knows.

**Solution.** Ritual is GoF's two-way ADAPTER: a commander Command that is also an eldritch Invocation, so a launcher executes it and its work asks it for the arguments. FromCommandLine makes one of the arguments a program was launched with.

## Key Concepts

### Ritual

**Role.** GoF's two-way ADAPTER, with no members of its own: the Command a launcher executes, and the Invocation its work reads its arguments from and reports progress and complaints to.

**Pattern.** Adapter

### FromCommandLine

**Role.** A program's reading of its own command line: a Function from the arguments it was launched with to the Ritual they mean.

**Pattern.** Factory Method

## How It Works

**Guarantees.** <code>FromCommandLine</code> refuses null arguments and never answers a null Ritual.

**Thread safety.** Cthulu holds no state; a Ritual is as safe as its implementor.

## Lane

**Purpose.** The contract between a launcher and a program launched from a command line.

**Alternative.** <code>java.util.spi.ToolProvider</code>, when the caller needs an exit status rather than an exception.

## Usage

A program says what its arguments mean

```java
public final class MyCommandLine implements FromCommandLine {
    @Override
    public Ritual apply(final String[] arguments) {
        return new MyRun(new MyArguments(arguments));
    }
}

```

## Dependencies

- `software.visionary:commander:2026.10.13` at Compile
- `software.visionary:eldritch:2026.10.13` at Compile
- `software.visionary.contrax:processor:2026.10.13` at Processor

## Caveats

- A Ritual refuses by throwing, never by a status; whoever executes it decides what a refusal means. Because <code>complain()</code> promises the run exits 1, a Ritual that complained throws once its work is done.