view release on metacpan or  search on metacpan

README  view on Meta::CPAN

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").

README  view on Meta::CPAN

    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: