Name

Mungo — An Apache::ASP inspired lightweight ASP framework

Synopsis

# In your httpd.conf:
<FilesMatch "\.asp$">
  SetHandler perl-script
PerlHandler Mungo
# This is optional, see PREAMBLE SUPPORT below
PerlSetVar MungoPreamble My::PreambleHandler
# Optionally enable output buffering
# see Mungo::Response - OUTPUT BUFFERING section
PerlSetVar MungoBuffer 1
# Turn this on if you want pages to recompile on each load
#          off to cache the bytecode for performance
<IfDefine DEVELOPMENT>
  PerlSetVar StatINC 1
</IfDefine>
<IfDefine PRODUCTION>
  # This is the default anyway
  PerlSetVar StatINC 0
</IfDefine>
</FilesMatch>
# In asp pages:
<html>
  <%= 1 + 1; %><!-- Output: 2 -->
  <% 1 + 1; %><!-- No Output  -->
<!-- Variable scope extends across tags -->
<% my $pet = 'pony'; %>
<%= $pet %><!-- you get a pony! -->
<!-- Can embed control structures into pages -->
<% if ($prefer_daisies) { %>
  <h2>Here are your daisies!</h2>
<% } else { %>
  <h2>Brown-Eyed Susans, Just For You!</h2>
<% } %>
<!-- For, foreach, while loops, too -->
<% foreach my $beer_num (0..99) { %>
  <p><%= 99 - $beer_num %> bottles of beer on the wall</p>
<% } %>
<%
   # Write arbitrary amounts of Perl here
# you can use modules
# (just don't define subroutines or change packages)
use Some::Module;
# Access info about the request
# TODO - DOCS
# $Request->
# Access info about the server
# TODO - DOCS
# $Server->
# Redirect to somewhere else...
if ($want_to_redirect) {
   $Response->Redirect($url);
   # Never reach here
}
   # Abort further processing and close outout stream
   if ($want_to_end) {
      $Response->End;
      # Never reach here
   }
%>
<!-- Can also include other pages or fragments -->
<% $Response->Include($filesystem_path); %>
<!-- may also include args -->
<% $Response->Include($filesystem_path, @args); %>
<!-- If args are passed to an ASP page (or page fragment) access them via @_ -->
<%
  # In included file
  my $arg1 = shift;
%>
<!-- What if you want to grab that output instead of sending to the browser? -->
<% my $output = $Response->TrapInclude($filesystem_path, @args); %>
<!-- You can also send a string of ASP code instead of using a file -->
<%
  # Use a scalar reference!
  $Response->Include(\$asp, @args);
%>
<!-- Cookie facilities -->
<%
  # Read cookie
  $single_value = $Request->Cookies($cookie_name);
  $hashref = $Request->Cookies($cookie_name);
  # Set cookie
  $Response->Cookies($cookie_name, $single_value);
  $Response->Cookies($cookie_name, $hash_ref);
%>
</html>

DESCRIPTION

What is Mungo?

Mungo is a mod_perl 1 or 2 PerlHandler module. It allows you to embed Perl code directly into HTML files, using <% %> tags.

Mungo also provides Request and Response objects, similar to many ASP environments. These facilities are aimed at applications needing simple, lightweight features.

What Mungo does:

  • Allows perl to be embedded in web pages with <% %> tags.

  • Provides simplistic access to various aspects of the client request via a Mungo::Request object.

  • Provides simplistic manipulation of the response via a Mungo::Response object.

  • Handles query strings, post forms (urlencoded and multipart) as well as cookies.

What Mungo does not do:

  • Manage sessions

  • XML/XSLT/etc

Implementation Goals

Mungo was originally developed as a simpler, non-GPL'd Apache::ASP with far fewer CPAN dependencies. It is somewhat compatible with Apache::ASP, but there are enough differences to warrant close attention to the docs here.

While Mungo is very simple and has a very small fetureset, the object APIs it does implement adhere closely to those present in Apache::ASP. So, assuming you are not using sessions or the XML features, you should find few obstacles in making your application run under Mungo (it could be as simple as setting PerlHandler Mungo in your httpd.conf file).


Preamble Support

In addition to normal Apache stacked handlers, Mungo also supports a mechanism for inserting code to execute before every Mungo request is processed, while still having access to the Mungo environment.

To use this mechanism, define a Perl module as follows:

package My::PreambleHandler;
use strict;
use warnings;

use Apache2::Const qw ( OK DECLINED ); # Others as needed by your code

sub handler {
   my $class          = shift;
   my $apache_request = shift;
   my $mungo_request  = shift;
   my $mungo_response = shift;
   my $mungo_server   = shift;

# Determine what to do with the request, if anything

if ( ... ) {
    # Continue normal Mungo processing
    return Apache2::Const::DECLINED;

} elsif ( ... ) {
    # If handled entirely within the preamble, skip further Mungo work
    return Apache2::Const::OK;

} elsif ( ... ) {
    # Returning anything other than DECLINED will 
    # skip further Mungo work - but should be informative
    # for example, if the user's credentials are bad...
    return Apache2::Const::NOT_AUTHORIZED;
}

}

With your preamble code in hand, you may now register this code to run on a per-location, directory, or file basis:

&lt;Location /restricted&gt;
  SetHandler perl-script
  PerlSetVar MungoPreamble My::AuthorizationCheckingPreamble
  PerlHandler Mungo
&lt;/location&gt;

Limitations of Preambles

Limit of one Preamble per location/file/directory stanza

If you require more flexibility, Apache stacked handlers are likely a better solution for you (though you will not have the Mungo environment setup in your stacked handler).

Preambles Modules will not be automatically loaded

You can add a PerlRequire directive to httpd.conf, or 'use' your preamble class in your startup.pl

MODPERL HANDLER

PerlHandler Mungo

When Mungo is the registered handler for a URL, it first locates the file (if not found, apache's 404 response mechanism is triggered). Global objects describing the transaction are created: $Request, $Server, and $Response (see Mungo::Response, etc. for details) Next, the file is parsed and evaluated, and the results are sent to the browser. This happens using $Request->Include().

$mungo = Mungo->new($req);

Given an Apache2::RequestRec or Apache request object, return the Mungo context, which is a Singleton.

Called from the modperl handler.

$mungo->cleanse();

Releases resources at the end of a request.

$encoded = $mungo->URLEncode($string);

$encoded = Mungo->URLEncode($string);

Encodes a string to escape characters that are not permitted in a URL.

$string = $mungo->URLDecode($encoded);

$string = Mungo->URLDecode($encoded);

Decodes a string to unescape characters that are not permitted in a URL.

LIMITATIONS/BUGS

  • Cannot define subroutines in ASP pages. Bad things will happen.

  • Documentation is spotty. This is being worked on.

LICENSE INFORMATION

Copyright (c) 2007 OmniTI Computer Consulting, Inc. All rights reserved. For information on licensing see:

https://labs.omniti.com/mungo/trunk/LICENSE

PROJECT WEBSITE

https://labs.omniti.com/trac/mungo/

AUTHOR

Theo Schlossnagle (code)

Clinton Wolfe (docs)