The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
PerlBean-1.0
River stage zero No dependents
++
/ PerlBean

NAME

PerlBean - Package to generate bean like Perl modules

SYNOPSIS

 use strict;
 use PerlBean;
 use PerlBean::Attribute::Factory;
 
 my $bean = PerlBean->new( {
     package => 'MyPackage',
 } );
 my $factory = PerlBean::Attribute::Factory->new();
 my $attr = $factory->create_attribute( {
     method_factory_name => 'true',
     short_description => 'something is true',
 } );
 $bean->add_method_factory($attr);
 
 use IO::File;
 -d 'tmp' || mkdir('tmp');
 my $fh = IO::File->new('> tmp/PerlBean.pl.out');
 $bean->write($fh);

ABSTRACT

Code generation for bean like Perl modules

DESCRIPTION

The PerlBean class models a Perl module with one package. After adding different components to the PerlBean, the Perl module can be generated.

The following sections in the code generated by a PerlBean are used to explain the concept.

PerlBean module file header section
 package Circle;
 
 use 5.008;
 use base qw( Shape Exporter );
 use strict;
 use warnings;
 use Error qw(:try);
 require Exporter;
set_package()

is used to set the package name in package Circle.

add_dependency() or set_dependency()

are used to add PerlBean::Dependency objects like the use and require lines in the example. Note however that except for use base all use dependencies in the example above are set by default when initializing a PerlBean object without specifying a dependency option.

set_use_perl_version()

is used to set the version number in the use 5.008 dependency. By default the version number is set to \$]. This is an exception to the PerlBean::Dependency mechanism.

push_base(), set_base() or unshift_base()

are used to express inheritance relationships. When the PerlBean is written, the inheritance relationships -like Shape in this example- appear in the use base list. The Exporter bit is there because symbols are exported by package Circle.

PerlBean symbols:
add_symbol() or set_symbol()

are used to add PerlBean::Symbol objects. PerlBean::Symbol objects are described in their own manual pages.

PerlBean complimentary symbols:
 # Used by _value_is_allowed
 our %ALLOW_ISA = (
 );
 
 # Used by _value_is_allowed
 our %ALLOW_REF = (
 );
 
 # Used by _value_is_allowed
 our %ALLOW_RX = (
     'radius' => [ '^\d*(\.\d+)?$' ],
 );

 # Used by _value_is_allowed
 our %ALLOW_VALUE = (
 );
 
 # Used by _initialize
 our %DEFAULT_VALUE = (
 );

 # Package version
 our ($VERSION) = '$Revision: 1.0 $' =~ /\$Revision:\s+([^\s]+)/;

The our %ALLOW.* symbols above are used by the generated class to check rules that apply to the PerlBean's attributes. They are not exported. You could theoretically overwrite them. But don't do that!

The our %DEFAULT_VALUE symbol above is used at class instantiation to set the attribute's default values of the PerlBean. It is not exported. Sometimes you need to overwrite values. That's not particularly nice and should be addressed.

The our ($VERSION) is there to allow versioning through CVS. You could overwrite it.

Preloaded section end
 1;
 
 __END__

If the PerlBean is autoloaded then the code above is generated in order to autoload the methods that follow. The method set_autoloaded() is used to change the autoload behavior of a PerlBean. NOTE: In my experience it pays to first have PerlBeans preloaded and to switch to autoload after debugging.

NAME section
 =head1 NAME
 
 Circle - circle shape

The package name ( which was set through set_package() ) is put in Circle -.

set_short_description()

is used to set a short package description in - circle shape.

ABSTRACT section
 =head1 ABSTRACT
 
 circle shape
set_abstract()

is used to set the abstract information in circle shape.

DESCRIPTION section
 =head1 DESCRIPTION
 
 circle shape
set_description()

is used to set the description information circle shape. If no description is set then C<Circle> TODO would be shown.

EXPORT section

This section describes all exported PerlBean::Symbol objects like in the following example.

 =head1 EXPORT
 
 By default nothing is exported.
 
 =head2 geo
 
 Geometric constants
 
 =over
 
 =item $PI
 
 The PI constant
 
 =back
