bibliotech catalog list --format=csv | grep "Java" | wc -l
cat isbns.txt | bibliotech catalog import --from-stdin
bibliotech report fines --format=json | jq '.[] | select(.amount > 10)'

Error: NullPointerException

Error: no material found with ISBN 978-0000000009.

  Cause: the ISBN does not exist in the catalogue.
  Suggestion: check the ISBN with 'bibliotech catalog search --title="..."'
              or import it with 'bibliotech catalog import'.

public static void main(String[] args) {
    String format = "table";
    boolean verbose = false;
    String isbn = null;

    for (int i = 0; i < args.length; i++) {
        switch (args[i]) {
            case "--format" -> format = args[++i];
            case "-v", "--verbose" -> verbose = true;
            case "--isbn" -> isbn = args[++i];
            default -> {
                System.err.println("Unknown option: " + args[i]);
                System.exit(2);
            }
        }
    }
    // …
}

<dependencies>
  <dependency>
    <groupId>com.nexussoftware</groupId>
    <artifactId>bibliotech-application</artifactId>
  </dependency>
  <dependency>
    <groupId>com.nexussoftware</groupId>
    <artifactId>bibliotech-infrastructure</artifactId>
  </dependency>

  <dependency>
    <groupId>info.picocli</groupId>
    <artifactId>picocli-spring-boot-starter</artifactId>   <!-- brings picocli + integration -->
  </dependency>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter</artifactId>           <!-- no 'web': this is not a server -->
  </dependency>
</dependencies>

package com.nexussoftware.bibliotech.console;

import picocli.CommandLine;
import picocli.CommandLine.Command;
import picocli.CommandLine.Option;
import picocli.CommandLine.Parameters;
import java.util.concurrent.Callable;

@Command(
    name = "bibliotech",                          // how it is invoked
    mixinStandardHelpOptions = true,              // adds --help and --version for free
    version = "BiblioTech CLI 1.0.0",
    description = "Management tool for Nexus Software's technical library.")
public class Example implements Callable<Integer> {   // Callable<Integer>: the int is the exit code

    @Parameters(index = "0", description = "ISBN of the material to look up.")
    private String isbn;

    @Option(names = {"-f", "--format"}, defaultValue = "table",
            description = "Output format: ${COMPLETION-CANDIDATES}. Default: ${DEFAULT-VALUE}")
    private Format format;

    @Override
    public Integer call() {
        System.out.println("Looking up " + isbn + " in format " + format);
        return 0;                                  // 0 = success
    }

    public static void main(String[] args) {
        int exitCode = new CommandLine(new Example()).execute(args);
        System.exit(exitCode);
    }
}

$ java -jar example.jar --help
Usage: bibliotech [-hV] [-f=<format>] <isbn>
Management tool for Nexus Software's technical library.
      <isbn>          ISBN of the material to look up.
  -f, --format=<format>
                      Output format: TABLE, CSV, JSON. Default: TABLE
  -h, --help          Show this help message and exit.
  -V, --version       Print version information and exit.

@Command(name = "loan")
class ExampleOptions {

    // Boolean: its mere presence sets it to true
    @Option(names = {"-v", "--verbose"}, description = "Shows execution detail.")
    boolean verbose;

    // Required: if it is missing, Picocli produces a clear error
    @Option(names = "--isbn", required = true, description = "ISBN of the material.")
    String isbn;

    // With a default value
    @Option(names = "--days", defaultValue = "15", description = "Duration in days.")
    int days;

    // A java.time type: automatic conversion from ISO-8601
    @Option(names = "--from", description = "Start date (yyyy-MM-dd).")
    LocalDate from;

    // Enum: Picocli validates the allowed values and lists them in the help
    @Option(names = "--format", defaultValue = "TABLE")
    Format format;

    // Repeatable: --tag java --tag design
    @Option(names = "--tag", description = "Tag (repeatable).")
    List<String> tags = new ArrayList<>();

    // With arity: exactly two values
    @Option(names = "--range", arity = "2", paramLabel = "<from> <to>")
    int[] range;

    // Map: -D key=value
    @Option(names = "-D", description = "Additional property.")
    Map<String, String> properties = new LinkedHashMap<>();

    // Sensitive: Picocli asks for it at the keyboard without echoing it if it is not passed
    @Option(names = "--key", interactive = true, arity = "0..1")
    char[] key;

    // Positional: the first one
    @Parameters(index = "0", description = "Input file.")
    Path file;

    @Parameters(index = "1..*", description = "Additional ISBNs.")
    List<String> extraIsbns;
}

static class DataSource {
    @Option(names = "--file", required = true) Path file;
    @Option(names = "--url", required = true) URI url;
    @Option(names = "--stdin", required = true) boolean stdin;
}

@ArgGroup(exclusive = true, multiplicity = "1")   // exactly one of the three
DataSource source;

/** Converts the command-line text into the domain's value object. */
public class IsbnConverter implements CommandLine.ITypeConverter<Isbn> {

    @Override
    public Isbn convert(String value) {
        try {
            return Isbn.of(value);          // the value object already validates (12-02)
        } catch (InvalidIsbnException e) {
            // TypeConversionException produces a usage message, not a stack trace
            throw new CommandLine.TypeConversionException(
                "'" + value + "' is not a valid ISBN-13. Expected format: 978-XXXXXXXXXX");
        }
    }
}

@Option(names = "--isbn", required = true, converter = IsbnConverter.class)
private Isbn isbn;      // the field is of the domain type, not String!

$ bibliotech loan create --isbn=1234 --employee=1
Invalid value for option '--isbn': '1234' is not a valid ISBN-13.
Expected format: 978-XXXXXXXXXX
Usage: bibliotech loan create [-hV] --employee=<id> --isbn=<isbn> [--days=<n>]
…

@Spec CommandLine.Model.CommandSpec spec;

private void validate() {
    if (from != null && to != null && from.isAfter(to)) {
        throw new CommandLine.ParameterException(spec.commandLine(),
            "--from (" + from + ") cannot be later than --to (" + to + ")");
    }
}

@Command(
    name = "bibliotech",
    mixinStandardHelpOptions = true,
    version = "BiblioTech CLI 1.0.0",
    description = "Management of Nexus Software's technical library.",
    subcommands = {
        CatalogCommand.class,
        LoanCommand.class,
        NoticesCommand.class,
        ReportCommand.class,
        CommandLine.HelpCommand.class          // 'bibliotech help catalog'
    })
