The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
App-SimpleScan-3.01
River stage one • 6 direct dependents • 6 total dependents
++
/ App::SimpleScan

NAME

App::SimpleScan - simple_scan's core code

VERSION

This document describes App::SimpleScan version 0.0.1

SYNOPSIS

    use App::SimpleScan;
    my $app = new App::SimpleScan;
    $app->go;

DESCRIPTION

App::SimpleScan allows us to package the core of simple_scan as a class; most importantly, this allows us to use Module::Pluggable to write extensions to this application without directly modifying this module or this simple_scan application.

IMPORTANT NOTE

The interfaces to this module are still evolving; plugin developers should monitor CPAN and look for new versions of this module. Henceforth, any change to the externals of this module will be denoted by a full version increase (e.g., from 0.34 to 1.00).

INTERFACE

Class methods

new

Creates a new instance of the application. Also invokes all of the basic setup so that when go is called, all of the plugins are available and all callbacks are in place.

Instance methods

Execution methods

go

Executes the application. Calls the subsidiary methods to read input, parse it, do substitutions, and transform it into code; loads the plugins and any code filters which they wish to install.

After the code is created, it consults the command-line switches and runs the generated program, prints it, or both.

create_tests

Transforms the input into code, and finalizes them, returning the actual test code (if any) to its caller.

transform_test_specs

Does all the work of transforming test specs into code, including processing substitutions, test specs, and pragmas, and handling substitutions.

finalize_tests

Adds all of the Perl modules required to run the tests to the test code generated by this module. This includes any modules specified by plugins via the plugin's test_modules class method.

execute

Actually run the generated test code. Currently just eval's the generated code.

Options methods

parse_command_line

Parses the command line and sets the corresponding fields in the App::SimpleScan object. See the section for more information.

handle_options

This method initializes your App::SimpleScan object. It installs the standard options (--run, --generate, and --warn), installs any options defined by plugins, and then calls parse_command_line to actually parse the command line and set the options.

install_options(option => receiving_variable, "method_name")

Plugin method - optional.

Installs an entry into the options description passed to GeOptions when parse_command_line is called. This automatically creates an accessor for the option. The option description(s) should conform to the requirements of GetOpt::Long.

You may specify as many option descriptions as you like in a single call. Remember that your option definitions will cause a new method to be created for each option; be careful not to accidentally override a pre-existing method ... unless you want to do that, for whatever reason.

app_defaults

Set up the default assumptions for the application. Simply turns run on if neither run nor generate is specified.

Pragma methods

install_pragma_plugins

This installs the standard pragmas (cache, nocache, and agent). Checks each plugin for a pragmas method and calls it to get the pragmas to be installed. In addition, if any pragmas are found, calls the corresponding plugin's init method if it exists.

pragma

Provides access to pragma-processing code. Useful in plugins to get to the pragmas installed for the plugin concerned.

Input/output methods

next_line

Reads the next line of input, handling the possibility that a plugin or substitution processing has stacked lines on the input queue to be read and processed (or perhaps reprocessed).

expand_backticked

Core and plugin method - a useful line-parsing utility.

Expands single-quoted, double-quoted, and backticked items in a text string as follows:

  • single-quoted: remove the quotes and use the string as-is.

  • double-quoted: eval() the string in the current context and embed the result.

  • backquoted: evaluate the string as a shell command and embed the output.

queue_lines

Queues one or more lines of input ahead of the current "next line".

If no lines have been queued yet, simply adds the lines to the input queue. If there are existing lines in the input queue, lines passed to this routine are queued ahead of those lines, like this:

  # Input queue = ()
  # $app->queue_lines("save this")
  #
  # Input queue now = ("save this")
  # $app->queue_lines("this one", "another")
  #
  # input queue now = ("this one", "another", "save this")

This is done so that if a pragma queues lines which are other pragmas, these get processed before any other pending input does.

set_current_spec

Save the object passed as the current test spec. If no argument is passed, deletes the current test spec object.

get_current_spec

Plugin method.

Retrieve the current test spec. Can be used to extract data from the parsed test spec.

last_line

Plugin and core method.

Current input line setter/getter. Can be used by plugins to look at the current line.

stack_code

Plugin and core method.

Adds code to the final output without incrementing the number of tests. Does not go through code filters, and does not increment the test count.