CONSTRUCTOR section

All constructors are documented in alphabetical order in this section. PerlBean by default generates documentation for the new() constructor. In theory you can overwrite the new() constructor and hence alter the documentation thereof. Before you do so, I suggest you thoroughly contemplate this. You can of course add a PerlBean::Method::Constructor object ( e.g. new_from_file ) in order to customize construction.

METHODS section

All methods that aren't constructors are documented in alphabetical order in this section. PerlBean::Method objects in the PerlBean by default generate documentation for the methods. In theory you can overwrite the methods. Again, I suggest you thoroughly contemplate the consequences.

SEE ALSO section
 L<Rectangle>,
 L<Shape>,
 L<Square>

All PerlBean objects inside a PerlBean::Collection are referred in this section as listed.

BUGS section
 None known (yet.)

This section always has None known (yet.) in it.

HISTORY section
 First development: September 2003
 Last update: September 2003

This section always has First development: C<current_date> Last update: C<current_date> in it.

AUTHOR section
 Vincenzo Zocca

This section always has the GECOS field from the passwd file.

 Copyright 2003 by Vincenzo Zocca

This section always contains the above message with the current_year and the GECOS field from the passwd file.

LICENSE section
 This code is licensed under B<GNU GENERAL PUBLIC LICENSE>.
 Details on L<http://gnu.org>.

This section either contains:

1) The license of the PerlBean which set through method set_license()

2) The license of the PerlBean::Collection

3) The text TODO

Implementation section

This section contains the implementation of the methods and constructors. First listed are the constructors which are ordered alphabetically and new() and _initialize() are kept near to each-other. Then the normal methods are listed alphabetically.

End of file
 1;

If the PerlBean is not autoloaded then the code above is generated in order to close the file the Perl way. The method set_autoloaded() is used to change the autoload behavior of a PerlBean. NOTE: In my experience it pays to first have PerlBeans preloaded and to switch to autoload after debugging.

CONSTRUCTOR

new(OPT_HASH_REF)

Creates a new PerlBean object. OPT_HASH_REF is a hash reference used to pass initialization options. OPT_HASH_REF is mandatory. On error an exception Error::Simple is thrown.

Options for OPT_HASH_REF may include:

abstract

Passed to set_abstract().

autoloaded

Passed to set_autoloaded(). Defaults to 1.

base

Passed to set_base(). Must be an ARRAY reference.

collection

Passed to set_collection().

dependency

Passed to set_dependency(). Must be an ARRAY reference. Defaults to a set of PerlBean::Dependency objects that yields to:

 use strict;
 use warnings;
 use Error qw(:try);
description

Passed to set_description().

exception_class

Passed to set_exception_class(). Defaults to 'Error::Simple'.

export_tag_description

Passed to set_export_tag_description(). Must be an ARRAY reference.

license

Passed to set_license().

method

Passed to set_method(). Must be an ARRAY reference.

method_factory

Passed to set_method_factory(). Must be an ARRAY reference.

package

Passed to set_package(). Mandatory option.

short_description

Passed to set_short_description(). Defaults to 'NO DESCRIPTION AVAILABLE'.

singleton

Passed to set_singleton(). Defaults to 0.

symbol

Passed to set_symbol(). Must be an ARRAY reference.

synopsis

Passed to set_synopsis().

use_perl_version

Passed to set_use_perl_version(). Defaults to $].

METHODS

add_attribute( See add_method_factory() )

Legacy method. Writes a warning to STDERR and calls add_method_factory(). Will be discontinued from the 4th of April 2004 on.

add_dependency( [ VALUE ... ] )

Add additional values on the list of 'PerlBean::Dependency' objects. Each VALUE is an object out of which the id is obtained through method get_dependency_name(). The obtained key is used to store the value and may be used for deletion and to fetch the value. 0 or more values may be supplied. Multiple occurrences of the same key yield in the last occurring key to be inserted and the rest to be ignored. Each key of the specified values is allowed to occur only once. On error an exception Error::Simple is thrown.