@Component
public class RootCommand implements Callable<Integer> {

    @Override
    public Integer call() {
        // With no subcommand, show the help and return a usage error:
        // that way a script knows the invocation was incomplete.
        CommandLine.usage(this, System.out);
        return ExitCode.USAGE_ERROR;
    }
}

@Command(name = "catalog",
         description = "Operations on the catalogue of materials.",
         subcommands = {CatalogListCommand.class, CatalogSearchCommand.class,
                        CatalogImportCommand.class, CatalogCardCommand.class})
@Component
public class CatalogCommand implements Callable<Integer> {
    @Override public Integer call() {
        CommandLine.usage(this, System.out);
        return ExitCode.USAGE_ERROR;
    }
}

@Command(name = "bibliotech", …)
public class RootCommand {

    @Option(names = {"-f", "--format"}, scope = CommandLine.ScopeType.INHERIT,
            defaultValue = "TABLE", description = "Output format: ${COMPLETION-CANDIDATES}")
    Format format;

    @Option(names = {"-q", "--quiet"}, scope = CommandLine.ScopeType.INHERIT,
            description = "Errors only.")
    boolean quiet;

    @Option(names = {"-v", "--verbose"}, scope = CommandLine.ScopeType.INHERIT,
            description = "Execution detail.")
    boolean verbose;
}

@Command(name = "import",
    description = "Imports materials into the catalogue from a file or from standard input.",
    footerHeading = "%nExamples:%n",
    footer = {
        "  bibliotech catalog import catalog.csv",
        "  bibliotech catalog import --input-format=json data.json --dry-run",
        "  cat isbns.txt | bibliotech catalog import --from-stdin --enrich",
        "",
        "Exit codes: 0 success, 1 error, 2 wrong usage, 4 partial import."
    })
class CatalogImportCommand implements Callable<Integer> { … }

# Generate the script (once, at build time)
java -cp bibliotech-console.jar picocli.AutoComplete \
     -n bibliotech com.nexussoftware.bibliotech.console.RootCommand

# Enable it in the session
source bibliotech_completion

# Now the tab key works
$ bibliotech cat<TAB>          → bibliotech catalog
$ bibliotech catalog <TAB>     → card  import  list  search
$ bibliotech catalog list --format=<TAB>  → TABLE  CSV  JSON

package com.nexussoftware.bibliotech.console;

@SpringBootApplication(scanBasePackages = "com.nexussoftware.bibliotech")
public class BiblioTechCli implements CommandLineRunner, ExitCodeGenerator {

    private final RootCommand rootCommand;
    private final CommandLine.IFactory factory;    // supplied by the Picocli starter
    private int exitCode;

    public BiblioTechCli(RootCommand rootCommand, CommandLine.IFactory factory) {
        this.rootCommand = rootCommand;
        this.factory = factory;
    }

    @Override
    public void run(String... args) {
        this.exitCode = new CommandLine(rootCommand, factory)
                .setCaseInsensitiveEnumValuesAllowed(true)     // --format=json and JSON
                .setExecutionExceptionHandler(new CliErrorHandler())
                .execute(args);
    }

    @Override
    public int getExitCode() { return exitCode; }

    public static void main(String[] args) {
        // SpringApplication.exit returns the ExitCodeGenerator's code,
        // and closes the context in an orderly way before exiting.
        System.exit(SpringApplication.exit(SpringApplication.run(BiblioTechCli.class, args)));
    }
}

@Command(name = "create", description = "Creates a loan of a material to an employee.")
@Component
public class LoanCreateCommand implements Callable<Integer> {

    private final ManageLoans manager;            // constructor injection, as always!
    private final Output output;

    public LoanCreateCommand(ManageLoans manager, Output output) {
        this.manager = manager;
        this.output = output;
    }

    @Option(names = "--isbn", required = true, converter = IsbnConverter.class)
    private Isbn isbn;

    @Option(names = "--employee", required = true, paramLabel = "<id>")
    private Long employeeId;

    @Option(names = "--days", description = "Duration. Defaults to the material type's.")
    private Integer days;

    @Override
    public Integer call() {
        Loan loan = manager.lend(isbn, employeeId, days);
        output.success("Loan #%d created. Due on %s."
                .formatted(loan.getId(), loan.getDueDate()));
        return ExitCode.OK;
    }
}

spring:
  main:
    web-application-type: none      # no Tomcat
    banner-mode: off                # no ASCII banner polluting the output
  output:
    ansi:
      enabled: detect               # colours only if the terminal supports them

logging:
  pattern:
    console: "%d{HH:mm:ss} %-5level %msg%n"
  level:
    root: WARN                      # a quiet CLI by default
    com.nexussoftware.bibliotech: INFO

@Command(name = "list",
    description = "Lists the materials in the catalogue.",
    footerHeading = "%nExamples:%n",
    footer = {
        "  bibliotech catalog list --type=BOOK --available",
        "  bibliotech catalog list --format=csv > catalog.csv",
        "  bibliotech catalog list --format=json | jq '.[].title'"
    })
@Component
public class CatalogListCommand implements Callable<Integer> {

    private final QueryCatalog catalog;
    private final Output output;

    public CatalogListCommand(QueryCatalog catalog, Output output) {
        this.catalog = catalog;
        this.output = output;
    }

    @Option(names = "--type", description = "Filter by type: ${COMPLETION-CANDIDATES}")
    private MaterialType type;

    @Option(names = "--available", description = "Only materials with free copies.")
    private boolean onlyAvailable;

    @Option(names = "--limit", defaultValue = "50",
            description = "Maximum number of results. Default: ${DEFAULT-VALUE}")
    private int limit;

    @Option(names = "--sort-by", defaultValue = "TITLE",
            description = "Sort criterion: ${COMPLETION-CANDIDATES}")
    private SortCriterion sort;

    @Override
    public Integer call() {
        var criteria = SearchCriteria.builder()            // Builder from 12-02
                .type(type)
                .onlyAvailable(onlyAvailable)
                .build();

        List<Material> results = catalog.search(criteria, sort, limit);

        if (results.isEmpty()) {
            output.warn("No material matches those criteria.");
            return ExitCode.NO_RESULTS;                    // 3: not the same as an error
        }

        output.writeMaterials(results);                    // Output decides the format
        output.info("%d materials.".formatted(results.size()));
        return ExitCode.OK;
    }
}

