Changeset 33

Show
Ignore:
Timestamp:
02/20/08 21:39:15 (6 years ago)
Author:
clinton
Message:

First stabs at documentation

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved
  • trunk/lib/Mungo.pm

    r23 r33  
    11package Mungo; 
    22 
    3 # Copyright (c) 2007 OmniTI Computer Consulting, Inc. All rights reserved. 
    4 # For information on licensing see: 
    5 #   https://labs.omniti.com/mungo/trunk/LICENSE 
     3=head1 NAME 
     4 
     5Mungo - An Apache::ASP inspired lightweight ASP framework 
     6 
     7=head1 SYNOPSIS 
     8 
     9 # In your httpd.conf: 
     10 <FilesMatch "\.asp$"> 
     11   SetHandler perl-script 
     12   PerlHandler Mungo 
     13 </FilesMatch> 
     14 
     15 # In asp pages: 
     16 <html> 
     17   <%= 1 + 1; %><!-- Output: 2 --> 
     18   <% 1 + 1; %><!-- No Output  --> 
     19 
     20   <!-- Variable scope extends across tags --> 
     21   <% my $pet = 'pony'; %> 
     22   <%= $pet %><!-- you get a pony! --> 
     23 
     24   <!-- Can embed control structures into pages --> 
     25   <% if ($prefer_daisies) { %> 
     26     <h2>Here are your daisies!</h2> 
     27   <% } else { %> 
     28     <h2>Brown-Eyed Susans, Just For You!</h2> 
     29   <% } %> 
     30 
     31   <!-- For, foreach, while loops, too --> 
     32   <% foreach my $beer_num (0..99) { %> 
     33     <p><%= 99 - $beer_num %> bottles of beer on the wall</p> 
     34   <% } %> 
     35 
     36   <% 
     37      # Write arbitrary amounts of Perl here 
     38 
     39      # you can use modules 
     40      # (just don't define subroutines or change packages) 
     41      use Some::Module; 
     42 
     43      # Access info about the request 
     44      # TODO - DOCS 
     45      # $Request-> 
     46 
     47      # Access info about the server 
     48      # TODO - DOCS 
     49      # $Server-> 
     50 
     51 
     52      # Redirect to somewhere else... 
     53      if ($want_to_redirect) { 
     54         $Response->Redirect($url); 
     55         # Never reach here 
     56      } 
     57 
     58      # Abort further processing and close outout stream 
     59      if ($want_to_end) { 
     60         $Response->End; 
     61         # Never reach here 
     62      } 
     63   %> 
     64 
     65   <!-- Can also include other pages or fragments --> 
     66   <% $Response->Include($filesystem_path); %> 
     67 
     68   <!-- may also include args --> 
     69   <% $Response->Include($filesystem_path, @args); %> 
     70 
     71   <!-- If args are passed to an ASP page (or page fragment) access them via @_ --> 
     72   <% 
     73     # In included file 
     74     my $arg1 = shift; 
     75   %> 
     76 
     77   <!-- What if you want to grab that output instead of sending to the browser? --> 
     78   <% my $output = $Response->TrapInclude($filesystem_path, @args); %> 
     79 
     80   <!-- You can also send a string of ASP code instead of using a file --> 
     81   <% 
     82     # Use a scalar reference! 
     83     $Response->Include(\$asp, @args); 
     84   %> 
     85 
     86 </html> 
     87 
     88 
     89=head1 DESCRIPTION 
     90 
     91=head2 What is Mungo? 
     92 
     93Mungo is a mod_perl 1 or 2 PerlHandler module.  It allows you to  
     94embed Perl code directly into HTML files, using <% %> tags. 
     95 
     96Mungo also provides Request and Response objects, similar to many ASP  
     97environments.  These facilities are aimed at applications needing simple,  
     98lightweight features. 
     99 
     100=head2 What Mungo does: 
     101 
     102=over 4 
     103 
     104=item * 
     105 
     106Allows perl to be embedded in web pages with <% %> tags. 
     107 
     108=item * 
     109 
     110Provides simplistic access to various aspects of the client request via a Mungo::Request object. 
     111 
     112=item * 
     113 
     114Provides simplistic manipulation of the response via a Mungo::Response object. 
     115 
     116=item * 
     117 
     118Handles query strings, post forms (urlencoded and multipart) as well as cookies.  
     119 
     120=back 
     121 
     122=head2 What Mungo does not do: 
     123 
     124=over 4 
     125 
     126=item * 
     127 
     128Manage sessions 
     129 
     130=item * 
     131 
     132XML/XSLT/etc 
     133 
     134=back 
     135 
     136=head2 Implementation Goals 
     137 
     138Mungo was originally developed as a simpler, non-GPL'd Apache::ASP with far  
     139fewer CPAN dependencies.  It is somewhat compatible with Apache::ASP, but  
     140there are enough differences to warrant close attention to the docs here. 
     141 
     142While Mungo is very simple and has a very small fetureset, the object APIs it  
     143does implement adhere closely to those present in Apache::ASP. So, assuming you 
     144are not using sessions or the XML features, you should find few obstacles 
     145in making your application run under Mungo (it could be as simple as 
     146setting PerlHandler Mungo in your httpd.conf file). 
     147 
     148=cut 
     149 
     150 
     151#=============================================================================# 
     152#                           Implementation Notes 
     153#=============================================================================# 
     154# - public methods are CamelCase 
     155#  
     156#=============================================================================# 
    6157 
    7158use strict; 
     
    41192$DEFAULT_POST_MAX_IN_MEMORY = 1024*128; # 128k 
    42193 
     194=head1 MODPERL HANDLER 
     195 
     196  PerlHandler Mungo 
     197 
     198When Mungo is the registered handler for a URL, it first locates the file (if 
     199not found, apache's 404 response mechanism is triggered).  Global objects 
     200describing the transaction are created: $Request, $Server, and $Response  
     201(see Mungo::Response, etc. for details) Next, the file is parsed and  
     202evaluated, and the results are sent to the browser. This happens using $Request->Include(). 
     203 
     204=cut 
     205 
     206sub handler($$) { 
     207  my ($self, $r) = @_; 
     208  if (ref $self eq 'Apache2::RequestRec') { 
     209    $r = $self; 
     210    $self = __PACKAGE__; 
     211  } 
     212  # Short circuit if we can't find the file. 
     213  return NOT_FOUND() if(! -r $r->filename); 
     214 
     215  $self = $self->new($r) unless(ref $self); 
     216  $self->Response()->start(); 
     217  $main::Request = $self->Request(); 
     218  $main::Response = $self->Response(); 
     219  $main::Server = $self->Server(); 
     220  local $SIG{__DIE__} = \&Mungo::MungoDie; 
     221  eval { 
     222    $self->Response()->Include($r->filename); 
     223  }; 
     224  if($@) { 
     225    # print out the error to the logs 
     226    print STDERR $@ if($@); 
     227    # If it isn't too late, make this an internal server error 
     228    eval { $self->Response()->{Status} = 500; }; 
     229  } 
     230 
     231  # gotos come here from: 
     232  #   $Response->End() 
     233 MUNGO_HANDLER_FINISH: 
     234  $self->Response()->finish(); 
     235 
     236  $self->cleanse(); 
     237  undef $main::Request; 
     238  undef $main::Response; 
     239  undef $main::Server; 
     240  undef $self; 
     241  return &OK; 
     242} 
     243 
     244 
    43245sub MungoDie { 
    44246  my $i = 0; 
     
    49251  die Mungo::Error->new({ error => shift, callstack => \@callstack }); 
    50252} 
     253 
     254=for private_developer_docs 
     255 
     256=head2 $mungo = Mungo->new($req); 
     257 
     258Given an Apache2::RequestRec or Apache request object, 
     259return the Mungo context, which is a Singleton. 
     260 
     261Called from the modperl handler. 
     262 
     263=cut 
    51264 
    52265sub new { 
     
    60273  return $self; 
    61274} 
     275 
    62276sub DESTROY { } 
     277 
     278=for private_developer_docs 
     279 
     280=head2 $mungo->cleanse(); 
     281 
     282Releases resources at the end of a request. 
     283 
     284=cut 
     285 
    63286sub cleanse { 
    64287  my $self = shift; 
     
    127350  return $type . "::MemPage::" . md5_hex($$contents); 
    128351} 
     352 
     353 
     354# $output = $mungo->include_mem(  
     355# 
    129356sub include_mem { 
    130357  my $self = shift; 
     
    230457} 
    231458 
    232 sub handler($$) { 
    233   my ($self, $r) = @_; 
    234   if (ref $self eq 'Apache2::RequestRec') { 
    235     $r = $self; 
    236     $self = __PACKAGE__; 
    237   } 
    238   # Short circuit if we can't fine the file. 
    239   return NOT_FOUND() if(! -r $r->filename); 
    240  
    241   $self = $self->new($r) unless(ref $self); 
    242   $self->Response()->start(); 
    243   $main::Request = $self->Request(); 
    244   $main::Response = $self->Response(); 
    245   $main::Server = $self->Server(); 
    246   local $SIG{__DIE__} = \&Mungo::MungoDie; 
    247   eval { 
    248     $self->Response()->Include($r->filename); 
    249   }; 
    250   if($@) { 
    251     # print out the error to the logs 
    252     print STDERR $@ if($@); 
    253     # If it isn't too late, make this an internal server error 
    254     eval { $self->Response()->{Status} = 500; }; 
    255   } 
    256  MUNGO_HANDLER_FINISH: 
    257   $self->Response()->finish(); 
    258  
    259   $self->cleanse(); 
    260   undef $main::Request; 
    261   undef $main::Response; 
    262   undef $main::Server; 
    263   
    264   undef $self;  
    265   return &OK; 
    266 } 
    267459 
    268460sub convertStringToExpression { 
     
    292484} 
    293485 
     486=head1 LIMITATIONS/BUGS 
     487 
     488=over 4 
     489 
     490=item * 
     491 
     492Cannot define subroutines in ASP pages.  Bad things will happen. 
     493 
     494=item * 
     495 
     496Documentation is spotty.  This is being worked on. 
     497 
     498=back 
     499 
     500=head1 LICENSE INFORMATION 
     501 
     502Copyright (c) 2007 OmniTI Computer Consulting, Inc. All rights reserved. 
     503For information on licensing see: 
     504 
     505https://labs.omniti.com/mungo/trunk/LICENSE 
     506 
     507=head1 PROJECT WEBSITE 
     508 
     509https://labs.omniti.com/trac/mungo/ 
     510 
     511=head1 AUTHOR 
     512 
     513Theo Schlossnagle (code) 
     514 
     515Clinton Wolfe (docs) 
     516 
     517=cut 
     518 
     519 
    2945201; 
  • trunk/lib/Mungo/Response.pm

    r17 r33  
    126126  $self->End(); 
    127127} 
     128 
     129 
     130=head2 $res->Include($filename, $arg1, $arg2, ...); 
     131 
     132=head2 $res->Include(\$string, $arg1, $arg2, ...); 
     133 
     134Reads the given filename or string and interprets it as Mungo ASP code. 
     135 
     136Any passed arguments are available in the @_ array within the ASP code. 
     137 
     138The results of evaluating the code is printed to STDOUT. 
     139 
     140=cut 
     141 
    128142sub Include { 
    129143  my $self = shift; 
     
    222236  } 
    223237  $self->Flush(); 
    224   eval { goto  MUNGO_HANDLER_FINISH; }; 
     238  eval { goto  MUNGO_HANDLER_FINISH; }; # Jump back to Mungo::handler() 
    225239} 
    226240