NAME

Clean::Eval - Run code under eval without leaking $@ and get a rich error object back on failure.

DESCRIPTION

Perl's built-in eval is the standard way to trap exceptions, but it has two long-standing ergonomic problems:

• It modifies the global $@, which can be clobbered by destructors or other code running during stack unwind, leading to lost or corrupted error messages.
• The return value of eval can be ambiguous: a successful eval that legitimately returns a false value is indistinguishable from a failure unless you check $@.

Clean::Eval wraps eval in a way that avoids both problems. It localizes $@ so the caller's copy is never touched and always returns a blessed result object that is overloaded for boolean and string context. The object is true on success and false on failure regardless of what the wrapped code returned, so a single if check is enough to distinguish the two.

On success the block form also stashes the block's return value (taken in scalar context) in an out field on the object, so the typical pattern is:

if (my $ev = clean_eval { get_message() }) {
    $msg = $ev->out;
}
else {
    die $ev;        # stringifies to the trapped error
}

Both a block form (clean_eval { ... }) and a string form (clean_string_eval $code) are provided. The string form rewrites #line information so that any error reports the file and line of the caller, not an anonymous (eval N). The string form does not capture a return value - see "clean_string_eval".

SYNOPSIS

use Clean::Eval qw/clean_eval clean_string_eval last_error/;

# Block form - object is always returned; bool overload picks
# success vs failure; on success ->out holds the block's scalar
# return value.
my $msg;
if (my $ev = clean_eval { get_message() }) {
    $msg = $ev->out;
}
else {
    die $ev;        # stringifies to trapped error
}

# Or, branchless:
my $ev = clean_eval { risky() };
die "Failed: $ev\n  at $ev->{file} line $ev->{line}\n" unless $ev;
my $result = $ev->out;

# String form - same overloaded object, but no ->out is ever set
# (see "clean_string_eval" below). No need to add a trailing "; 1"
# - it is appended for you.
my $ev = clean_string_eval 'use SomeOptionalModule';
warn "Optional dep missing: $ev\n" unless $ev;

# Retrieve the most recent failure from anywhere
my $last = last_error();

EXPORTS

Nothing is exported by default. The three functions below may be imported individually using Importer-style syntax:

use Clean::Eval qw/clean_eval clean_string_eval last_error/;

• $ev = clean_eval { BLOCK }

  Run BLOCK under eval. Always returns a Clean::Eval result object (see "RESULT OBJECT"). $@ in the caller's scope is not touched.

  On success the block's return value is captured in scalar context and stored in the object's out field. Scalar context is forced because the object is a scalar-context-only carrier - capturing a list there would require API choices (arrayref? flatten?) that would surprise callers. If you need list-context results, assign to an outer my @list from inside the block:

    my @rows;
    my $ev = clean_eval { @rows = fetch_rows() };
    die $ev unless $ev;
  

  On failure the out key is not present on the object and the error, package, file, and line keys are populated instead.

  The prototype is (&), so the block form works without a leading sub.

• $ev = clean_string_eval $STRING

  Run $STRING as Perl code under eval. Always returns a Clean::Eval result object. $@ in the caller's scope is not touched.

  Unlike the block form, the string form never captures a return value. The out field is always absent on the result object, even on success. This is because the body of a string eval is not necessarily a value- producing expression: it might be defining a subroutine, opening a BEGIN/INIT/END block, declaring a package, loading a module via use, or otherwise producing something that has no meaningful "scalar return value" to record. Trying to capture and stash a result in those cases would just be misleading. If you need a value out of string eval'd code, write to an outer our package variable from inside the string, or use clean_eval { eval $string } and capture the result yourself.

  A #line directive is prepended to $STRING using the caller's filename and line number, so any error or warning produced by the eval'd code refers to the source location of the clean_string_eval call rather than to an anonymous eval string.

  A trailing ; 1 is also appended to $STRING, so you do not need to remember the usual eval "...; 1" success guard - success is recorded on the result object regardless of what the final statement in $STRING evaluates to. Including the ; 1 yourself is harmless.

  The prototype is ($), so a single scalar argument is taken.

• $err = last_error()

  Return the result object of the most recent failure produced by clean_eval or clean_string_eval anywhere in the program, or undef if no failure has been recorded yet. Successful calls do not reset this slot. Useful for code paths that discarded the result object or want to inspect a previous failure after the fact.

  Caveat: last_error is a global slot and is subject to the same class of bug that makes raw $@ fragile. If a DESTROY method (or anything else running during stack unwind) calls clean_eval or clean_string_eval and that inner call fails, it will overwrite the global and the error you actually cared about will be lost. last_error is a convenience, not a guarantee - the only robust way to inspect a particular failure is to capture the result object of clean_eval/clean_string_eval directly at the call site and keep it in a lexical of your own.

RESULT OBJECT

Both clean_eval and clean_string_eval always return a blessed hashref of class Clean::Eval. It overloads boolean and stringification context:

• Boolean context: true on success, false on failure. This is computed from the ok field, so a successful eval whose block legitimately returned a false value is still distinguishable from a failure.
• String context: the trapped error message on failure (the value $@ had inside the eval), or the empty string on success. This lets you write die $ev on a failure without having to dig out a field.