@Command(name = "shell", description = "Interactive mode. Type 'exit' to finish.")
@Component
public class ShellCommand implements Callable<Integer> {

    private final RootCommand root;
    private final CommandLine.IFactory factory;

    @Override
    public Integer call() {
        // Console is null if input is redirected: then the shell makes no sense
        Console console = System.console();
        if (console == null) {
            System.err.println("Interactive mode requires a terminal.");
            return ExitCode.USAGE_ERROR;
        }

        System.out.println("BiblioTech 1.0.0 — type 'help' or 'exit'.");
        CommandLine cl = new CommandLine(root, factory);

        while (true) {
            String line = console.readLine("bibliotech> ");
            if (line == null || line.isBlank()) continue;
            if (line.equals("exit") || line.equals("quit")) return ExitCode.OK;
            if (line.equals("help")) { cl.usage(System.out); continue; }

            // Reuses EXACTLY the same parsing and the same commands
            cl.execute(split(line));
        }
    }

    /** Splits while respecting quotes: search --title="Effective Java" */
    private String[] split(String line) {
        List<String> parts = new ArrayList<>();
        Matcher m = Pattern.compile("\"([^\"]*)\"|(\\S+)").matcher(line);
        while (m.find()) {
            parts.add(m.group(1) != null ? m.group(1) : m.group(2));
        }
        return parts.toArray(String[]::new);
    }
}

@Option(names = "--from-stdin", description = "Reads the ISBNs from standard input, one per line.")
private boolean fromStdin;

@Parameters(index = "0", arity = "0..1", description = "Input file.")
private Path file;

private List<String> readInput() throws IOException {
    if (fromStdin) {
        // Mind the encoding: in Java 18+ the default is UTF-8, but being explicit does no harm
        try (BufferedReader reader = new BufferedReader(
                new InputStreamReader(System.in, StandardCharsets.UTF_8))) {
            return reader.lines()
                    .map(String::strip)
                    .filter(l -> !l.isEmpty() && !l.startsWith("#"))   // ignore comments
                    .toList();
        }
    }
    if (file != null) {
        return Files.readAllLines(file, StandardCharsets.UTF_8);
    }
    throw new CommandLine.ParameterException(spec.commandLine(),
        "Give an input file or use --from-stdin.");
}

/** true if stdout goes to a terminal; false if it goes to a file or to another process. */
public static boolean isTerminal() {
    return System.console() != null;
}

$ bibliotech catalog list                         # terminal: colours, headers, totals
$ bibliotech catalog list > catalog.txt           # file: no colours, no decoration
$ bibliotech catalog list | grep Java             # pipe: the same

# The result goes to the file; the warnings are still visible on screen
bibliotech catalog import data.csv > result.json 2> import.log

# Chaining without anything getting polluted
bibliotech report fines --format=json | jq '[.[] | select(.amount > 10)] | length'

# Using one command's output as another one's input
bibliotech loan list --overdue --format=csv | cut -d';' -f2 | \
  bibliotech notices send --from-stdin

bibliotech notices send || echo "FAILED: check the log"     # || runs if the code != 0

public final class ExitCode {
    public static final int OK = 0;
    public static final int ERROR = 1;
    public static final int USAGE_ERROR = 2;
    public static final int NO_RESULTS = 3;
    public static final int PARTIAL = 4;
    public static final int NOT_FOUND = 5;
    public static final int CONFLICT = 6;
    public static final int UNAVAILABLE = 7;
    public static final int INTERRUPTED = 130;

    private ExitCode() { }
}

#!/usr/bin/env bash
# Retry only when it makes sense
for attempt in 1 2 3; do
  bibliotech catalog import --enrich data.csv
  code=$?
  case $code in
    0) echo "Import successful"; exit 0 ;;
    7) echo "Service unavailable; retry $attempt"; sleep $((attempt * 30)) ;;
    *) echo "Unrecoverable error (code $code)"; exit $code ;;
  esac
done
exit 7

@Component
public class Output {

    private final ObjectMapper json;         // Jackson, from module 11: a single bean
    private final PrintStream out;
    private final PrintStream err;

    private Format format = Format.TABLE;
    private Level level = Level.NORMAL;
    private boolean colour = true;

    public Output(ObjectMapper json) {
        this.json = json;
        // Explicit encoding: without this, accents break when redirecting on Windows
        this.out = new PrintStream(new FileOutputStream(FileDescriptor.out), true, UTF_8);
        this.err = new PrintStream(new FileOutputStream(FileDescriptor.err), true, UTF_8);
    }

    public void writeMaterials(List<Material> materials) {
        switch (format) {
            case TABLE -> table(materials);
            case CSV   -> csv(materials);
            case JSON  -> json(materials.stream().map(MaterialDto::from).toList());
        }
    }
    // …
}

private void table(List<Material> materials) {
    // 1. Work out each column's width: that of the longest content, with a maximum
    int titleWidth = Math.min(45, Math.max(6,
            materials.stream().mapToInt(m -> m.getTitle().length()).max().orElse(6)));

    String rowFormat = "%-17s  %-" + titleWidth + "s  %-8s  %5s%n";

    // 2. Header only if this is NOT a pipe and we are not in quiet mode
    if (showDecoration()) {
        out.printf(rowFormat, "ISBN", "TITLE", "TYPE", "FREE");
        out.println("-".repeat(17 + titleWidth + 8 + 5 + 6));
    }

    // 3. Rows
    for (Material m : materials) {
        out.printf(rowFormat,
                m.getIsbn().value(),
                truncate(m.getTitle(), titleWidth),
                m.type(),
                colourAvailability(m.availableCopies()));
    }
}

/** Truncates with an ellipsis so the table does not fall out of alignment. */
private String truncate(String text, int max) {
    return text.length() <= max ? text : text.substring(0, max - 1) + "…";
}

ISBN               TITLE            TYPE       FREE
---------------------------------------------------
978-0000000001     Effective Java   BOOK          2
978-0000000002     Design Patterns  BOOK          0
978-0000000003     Refactoring      BOOK          1

private void csv(List<Material> materials) {
    if (showDecoration()) out.println("isbn;title;type;available");
    for (Material m : materials) {
        out.printf("%s;%s;%s;%d%n",
                m.getIsbn().value(), escape(m.getTitle()), m.type(), m.availableCopies());
    }
}

