view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

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:

```perl
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](https://metacpan.org/pod/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](https://metacpan.org/pod/Mojo%3A%3AException), [Exception::Base](https://metacpan.org/pod/Exception%3A%3ABase),
[Exception::Class::Base](https://metacpan.org/pod/Exception%3A%3AClass%3A%3ABase) and [Class::Throwable](https://metacpan.org/pod/Class%3A%3AThrowable).

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](https://metacpan.org/pod/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.