Menu
▾
▴
[Openinteract-commits] CVS: OpenInteract2/lib/OpenInteract2 Brick.pm,1.4,1.5
|
From: Chris W. <la...@us...> - 2005-03-24 05:13:56
|
Update of /cvsroot/openinteract/OpenInteract2/lib/OpenInteract2 In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv17863 Modified Files: Brick.pm Log Message: move docs so CPAN sees them ok Index: Brick.pm =================================================================== RCS file: /cvsroot/openinteract/OpenInteract2/lib/OpenInteract2/Brick.pm,v retrieving revision 1.4 retrieving revision 1.5 diff -C2 -d -r1.4 -r1.5 *** Brick.pm 17 Feb 2005 04:59:43 -0000 1.4 --- Brick.pm 24 Mar 2005 05:13:47 -0000 1.5 *************** *** 17,20 **** --- 17,221 ---- $OpenInteract2::Brick::VERSION = sprintf("%d.%02d", q$Revision$ =~ /(\d+)\.(\d+)/); + # Docs are up here because parsers get confused by the included class + # below... + + =pod + + =head1 NAME + + OpenInteract2::Brick - Base class for inlined data packages + + =head1 SYNOPSIS + + use OpenInteract2::Brick; + + my $loader = OpenInteract2::Brick->new( 'apache' ); + my @resources = $loader->list_resources; + print "Resources available in 'Apache': ", + join( ', ', @resources ), "\n"; + + my $httpd_static_info = $loader->load_resource( 'httpd_static.conf' ); + print "File should be stored in: $httpd_static_info->{destination}\n"; + print "File contents:\n$httpd_static_info->{content}\n"; + + =head1 DESCRIPTION + + Rather than including lots of sample files used to create packages and + websites, OI2 has a set of 'bricks'. Each one of these classes has one + or more inlined files you can ask for by file name. Each of these + files also has associated with it some metadata to determine where it + should go and whether it should be evaluated as a template before + being stored. (Of course, you're free to ignore these data and do + whatever you want with the contents, but other parts of the OI2 + framework need them.) + + =head1 CLASS METHODS + + B<new( $type )> + + Returns an instance of the bricks associated with C<$type>, which + should always be a lowercased value. + + B<list_bricks()> + + Returns a sorted list of all available brick names. With the name you + can instantiate a new brick: + + my @brick_names = OpenInteract2::Brick->list_bricks; + foreach my $name ( @brick_names ) { + my $brick = OpenInteract2::Brick->new( $name ); + print "Resources in brick '$name': ", + join( ", ", $brick->list_resources ), "\n"; + } + + =head1 OBJECT METHODS + + B<list_resources()> + + Returns an array of all resources defined. These are always simple + filenames with no paths, so with the 'apache2' type you would do + something like: + + my $loader = OpenInteract2::Brick->new( 'apache2' ); + print "Apache2 resources:\n ", + join( "\n ", $loader->list_resources ), "\n"; + + And get: + + Apache2 resources: + httpd_mp2_solo.conf + startup_mp2.pl + + These resource names are what you use in C<load_resource()>: + + my $startup_info = $loader->load_resource( 'startup_mp2.pl' ); + print "Startup script is:\n", $startup_info->{contents}; + + B<load_resource( $resource_name > + + Loads the resource and metdata associated with C<$resource_name>. If + C<$resource_name> is empty or no resource is actually associated with + it we throw an exception. + + If the resource is found we return a hashref with the following keys: + + =over 4 + + =item * + + B<content>: Contents of the resource. + + =item * + + B<destination>: Space-delimited string of directories where this + resource should be copied. Note that the string may have template + directives in it. + + =item * + + B<evaluate>: Whether you should evaluate the data in 'content' before + storing it. + + =back + + Regarding template directives. A number of resources have template + directives in them so they can be properly named -- for instance, the + perl 'package' declaration in the generated action whene you create a + new package looks like this: + + package OpenInteract2::Action::[% class_name %]; + + When we use this resource we first run it through a template processor + (Template Toolkit) so that when we create a package called + 'baseball_stats' the above will get translated to: + + package OpenInteract2::Action::BaseballStats; + + B<copy_all_resources_to( $destination_dir, [ \%token_replacements ] )> + + Copies all resources from this brick to C<$destination_dir>. See + L<copy_resources_to()> for more. + + Returns: hashref with keys 'copied', 'skipped', 'same' each of which + has as its value an arrayref of the relevant files. + + B<copy_resources_to( $destination_dir, \%token_replacements, @resource_names )> + + Copies the resources with C<@resource_names> to the given + C<$destination_dir>. For those resources that are evaluatable use the + C<\%token_replacements> when evaluating as Template Toolkit templates. + + If the source and destination are the same -- checked by the content + size and MD5 digest -- we don't do a copy. + + We also don't do a copy if the resource is specified in the + directory's has a '.no_overwrite' file. (See + L<OpenInteract2::Config::Readonly> for this file's format and how we + use it.) + + Returns: hashref with keys 'copied', 'skipped', 'same' each of which + has as its value an arrayref of the relevant files. + + =head1 SUBCLASSING + + Since you typically don't create subclasses by hand this is mostly + unnecessary. If you're interested in creating a C<::Brick> subclass by + hand first look in the C<build_bricks> script found at the root of the + OI2 source tree -- it builds the class dynamically based on + specifications and files found in the filesystem. + + That said, subclasses must implement the following methods: + + B<get_name()> + + Return the name by which people instantiate this loader. Should be + lower-cased. + + B<get_resources()> + + Return a hash of data regarding the resources specified by this + class. Keys are resource names (generally filenames) and values are + arrayrefs with two elements: + + =over 4 + + =item 0. + + String with destination information. This tells the caller where the + contents should be stored. Should be space-delimited and may have + template directives in it. + + =item 1. + + Whether the content can be evaluated by a template processor as 'yes' + or 'no'. Generally you should leave this as 'yes' unless the specified + resource is actually a TT2 template. + + =back + + B<load( $resource_name )> + + Return the content associated with C<$resource_name>. The caller + (L<OpenInteract2::Brick> checks that C<$resource_name> is valid before + invoking this method. + + =head1 SEE ALSO + + L<Class::Factory> + + =head1 COPYRIGHT + + Copyright (c) 2005 Chris Winters. All rights reserved. + + This library is free software; you can redistribute it and/or modify + it under the same terms as Perl itself. + + =head1 AUTHORS + + Chris Winters E<lt>ch...@cw...E<gt> + + =cut + + my $TEMPLATE = Template->new(); *************** *** 265,461 **** 1; - - __END__ - - =head1 NAME - - OpenInteract2::Brick - Base class for inlined data packages - - =head1 SYNOPSIS - - use OpenInteract2::Brick; - - my $loader = OpenInteract2::Brick->new( 'apache' ); - my @resources = $loader->list_resources; - print "Resources available in 'Apache': ", - join( ', ', @resources ), "\n"; - - my $httpd_static_info = $loader->load_resource( 'httpd_static.conf' ); - print "File should be stored in: $httpd_static_info->{destination}\n"; - print "File contents:\n$httpd_static_info->{content}\n"; - - =head1 DESCRIPTION - - Rather than including lots of sample files used to create packages and - websites, OI2 has a set of 'bricks'. Each one of these classes has one - or more inlined files you can ask for by file name. Each of these - files also has associated with it some metadata to determine where it - should go and whether it should be evaluated as a template before - being stored. (Of course, you're free to ignore these data and do - whatever you want with the contents, but other parts of the OI2 - framework need them.) - - =head1 CLASS METHODS - - B<new( $type )> - - Returns an instance of the bricks associated with C<$type>, which - should always be a lowercased value. - - B<list_bricks()> - - Returns a sorted list of all available brick names. With the name you - can instantiate a new brick: - - my @brick_names = OpenInteract2::Brick->list_bricks; - foreach my $name ( @brick_names ) { - my $brick = OpenInteract2::Brick->new( $name ); - print "Resources in brick '$name': ", - join( ", ", $brick->list_resources ), "\n"; - } - - =head1 OBJECT METHODS - - B<list_resources()> - - Returns an array of all resources defined. These are always simple - filenames with no paths, so with the 'apache2' type you would do - something like: - - my $loader = OpenInteract2::Brick->new( 'apache2' ); - print "Apache2 resources:\n ", - join( "\n ", $loader->list_resources ), "\n"; - - And get: - - Apache2 resources: - httpd_mp2_solo.conf - startup_mp2.pl - - These resource names are what you use in C<load_resource()>: - - my $startup_info = $loader->load_resource( 'startup_mp2.pl' ); - print "Startup script is:\n", $startup_info->{contents}; - - B<load_resource( $resource_name > - - Loads the resource and metdata associated with C<$resource_name>. If - C<$resource_name> is empty or no resource is actually associated with - it we throw an exception. - - If the resource is found we return a hashref with the following keys: - - =over 4 - - =item * - - B<content>: Contents of the resource. - - =item * - - B<destination>: Space-delimited string of directories where this - resource should be copied. Note that the string may have template - directives in it. - - =item * - - B<evaluate>: Whether you should evaluate the data in 'content' before - storing it. - - =back - - Regarding template directives. A number of resources have template - directives in them so they can be properly named -- for instance, the - perl 'package' declaration in the generated action whene you create a - new package looks like this: - - package OpenInteract2::Action::[% class_name %]; - - When we use this resource we first run it through a template processor - (Template Toolkit) so that when we create a package called - 'baseball_stats' the above will get translated to: - - package OpenInteract2::Action::BaseballStats; - - B<copy_all_resources_to( $destination_dir, [ \%token_replacements ] )> - - Copies all resources from this brick to C<$destination_dir>. See - L<copy_resources_to()> for more. - - Returns: hashref with keys 'copied', 'skipped', 'same' each of which - has as its value an arrayref of the relevant files. - - B<copy_resources_to( $destination_dir, \%token_replacements, @resource_names )> - - Copies the resources with C<@resource_names> to the given - C<$destination_dir>. For those resources that are evaluatable use the - C<\%token_replacements> when evaluating as Template Toolkit templates. - - If the source and destination are the same -- checked by the content - size and MD5 digest -- we don't do a copy. - - We also don't do a copy if the resource is specified in the - directory's has a '.no_overwrite' file. (See - L<OpenInteract2::Config::Readonly> for this file's format and how we - use it.) - - Returns: hashref with keys 'copied', 'skipped', 'same' each of which - has as its value an arrayref of the relevant files. - - =head1 SUBCLASSING - - Since you typically don't create subclasses by hand this is mostly - unnecessary. If you're interested in creating a C<::Brick> subclass by - hand first look in the C<build_bricks> script found at the root of the - OI2 source tree -- it builds the class dynamically based on - specifications and files found in the filesystem. - - That said, subclasses must implement the following methods: - - B<get_name()> - - Return the name by which people instantiate this loader. Should be - lower-cased. - - B<get_resources()> - - Return a hash of data regarding the resources specified by this - class. Keys are resource names (generally filenames) and values are - arrayrefs with two elements: - - =over 4 - - =item 0. - - String with destination information. This tells the caller where the - contents should be stored. Should be space-delimited and may have - template directives in it. - - =item 1. - - Whether the content can be evaluated by a template processor as 'yes' - or 'no'. Generally you should leave this as 'yes' unless the specified - resource is actually a TT2 template. - - =back - - B<load( $resource_name )> - - Return the content associated with C<$resource_name>. The caller - (L<OpenInteract2::Brick> checks that C<$resource_name> is valid before - invoking this method. - - =head1 SEE ALSO - - L<Class::Factory> - - =head1 COPYRIGHT - - Copyright (c) 2005 Chris Winters. All rights reserved. - - This library is free software; you can redistribute it and/or modify - it under the same terms as Perl itself. - - =head1 AUTHORS - - Chris Winters E<lt>ch...@cw...E<gt> --- 466,467 ---- |
