/ 
App-karr-0.600
/ App::karr::Dispatch

NAME

App::karr::Dispatch - The one dispatch path shared by bin/karr and the in-process test runner

VERSION

version 0.600

SYNOPSIS

use App::karr::Dispatch qw( dispatch );
dispatch(@ARGV);

DESCRIPTION

Everything that sits between a program's start and App::karr->new_with_cmd lived inline in bin/karr: the character/octet boundary setup, the record of the caller's own argv, the two argv rewrites (empty-argument refusal and dashed-option normalisation), and the central handler that turns an uncaught die into the exit-code contract (ADR 0002). This module is that code, moved out whole so the karr executable and the in-process test runner (t/lib/TestKarr.pm) share one dispatch path rather than two copies that drift.

"dispatch" does exactly what bin/karr used to do inline. bin/karr is now a thin wrapper that calls it (and keeps the END block that flushes App::karr::SyncGuard, which is a process-lifecycle concern -- see there).

EMBEDDING

An embedding host may run "dispatch" many times in one interpreter -- the in-process test runner does, to skip ~0.3s of Perl startup per karr call. Such a host installs, in a BEGIN block before App::karr is compiled, an override of CORE::GLOBAL::exit that raises an exception instead of tearing the whole interpreter down. karr reaches exit from three places -- this module's handler, App::karr::Role::ExitCodes, and "_print_help" in App::karr -- and the override catches all three.

So that "dispatch"'s own handler does not mistake such an exit-signal for a command that died, it re-raises any caught exception that answers true to a __karr_dispatch_exit method, leaving it for whoever installed the override. Nothing in karr's own code blesses such an object, so under bin/karr -- which installs no override and lets exit exit -- this never fires and the handler behaves exactly as it always did.

dispatch

dispatch(@ARGV);

Runs one karr invocation: sets up the character/octet boundary, records the caller's argv, applies the empty-argument (#243) and dashed-option (#256) rewrites, and calls App::karr->new_with_cmd inside the central exit-code handler (ADR 0002). Operates on a localised @ARGV. Returns nothing on success; on failure it prints the message to STDERR and exits 1 or 2 -- which, under an embedding host that overrides exit (see "EMBEDDING"), becomes the host's exit-signal instead.

SEE ALSO

karr, App::karr, App::karr::Error, App::karr::Encoding, App::karr::SyncGuard

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, licensed under:

The Artistic License 2.0 (GPL Compatible)