view release on metacpan or  search on metacpan

lib/Devel/Examine/Subs.pm  view on Meta::CPAN

    $file

Optional, C<File::Temp> object, typically generated through a call to
C<File::Edit::Portable>'s C<tempfile()>.

On first call, a C<Temp::File> object must be sent in. On subsequent calls,
we'll return that object.

Returns: C<Temp::File> object if previously sent in, else returns C<undef>.


=head2 C<add_functionality>

WARNING!: This method is for development of this distribution only!

While writing new processors, set the processor type to a callback within the
local working file. When the code performs the actions you want it to, put a
comment line before the code with C<#<des>> and a line following the code with
C<#</des>>. DES will slurp in all of that code live-time, inject it into the
specified processor, and configure it for use. See
C<examples/write_new_engine.pl> for an example of creating a new 'engine'
processor.

Returns 1 on success.

Parameters:

=over 4

=item C<add_functionality>

Informs the system which type of processor to inject and configure. Permitted
values are 'pre_proc', 'post_proc' and 'engine'.

=item C<add_functionality_prod>

Set to a true value, will update the code in the actual installed Perl module
file, instead of a local copy.

=back





Optional parameters:

=over 4

=item C<copy>

Set it to a new file name which will be a copy of the specified file, and only
change the copy. Useful for verifying the changes took properly.

=back


=head2 C<pre_procs>, C<post_procs>, C<engines>

For development. Returns the list of the respective built-in callbacks.




=head1 PARAMETERS

There are various parameters that can be used to change the behaviour of the
application. Some are persistent across calls, and others aren't. You can
change or null any/all parameters in any call, but some should be set in the
C<new()> method (set it and forget it).

The following list are persistent parameters, which need to be manually
changed or nulled. Consider setting these in C<new()>.

=over 4

=item C<file>

State: Persistent

Default: None

The name of a file, directory or module name. Will convert module name to a
file name if the module is installed on the system. It'll C<require> the
module temporarily and then 'un'-C<require> it immediately after use.

If set in C<new()>, you can omit it from all subsequent method calls until you
want it changed. Once changed in a call, the updated value will remain
persistent until changed again.

=item C<backup>

State: Persistent

Default: Disabled

Set this to a true value to have a C<.bak> file copy created on all file reads.
The C<.bak> file will be created in the directory the script is run in.

=item C<extensions>

State: Persistent

Default: C<['*.pm', '*.pl')]>

By default, we load only C<*.pm> and C<*.pl> files. Use this parameter to load
different files. Only useful when a directory is passed in as opposed to a
file. This parameter is persistent until manually reset and should be set in
C<new()>.

Values: Array reference where each element is the names of files to find. Any wildcard or regex that are valid in L<File::Find::Rule's|http://search.cpan.org/~rclamp/File-Find-Rule-0.33/lib/File/Find/Rule.pm> are valid here. For example, C<[qw(*.pm *...


=item C<maxdepth>

When running in directory mode, how many levels deep do you want to traverse? Default is unlimited. Set to a positive integer to set.


=item C<cache>

lib/Devel/Examine/Subs.pm  view on Meta::CPAN

State: Transient

Default: Disabled

Set to 1 to activate, C<exit()>s after completion.

Print to STDOUT using Data::Dumper the structure of the data following the
respective phase. The C<core_dump> will print the state of the data, as well
as the current state of the entire DES object.

NOTE: The 'post_proc' phase is run in such a way that the filters can be
daisy-chained. Due to this reason, the value of C<post_proc_dump> works a
little differently. For example:

    post_proc => ['one', 'two'];

...will execute filter 'one' first, then filter 'two' with the data that came
out of filter 'one'. Simply set the value to the number that coincides with
the location of the filter. For instance, C<post_proc_dump =E<gt> 2;> will
dump the output from the second filter and likewise, C<1> will dump after the
first.

For C<cache_dump>, if it is set to one, it'll dump cache but the application
will continue. Set this parameter to an integer larger than one to have the
application C<exit> immediately after dumping the cache to STDOUT.


=item C<pre_proc_return>, C<post_proc_return>, C<engine_return>

State: Transient

Default: Disabled

Returns the structure of data immediately after being processed by the
respective phase. Useful for writing new 'phases'. (See "SEE ALSO" for
details).

NOTE: C<post_proc_return> does not behave like C<post_proc_dump>. It will
only return after all post_procs have executed.




=item C<config_dump>

State: Transient

Default: Disabled

Prints to C<STDOUT> with C<Data::Dumper> the current state of all loaded
configuration parameters.



=item C<pre_proc, post_proc, engine>

State: Transient

Default: undef

These are mainly used to set up the public methods with the proper callbacks
used by the C<run()> command.

C<engine> and C<pre_proc> take either a single string that contains a valid
built-in callback, or a single code reference of a custom callback.

C<post_proc> works a lot differently. These modules can be daisy-chained.
Like C<engine> and C<pre_proc>, you can send in a string or cref, or to chain,
send in an aref where each element is either a string or cref. The filters
will be executed based on their order in the array reference.


=back



=head1 REPOSITORY



L<https://github.com/stevieb9/devel-examine-subs>

=head1 BUILD REPORTS

CPAN Testers: L<http://matrix.cpantesters.org/?dist=Devel-Examine-Subs>

=head1 DEBUGGING

If C<Devel::Trace::Subs> is installed, you can configure stack tracing.

In your calling script, set C<$ENV{DES_TRACE} = 1>.

See C<perldoc Devel::Trace::Subs> for information on how to access the traces.

=head1 SEE ALSO

=over 4

=item C<perldoc Devel::Examine::Subs::Preprocessor>

Information related to the 'pre_proc' phase core modules.

=item C<perldoc Devel::Examine::Subs::Postprocessor>

Information related to the 'post_proc' phase core modules.

=item C<perldoc Devel::Examine::Subs::Engine>

Information related to the 'engine' phase core modules.

=back

=head1 AUTHOR

Steve Bertrand, C<< <steveb at cpan.org> >>

=head1 SUPPORT

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

    perldoc Devel::Examine::Subs