home *** CD-ROM | disk | FTP | other *** search
/ PC Professionell 2004 December / PCpro_2004_12.ISO / files / webserver / tsw / TSW_3.4.0.exe / Apache2 / perl / ComponentSource.pm < prev    next >
Encoding:
Perl POD Document  |  2003-11-12  |  5.0 KB  |  202 lines
  1. # Copyright (c) 1998-2003 by Jonathan Swartz. All rights reserved.
  2. # This program is free software; you can redistribute it and/or modify it
  3. # under the same terms as Perl itself.
  4.  
  5. package HTML::Mason::ComponentSource;
  6.  
  7. use strict;
  8. use File::Basename;
  9. use File::Spec;
  10. use HTML::Mason::Exceptions( abbr => [qw(param_error error)] );
  11. use Params::Validate qw(:all);
  12. Params::Validate::validation_options( on_fail => sub { param_error join '', @_  } );
  13.  
  14. # for reference later
  15. #
  16. # BEGIN
  17. # {
  18. #     __PACKAGE__->valid_params
  19. #         (
  20. #          comp_id       => { type => SCALAR | UNDEF, public => 0 },
  21. #          friendly_name => { type => SCALAR, public => 0 },
  22. #          last_modified => { type => SCALAR, public => 0 },
  23. #          comp_path     => { type => SCALAR, public => 0 },
  24. #          comp_class    => { isa => 'HTML::Mason::Component',
  25. #                             default => 'HTML::Mason::Component',
  26. #                             public => 0 },
  27. #          extra         => { type => HASHREF, default => {}, public => 0 },
  28. #          source_callback => { type => CODEREF, public => 0 },
  29. #     );
  30. # }
  31.  
  32. use HTML::Mason::MethodMaker
  33.     ( read_only => [ qw( comp_id
  34.                          friendly_name
  35.                          last_modified
  36.                          comp_path
  37.                          comp_class
  38.                          extra
  39.                         ) ],
  40.       );
  41.  
  42. my %defaults = ( comp_class => 'HTML::Mason::Component' );
  43.  
  44. sub new
  45. {
  46.     my $class = shift;
  47.  
  48.     return bless { %defaults, @_ }, $class
  49. }
  50.  
  51. sub comp_source_ref
  52. {
  53.     my $self = shift;
  54.  
  55.     my $source = eval { $self->{source_callback}->() };
  56.  
  57.     rethrow_exception $@;
  58.  
  59.     unless ( defined $source )
  60.     {
  61.     error "source callback returned no source for $self->{friendly_name} component";
  62.     }
  63.  
  64.     my $sourceref = ref($source) ? $source : \$source;
  65.     return $sourceref;
  66. }
  67.  
  68. sub comp_source { ${shift()->comp_source_ref} }
  69.  
  70. sub object_code
  71. {
  72.     my $self = shift;
  73.     my %p = validate( @_, { compiler => { isa => 'HTML::Mason::Compiler' } } );
  74.  
  75.     return $p{compiler}->compile( comp_source => $self->comp_source,
  76.                   name => $self->friendly_name,
  77.                   comp_class => $self->comp_class );
  78. }
  79.  
  80. 1;
  81.  
  82. __END__
  83.  
  84. =head1 NAME
  85.  
  86. HTML::Mason::ComponentSource - represents information about an component
  87.  
  88. =head1 SYNOPSIS
  89.  
  90.     my $info = $resolver->get_info($comp_path);
  91.  
  92. =head1 DESCRIPTION
  93.  
  94. Mason uses the ComponentSource class to store information about a
  95. source component, one that has yet to be compiled.
  96.  
  97. =head1 METHODS
  98.  
  99. =over
  100.  
  101. =item new
  102.  
  103. This method takes the following arguments:
  104.  
  105. =over 4
  106.  
  107. =item * comp_path
  108.  
  109. The component's component path.
  110.  
  111. =item * last_modified
  112.  
  113. This is the last modificatoin time for the component, in Unix time
  114. (seconds since the epoch).
  115.  
  116. =item * comp_id
  117.  
  118. This is a unique id for the component used to distinguish two
  119. components with the same name in different component roots.
  120.  
  121. If your resolver does not support multiple component roots, this can
  122. simply be the same as the "comp_path" key or it can be any other id
  123. you wish.
  124.  
  125. This value will be used when constructing filesystem paths so it needs
  126. to be something that works on different filesystems.  If it contains
  127. forward slashes, these will be converted to the appropriate
  128. filesystem-specific path separator.
  129.  
  130. In fact, we encourage you to make sure that your component ids have
  131. some forward slashes in them or also B<all> of your generated object
  132. files will end up in a single directory, which could affect
  133. performance.
  134.  
  135. =item * comp_class
  136.  
  137. The component class into which this particular component should be
  138. blessed when it is created.  This must be a subclass of
  139. C<HTML::Mason::Component>, which is the default.
  140.  
  141. =item * friendly_name
  142.  
  143. This is used when displaying error messages related to the component,
  144. like parsing errors.  This should be something that will help whoever
  145. sees the message identify the component.  For example, for component
  146. stored on the filesystem, this should be the absolute path to the
  147. component.
  148.  
  149. =item * source_callback
  150.  
  151. This is a subroutine reference which, when called, returns the
  152. component source.
  153.  
  154. The reasoning behind using this parameter is that it helps avoid a
  155. profusion of tiny little C<HTML::Mason::ComponentSource> subclasses that
  156. don't do very much.
  157.  
  158. =item * extra
  159.  
  160. This optional parameter should be a hash reference.  It is used to
  161. pass information from the resolver to the component class.
  162.  
  163. This is needed since a
  164. L<C<HTML::Mason::Resolver>|HTML::Mason::Resolver> subclass and a
  165. L<C<HTML::Mason::Component>|HTML::Mason::Component> subclass can be
  166. rather tightly coupled, but they must communicate with each through
  167. the interpreter (this may change in the future).
  168.  
  169. =back
  170.  
  171. =item comp_path
  172.  
  173. =item last_modified
  174.  
  175. =item comp_id
  176.  
  177. =item comp_class
  178.  
  179. =item friendly_name
  180.  
  181. =item extra
  182.  
  183. These are all simple accessors that return the value given to the
  184. constructor.
  185.  
  186. =item comp_source
  187.  
  188. Returns the source of the component.
  189.  
  190. =item object_code ( compiler => $compiler )
  191.  
  192. Given a compiler, this method returns the object code for the
  193. component.
  194.  
  195. =back
  196.  
  197. L<HTML::Mason|HTML::Mason>,
  198. L<HTML::Mason::Admin|HTML::Mason::Admin>,
  199. L<HTML::Mason::Component|HTML::Mason::Component>
  200.  
  201. =cut
  202.