Raku Land

Carp

github:alabamenhu

Carp for Raku

Carp is a module that lets you identify errors from the caller side, rather than from within callee (this means if you call foo inside of bar, and foo carps, the error will appear as coming from the line where foo was called, rather than from inside of foo. This can be useful when writing modules to identify the error as resulting from something that happened outside of the sub where it is being called. It is modeled after Perl’s C module, although it doesn’t quite (yet) support all of the same features. Additional options will be enabled in the future.

Usage

By default, Carp only imports a single routine, C. You can add the others in with the named arguments :cluck, :croak, :confess, or for ease, you can use :all. There are two options that can be specified with positional parameters, 'block' and 'ofun'.

use Carp;                    # imports only carp
use Carp :cluck;             # imports carp and cluck
use Carp :croak, :confess;   # imports carp, croak, and confess
use Carp :X;                 # imports exceptions (useful in CATCH blocks)
use Carp :all;               # imports carp, cluck, croak, and confess
use Carp 'block';            # enable block-level status
use Carp 'ofun';             # use -Ofun optimization
use Carp :all, <block ofun>; # import/enable everything

To use, just call the routine, optionally with a message.

use Carp;
carp;   # output: │Carped: something's wrong
        #         │  in block <foo> at <file> line <line>
        # (the values in <> will have useful information)

carp "foo";   # output: │foo
              #         │  in block <foo> at <file> line <line>

Differences

The following table is a quick reference guide on the meaning:

            ┏━━━━━━━━━━┯━━━━━━━━━━━┓
            ┃  Warns   │    Dies   ┃
┏━━━━━━━━━━━╋━━━━━━━━━━┿━━━━━━━━━━━┫
┃ No trace  ┃   carp   │   croak   ┃
┠───────────╂──────────┼───────────┨
┃ Backtrace ┃   cluck  │  confess  ┃
┗━━━━━━━━━━━┻━━━━━━━━━━┷━━━━━━━━━━━┛

carp and cluck will only warn (CX-Warn), and normally not interrupt your program flow. croak and confess will die, and must be manually resumed if recovery is possible. carp and croak will only output a single indicating where the issue occurred. cluck and confess will output a full backtrace.

Options

Examples

use Carp :all;

sub xyz { confess "Confessing in XYX" }

sub bar {
  carp "carping inside bar";
  cluck "clucking inside bar";
  CATCH {
    $*ERR.say: "===SORRY!===";
    $*ERR.say: .message;
    $*ERR.say: "===RESUMING!===";
    .resume;
  }
  croak  "Croaking inside bar";
  xyz;
}

sub foo {
  carp "Carping inside foo";
  bar;
}

foo;

The output of this is (with default options)

Carping inside foo
  in block <unit> at 00-sanity.t line 19
carping inside bar
  in sub foo at 00-sanity.t line 6
clucking inside bar
  in sub foo at 00-sanity.t line 7
  in sub foo at 00-sanity.t line 20
  in block <unit> at 00-sanity.t line 23
===SORRY!===
Croaking inside bar
  in sub foo at 00-sanity.t line 14
===RESUMING!===
===SORRY!===
Confessed:
  in sub bar at 00-sanity.t line 3
  in sub foo at 00-sanity.t line 20
  in block <unit> at 00-sanity.t line 23
===RESUMING!===

With :ofun, we get a funner (but equally useful) output:

🐟 . o O ( Carping inside foo )
  in block <unit> at 00-sanity.t line 19
🐟 . o O ( carping inside bar )
  in sub foo at 00-sanity.t line 6
🐔 . o O ( clucking inside bar )
  in sub foo at 00-sanity.t line 7
  in block <unit> at 00-sanity.t line 23
===SORRY!===
🐸 . o O ( Croaking inside bar )
  in sub foo at 00-sanity.t line 14
===RESUMING!===
===SORRY!===
🙏 . o O ( confession )
  in sub bar at 00-sanity.t line 3
  in sub foo at 00-sanity.t line 20
  in block <unit> at 00-sanity.t line 23
===RESUMING!===

To do

Carp in Perl has quite a few options that could be implemented, and then some.

Licenses and Acknowledgements

All code is and documentation is licensed under the Artistic License 2.0, included with the module.

The original Carp was created by Larry Wall and Andrew Main (Zefram). Because of differences between Perl and Raku, no code was ported directly.

The logo.png was created by me (and licensed under the Artistic License 2.0), based on an image of a fish licensed under CC-0.