UPGRADE GUIDE for Mason

Hints about upgrading to various major revisions of Mason. To be
completely safe, always read carefully through the Changes file and
upgrade first on a test server.

Version 1.10

- *** This version does not play nice with PerlFreshRestart! ***

Please see the FAQ, which details a variety of error messages you
might get when using PerlFreshRestart.  Turn it off and check out
Apache::Reload instead.

- The HTML::Mason::Commands module has been removed.  None of the old
'mc_' style commands will work with this version.

- The "perl_" prefix for Mason tags (like <%perl_args>) is no longer
supported.  Simply remove this prefix.

- The HTML::Mason::Parser class no longer exists.  If you were
creating one with the default options in your handler.pl file, you can
remove the Parser-related code entirely.  Otherwise see the
HTML::Mason::Compiler and HTML::Mason::Compiler::ToObject
documentation for more details.

- If your handler.pl file creates an Interp object and then passes
that object to the ApacheHandler constructor, this will no longer
work.  Instead, simply pass all of the parameters for both the Interp
and ApacheHandler to the ApacheHandler constructor.

So this:

  my $interp = HTML::Mason::Interp->new( comp_root => ..., data_dir =>... );

  my $ah = HTML::Mason::ApacheHandler->new( interp => $interp );

becomes this:

  my $ah = HTML::Mason::ApacheHandler->new( comp_root => ..., data_dir =>... );

- The use_reload_file Interp parameter has been removed.  See the
documentation on the static_source parameter (in HTML::Mason::Interp),
which is intended to provide a similar performance enhancement.

- Previous versions of Mason split the POD documentation into separate
.pod files from the code, which was in .pm files.  Now, these have
been combined into one file, the .pm file.  However, perldoc will look
for a .pod file before a .pm file.

During the install, we try to find these old .pod files and delete
them.  However, if that isn't successful, you may see the old
documentation for the following modules: HTML::Mason::Interp,
HTML::Mason::Request, HTML::Mason::ApacheHandler,
HTML::Mason::Component.  If you are experiencing this problem after
installing this new version of Mason, you will need to delete the old
.pod files manually.

- The top_args and top_comp methods have been renamed to request_args
and request_comp, respectively.  The old method names have been
deprecated but will continue to work until 1.20.

- The run_count and first_time component object methods have been
removed.

- The Parser's taint_check method no longer exists in any form.  We
now automatically detect taint mode and act appropriately to untaint
component source and object files.

- The use_autohandlers, use_dhandlers, and
allow_recursive_autohandlers Interp parameters have been removed.

- The autohandler_name and dhandler_name Interp parameters no longer
accept undef as a valid value.  The upshot of these two changes is
that there is no way to "turn off" autohandlers or dhandlers.  Of
course, the "inherit" flag for components still works.

- The home-brew caching architecture, using MLDBM, has been replaced
with one that uses Cache::Cache. In particular:
   - The old $m->cache and $m->cache_self methods still exist but
     their semantics have changed.  See the Developer's Manual
     (HTML::Mason::Devel) and Request object docs
     (HTML::Mason::Request) for more details.
   - Busy locks have not yet been ported to Cache::Cache; this is on
     the todo list.
   - The expire_if option is no longer supported. Instead, you can
     manually perform introspection on the cache object before trying
     to retrieve the cache. An example is provided in the docs.

- The top_level_predicate ApacheHandler parameter has been removed.
If you would like to filter requests you can do this via the new
ApacheHandler prepare_request method, which will give you a Request
object that you can manipulate before deciding to serve a request.
See the ApacheHandler docs (HTML::Mason::ApacheHandler) for more
details.

- The ApacheHandler module no longers accepts parameters when
imported, as in:

  use HTML::Mason::ApacheHandler (args_method => 'mod_perl');

Instead, you specify this via the ApacheHandler constructor, via:

  my $ah = HTML::Mason::ApacheHandler->new(args_method => 'mod_perl');

You should preload the Apache::Request or CGI module in your handler
or httpd.conf, in order to save memory.

- The default HTTP argument processor is now Apache::Request instead
of CGI.pm. This entails several differences:

  * Apache::Request treats parameters case-insensitively for purposes
  of grouping. This would  only be a problem if you expect two arguments
  that differ only by case (e.g. "mode" and "MODE").

  * Apache::Request always parses the query string, even for POST requests.

- There is no more batch vs. stream mode.  In its place, the Request
object now has an attribute called "autoflush", which is a much
simpler version of the same idea.  See the Request class documentation
for details.

- The ApacheHandler module now requires a minimum of mod_perl 1.22
(though using something more up to date is highly recommended).

- The ApacheHandler module will take care of chown'ing files created
during server startup, when needed.

- The MasonMultipleConfig parameter is no longer needed, and will
cause an error if given.  Mason can now figure out for itself whether
or not multiple ApacheHandler objects should be created.

- The Interp class's time method is gone.

- The Component class's create_time method has been renamed to
load_time, which better reflects its semantics.

- The debug file feature has been removed.

- The Previewer has been removed.

Version 0.85

- Autohandlers are now recursive by default. If your site uses
directory-specific autohandlers depending on the default value of
allow_recursive_autohandlers=0, you must explicitly pass
allow_recursive_autohandlers=>0 when creating the Interp.

- All applicable autohandlers now get a chance to run. If your site
has multiple autohandlers in parent/child directories, you'll likely
get display problems when upgrading (e.g. multiple templates showing
up per page). For a short-term fix, place

    <%flags>
    inherit=>undef
    </%flags>

in every autohandler. Ideally, in the long-term you'll be able to
make the autohandlers work well together.

- When calling components, base_comp now gets set to the called
components, _unless_ you call a component with a component object or
your component call starts with SELF: or PARENT:.  So a call like
this:

  <& /some/comp, foo => 1 &>

causes the return value of $m->base_comp to be the "/some/comp"
component object inside the "/some/comp" component.  But this:

  <& $some_comp_obj, foo => 1 &>

does not change what $m->base_comp returns.

Version 0.8

- Version 0.8 sports a new request API. $m now contains the current
request object, and all mc_ commands have been incorporated into $m
methods. The utility bin/convert0.8.pl converts existing components to
use the new syntax. See Commands.pod for a manual conversion guide and
a list of rare conversion problems.