The values in ARRAY must be a (sub)class of:
PerlBean::Dependency
add_export_tag_description( [ VALUE ... ] )

Add additional values on the list of 'PerlBean::Described::ExportTag' objects. Each VALUE is an object out of which the id is obtained through method get_export_tag_name(). The obtained key is used to store the value and may be used for deletion and to fetch the value. 0 or more values may be supplied. Multiple occurrences of the same key yield in the last occurring key to be inserted and the rest to be ignored. Each key of the specified values is allowed to occur only once. On error an exception Error::Simple is thrown.

The values in ARRAY must be a (sub)class of:
PerlBean::Described::ExportTag
add_method( [ VALUE ... ] )

Add additional values on the list of 'PerlBean::Method' objects. Each VALUE is an object out of which the id is obtained through method get_method_name(). The obtained key is used to store the value and may be used for deletion and to fetch the value. 0 or more values may be supplied. Multiple occurrences of the same key yield in the last occurring key to be inserted and the rest to be ignored. Each key of the specified values is allowed to occur only once. On error an exception Error::Simple is thrown.

The values in ARRAY must be a (sub)class of:
PerlBean::Method
add_method_factory( [ VALUE ... ] )

Add additional values on the list of 'PerlBean::Method::Factory' objects. Each VALUE is an object out of which the id is obtained through method get_method_factory_name(). The obtained key is used to store the value and may be used for deletion and to fetch the value. 0 or more values may be supplied. Multiple occurrences of the same key yield in the last occurring key to be inserted and the rest to be ignored. Each key of the specified values is allowed to occur only once. On error an exception Error::Simple is thrown.

The values in ARRAY must be a (sub)class of:
PerlBean::Method::Factory
add_symbol( [ VALUE ... ] )

Add additional values on the list of 'PerlBean::Symbol' objects. Each VALUE is an object out of which the id is obtained through method get_symbol_name(). The obtained key is used to store the value and may be used for deletion and to fetch the value. 0 or more values may be supplied. Multiple occurrences of the same key yield in the last occurring key to be inserted and the rest to be ignored. Each key of the specified values is allowed to occur only once. On error an exception Error::Simple is thrown.

The values in ARRAY must be a (sub)class of:
PerlBean::Symbol
delete_attribute( See delete_method_factory() )

Legacy method. Writes a warning to STDERR and calls delete_method_factory(). Will be discontinued from the 4th of April 2004 on.

delete_dependency(ARRAY)

Delete elements from the list of 'PerlBean::Dependency' objects. Returns the number of deleted elements. On error an exception Error::Simple is thrown.

delete_export_tag_description(ARRAY)

Delete elements from the list of 'PerlBean::Described::ExportTag' objects. Returns the number of deleted elements. On error an exception Error::Simple is thrown.

delete_method(ARRAY)

Delete elements from the list of 'PerlBean::Method' objects. Returns the number of deleted elements. On error an exception Error::Simple is thrown.

delete_method_factory(ARRAY)

Delete elements from the list of 'PerlBean::Method::Factory' objects. Returns the number of deleted elements. On error an exception Error::Simple is thrown.

delete_symbol(ARRAY)

Delete elements from the list of 'PerlBean::Symbol' objects. Returns the number of deleted elements. On error an exception Error::Simple is thrown.

exists_attribute( See exists_method_factory() )

Legacy method. Writes a warning to STDERR and calls exists_method_factory(). Will be discontinued from the 4th of April 2004 on.

exists_base(ARRAY)

Returns the count of items in ARRAY that are in the list of class names in use base.

exists_dependency(ARRAY)

Returns the count of items in ARRAY that are in the list of 'PerlBean::Dependency' objects.

exists_export_tag_description(ARRAY)

Returns the count of items in ARRAY that are in the list of 'PerlBean::Described::ExportTag' objects.

exists_method(ARRAY)

