view release on metacpan or  search on metacpan

README  view on Meta::CPAN

      1   use v5.36;
      2
      3   sub test {
      4
      5=>   my $a=1/0;
      6   }
      7
      8
      9   test;
      Illegal division by zero at examples/synopsis2.pl 5

          examples/synopsis2.pl
          4
          5     my $a=1/0;
          6   }
          7
          8
          9=> test;
      Illegal division by zero at examples/synopsis2.pl 5

  In Program
    Use at runtime to supplement exception handling without signal handler
    modification:

      use Error::Show;

      #an die caught in a try/eval triggers an exception

      # No argument uses $@ as error
      #
      eval { exceptional_code };
      say STDERR context if $@;


      # or a single exception argument of your choosing
      #
      use v5.36;
      try { 
        exceptional_code
      }
      catch($e) {
        say STDERR context $e;
      }

      # Show context down a stack

      try {

        Some_execption_class->throw("Bad things");

      }
      catch($e){
        say STDERR context $e;
      }

DESCRIPTION
    This module provides three tools/modes to help locate and diagnose
    errors in your Perl programs.

  Command Line
    From the command line this module transparently executes your
    syntactically correct program. No code changes are required. However in
    the case of syntax errors (or warnings if desired), it extracts context
    (lines of code) surrounding them. The lines are prefixed with numbers
    and the nicely formatted context is dumped on STDERR for you to see the
    error or your ways.

    The resulting output is optionally filtered seamlessly through the
    splain program (see diagnostics), giving more information on why the
    reported syntax errors and warnings might have occurred.

  In Program Exception Context
    From within a program, this module can be used to give formatted code
    context around the source of an exception and the context of each of the
    stack frames captured when the exception was raised.

    It supports Perl string exceptions and warnings directly and also
    provides the ability to integrate third party CPAN exception objects and
    traces with minimal effort. Please see examples in this document or in
    the examples directory of the distribution showing use with
    Mojo::Exception, Exception::Base, Exception::Class::Base and
    Class::Throwable.

    From "v0.5.0" a "throw" routine is exported which, generates a very
    basic exception object, with stack frame capture, in case using an
    larger exception object/class is unneeded

  String evals with Execption/Syntax Error Context
    From "v0.5.0" the "streval" subroutine has been added to allow context
    information to be generated for errors originating from code dynamically
    created from string evaluations.

Changes and Options
    A handful of options are available for basic configuration of how many
    lines of code to print before and after the error line, indenting of
    stack trace context, etc.

    v0.5.0 Has alot of changes which might break compatibility. THe up side
    is the codes is simpler, has less errors, and easier to use. This is
    especial the case for third party exceptions objects. It also gives the
    intended purpose of handling errors and exceptions from string evals
    like any other.

    That being said, an earlier version might need to be used if you want
    the use the $@ variable implicitly in a call to "context". This
    subroutine now requires an explicated error argument

    Sub routines "context", "throw" and "streval" are exported by default.

    From v0.3.0: "context" subroutine is now exported by default. To prevent
    this, import with an empty list, ie "use Error::Show ()".

    "From v0.2.0:", Added 'advanced string eval' support has been added for
    better context reporting of dynamically generated code.

USAGE
  Command Line Usage (Syntax check and Exception Catching)
            perl -MError::Show  [options] file.pl

    When included in a command line switch to Perl, "-MError::Show" syntax
    checks the input program. If the syntax is OK, normal execution
    continues in a transparent fashion. Otherwise, detailed code context
    surrounding the source of the error is generated and printed on STDERR.

    From v0.4.0 a global __DIE__ handler is also installed, which will catch
    any stray exceptions during execution and present a line numbered
    summary stack trace. Programs a free to overload this handler. However
    the features of this module will be lost.

    NOTE: It is important that it's the first "-M" switch for this module to
    operate correctly and to prevent any incompatibilities withe global
    signal handlers.

    If the -c flag is specified, only a syntax check will be performed,
    mimicking normal Perl behaviour.

    Additional @INC directories using the -I switch are supported as are
    additional modules via the -M switch.

   CLI Usage Options
    The following options can be used in isolation or together:

   clean
    If you prefer just the code context without the Perl error, add the
    clean option:

      perl -MError::Show=clean file.pl

   warn
    This options enables processing of warnings as well as errors.

      perl -MError::Show=warn file.pl

   splain
    Runs the output through the splain program (see diagnostics), giving
    probable reasons behind the error or warning

      perl -MError::Show=splain file.pl

   no_handler (from v0.4.0)
      perl -MError::Show=no_handler file.pl

    Prevents the global DIE handler from being installed.

   Return code
    When in check only mode (-c), the main process is exited, just has Perl
    normally would have done. The return code is a replica of what Perl
    would have reported for success/failure of a syntax check.

  In Program (Exception) Usage
    Simply bring Error::Show into your program with a use statement:

      use Error::Show;

    It provides a single subroutine for processing errors and exceptions.

   Error::Show::context
      my $context=Error::Show::context $error , options_pairs, ...;

    Takes an error string, or exception object $error and extracts the code
    surrounding the source of the error. The code lines are prefixed with
    line numbers and the error line marked with a fat arrow.