private String escape(String value) {
    // If it contains the separator, quotes or line breaks, quote it and double the quotes
    if (value.contains(";") || value.contains("\"") || value.contains("\n")) {
        return '"' + value.replace("\"", "\"\"") + '"';
    }
    return value;
}

private void json(Object value) {
    try {
        // Not indented if it is a pipe (more compact); indented if a person is reading it
        ObjectWriter writer = isTerminal()
                ? json.writerWithDefaultPrettyPrinter()
                : json.writer();
        out.println(writer.writeValueAsString(value));
    } catch (JsonProcessingException e) {
        throw new OutputFailedException("Could not serialise the result", e);
    }
}

public enum Level { QUIET, NORMAL, VERBOSE, TRACE }

@Component
public class Output {

    /** Result: ALWAYS to stdout, even in quiet mode. It is what the user asked for. */
    public void result(String text) { out.println(text); }

    /** Contextual information: to stderr, so as not to pollute the pipe. */
    public void info(String text) {
        if (level.ordinal() >= Level.NORMAL.ordinal()) err.println(text);
    }

    /** Execution detail: only with -v. */
    public void detail(String text) {
        if (level.ordinal() >= Level.VERBOSE.ordinal()) err.println(grey("  " + text));
    }

    public void warn(String text)    { err.println(yellow("Warning: ") + text); }
    public void error(String text)   { err.println(red("Error: ") + text); }
    public void success(String text) { if (level != Level.QUIET) err.println(green("✓ ") + text); }
}

@Option(names = {"-v", "--verbose"}, scope = ScopeType.INHERIT)
void setVerbose(boolean[] times) {
    Level level = times.length >= 2 ? Level.TRACE : Level.VERBOSE;
    output.setLevel(level);
    if (level == Level.TRACE) {
        // Raise Logback's level on the fly (11-07)
        ((ch.qos.logback.classic.Logger) LoggerFactory.getLogger("com.nexussoftware.bibliotech"))
            .setLevel(ch.qos.logback.classic.Level.DEBUG);
    }
}

@Command(name = "import", description = "Imports materials into the catalogue.")
@Component
public class CatalogImportCommand implements Callable<Integer> {

    private final CatalogImporter importer;
    private final Output output;

    @Parameters(index = "0", arity = "0..1") private Path file;
    @Option(names = "--from-stdin") private boolean fromStdin;
    @Option(names = "--enrich", description = "Completes the metadata from the external API.")
    private boolean enrich;
    @Option(names = "--dry-run", description = "Writes nothing; shows what it would do.")
    private boolean dryRun;

    @Override
    public Integer call() throws Exception {
        List<ImportRecord> records = readInput();
        output.info("Importing %d records%s…"
                .formatted(records.size(), dryRun ? " (DRY RUN)" : ""));

        var progress = new ProgressBar(records.size(), output);
        var succeeded = new AtomicInteger();                 // module 8
        var errors = Collections.synchronizedList(new ArrayList<ImportError>());

        // Virtual threads: thousands of blocking I/O tasks without exhausting the system
        try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
            for (ImportRecord record : records) {
                executor.submit(() -> {
                    try {
                        if (!dryRun) importer.importRecord(record, enrich);
                        succeeded.incrementAndGet();
                    } catch (BiblioTechException e) {
                        errors.add(ImportError.from(record, e));
                    } finally {
                        progress.advance();
                    }
                });
            }
        }   // closing the try-with-resources waits for ALL of them to finish

        progress.finish();

        output.writeImportResult(succeeded.get(), errors);

        if (errors.isEmpty()) return ExitCode.OK;
        if (succeeded.get() == 0) return ExitCode.ERROR;
        return ExitCode.PARTIAL;                              // the 4 in the table
    }
}

public class ProgressBar {

    private static final int WIDTH = 40;

    private final int total;
    private final Output output;
    private final AtomicInteger current = new AtomicInteger();
    private final long start = System.nanoTime();
    private final boolean active;
    private volatile long lastRepaint;

    public ProgressBar(int total, Output output) {
        this.total = total;
        this.output = output;
        // DECISION 1: only if there is a terminal and we are not in quiet mode.
        // A progress bar in a log file is unreadable rubbish.
        this.active = output.isTerminal() && output.level() != Level.QUIET;
    }

    public void advance() {
        int n = current.incrementAndGet();
        if (!active) return;

        // DECISION 2: throttle the repainting. Repainting 5,000 times a second
        // burns more CPU than the work itself.
        long now = System.nanoTime();
        if (n < total && now - lastRepaint < 100_000_000L) return;   // 100 ms
        lastRepaint = now;

        paint(n);
    }

    private void paint(int n) {
        int filled = (int) ((double) n / total * WIDTH);
        long seconds = (System.nanoTime() - start) / 1_000_000_000L;
        long remaining = n > 0 ? seconds * (total - n) / n : 0;

        // DECISION 3: to stderr, not to stdout. Progress is NOT the result.
        // \r goes back to the start of the line without a newline: the bar overwrites itself.
        output.err().printf("\r[%s%s] %d/%d (%d%%) ETA %ds  ",
                "=".repeat(filled), " ".repeat(WIDTH - filled),
                n, total, n * 100 / total, remaining);
    }

    public void finish() {
        if (active) output.err().println();     // close the bar's line
    }
}

[========================>               ] 3120/5000 (62%) ETA 47s

@Component
public class CancellationManager {

    private static final Logger log = LoggerFactory.getLogger(CancellationManager.class);

    private final AtomicBoolean cancelled = new AtomicBoolean(false);
    private final CountDownLatch workFinished = new CountDownLatch(1);

    @PostConstruct
    void register() {
        Runtime.getRuntime().addShutdownHook(new Thread(this::onSignal, "cancellation"));
    }

    private void onSignal() {
        cancelled.set(true);
        System.err.println("\nCancelling… (press Ctrl+C again to force)");
        try {
            // Allow some leeway to finish in an orderly way, but do NOT wait indefinitely:
            // a hook that never ends leaves the process hanging.
            if (!workFinished.await(10, TimeUnit.SECONDS)) {
                System.err.println("The work did not finish in time; exiting anyway.");
            }
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        }
    }

    /** Long loops check this on every iteration. */
    public boolean cancelled() { return cancelled.get(); }

    public void workCompleted() { workFinished.countDown(); }
}