Returns the count of items in ARRAY that are in the list of 'PerlBean::Method' objects.

exists_method_factory(ARRAY)

Returns the count of items in ARRAY that are in the list of 'PerlBean::Method::Factory' objects.

exists_symbol(ARRAY)

Returns the count of items in ARRAY that are in the list of 'PerlBean::Symbol' objects.

get_abstract()

Returns the PerlBean's abstract (a one line description of the module).

get_base( [ INDEX_ARRAY ] )

Returns an ARRAY containing the list of class names in use base. INDEX_ARRAY is an optional list of indexes which when specified causes only the indexed elements in the ordered list to be returned. If not specified, all elements are returned.

get_collection()

Returns class to throw when exception occurs.

get_description()

Returns the PerlBean description.

get_exception_class()

Returns class to throw when exception occurs.

get_license()

Returns the software license for the PerlBean.

get_package()

Returns package name.

get_short_description()

Returns the short PerlBean description.

get_synopsis()

Returns the synopsis for the PerlBean.

get_use_perl_version()

Returns the Perl version to use.

is_autoloaded()

Returns whether the methods in the PerlBean are autoloaded or not.

is_singleton()

Returns whether the package is a singleton and an instance() method is implemented or not.

keys_attribute( See keys_method_factory() )

Legacy method. Writes a warning to STDERR and calls keys_method_factory(). Will be discontinued from the 4th of April 2004 on.

keys_dependency()

Returns an ARRAY containing the keys of the list of 'PerlBean::Dependency' objects.

keys_export_tag_description()

Returns an ARRAY containing the keys of the list of 'PerlBean::Described::ExportTag' objects.

keys_method()

Returns an ARRAY containing the keys of the list of 'PerlBean::Method' objects.

keys_method_factory()

Returns an ARRAY containing the keys of the list of 'PerlBean::Method::Factory' objects.

keys_symbol()

Returns an ARRAY containing the keys of the list of 'PerlBean::Symbol' objects.

pop_base()

Pop and return an element off the list of class names in use base. On error an exception Error::Simple is thrown.

push_base(ARRAY)

Push additional values on the list of class names in use base. ARRAY is the list value. The push may not yield to multiple identical elements in the list. Hence, multiple occurrences of the same element are ignored. On error an exception Error::Simple is thrown.

The values in ARRAY must match regular expression:
^\S+$
set_abstract(VALUE)

Set the PerlBean's abstract (a one line description of the module). VALUE is the value. On error an exception Error::Simple is thrown.

VALUE must match regular expression:
^.*$
set_attribute( See set_method_factory() )

Legacy method. Writes a warning to STDERR and calls set_method_factory(). Will be discontinued from the 4th of April 2004 on.

set_autoloaded(VALUE)

State that the methods in the PerlBean are autoloaded. VALUE is the value. Default value at initialization is 1. On error an exception Error::Simple is thrown.

set_base(ARRAY)

Set the list of class names in use base absolutely. ARRAY is the list value. Each element in the list is allowed to occur only once. Multiple occurrences of the same element yield in the first occurring element to be inserted and the rest to be ignored. On error an exception Error::Simple is thrown.

The values in ARRAY must match regular expression:
^\S+$
set_collection(VALUE)

Set class to throw when exception occurs. VALUE is the value. On error an exception Error::Simple is thrown.

VALUE must be a (sub)class of:
PerlBean::Collection
set_dependency( [ VALUE ... ] )

Set the list of 'PerlBean::Dependency' objects absolutely using values. Each VALUE is an object out of which the id is obtained through method get_dependency_name(). The obtained key is used to store the value and may be used for deletion and to fetch the value. 0 or more values may be supplied. Multiple occurrences of the same key yield in the last occurring key to be inserted and the rest to be ignored. Each key of the specified values is allowed to occur only once. On error an exception Error::Simple is thrown. Defaults value at initialization is a set of PerlBean::Dependency objects that yields to:

 use strict;
 use warnings;
 use Error qw(:try);
