view release on metacpan or  search on metacpan

lib/Carp/Proxy.pm  view on Meta::CPAN

=head2 configuration

 Usage:
    <HashRef> fatal '*configuration*';

The C<'*configuration*'> Handler is unconventional in that no exception is
thrown.  Instead, a reference to an internal hash is returned to the
calling environment.  Any changes to the referenced hash affect all future
Proxy invocations.

Proxy configuration is established when a Proxy is created - either during
B<use()> or L<import()|/import>.  Configuration consists of attribute
=E<gt> parameter pairs that are supplied by the user.

    use Carp::Proxy ( warning => { banner_title => 'Warning',
                                   disposition  => 'warn'      });

In the above snippet, L<banner_title|/banner_title> and
L<disposition|/disposition>, are internally held in a
closure-based hash that persists across all invocations of the Proxy.  The
B<*configuration*> Handler causes the Proxy to return a reference to this
internal hash.

Here is an example of wanting to change Proxy behavior after Proxy
creation:

    #----- fatal() does NOT throw an exception here...
    my $config = fatal '*configuration*';
 
    $config->{ disposition } = \&GUI::as_dialog;

As alluded to above, we want our GUI program to use conventional STDERR
based messages during initialization, but once the GUI is up we want
future messages to go to a dialog widget.

=head1 PROPAGATION

The I<as_yaml> attribute controls stringification of the Proxy object.
In its normal state of false (0), I<as_yaml> produces the formatted
error message.  When true (1), I<as_yaml> instead produces a YAML Dump()
of the proxy object.

Newer versions of YAML do not bless reconstituted objects as a security
precaution, so if you want to propagate errors up from child processes
you will need to specifically allow it.

    # 'cmd' here throws a fatal() with as_yaml set to 1
    $output = qx{ cmd 2>&1 1>/dev/null };
 
    if ( $CHILD_ERROR ) {
 
        my $kids_proxy;
        {
            local $YAML::XS::LoadBlessed = 1;
            $kids_proxy = YAML::XS::Load( $output );
        }
        do_something( $kids_proxy )
    }


=head1 BUGS AND LIMITATIONS

Please report any bugs or feature requests to C<bug-carp-proxy at
rt.cpan.org>, or through the web interface at
L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Carp-Proxy>.  I will be
notified, and then you'll automatically be notified of progress on your
bug as I make changes.

=head1 DEPENDENCIES

Core dependencies (come with Perl)

 Config
 Cwd
 English
 overload
 Pod::Usage

External dependencies (install from CPAN)

 Moose
 Readonly
 Sub::Name
 YAML::XS

=head1 SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Carp::Proxy


You can also look for information at:

=over 4

=item * RT: CPAN's request tracker (report bugs here)

L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Carp-Proxy>

=item * AnnoCPAN: Annotated CPAN documentation

L<http://annocpan.org/dist/Carp-Proxy>

=item * CPAN Ratings

L<http://cpanratings.perl.org/d/Carp-Proxy>

=item * Search CPAN

L<http://search.cpan.org/dist/Carp-Proxy/>

=back


=head1 SEE ALSO

=over 4

=item perldoc L<perlvar>