stack_test

Adds code to the final output and bumps the test count by one. The code passes through any plugin code filters.

tests

Accessor that stores the test code generated during the run.

EXTENDING SIMPLESCAN

Adding new command-line options

Plugins can add new command-line options by defining an options class method which returns a list of parameter/variable pairs, like those used to define options with Getopt::Long.

App::SimpleScan will check for the options method in your plugin when it is loaded, and call it to install your options automatically.

Adding new pragmas

Plugins can install new pragmas by implementing a pragmas class method. This method should return a list of array references, with each array reference containing a pragma name and a code reference which will implement the pragma.

The actual pragma implementation will, when called by transform_test_specs, receive a reference to the App::SimpleScan object and the arguments to the pragma (from the pragma line in the input) as a string of text. It is up to the pragma to parse the string; the use of expand_backticked is recommended for pragmas which take a variable number of arguments, and wish to adhere to the same syntax that standard substitutions use.

PLUGIN SUMMARY

Standard plugin methods that App::SimpleScan will look for; none of these is required, though you should choose to implement the ones that you actually need.

Basic callbacks

init

The init class method is called by App:SimpleScan when the plugin class is loaded; the App::SimpleScan object is suppled to allow the plugin to alter or add to the contents of the object. This allows plugins to export methods to the base class, or to add instance variables dynamically.

Note that the class passed in to this method is the class of the plugin, not of the caller (App::SimpleScan or a derived class). You should use caller() if you wish to export subroutines into the package corresponding to the base class object.

pragmas

Defines any pragmas that this plugin implements. Returns a list of names and subroutine references. These will be called with a reference to the App::SimpleScan object.

filters

Defines any code filters that this plugin wants to add to the output filter queue. These methods are called with a copy of the App::SimpleScan object and an array of code that is about to be stacked. The filter should return an array containing either the unaltered code, or the code with any changes the plugin sees fit to make.

If your filter wants to stack tests, it should call stack_code and increment the test count itself (by a call to test_count); trying to use stack_test in a filter will cause it to be called again and again in an infinite recursive loop.

test_modules

If your plugin generates code that requires other Perl modules, its test_modules class method should return an array of the names of these modules.

options

Defines options to be added to the command-line options. You should return an array of items that would be suitable for passing to Getopt::Long, which is what we'll do with them.

validate_options

Validate your options. You can access any of the variables you passed to options; these will be initialized with whatever values Getopt::Long got from the command line. You should try to ignore invalid values and choose defaults for missing items if possible; if not, you should die with an appropriate message.

Methods to alter the input stream

next_line

If a plugin wishes to read the input stream for its own purposes, it may do so by using next_line. This returns either a string or undef (at end of file).

stack_input

Adds lines to the input queue ahead of the next line to be read from whatever source is supplying them. This allows your plugin to process a line into multiple lines "in place".

Methods for outputting code

Your pragma will probably use one of the following methods to output code:

stack_code

A call to stack_code will cause the string passed back to be emitted immediately into the code stream. The test count will remain at its current value.

stack_test

stack_test will immediately emit the code supplied as its argument, and will increment the test count by one. You should use multiple calls to stack_test if you need to stack more than one test.

Code passed to stack_test will go through all of the filters in the output filter queue; be careful to not call stack_test in an output filter, as this will cause a recursive loop that will run you out of memory.

Informational methods

get_current_spec

Returns the current App::SimpleScan::TestSpec object, if there is one. If code in your plugin is called when either we haven't read any lines yet, or the last line read was a pragma, there won't be any "current test spec".

last_line

Returns the actual text of the previous line read. Plugin code that does not specifically involve the current line (like output filters) may wish to look at the current line.

DIAGNOSTICS

None as yet.

CONFIGURATION AND ENVIRONMENT

App::SimpleScan requires no configuration files or environment variables.

DEPENDENCIES

Module::Pluggable and WWW::Mechanize::Pluggable.

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests to bug-app-simplescan@rt.cpan.org, or through the web interface at http://rt.cpan.org.

AUTHOR

Joe McMahon <mcmahon@yahoo-inc.com >

LICENCE AND COPYRIGHT

Copyright (c) 2005, Joe McMahon <mcmahon@yahoo-inc.com >. All rights reserved.

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

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.