TITLE

POOL - The Perl Object-Oriented (Definition) Language

DESCRIPTION

This is an initial release of the POOL code generation system. The basic idea behind POOL is to write object-oriented classes so you don't have to. You specify a very simple description of what you want your class to look like, and the POOL code generator does the rest, turning the definition into code, tests, documentation, and so on.

As it's an initial release, it's rather rough around the edges, and this is the only documentation, but I'm releasing it now on the "half a loaf" principle.

INSTALLATION

POOL requires the following Perl modules to be installed:

    Template
    Sys::Hostname (core)

It also requires the template files found in the template/ directory to be installed somewhere it can find it. This is currently either /usr/share/pool/templates or ~/.pool/. Templates in your local ~/.pool will override the system-wide ones in /usr/share; you can have an even more local directory called templates in your current path.

Next you'll probably want to put pool itself somewhere you can execute it.

Now I suppose you're going to want to know how to use it.

USAGE

The general procedure for writing a module with POOL is as follows:

1. Make a new directory to hold your module and change into it.

2. Write your POOL file as described below.

3. Optionally, set the environment variables POOL_NAME and POOL_EMAIL to be your full name and email address.

4. Run

       pool your.pool

5. Edit the resulting files.

SYNTAX

The syntax for POOL is a bit ad-hoc at the moment and I expect it to remain ad-hoc for a few versions until I've worked out how to specify everything I want to specify.

Let's look at the sample POOL file specified, to show the main features of the language.

    Devel::DProfPP - Parse C<Devel::DProf> output

The first line contains the name of the module, and optionally a hyphen and the short description. Some general points about POOL: comments are specified with a # ... , and a blank line separates different classes in a module. The first class specified should be the "main" one, but you can have as many classes as you like in a POOL file.

        DESCRIPTION

    This module takes the output file from L<Devel::DProf> (typically
    F<tmon.out>) and parses it into a Perl data structure. Additionally, it
    can be used in an event-driven style to produce reports more
    immediately.

        EOD

The description, which ends with the magic text EOD. This is optional, and appears in the DESCRIPTION section of the class's documentation. It's the only place in a POOL file you can get away with a blank line.

        @fh

fh is a member variable which does not have an accessor or a default.

        ->@enter    || sub {}
        ->@leave    || sub {}

enter and leave are variables with an accessor, with default values of sub {} if no enter (or leave) parameter is given to the constructor.

        ro->@stack  []

The stack is a member variable which is initialized to be an empty array reference. As it's initialized, you can't pass a stack parameter to the constructor. There's also a read-only accessor generator for this member. As it knows that stack is going to be an array, it will dereference this array before returning it.

        @syms       []

syms is a completely internal member variable, initialized to [], and with no accessor.

        parse

This is just an ordinary method.

        top_frame   ->stack->[0]

This is a delegate method. It returns the first element of the result from calling stack. This is me being overly clever, and probably won't work. Normally you'd use this with another method name:

        header_get  ->header->get

would delegate the header_get method to the get method of the result of calling header. You can also say

        get         ->header->

to pass on the get method. (This will define a get method which calls $self->header->get).

Note that we didn't specify a constructor, and so a new constructor is automatically defined.

Other things I need to think about are a syntax for class methods, a way to define metadata like version numbers, but this does most of what I want for now.

TEMPLATING

The beauty of POOL is that the code generation is all done through Template Toolkit templates and components. Don't like the default method code you get? No problem, just write your own method_code template. Do you want your tests provided inline a la Test::Inline? No problem, alter do_method so that it calls the appropriate method_test routines in the right place.

I hope to add a "flavour" system to POOL whereby you can pick and choose what templates to apply - there'll be a directory of templates which implement inline tests, one with more sophisticated accessors, and so on, and you'll be able to say pool --flavors="testinline,myaccessor" foo.pool.

For that to happen, though, I'm going to need to build up a library of neat template hacks. Please send me your neat template hacks.

For your reference, here's the data structures provided to the templates:

    author
        .name              Your name
        .email             Your email address
    year                   The current year
    module                 The current module
        .package           Its Perl package name
        .description       The description
        .methods           A list of defined methods
            .name          The name of the method
            .type          Its type: method / accessor / delegate /
                                    constructor / classmethod
            .via           Delegation method for delegates
            .how           Delegation goes $self->via->how
            .ro            Is this accessor read-only?
            .var           Is this accessor's member scalar/array/hash?
        .fields            A HASH of defined member variables
            .name          The member's name
            .default       Any default value
            .set           Any pre-initialized non-default
            .type          Scalar/array/hash

AUTHOR

Simon Cozens, simon@cpan.org

cpanm SIMON/pool-0.0.1.tar.gz

perl -MCPAN -e shell
install SIMON/pool-0.0.1.tar.gz