@Override
public Integer call() {
    try {
        for (ImportRecord record : records) {
            if (cancellation.cancelled()) {
                output.warn("Import cancelled by the user. "
                          + "Processed %d of %d records.".formatted(processed, records.size()));
                return ExitCode.INTERRUPTED;          // 130, POSIX convention
            }
            importer.importRecord(record, enrich);
            processed++;
        }
        return ExitCode.OK;
    } finally {
        cancellation.workCompleted();        // releases the hook
    }
}

public final class Ansi {
    public static final String RESET  = "";
    public static final String RED    = "";
    public static final String GREEN  = "";
    public static final String YELLOW = "";
    public static final String GREY   = "";
    public static final String BOLD   = "";
}

$ bibliotech catalog list > output.txt
$ cat output.txt
^[[32m978-0000000001^[[0m  Effective Java …

public class ColourDetector {

    public static boolean shouldUseColour(boolean noColourOption) {
        // 1. The user's explicit option wins
        if (noColourOption) return false;

        // 2. NO_COLOR: a universal convention (no-color.org). If it exists, with any value, honour it
        if (System.getenv("NO_COLOR") != null) return false;

        // 3. FORCE_COLOR: to force colours in a CI pipeline that does render them
        if (System.getenv("FORCE_COLOR") != null) return true;

        // 4. A "dumb" terminal (some CI environments, the Emacs shell)
        String term = System.getenv("TERM");
        if ("dumb".equals(term)) return false;

        // 5. No terminal (pipe or redirection): no colour
        return System.console() != null;
    }
}

Error: cannot lend "Effective Java" to Diego Alonso.

  Cause:      the employee already has 3 active loans (maximum allowed: 3).
  Suggestion: list their loans with
              bibliotech loan list --employee=2
              and return one before creating a new one.

  Technical detail recorded with id: a7f3e91c

public class CliErrorHandler implements CommandLine.IExecutionExceptionHandler {

    private static final Logger log = LoggerFactory.getLogger(CliErrorHandler.class);

    @Override
    public int handleExecutionException(Exception e, CommandLine cl, CommandLine.ParseResult parseResult) {

        String incidentId = UUID.randomUUID().toString().substring(0, 8);
        // The FULL technical detail goes to the log, not to the user's screen (06-07)
        log.error("Error while executing the command [id={}]", incidentId, e);

        PrintWriter err = cl.getErr();

        return switch (e) {
            case MaterialNotFoundException ex -> {
                err.println(red("Error: ") + "there is no material with ISBN " + ex.getIsbn() + ".");
                err.println("  Suggestion: look for it with 'bibliotech catalog search --title=\"...\"'");
                yield ExitCode.NOT_FOUND;
            }
            case LoanLimitExceededException ex -> {
                err.println(red("Error: ") + "employee " + ex.getName()
                          + " already has " + ex.getMax() + " active loans.");
                err.println("  Suggestion: 'bibliotech loan list --employee=" + ex.getId() + "'");
                yield ExitCode.CONFLICT;
            }
            case GatewayUnavailableException ex -> {
                err.println(red("Error: ") + "the metadata service is not responding.");
                err.println("  Suggestion: retry later, or use --no-enrich.");
                yield ExitCode.UNAVAILABLE;            // 7: the script SHOULD retry
            }
            case BiblioTechException ex -> {
                err.println(red("Error: ") + ex.getMessage());
                yield ExitCode.ERROR;
            }
            default -> {
                // The unexpected: a generic message + an identifier to correlate with the log
                err.println(red("Unexpected error. ") + "Incident " + incidentId + ".");
                err.println("  Run with -vv to see the detail, or send that identifier to support.");
                yield ExitCode.ERROR;
            }
        };
    }
}

<build>
  <finalName>bibliotech-cli</finalName>
  <plugins>
    <plugin>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-maven-plugin</artifactId>
      <configuration>
        <mainClass>com.nexussoftware.bibliotech.console.BiblioTechCli</mainClass>
        <executable>true</executable>   <!-- adds a launch script to the jar itself -->
      </configuration>
      <executions>
        <execution><goals><goal>repackage</goal></goals></execution>
      </executions>
    </plugin>
  </plugins>
</build>

./mvnw -pl bibliotech-console clean package
java -jar bibliotech-console/target/bibliotech-cli.jar catalog list

#!/usr/bin/env bash
# scripts/bibliotech — install it as /usr/local/bin/bibliotech
set -euo pipefail

BIBLIOTECH_HOME="${BIBLIOTECH_HOME:-/opt/bibliotech}"
JAVA_BIN="${JAVA_HOME:+$JAVA_HOME/bin/java}"
JAVA_BIN="${JAVA_BIN:-java}"

# JVM options aimed at fast start-up, not at a long-lived server:
#  -XX:TieredStopAtLevel=1  do not compile deeply: the process lasts seconds
#  -XX:+UseSerialGC         the cheapest GC to initialise
#  -Xshare:auto             use the shared class archive
exec "$JAVA_BIN" \
  -XX:TieredStopAtLevel=1 \
  -XX:+UseSerialGC \
  -Xshare:auto \
  -Dfile.encoding=UTF-8 \
  ${BIBLIOTECH_OPTS:-} \
  -jar "$BIBLIOTECH_HOME/bibliotech-cli.jar" "$@"      # "$@" preserves arguments with spaces

jpackage --type deb \
  --name bibliotech \
  --input bibliotech-console/target \
  --main-jar bibliotech-cli.jar \
  --main-class org.springframework.boot.loader.launch.JarLauncher \
  --app-version 1.0.0 \
  --vendor "Nexus Software"

./mvnw -pl bibliotech-console -Pnative native:compile
./bibliotech-console/target/bibliotech catalog list         # starts in ~50 ms

@ExtendWith(MockitoExtension.class)
class LoanCreateCommandTest {

    @Mock ManageLoans manager;
    @Mock Output output;
    @InjectMocks LoanCreateCommand command;

    @Test
    void returnsOkAndReportsWhenTheLoanIsCreated() {
        var loan = aLoanOf("978-0000000001", "Marta Ruiz");
        when(manager.lend(any(), eq(1L), isNull())).thenReturn(loan);
        ReflectionTestUtils.setField(command, "isbn", Isbn.of("978-0000000001"));
        ReflectionTestUtils.setField(command, "employeeId", 1L);

        Integer exitCode = command.call();

        assertThat(exitCode).isEqualTo(ExitCode.OK);
        verify(output).success(contains("Loan #" + loan.getId()));
    }
}

class ArgumentParsingTest {

    @Test
    void parsesTheOptionsOfTheListCommand() {
        var command = new CatalogListCommand(mock(QueryCatalog.class), mock(Output.class));
        var cl = new CommandLine(command);

        cl.parseArgs("--type=BOOK", "--available", "--limit=10");

        assertThat(ReflectionTestUtils.getField(command, "type")).isEqualTo(MaterialType.BOOK);
        assertThat(ReflectionTestUtils.getField(command, "onlyAvailable")).isEqualTo(true);
        assertThat(ReflectionTestUtils.getField(command, "limit")).isEqualTo(10);
    }

    @Test
    void rejectsAnInvalidIsbnWithAUsefulMessage() {
        var cl = new CommandLine(new LoanCreateCommand(mock(…), mock(…)));

        assertThatThrownBy(() -> cl.parseArgs("--isbn=1234", "--employee=1"))
            .isInstanceOf(CommandLine.ParameterException.class)
            .hasMessageContaining("is not a valid ISBN-13");
    }

    @Test
    void requiresTheMandatoryOptions() {
        var cl = new CommandLine(new LoanCreateCommand(mock(…), mock(…)));

        assertThatThrownBy(() -> cl.parseArgs("--employee=1"))
            .isInstanceOf(CommandLine.MissingParameterException.class)
            .hasMessageContaining("--isbn");
    }
}

@SpringBootTest
class BiblioTechCliIT {

    @Autowired RootCommand root;
    @Autowired CommandLine.IFactory factory;

    @Test
    void listingTheCatalogueAsJsonProducesValidJson() throws Exception {
        var capturedOut = new StringWriter();
        var capturedErr = new StringWriter();

        int exitCode = new CommandLine(root, factory)
                .setOut(new PrintWriter(capturedOut))         // Picocli allows redirection
                .setErr(new PrintWriter(capturedErr))
                .execute("catalog", "list", "--format=json");

        assertThat(exitCode).isEqualTo(ExitCode.OK);

        // The result must be VALID JSON: no banners or messages polluting it
        JsonNode tree = new ObjectMapper().readTree(capturedOut.toString());
        assertThat(tree.isArray()).isTrue();
        assertThat(tree).hasSize(3);
        assertThat(tree.get(0).get("title").asText()).isEqualTo("Effective Java");
    }

    @Test
    void returnsCode5WhenTheMaterialDoesNotExist() {
        int exitCode = new CommandLine(root, factory)
                .setExecutionExceptionHandler(new CliErrorHandler())
                .execute("catalog", "card", "978-9999999999");

        assertThat(exitCode).isEqualTo(ExitCode.NOT_FOUND);
    }

    @Test
    void returnsCode2WhenAMandatoryOptionIsMissing() {
        int exitCode = new CommandLine(root, factory).execute("loan", "create", "--employee=1");
        assertThat(exitCode).isEqualTo(2);      // usage error, the one Picocli uses by default
    }
}

ConsoleTable.of(materials)
    .column("ISBN", m -> m.getIsbn().value())
    .column("TITLE", Material::getTitle, 45)
    .column("TYPE", m -> m.type().name())
    .numericColumn("FREE", m -> m.availableCopies())
    .withTotals()
    .print(output);

@Command(name = "return",
    description = "Records the return of a loan.",
    footerHeading = "%nExamples:%n",
    footer = {
        "  bibliotech loan return 42",
        "  bibliotech loan return 42 --date=2026-03-15",
        "  bibliotech loan return 42 --dry-run --format=json"
    })
@Component
public class LoanReturnCommand implements Callable<Integer> {

    private final ManageLoans manager;
    private final FineCalculator calculator;
    private final Output output;
    private final Clock clock;

    @Spec CommandLine.Model.CommandSpec spec;

    public LoanReturnCommand(ManageLoans manager, FineCalculator calculator,
                             Output output, Clock clock) {
        this.manager = manager;
        this.calculator = calculator;
        this.output = output;
        this.clock = clock;
    }

    @Parameters(index = "0", paramLabel = "<loanId>",
                description = "Identifier of the loan to return.")
    private Long loanId;

    @Option(names = "--date", description = "Return date (yyyy-MM-dd). Today by default.")
    private LocalDate date;

    @Option(names = "--dry-run",
            description = "Works out the fine without recording the return.")
    private boolean dryRun;

    @Override
    public Integer call() {
        LocalDate today = LocalDate.now(clock);
        LocalDate effectiveDate = (date != null) ? date : today;

        // Cross-field validation: ParameterException produces message + usage + code 2
        if (effectiveDate.isAfter(today)) {
            throw new CommandLine.ParameterException(spec.commandLine(),
                "--date (%s) cannot be later than today (%s)."
                    .formatted(effectiveDate, today));
        }

        Loan loan = manager.find(loanId)
                .orElseThrow(() -> new LoanNotFoundException(loanId));

        if (loan.getReturnDate().isPresent()) {
            // CliErrorHandler translates the exception into code 6 (CONFLICT)
            throw new LoanAlreadyReturnedException(loanId,
                    loan.getReturnDate().orElseThrow());
        }

        if (effectiveDate.isBefore(loan.getLoanDate())) {
            throw new CommandLine.ParameterException(spec.commandLine(),
                "--date (%s) is earlier than the loan date (%s)."
                    .formatted(effectiveDate, loan.getLoanDate()));
        }

        if (dryRun) {
            Money fine = calculator.calculate(loan, effectiveDate);
            output.writeReturn(new ReturnResult(
                    loan.getId(), loan.materialTitle(), loan.employeeName(),
                    effectiveDate, fine, true));
            output.warn("DRY RUN: nothing has been recorded.");
            return ExitCode.OK;
        }

        ReturnResult result = manager.returnItem(loanId, effectiveDate);
        output.writeReturn(result);

        if (result.fine().isPositive()) {
            output.success("Return recorded. Fine: %s (%d days late)."
                    .formatted(result.fine(), result.daysLate()));
        } else {
            output.success("Return recorded on time. No fine.");
        }
        return ExitCode.OK;
    }
}

public void writeReturn(ReturnResult r) {
    switch (format) {
        case TABLE -> {
            out.printf("%-14s %s%n", "Loan:", "#" + r.loanId());
            out.printf("%-14s %s%n", "Material:", r.materialTitle());
            out.printf("%-14s %s%n", "Employee:", r.employeeName());
            out.printf("%-14s %s%n", "Returned:", r.date());
            out.printf("%-14s %s%n", "Fine:",
                    r.fine().isPositive() ? red(r.fine().toString()) : green("no fine"));
        }
        case CSV -> {
            if (showDecoration()) out.println("id;material;employee;date;fine");
            out.printf("%d;%s;%s;%s;%s%n", r.loanId(), escape(r.materialTitle()),
                    escape(r.employeeName()), r.date(), r.fine().amount());
        }
        case JSON -> json(r);
    }
}

$ bibliotech loan return 42;                    echo $?   # 0
$ bibliotech loan return 9999;                  echo $?   # 5 (not found)
$ bibliotech loan return 42;                    echo $?   # 6 (already returned)
$ bibliotech loan return 42 --date=2099-01-01;  echo $?   # 2 (wrong usage)

@Command(name = "send",
    description = "Sends notices of an approaching due date to the employees affected.",
    footerHeading = "%nExit codes:%n",
    footer = {
        "  0  every notice was sent",
        "  3  there was no notice to send",
        "  4  some notices failed",
        "  7  the mail server is not responding"
    })
@Component
public class NoticesSendCommand implements Callable<Integer> {

    private final NoticeService notices;
    private final LoanRepository loans;
    private final Output output;
    private final CancellationManager cancellation;
    private final Clock clock;

    @Option(names = "--days-ahead", defaultValue = "3",
            description = "Notify about due dates N days away. Default: ${DEFAULT-VALUE}")
    private int daysAhead;

    @Option(names = "--from-stdin",
            description = "Reads employee identifiers from standard input, one per line.")
    private boolean fromStdin;

    @Option(names = "--dry-run", description = "Shows who would be notified, without sending anything.")
    private boolean dryRun;

    @Override
    public Integer call() throws IOException {
        List<Loan> target = selectLoans();

        if (target.isEmpty()) {
            output.info("There is no loan that requires a notice.");
            return ExitCode.NO_RESULTS;                  // 3: NOT an error
        }

        output.info("Preparing %d notices%s…".formatted(target.size(), dryRun ? " (DRY RUN)" : ""));

        var progress = new ProgressBar(target.size(), output);   // switches itself off with no terminal
        int sent = 0;
        List<SendFailure> failures = new ArrayList<>();

        for (Loan l : target) {
            if (cancellation.cancelled()) {
                progress.finish();
                output.warn("Cancelled. Sent %d of %d.".formatted(sent, target.size()));
                return ExitCode.INTERRUPTED;
            }
            try {
                if (dryRun) {
                    // The dry run's output IS the result: it goes to stdout
                    output.result("%s <%s> — \"%s\" is due on %s"
                            .formatted(l.employeeName(), l.employeeEmail(),
                                       l.materialTitle(), l.getDueDate()));
                } else {
                    notices.send(Notice.forDueDate(l));
                }
                sent++;
            } catch (GatewayUnavailableException e) {
                // A mail server that is down affects EVERYONE: there is no point carrying on
                progress.finish();
                throw e;                                  // the handler translates it into 7
            } catch (BiblioTechException e) {
                failures.add(new SendFailure(l.getId(), l.employeeEmail(), e.getMessage()));
            } finally {
                progress.advance();
            }
        }
        progress.finish();

        if (!failures.isEmpty()) {
            output.warn("%d notices failed:".formatted(failures.size()));
            failures.forEach(f -> output.warn("  loan #%d (%s): %s"
                    .formatted(f.loanId(), f.recipient(), f.reason())));
            output.info("Sent %d of %d.".formatted(sent, target.size()));
            return ExitCode.PARTIAL;                      // 4
        }

        output.success("Sent %d notices.".formatted(sent));
        return ExitCode.OK;
    }

    private List<Loan> selectLoans() throws IOException {
        LocalDate cutoff = LocalDate.now(clock).plusDays(daysAhead);

        if (!fromStdin) {
            return loans.activeDueBefore(cutoff);
        }

        List<Long> ids = readIdsFromStdin();
        if (ids.isEmpty()) {
            output.warn("No identifier was read from standard input.");
            return List.of();
        }
        output.detail("Filtering by %d employees read from stdin".formatted(ids.size()));
        return loans.activeDueBefore(cutoff).stream()
                .filter(l -> ids.contains(l.getEmployeeId()))
                .toList();
    }

    private List<Long> readIdsFromStdin() throws IOException {
        try (var reader = new BufferedReader(new InputStreamReader(System.in, UTF_8))) {
            return reader.lines()
                    .map(String::strip)
                    .filter(l -> !l.isEmpty() && !l.startsWith("#"))
                    .map(l -> {
                        try {
                            return Long.parseLong(l);
                        } catch (NumberFormatException e) {
                            output.warn("Ignoring the non-numeric line: '%s'".formatted(l));
                            return null;
                        }
                    })
                    .filter(Objects::nonNull)
                    .distinct()
                    .toList();
        }
    }
}

# Every due date in the next 3 days
bibliotech notices send

# Only the employees in the Architecture department
bibliotech employee list --department=Architecture --format=csv \
  | cut -d';' -f1 | tail -n +2 \
  | bibliotech notices send --from-stdin --days-ahead=7

# See who would be notified, without sending anything
bibliotech notices send --dry-run --format=json | jq -r '.[].email'

#!/usr/bin/env bash
# /opt/bibliotech/scripts/daily-notices.sh
# Run with: 0 8 * * * /opt/bibliotech/scripts/daily-notices.sh
set -uo pipefail                    # no -e: we want to handle the codes ourselves

LOG="/var/log/bibliotech/notices-$(date +%F).log"
MAX_ATTEMPTS=3

for attempt in $(seq 1 $MAX_ATTEMPTS); do
  # The result to the log; the diagnostics too, but separable just in case
  bibliotech notices send --days-ahead=3 --quiet >>"$LOG" 2>&1
  code=$?

  case $code in
    0) echo "$(date -Is) OK: notices sent" >>"$LOG"; exit 0 ;;
    3) echo "$(date -Is) Nothing to send today" >>"$LOG"; exit 0 ;;   # NOT a failure
    4) echo "$(date -Is) WARNING: partial send; check the log" >>"$LOG"
       mail -s "BiblioTech: partial notices" [email protected] <"$LOG"
       exit 0 ;;
    7) echo "$(date -Is) Mail unavailable; retry $attempt of $MAX_ATTEMPTS" >>"$LOG"
       sleep $((attempt * 120)) ;;                                    # 2, 4, 6 minutes
    *) echo "$(date -Is) Unrecoverable ERROR (code $code)" >>"$LOG"
       mail -s "BiblioTech: notice job failed" [email protected] <"$LOG"
       exit "$code" ;;
  esac
done

echo "$(date -Is) ERROR: retries exhausted" >>"$LOG"
mail -s "BiblioTech: mail down after 3 attempts" [email protected] <"$LOG"
exit 7

/**
 * A console table formatter, with automatic widths.
 * Usage:
 *   ConsoleTable.of(materials)
 *       .column("ISBN", m -> m.getIsbn().value())
 *       .column("TITLE", Material::getTitle, 45)
 *       .numericColumn("FREE", Material::availableCopies)
 *       .withTotals()
 *       .print(output);
 */
public class ConsoleTable<T> {

    private static final int DEFAULT_TERMINAL_WIDTH = 120;
    private static final String SEPARATOR = "  ";

    private final List<T> rows;
    private final List<Column<T>> columns = new ArrayList<>();
    private boolean totals = false;

    private ConsoleTable(List<T> rows) { this.rows = rows; }

    public static <T> ConsoleTable<T> of(List<T> rows) { return new ConsoleTable<>(rows); }

    // --- Column definition ---

    public ConsoleTable<T> column(String title, Function<T, String> extractor) {
        return column(title, extractor, Integer.MAX_VALUE);
    }

    public ConsoleTable<T> column(String title, Function<T, String> extractor, int maxWidth) {
        columns.add(new Column<>(title, extractor, Alignment.LEFT, maxWidth, null));
        return this;
    }

