Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/joemcmahon/app-simplescan

simple web testing environment
https://github.com/joemcmahon/app-simplescan

Last synced: 11 days ago
JSON representation

simple web testing environment

Awesome Lists containing this project

README 

        
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

    "[email protected]", or through the web interface at

    .



AUTHOR

    Joe McMahon ""



LICENCE AND COPYRIGHT

    Copyright (c) 2005, Joe McMahon "". 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.