view release on metacpan or  search on metacpan

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

I<$content> is expected to be a string.  If I<$content> is the empty
string then no Section is generated and an empty string is returned.

I<$title> is converted into a Section title string using
L<header()|/header>.

I<$content> is split into lines on newline ("\n") characters for
processing.  Trailing whitespace is removed.  Embedded tabs are converted
to the equivalent number of spaces assuming eight character boundarys.
Indentation corresponding to the sum of
L<header_indent|/header_indent> and
L<body_indent|/body_indent> is added to the beginning of each
line.  Lines are joined with platform-appropriate line termination.

Trailing whitespace is removed, the section-title is prepended and a
single blank line is added to the end.

=head2 header

 Usage:
    <String> $cp->header( $title );

B<header()> produces an introductory line for a Section of paragraphs.
The line is indented from the left margin by
L<header_indent|/header_indent> spaces.  The line is formed
using the following template:

    <indent>*** <$title> ***

The intent is to provide an introductory heading for Section paragraphs.

    *** Description ***
      The database server is refusing connections.

If I<$title> is undef then the L<section_title|/section_title>
attribute is used in its place.  Passing an empty string (C<''>) for
I<title> causes B<header()> to omit Header generation.  In this case an
empty string is returned.

B<header()> is called by the Section creating methods
L<filled_section()|/filled_section> and
L<fixed_section()|/fixed_section>.

Subclass B<Carp::Proxy> and override B<header()> for a different look.

=head2 identifier_presentation

 Usage:
    <String> $class->identifier_presentation( $name );

The Banner reads better when words in the
L<handler_name|/handler_name> are separated by spaces rather
than underscores (C<_>).  Likewise with camelCasedIdentifiers.

Underscores are replaced by single spaces everywhere they occur.  Spaces
are inserted everywhere character-case changes from lower to upper, and
upper-case characters are folded to lower-case.  The following are example
conversions:

    'no_user_credentials'  => 'no user credentials'
    'nonexistentRecord'    => 'nonexistent record'

Sub-class B<Carp::Proxy> and override B<identifier_presentation()> if
you want a different convention.

=head2 import

 Usage:
    <void> $class->import( <%attrs_by_proxy>);

B<import()> accepts specifications for Proxy construction.  Specifications
take the form of a proxyname and a hashref of attribute initializations.

    proxyname1 => {
                   attributeA => initial_valueA,
                   attributeB => initial_valueB,
                   ...
                  }

Any number of proxyname, hashref pairs may be specified; a proxy subroutine
will be constructed for each pair.

If there is only one argument it is taken to be a proxyname introducing an
empty hashref.  If there are no arguments then it is assumed that the
builder-specified default for the L<proxy_name|/proxy_name> attribute
(C<'fatal'>), should be used for the proxyname and an empty hashref used for
the attribute initializations.

B<import()> probes the callstack to determine the package and filename of
the user code that called B<import()>.  B<import()> uses these values to create
a hash containing the attributes L<proxy_filename|/proxy_filename>,
L<proxy_name|/proxy_name> L<proxy_package|/proxy_package> and
L<fq_proxy_name|/fq_proxy_name>.  Any supplied attributes are added to the
hash.  The builtin handler L<*configuration*|/configuration> returns a
reference to this hash.

=head2 list_handler_packages

 Usage:
    <list> $cp->list_handler_packages();

B<list_handler_packages()> is sugar that dereferences the
L<handler_pkgs|/handler_pkgs> attribute (an ArrayRef) and
returns the contents.

=head2 list_sections

 Usage:
    <list> $cp->list_sections();

The L<sections|/sections> attribute is an ArrayRef.
B<list_sections()> is sugar to return all the elements of
L<sections|/sections>.

=head2 new

 Usage:
    <Carp::Proxy object> $class->new
        ( arg            => harvested $_,
          eval_error     => harvested $@,