=head1 TITLE POOL - The Perl Object-Oriented (Definition) Language =head1 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. =head1 INSTALLATION POOL requires the following Perl modules to be installed: Template Sys::Hostname (core) It also requires the template files found in the F<template/> directory to be installed somewhere it can find it. This is currently either F</usr/share/pool/templates> or F<~/.pool/>. Templates in your local F<~/.pool> will override the system-wide ones in F</usr/share>; you can have an even more local directory called F<templates> in your current path. Next you'll probably want to put C<pool> itself somewhere you can execute it. Now I suppose you're going to want to know how to use it. =head1 USAGE The general procedure for writing a module with POOL is as follows: =over 3 =item 1 Make a new directory to hold your module and change into it. =item 2 Write your POOL file as described below. =item 3 Optionally, set the environment variables C<POOL_NAME> and C<POOL_EMAIL> to be your full name and email address. =item 3 Run pool your.pool =item 4 Edit the resulting files. =cut At present, this will generate a bunch of modules in F<lib/>, a set of tests in F<t/>, a simple F<Makefile.PL> and a F<MANIFEST> file. It would prefer to make a C<Module::Build> F<Build.PL> file, but I haven't written the templates for that yet. If you write a F<buildpl> template, it'll use that instead. =head1 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 C<# ... >, 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 C<EOD>. This is optional, and appears in the C<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 C<fh> is a member variable which does not have an accessor or a default. ->@enter || sub {} ->@leave || sub {} C<enter> and C<leave> are variables with an accessor, with default values of C<sub {}> if no C<enter> (or C<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 C<stack> parameter to the constructor. There's also a read-only accessor generator for this member. As it knows that C<stack> is going to be an array, it will dereference this array before returning it. @syms [] C<syms> is a completely internal member variable, initialized to C<[]>, 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 C<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 C<header_get> method to the C<get> method of the result of calling C<header>. You can also say get ->header-> to pass on the C<get> method. (This will define a C<get> method which calls C<< $self->header->get >>). Note that we didn't specify a constructor, and so a C<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. =head1 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 C<method_code> template. Do you want your tests provided inline a la C<Test::Inline>? No problem, alter C<do_method> so that it calls the appropriate C<method_test> routines in the right place. I hope to add a "flavour" system to C<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 C<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 =head1 AUTHOR Simon Cozens, C<simon@cpan.org>