The object is a plain hashref with the following keys. Which keys are present depends on whether the eval succeeded:

• ok

  Always present. 1 on success, 0 on failure.

• out

  Present only on success, and only for the block form. Holds the block's return value, taken in scalar context. Absent (the key does not exists at all) on failure, and absent for clean_string_eval in all cases.

• error

  Present only on failure. The trapped error message (string or object, whatever was die'd).

• package

  The package the call was made from. Always present.

• file

  The file the call was made from. Always present.

• line

  The line the call was made from. Always present.

Convenience accessors ok, out, and error return the corresponding fields. to_string returns the same string the "" overload yields.

WHY NOT JUST USE eval?

You can, but you have to be careful. The idiomatic safe pattern looks like:

my $ok = eval { ...; 1 };
if (!$ok) {
    my $err = $@;
    ...
}

This is correct but verbose, and the ; 1 trailer is easy to forget. The $@ variable is also famously fragile: destructors that run during stack unwind can call eval themselves and reset it before you read it. Localizing $@ the way Clean::Eval does avoids that class of bug entirely.

PITFALLS

my $ev = clean_eval { ... } or die "$ev" does not work

This looks natural but contains a subtle bug. A lexical introduced by my is not in scope until the statement that declared it has finished, so the $ev referenced by die "$ev" is a different, package-global $ev (which is undef):

use Clean::Eval qw/clean_eval/;

# WRONG - $ev inside the die is the package global, not the lexical;
# the die fires (clean_eval returned a false-overloaded object) but
# with an empty message.
my $ev = clean_eval { die "foo" } or die "$ev";

Declare the lexical on its own statement first so it is in scope by the time the or die runs:

use Clean::Eval qw/clean_eval/;

# CORRECT - $ev refers to the lexical in both spots
my $ev;
$ev = clean_eval { die "foo" } or die "$ev";

Or split the check off into its own statement, which has the same effect:

use Clean::Eval qw/clean_eval/;

my $ev = clean_eval { die "foo" };
die "$ev" unless $ev;

The reliable rule: do not reference a my-declared variable in the same statement that declares it. Running with use warnings will diagnose this with "Name main::ev used only once: possible typo".

The block's return value is taken in scalar context

clean_eval stashes the block's return value in $ev->out, but it does so in scalar context. A block that returns a list will be collapsed to the last element (or to the list count, depending on the expression):

use Clean::Eval qw/clean_eval/;

my $ev = clean_eval { (1, 2, 3) };
# $ev->out is 3, not [1, 2, 3]

If you need a list result, write to an outer lexical from inside the block:

my @rows;
my $ev = clean_eval { @rows = fetch_rows() };
die $ev unless $ev;
# use @rows here

Scalar context is forced deliberately - the out field is a single scalar slot, and silently picking a list-handling convention would surprise callers.

clean_string_eval never sets out

The string form never records a return value, even on success. A string eval may be defining subs, opening BEGIN/END blocks, loading modules, or otherwise doing things with no meaningful scalar result. If you need a value back from a string eval, write to an our package variable from inside the string, or wrap a real eval $str inside a clean_eval block and capture from there.

clean_string_eval does not see the caller's lexicals

With a raw eval $string, the eval'd code can see any my variables in the surrounding scope. clean_string_eval cannot: the string is eval'd inside this module, so the caller's lexicals are out of reach. Only package globals are visible.

use Clean::Eval qw/clean_string_eval/;

my $x = 42;
my $ret = clean_string_eval 'print $x';
# $ret is an error: "Global symbol $x requires explicit package name"
# (or, without strict, $x is just an unrelated undef global)

our $y = 42;
clean_string_eval 'print $y';   # prints 42 - $y is a package global

If you need to feed values in, pass them through globals you control or through the environment, or build a closure and use clean_eval with a block instead.

return inside the block returns from the block, not the caller

The block passed to clean_eval is an anonymous subroutine. A return inside it returns from that anonymous subroutine - not from the enclosing named sub - and clean_eval still gets control back and returns 1 for success.

sub do_work {
    my $ok = clean_eval {
        return if $skip;     # returns from the block only
        risky_thing();
    };
    return 0 unless $ok;
    ...
}

This matches the behavior of plain eval { ... }.

Cannot pass a coderef variable with block syntax

The (&) prototype makes clean_eval parse a literal block; it will not accept a coderef in scalar variable form:

my $cref = sub { die "foo" };
clean_eval $cref;          # syntax error / wrong parse

Workarounds:

clean_eval(\&named_sub);   # named sub via \&
clean_eval { $cref->() };  # wrap in a literal block
&Clean::Eval::clean_eval($cref);   # bypass the prototype

SEE ALSO

Try::Tiny, Syntax::Keyword::Try, Feature::Compat::Try.

SOURCE

The source code repository for Clean-Eval can be found at https://github.com/exodist/Clean-Eval/.

MAINTAINERS

• Chad Granum exodist@cpan.org

AUTHORS

• Chad Granum exodist@cpan.org

COPYRIGHT

Copyright 2026 Chad Granum exodist7@gmail.com.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://dev.perl.org/licenses/