### ----------------------------------------------------
### -- Carp
### -- Licenses: Artistic-2.0
### -- Authors: 
### -- File: README.md
### ----------------------------------------------------
![Carp for Raku](docs/logo.png)

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<Carp> 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<carp>.  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'`.

```raku
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.

```raku
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

- **`block`**
Because `carp` and `croak` provide a single line, it makes more sense to identify the sub or
method where the error happened, as otherwise reporting something as occurring in an unnamed
block isn’t very helpful.  So instead, the original line of the error is noted, but reported
as occurring inside of the most immediate sub/method.  The same behavior exists for `cuckle`
and `confess`, but after their *first* line of output in the trace, every block is reported.

- **`ofun`**
The names of the routines were inherited from Perl’s Carp module.  Since Raku can handle
Unicode no problem, there’s nothing wrong with a little bit of **O**(*fun*), right?  Enable
this, and instead of seeing the out "Croak:", you'll get a little frog saying it instead.
No other functionality is changed:

## Examples

```raku
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.

  - Creating settings at scope level (currently settings are global)
  - Formatter options
  - Excluded packages, either generally (like in Perl) or in each call.
  - Adjust default frames to skip (for example, using carp in a signatuers where clause results in the error unusefully being reported as from the ACCEPTS sub)
  - Verbose option (make croak act like confess, and carp like cluck)
  - Return proper values for the `.backtrace` method (creating a modified Backtrace isn't presently working well).
  - Implement warnings proper: throwing a CX::Warn currently dies, so `note` is used in the meantime.

# 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](https://www.pxfuel.com/en/free-photo-xsgne) licensed under
[CC-0](https://creativecommons.org/publicdomain/zero/1.0/).