The values in ARRAY must be a (sub)class of:
PerlBean::Dependency
set_description(VALUE)

Set the PerlBean description. VALUE is the value. On error an exception Error::Simple is thrown.

set_exception_class(VALUE)

Set class to throw when exception occurs. VALUE is the value. Default value at initialization is Error::Simple. VALUE may not be undef. On error an exception Error::Simple is thrown.

set_export_tag_description( [ VALUE ... ] )

Set the list of 'PerlBean::Described::ExportTag' objects absolutely using values. Each VALUE is an object out of which the id is obtained through method get_export_tag_name(). The obtained key is used to store the value and may be used for deletion and to fetch the value. 0 or more values may be supplied. Multiple occurrences of the same key yield in the last occurring key to be inserted and the rest to be ignored. Each key of the specified values is allowed to occur only once. On error an exception Error::Simple is thrown.

The values in ARRAY must be a (sub)class of:
PerlBean::Described::ExportTag
set_license(VALUE)

Set the software license for the PerlBean. VALUE is the value. On error an exception Error::Simple is thrown.

VALUE must match regular expression:
.*
set_method( [ VALUE ... ] )

Set the list of 'PerlBean::Method' objects absolutely using values. Each VALUE is an object out of which the id is obtained through method get_method_name(). The obtained key is used to store the value and may be used for deletion and to fetch the value. 0 or more values may be supplied. Multiple occurrences of the same key yield in the last occurring key to be inserted and the rest to be ignored. Each key of the specified values is allowed to occur only once. On error an exception Error::Simple is thrown.

The values in ARRAY must be a (sub)class of:
PerlBean::Method
set_method_factory( [ VALUE ... ] )

Set the list of 'PerlBean::Method::Factory' objects absolutely using values. Each VALUE is an object out of which the id is obtained through method get_method_factory_name(). The obtained key is used to store the value and may be used for deletion and to fetch the value. 0 or more values may be supplied. Multiple occurrences of the same key yield in the last occurring key to be inserted and the rest to be ignored. Each key of the specified values is allowed to occur only once. On error an exception Error::Simple is thrown.

The values in ARRAY must be a (sub)class of:
PerlBean::Method::Factory
set_package(VALUE)

Set package name. VALUE is the value. VALUE may not be undef. On error an exception Error::Simple is thrown.

set_short_description(VALUE)

Set the short PerlBean description. VALUE is the value. Default value at initialization is NO DESCRIPTION AVAILABLE. On error an exception Error::Simple is thrown.

set_singleton(VALUE)

State that the package is a singleton and an instance() method is implemented. VALUE is the value. Default value at initialization is 0. On error an exception Error::Simple is thrown.

set_symbol( [ VALUE ... ] )

Set the list of 'PerlBean::Symbol' objects absolutely using values. Each VALUE is an object out of which the id is obtained through method get_symbol_name(). The obtained key is used to store the value and may be used for deletion and to fetch the value. 0 or more values may be supplied. Multiple occurrences of the same key yield in the last occurring key to be inserted and the rest to be ignored. Each key of the specified values is allowed to occur only once. On error an exception Error::Simple is thrown.

The values in ARRAY must be a (sub)class of:
PerlBean::Symbol
set_synopsis(VALUE)

Set the synopsis for the PerlBean. VALUE is the value. On error an exception Error::Simple is thrown.

VALUE must match regular expression:
.*
set_use_perl_version(VALUE)

Set the Perl version to use. VALUE is the value. Default value at initialization is $]. VALUE may not be undef. On error an exception Error::Simple is thrown.

VALUE must match regular expression:
^v?\d+(\.[\d_]+)*
shift_base()

Shift and return an element off the list of class names in use base. On error an exception Error::Simple is thrown.

unshift_base(ARRAY)

Unshift additional values on the list of class names in use base. ARRAY is the list value. The push may not yield to multiple identical elements in the list. Hence, multiple occurrences of the same element are ignored. On error an exception Error::Simple is thrown.

The values in ARRAY must match regular expression:
^\S+$
values_attribute( See values_method_factory() )

Legacy method. Writes a warning to STDERR and calls values_method_factory(). Will be discontinued from the 4th of April 2004 on.

values_dependency( [ KEY_ARRAY ] )

Returns an ARRAY containing the values of the list of 'PerlBean::Dependency' objects. If KEY_ARRAY contains one or more KEYs the values related to the KEYs are returned. If no KEYs specified all values are returned.

values_export_tag_description( [ KEY_ARRAY ] )

Returns an ARRAY containing the values of the list of 'PerlBean::Described::ExportTag' objects. If KEY_ARRAY contains one or more KEYs the values related to the KEYs are returned. If no KEYs specified all values are returned.

values_method( [ KEY_ARRAY ] )

Returns an ARRAY containing the values of the list of 'PerlBean::Method' objects. If KEY_ARRAY contains one or more KEYs the values related to the KEYs are returned. If no KEYs specified all values are returned.

values_method_factory( [ KEY_ARRAY ] )

Returns an ARRAY containing the values of the list of 'PerlBean::Method::Factory' objects. If KEY_ARRAY contains one or more KEYs the values related to the KEYs are returned. If no KEYs specified all values are returned.

values_symbol( [ KEY_ARRAY ] )

Returns an ARRAY containing the values of the list of 'PerlBean::Symbol' objects. If KEY_ARRAY contains one or more KEYs the values related to the KEYs are returned. If no KEYs specified all values are returned.

write(FILEHANDLE)

Write the Perl class code to FILEHANDLE. FILEHANDLE is an IO::Handle object. On error an exception Error::Simple is thrown.

SEE ALSO

PerlBean::Attribute, PerlBean::Attribute::Boolean, PerlBean::Attribute::Factory, PerlBean::Attribute::Multi, PerlBean::Attribute::Multi::Ordered, PerlBean::Attribute::Multi::Unique, PerlBean::Attribute::Multi::Unique::Associative, PerlBean::Attribute::Multi::Unique::Associative::MethodKey, PerlBean::Attribute::Multi::Unique::Ordered, PerlBean::Attribute::Single, PerlBean::Collection, PerlBean::Dependency, PerlBean::Dependency::Import, PerlBean::Dependency::Require, PerlBean::Dependency::Use, PerlBean::Described, PerlBean::Described::ExportTag, PerlBean::Method, PerlBean::Method::Constructor, PerlBean::Method::Factory, PerlBean::Style, PerlBean::Symbol

BUGS

OS dependency

PerlBean is written on/for Unix. File handling and system file access should be enhanced to be OS independent.

PerlBean rules
Symbols

I am not satisfied with the our %ALLOW.* symbols that are used to check rules that apply to the PerlBean's attributes. They pollute the class' name space. Also there are too many symbols in use. Once I will restructure these into one hash ( e.g. _RULES_ ).

PerlBean::Attribute
Default values

Currently, default values can only be defined fixed. Expressions that are evaluated at module load and expressions that are evaluated at class instantiation would make sense.

Also, their representations in code and in pod have issues with special characters.

Allow/deny undef

Currently, allow/deny of undef is handled poorly by _value_is_allowed(). That has to get better.

A lock property

In order to deny attributes being changed after they are set.

SEE ALSO section

I am not satisfied with the long lists in the SEE ALSO section. PerlBean objects must get a documentation scope or some other restriction scheme. I don't know exactly yet.

BUGS section

The BUGS section always has None known (yet.) in it. That must improve.

HISTORY section

The HISTORY section always has First development: C<current_date> Last update: C<current_date> in it. That must improve.

TODO section

I need a TODO section.

HISTORY

First development: November 2002 Last update: September 2003

AUTHOR

Vincenzo Zocca

COPYRIGHT

Copyright 2002, 2003 by Vincenzo Zocca

LICENSE

This file is part of the PerlBean module hierarchy for Perl by Vincenzo Zocca.

The PerlBean module hierarchy is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

The PerlBean module hierarchy is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with the PerlBean module hierarchy; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA