# exceptional

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

Simplifying exception handling: checked exceptions become unchecked, and preconditions are demanded where they hold.

Converts checked exceptions to runtime exceptions and provides explicit condition and non-null checks. Use it where the caller has chosen to propagate failure without a checked throws clause.

## Key Concepts

### Exception conversion

**Role.** <code>tosser(Exception)</code> returns a RuntimeException unchanged or wraps another Exception in a RuntimeException with the original as its cause. <code>toss(Exception)</code> throws that result.

### Calling checked operations

**Role.** <code>yoda(Callable)</code> returns the callable's result. If the call throws an Exception, yoda throws the converted runtime exception. Errors propagate unchanged.

### Demand checks

**Role.** <code>demand(BooleanSupplier)</code> evaluates the condition once and throws <code>DemandFailedException</code> if it is false. An overload accepts a message. <code>fixHoaresBillionDollarMistake(value)</code> returns a non-null value unchanged or throws DemandFailedException.

## How It Works

**Guarantees.** Place demand checks at the point that requires a condition. Call yoda around a checked operation when runtime propagation is the intended boundary, or throw tosser from an existing catch block.

## Usage

Read a supplied file while propagating I/O failure as a runtime exception

```java
import java.nio.file.Files;
import java.nio.file.Path;
import software.visionary.exceptional.Exceptional;

public class ReadWithoutCheckedClause {
    public static void main(String[] args) {
        Exceptional.demand(() -> args.length == 1, "Supply one file path");
        String path = Exceptional.fixHoaresBillionDollarMistake(args[0]);
        String text = Exceptional.yoda(() -> Files.readString(Path.of(path)));
        System.out.println(text);
    }
}
```

## Dependencies

- `software.visionary.contrax:enforcements:2026.10.13` at Processor
- `software.visionary:junit-closure:2026.10.13` at Testing

## Caveats

- Checked exceptions are wrapped, not rethrown with their original runtime type. A caller inspecting a wrapped failure uses its cause.