NAME

Package::FromData - generate a package with methods and variables from a data structure

SYNOPSIS

Given a data structure like this:

  my $packages = { 
      'Foo::Bar' => {
          constructors   => ['new'],        # my $foo_bar = Foo::Bar->new
          static_methods => {               # Foo::Bar->method
              next_word => [                # Foo::Bar->next_word
                  ['foo']       => 'bar',   # Foo::Bar->next_word('foo') = bar
                  ['hello']     => 'world',
                  [qw/bar baz/] => 'baz',   # Foo::Bar->next_word(qw/foo bar/) 
                                            #    = baz
                  'default_value'
              ],
              one => [ 1 ],                 # Foo::Bar->one = 1
          },
          methods => {
              wordify => [ '...' ],         # $foo_bar->wordify = '...'
                                            # Foo::Bar->wordify = <exception>
          
              # baz always returns Foo::Bar::Baz->new
              baz     => [ { new => 'Foo::Bar::Baz' } ],
          },
          functions => {
              map_foo_bar => [ 'foo' => 'bar', 'bar' => 'foo' ],
              context     => {
                  scalar => 'called in scalar context',
                  list   => [qw/called in list context/],
              }
          },
          variables => {
              '$VERSION' => '42',           # $Foo::Bar::VERSION
              '@ISA'     => ['Foo'],        # @Foo::Bar::ISA
              '%FOO'     => {Foo => 'Bar'}, # %Foo::Bar::FOO
          },
      },
  };

and some code like this:

   use Package::FromData;
   create_package_from_data($packages);

create the package Foo::Bar and the functions as specified above.

After you create_package_from_data, you can use Foo::Bar as though it were a module you wrote:

   my $fb = Foo::Bar->new       # blessed hash reference
   $fb->baz                     # a new Foo::Bar::Baz
   $fb->wordify                 # '...'
   $fb->next_word('foo')        # 'bar'
   Foo::Bar->next_word('foo')   # 'bar'
   Foo::Bar->baz                # <exception>, it's an instance method
   Foo::Bar::map_foo_bar('foo') # 'bar'
   $Foo::Bar::VERSION           # '42'

Not a very useful package, but you get the idea.

DESCRIPTION

This module creates a package with predefined methods, functions, and variables from a data structure. It's used for testing (mock objects) or experimenting. The idea is that you define a package containing functions that return values based on keys, and the rest of your app uses this somehow. (I use it so that Jifty->... or Catalyst.uri_for will work in templates being served via App::TemplateServer.)

THE TOP

The top level data structure is a hash of package names / package definition hash pairs.

PACKAGE DEFINITION HASHES

Each package is defined by a package definition hash. This can contain a few keys:

constructors

An arrayref of constructors to be generated. The generated code looks like:

   sub <the name> {
       my $class = shift;
       return bless {}, $class;
   }

functions

The functions key should point to a hash of function names / function definiton array pairs.

FUNCTION DEFINITION ARRAYS

The function definition array is a list of pairs followed by an optional single value. The pairs are treated like a @_ => result of function hash, and the optional single element is used as a default return value. The expected input (@_) can be deep Perl data structures; an input => output pair matches if the \@_ in the program Test::Deep::NoTest::eq_deeplys the input rule you specify.

The pairs are of the form ARRAYREF => SCALAR|ARRAYREF|SEPECIAL. To make function('foo','bar') return baz, you would add a pair like [ 'foo', 'bar' ] = 'baz'> to the definition hash. To return a bare list, use a arrayref; ['foo','bar'] = ['foo','bar']>. To return a reference to a list, nest an arrayrf in the arrayref; foo('bar') = ['baz'].

To return different values in scalar or list context, pass a hash as the output definition:

    [ [input] => { scalar => '42', list => [qw/contents of the list/] },
      ... ]

To return a hashref, just say [{ ... }].

Finally, the function definition array may be a single hash containing a method = package> pair, which means to always call package->method and return the result. This makes it possible for packages defined with Package::FromData to be nested.

methods

Like functions, but the first argument (<$self>) is ignored.

static_methods

Like methods, but can be invoked against the class name instead of and instance of the class.

variables

A hash of variable name (including sigil) / value pairs. Keys starting with @ or % must point to the appropriate reference type.

EXPORTS

create_package_from_data

FUNCTIONS

create_package_from_data

See "DESCRIPTION" above.

BUGS

Probably. Report them to RT.

CODE REPOSITORY

The git repository is at http://git.jrock.us/ and can be cloned with:

    git clone git://git.jrock.us/Package-FromData

AUTHOR

Jonathan Rockway <jrockway@cpan.org>

COPYRIGHT

Copyright (c) 2007, Jonathan Rockway. This module free software. You may redistribute it under the same terms as Perl itself.

cpanm Package::FromData

perl -MCPAN -e shell
install Package::FromData