PerlBean - Package to generate bean like Perl modules
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);
Code generation for bean like Perl modules
The PerlBean class models a Perl module with one package. After adding different components to the PerlBean, the Perl module can be generated.
PerlBean
The following sections in the code generated by a PerlBean are used to explain the concept.
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.
package Circle
add_dependency()
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.
PerlBean::Dependency
use
require
use base
dependency
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.
use 5.008
\$]
push_base()
set_base()
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.
Shape
Exporter
add_symbol()
set_symbol()
are used to add PerlBean::Symbol objects. PerlBean::Symbol objects are described in their own manual pages.
PerlBean::Symbol
# 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!
our %ALLOW.*
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.
our %DEFAULT_VALUE
The our ($VERSION) is there to allow versioning through CVS. You could overwrite it.
our ($VERSION)
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.
autoloaded
set_autoloaded()
=head1 NAME Circle - circle shape
The package name ( which was set through set_package() ) is put in Circle -.
Circle -
set_short_description()
is used to set a short package description in - circle shape.
- circle shape
=head1 ABSTRACT circle shape
set_abstract()
is used to set the abstract information in circle shape.
circle shape
=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.
C<Circle> TODO
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
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.
new()
PerlBean::Method::Constructor
new_from_file
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.
PerlBean::Method
L<Rectangle>, L<Shape>, L<Square>
All PerlBean objects inside a PerlBean::Collection are referred in this section as listed.
PerlBean::Collection
None known (yet.)
This section always has None known (yet.) in it.
First development: September 2003 Last update: September 2003
This section always has First development: C<current_date> Last update: C<current_date> in it.
First development: C<current_date> Last update: C<current_date>
Vincenzo Zocca
This section always has the GECOS field from the passwd file.
passwd
Copyright 2003 by Vincenzo Zocca
This section always contains the above message with the current_year and the GECOS field from the passwd file.
current_year
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()
set_license()
2) The license of the PerlBean::Collection
3) The text TODO
TODO
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.
_initialize()
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.
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.
OPT_HASH_REF
Error::Simple
Options for OPT_HASH_REF may include:
abstract
Passed to set_abstract().
Passed to set_autoloaded(). Defaults to 1.
base
Passed to set_base(). Must be an ARRAY reference.
ARRAY
collection
Passed to set_collection().
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 $].
Legacy method. Writes a warning to STDERR and calls add_method_factory(). Will be discontinued from the 4th of April 2004 on.
add_method_factory()
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.
VALUE
get_dependency_name()
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.
get_export_tag_name()
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.
get_method_name()
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.
get_method_factory_name()
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.
get_symbol_name()
Legacy method. Writes a warning to STDERR and calls delete_method_factory(). Will be discontinued from the 4th of April 2004 on.
delete_method_factory()
Delete elements from the list of 'PerlBean::Dependency' objects. Returns the number of deleted elements. On error an exception Error::Simple is thrown.
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 elements from the list of 'PerlBean::Method' objects. Returns the number of deleted elements. On error an exception Error::Simple is thrown.
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 elements from the list of 'PerlBean::Symbol' objects. Returns the number of deleted elements. On error an exception Error::Simple is thrown.
Legacy method. Writes a warning to STDERR and calls exists_method_factory(). Will be discontinued from the 4th of April 2004 on.
exists_method_factory()
Returns the count of items in ARRAY that are in the list of class names in use base.
Returns the count of items in ARRAY that are in the list of 'PerlBean::Dependency' objects.
Returns the count of items in ARRAY that are in the list of 'PerlBean::Described::ExportTag' objects.
Returns the count of items in ARRAY that are in the list of 'PerlBean::Method' objects.
Returns the count of items in ARRAY that are in the list of 'PerlBean::Method::Factory' objects.
Returns the count of items in ARRAY that are in the list of 'PerlBean::Symbol' objects.
Returns the PerlBean's abstract (a one line description of the module).
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.
INDEX_ARRAY
Returns class to throw when exception occurs.
Returns the PerlBean description.
Returns the software license for the PerlBean.
Returns package name.
Returns the short PerlBean description.
Returns the synopsis for the PerlBean.
Returns the Perl version to use.
Returns whether the methods in the PerlBean are autoloaded or not.
Returns whether the package is a singleton and an instance() method is implemented or not.
instance()
Legacy method. Writes a warning to STDERR and calls keys_method_factory(). Will be discontinued from the 4th of April 2004 on.
keys_method_factory()
Returns an ARRAY containing the keys of the list of 'PerlBean::Dependency' objects.
Returns an ARRAY containing the keys of the list of 'PerlBean::Described::ExportTag' objects.
Returns an ARRAY containing the keys of the list of 'PerlBean::Method' objects.
Returns an ARRAY containing the keys of the list of 'PerlBean::Method::Factory' objects.
Returns an ARRAY containing the keys of the list of 'PerlBean::Symbol' objects.
Pop and return an element off the list of class names in use base. On error an exception Error::Simple is thrown.
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.
Set the PerlBean's abstract (a one line description of the module). VALUE is the value. On error an exception Error::Simple is thrown.
Legacy method. Writes a warning to STDERR and calls set_method_factory(). Will be discontinued from the 4th of April 2004 on.
set_method_factory()
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.
1
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.
Set class to throw when exception occurs. VALUE is the value. On error an exception Error::Simple is thrown.
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:
Set the PerlBean description. VALUE is the value. On error an exception Error::Simple is thrown.
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.
undef
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.
Set the software license for the PerlBean. VALUE is the value. On error an exception Error::Simple is thrown.
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.
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.
Set package name. VALUE is the value. VALUE may not be undef. On error an exception Error::Simple is thrown.
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.
NO DESCRIPTION AVAILABLE
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.
0
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.
Set the synopsis for the PerlBean. VALUE is the value. On error an exception Error::Simple is thrown.
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.
$]
Shift and return an element off the list of class names in use base. On error an exception Error::Simple is thrown.
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.
Legacy method. Writes a warning to STDERR and calls values_method_factory(). Will be discontinued from the 4th of April 2004 on.
values_method_factory()
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.
KEY_ARRAY
KEY
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.
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.
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.
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 the Perl class code to FILEHANDLE. FILEHANDLE is an IO::Handle object. On error an exception Error::Simple is thrown.
FILEHANDLE
IO::Handle
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
PerlBean is written on/for Unix. File handling and system file access should be enhanced to be OS independent.
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_ ).
_RULES_
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.
Currently, allow/deny of undef is handled poorly by _value_is_allowed(). That has to get better.
_value_is_allowed()
In order to deny attributes being changed after they are set.
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.
The BUGS section always has None known (yet.) in it. That must improve.
The HISTORY section always has First development: C<current_date> Last update: C<current_date> in it. That must improve.
HISTORY
I need a TODO section.
First development: November 2002 Last update: September 2003
Copyright 2002, 2003 by Vincenzo Zocca
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
To install PerlBean, copy and paste the appropriate command in to your terminal.
cpanm
cpanm PerlBean
CPAN shell
perl -MCPAN -e shell install PerlBean
For more information on module installation, please visit the detailed CPAN module installation guide.