/ 
App-karr-0.500
/ App::karr::Role::ExitCodes

NAME

App::karr::Role::ExitCodes - Normalize MooX::Options option-parse errors to exit code 2 (ADR 0002)

VERSION

version 0.500

DESCRIPTION

Part of karr's exit-code contract (ADR 0002): 0 success, 1 runtime failure, 2 usage error.

MooX::Options handles an option-parse failure -- an unknown option, an invalid option value, or a missing required option -- by printing a diagnostic and then calling $class->options_usage($code) with a positive $code, which exits that code. Historically that code was 1, which collided with genuine runtime failures. Those are usage errors, so this role wraps options_usage to force any positive (error) code to 2.

Help requests (-h, --help, --usage) reach options_usage with a code of 0 (or undef), so they are left untouched: they still print to STDOUT and exit 0.

The complementary half of the contract -- catching the uncaught dies raised by command bodies and classifying them into runtime (1) versus usage (2) -- lives in the central handler in bin/karr. That handler classifies by a stable leading marker on the message, so a command that wants to reject an invalid invocation itself calls usage_error, which emits the generic marker. The root command's own option-parse errors go through its _print_help override instead of this role, and that override applies the same positive-to-2 remap.

usage_error

$self->usage_error("--last must be 1 or greater (got 0)");

Dies with a message carrying the Usage error: marker that bin/karr classifies as a usage error, so the process exits 2.

This is for misuse that MooX::Options cannot catch on its own: an option value that parses but is out of range, a mutually exclusive combination of flags, an argument list that is syntactically fine but semantically empty. Anything MooX::Options can catch -- an unknown option, a value that does not fit the declared format -- already exits 2 through the options_usage wrapper above and must not be re-checked here.

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/karr/issues.

IRC

Join #langertha on irc.perl.org or message Getty directly.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <getty@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.