txt: ## dist_github-alabamenhu-Carp.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 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
  
  * **`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
  
  ```
  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/).
  