/ 
App-karr-0.500
/ App::karr::Error

NAME

App::karr::Error - Turn internal errors into one clean user-facing line

VERSION

version 0.500

SYNOPSIS

use App::karr::Error qw( user_error clean_error );

eval { $dir->mkpath; 1 }
  or user_error( "Could not create $dir: ", clean_error($@) );

DESCRIPTION

karr's errors are read by humans and by agents scripting the CLI, so a user-facing message is one line of prose and nothing else. Two things kept breaking that:

  • croak appends " at Some/Module.pm line 42." even when the message already ends in a newline -- the trailing-newline convention that die honours does not apply to Carp. Every croak "...\n" in a command path therefore leaks a module path and a line number at the user.

  • Exceptions raised underneath karr (Path::Tiny, libgit2, a captured git stderr) carry the same call-site suffix plus, often, several more lines of backend chatter.

user_error raises the first kind and clean_error reduces the second kind to something fit to embed in the first. Keep croak for programming errors -- a wrong argument to an internal method -- where the call site is the point.

SEE ALSO

karr, App::karr, App::karr::Git

clean_error

my $line = clean_error($@);

Reduces a caught exception to a single line of prose: drops the at FILE line N. call site, keeps only the first line, and trims trailing whitespace. Returns 'unknown error' when nothing is left. Accepts a plain string or an exception object (Git::Libgit2::Error-style objects are read through ->message).

user_error

user_error("Task $id not found");
user_error( "Could not install skill for $agent: ", clean_error($@) );

Raises a user-facing error whose message reaches STDERR exactly as written, with no module path or line number appended. Parts are concatenated, undef parts are dropped, and trailing whitespace is normalised to the single terminating newline. Never returns.

is_usage_error

exit( is_usage_error($@) ? 2 : 1 );

True when an exception is one of karr's usage errors -- "you called this wrong" rather than "the operation failed" -- decided by the stable leading markers listed in bin/karr. Accepts a plain string or an exception object; a new usage-error die must start with one of those markers, and usage_error in App::karr::Role::ExitCodes is the generic way to emit one.

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.