    public ConsoleTable<T> numericColumn(String title, ToLongFunction<T> extractor) {
        columns.add(new Column<>(title,
                t -> String.valueOf(extractor.applyAsLong(t)),
                Alignment.RIGHT, 15, extractor));
        return this;
    }

    public ConsoleTable<T> withTotals() { this.totals = true; return this; }

    // --- Printing ---

    public void print(Output output) {
        if (columns.isEmpty()) throw new IllegalStateException("Define at least one column");

        int[] widths = calculateWidths();
        fitToTerminal(widths);

        PrintStream out = output.out();

        if (output.showDecoration()) {
            out.println(row(widths, i -> columns.get(i).title()));
            out.println("-".repeat(totalWidth(widths)));
        }

        for (T item : rows) {
            out.println(row(widths, i -> value(columns.get(i), item, widths[i])));
        }

        if (totals && output.showDecoration()) {
            out.println("-".repeat(totalWidth(widths)));
            out.println(row(widths, this::columnTotal));
            out.printf("%d rows%n", rows.size());
        }
    }

    // --- Working out the widths ---

    private int[] calculateWidths() {
        int[] widths = new int[columns.size()];
        for (int i = 0; i < columns.size(); i++) {
            Column<T> c = columns.get(i);
            int contentWidth = rows.stream()
                    .map(c.extractor())
                    .mapToInt(String::length)
                    .max().orElse(0);
            // The width is the greater of title and content, capped by the maximum
            widths[i] = Math.min(c.maxWidth(), Math.max(c.title().length(), contentWidth));
        }
        return widths;
    }

    /**
     * If the table does not fit, proportionally shrinks the widest text
     * columns, keeping a minimum of 8 characters.
     */
    private void fitToTerminal(int[] widths) {
        int available = terminalWidth();
        int total = totalWidth(widths);
        if (total <= available) return;

        int excess = total - available;
        // Trim from largest to smallest until the excess is absorbed
        List<Integer> candidates = IntStream.range(0, widths.length)
                .boxed()
                .filter(i -> columns.get(i).alignment() == Alignment.LEFT)
                .sorted(Comparator.comparingInt((Integer i) -> widths[i]).reversed())
                .toList();

        for (int i : candidates) {
            if (excess <= 0) break;
            int trimmable = Math.max(0, widths[i] - 8);
            int trim = Math.min(trimmable, excess);
            widths[i] -= trim;
            excess -= trim;
        }
    }

    private int terminalWidth() {
        // COLUMNS is exported by the shell; if it is not there, use the default value
        String columns = System.getenv("COLUMNS");
        try {
            return columns != null ? Integer.parseInt(columns) : DEFAULT_TERMINAL_WIDTH;
        } catch (NumberFormatException e) {
            return DEFAULT_TERMINAL_WIDTH;
        }
    }

    private int totalWidth(int[] widths) {
        return Arrays.stream(widths).sum() + SEPARATOR.length() * (widths.length - 1);
    }

    // --- Cell formatting ---

    private String row(int[] widths, IntFunction<String> cell) {
        StringBuilder sb = new StringBuilder();
        for (int i = 0; i < widths.length; i++) {
            if (i > 0) sb.append(SEPARATOR);
            String text = truncate(cell.apply(i), widths[i]);
            sb.append(columns.get(i).alignment() == Alignment.RIGHT
                    ? " ".repeat(widths[i] - text.length()) + text
                    : text + " ".repeat(widths[i] - text.length()));
        }
        return sb.toString().stripTrailing();     // no trailing spaces: they are messy when copied
    }

    private String value(Column<T> c, T item, int width) {
        return truncate(c.extractor().apply(item), width);
    }

    private static String truncate(String text, int max) {
        if (text == null) return "";
        return text.length() <= max ? text : text.substring(0, Math.max(0, max - 1)) + "…";
    }

    private String columnTotal(int i) {
        Column<T> c = columns.get(i);
        if (c.adder() == null) return i == 0 ? "TOTAL" : "";
        long sum = rows.stream().mapToLong(c.adder()).sum();
        return String.valueOf(sum);
    }

    // --- Helper types ---

    private enum Alignment { LEFT, RIGHT }

    private record Column<T>(String title,
                             Function<T, String> extractor,
                             Alignment alignment,
                             int maxWidth,
                             ToLongFunction<T> adder) { }
}

ConsoleTable.of(materials)
    .column("ISBN", m -> m.getIsbn().value())
    .column("TITLE", Material::getTitle, 45)
    .column("TYPE", m -> m.type().name())
    .numericColumn("FREE", Material::availableCopies)
    .withTotals()
    .print(output);

ISBN            TITLE            TYPE  FREE
-------------------------------------------
978-0000000001  Effective Java   BOOK     2
978-0000000002  Design Patterns  BOOK     0
978-0000000003  Refactoring      BOOK     1
-------------------------------------------
TOTAL                                     3
3 rows