--- /dev/null
+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sh \" Subsection heading
+.br
+.if t .Sp
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings. \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote. | will give a
+.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
+.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
+.\" expand to `' in nroff, nothing in troff, for use with C<>.
+.tr \(*W-|\(bv\*(Tr
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+. ds -- \(*W-
+. ds PI pi
+. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
+. ds L" ""
+. ds R" ""
+. ds C` ""
+. ds C' ""
+'br\}
+.el\{\
+. ds -- \|\(em\|
+. ds PI \(*p
+. ds L" ``
+. ds R" ''
+'br\}
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
+.\" entries marked with X<> in POD. Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.if \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. nr % 0
+. rr F
+.\}
+.\"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.hy 0
+.if n .na
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear. Run. Save yourself. No user-serviceable parts.
+. \" fudge factors for nroff and troff
+.if n \{\
+. ds #H 0
+. ds #V .8m
+. ds #F .3m
+. ds #[ \f1
+. ds #] \fP
+.\}
+.if t \{\
+. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+. ds #V .6m
+. ds #F 0
+. ds #[ \&
+. ds #] \&
+.\}
+. \" simple accents for nroff and troff
+.if n \{\
+. ds ' \&
+. ds ` \&
+. ds ^ \&
+. ds , \&
+. ds ~ ~
+. ds /
+.\}
+.if t \{\
+. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+. \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+. \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+. \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+. ds : e
+. ds 8 ss
+. ds o a
+. ds d- d\h'-1'\(ga
+. ds D- D\h'-1'\(hy
+. ds th \o'bp'
+. ds Th \o'LP'
+. ds ae ae
+. ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "Catalyst::Upgrading 3"
+.TH Catalyst::Upgrading 3 "2009-11-23" "perl v5.8.7" "User Contributed Perl Documentation"
+.SH "NAME"
+Catalyst::Upgrading \- Instructions for upgrading to the latest Catalyst
+.SH "Upgrading to Catalyst 5.80"
+.IX Header "Upgrading to Catalyst 5.80"
+Most applications and plugins should run unaltered on Catalyst 5.80.
+.PP
+However, a lot of refactoring work has taken place, and several changes have
+been made which could cause incompatibilities. If your application or plugin
+is using deprecated code, or relying on side effects, then you could have
+issues upgrading to this release.
+.PP
+Most issues found with pre-existing components have been easy to
+solve. This document provides a complete description of behavior changes
+which may cause compatibility issues, and of new Catalyst warnings which
+be unclear.
+.PP
+If you think you have found an upgrade-related issue which is not covered in
+this document, please email the Catalyst list to discuss the problem.
+.SH "Moose features"
+.IX Header "Moose features"
+.Sh "Application class roles"
+.IX Subsection "Application class roles"
+You can only apply method modifiers after the application's \f(CW\*(C`\->setup\*(C'\fR
+method has been called. This means that modifiers will not work with methods
+which run during the call to \f(CW\*(C`\->setup\*(C'\fR.
+.PP
+See Catalyst::Manual::ExtendingCatalyst for more information about using
+Moose in your applications.
+.Sh "Controller actions in Moose roles"
+.IX Subsection "Controller actions in Moose roles"
+You can use MooseX::MethodAttributes::Role if you want to declare actions
+inside Moose roles.
+.Sh "Using Moose in Components"
+.IX Subsection "Using Moose in Components"
+The correct way to use Moose in a component in a both forward and backwards
+compatible way is:
+.PP
+.Vb 3
+\& package TestApp::Controller::Root;
+\& use Moose;
+\& BEGIN { extends 'Catalyst::Component' }; # Or ::Controller, or whatever
+.Ve
+.PP
+See \*(L"Components which inherit from Moose::Object before Catalyst::Component\*(R".
+.SH "Known backwards compatibility breakages"
+.IX Header "Known backwards compatibility breakages"
+.Sh "Applications in a single file"
+.IX Subsection "Applications in a single file"
+Applications must be in their own file, and loaded at compile time. This
+issue generally only affects the tests of \s-1CPAN\s0 distributions. Your
+application will fail if you try to define an application inline in a
+block, and use plugins which supply a \f(CW\*(C` new \*(C'\fR method, then use that
+application latter in tests within the same file.
+.PP
+This is due to the fact that Catalyst is inlining a new method on your
+application class allowing it to be compatible with Moose. The method
+used to do this changed in 5.80004 to avoid the possibility of reporting
+an 'Unknown Error' if your application failed to compile.
+.Sh "Issues with Class::C3"
+.IX Subsection "Issues with Class::C3"
+Catalyst 5.80 uses the Algorithm::C3 method dispatch order. This is
+built into Perl 5.10, and comes via Class::C3 for Perl 5.8. This
+replaces \s-1NEXT\s0 with Class::C3::Adopt::NEXT, forcing all components
+to resolve methods using C3, rather than the unpredictable dispatch
+order of \s-1NEXT\s0.
+.PP
+This issue is characterised by your application failing to start due to an
+error message about having a non-linear \f(CW@ISA\fR.
+.PP
+The Catalyst plugin most often causing this is
+Catalyst::Plugin::Session::Store::FastMmap \- if you are using this
+plugin and see issues, then please upgrade your plugins, as it has been
+fixed. Note that Makefile.PL in the distribution will warn about known
+incompatible components.
+.PP
+This issue can, however, be found in your own application \- the only solution is
+to go through each base class of the class the error was reported against, until
+you identify the ones in conflict, and resolve them.
+.PP
+To be able to generate a linear \f(CW@ISA\fR, the list of superclasses for each
+class must be resolvable using the C3 algorithm. Unfortunately, when
+superclasses are being used as mixins (to add functionality used in your class),
+and with multiple inheritence, it is easy to get this wrong.
+.PP
+Most common is the case of:
+.PP
+.Vb 2
+\& package Component1; # Note, this is the common case
+\& use base qw/Class::Accessor::Fast Class::Data::Inheritable/;
+.Ve
+.PP
+.Vb 2
+\& package Component2; # Accidentally saying it this way causes a failure
+\& use base qw/Class::Data::Inheritable Class::Accessor::Fast/;
+.Ve
+.PP
+.Vb 2
+\& package GoesBang;
+\& use base qw/Component1 Component2/;
+.Ve
+.PP
+Any situation like this will cause your application to fail to start.
+.PP
+For additional documentation about this issue, and how to resolve it, see
+Class::C3::Adopt::NEXT.
+.Sh "Components which inherit from Moose::Object before Catalyst::Component"
+.IX Subsection "Components which inherit from Moose::Object before Catalyst::Component"
+Moose components which say:
+.PP
+.Vb 3
+\& package TestApp::Controller::Example;
+\& use Moose;
+\& extends qw/Moose::Object Catalyst::Component/;
+.Ve
+.PP
+to use the constructor provided by Moose, while working (if you do some hacks
+with the \f(CW\*(C` BUILDARGS \*(C'\fR method), will not work with Catalyst 5.80 as
+\&\f(CW\*(C`Catalyst::Component\*(C'\fR inherits from \f(CW\*(C`Moose::Object\*(C'\fR, and so \f(CW @ISA \fR fails
+to linearize.
+.PP
+The correct way to use Moose in a component in a both forward and backwards
+compatible way is:
+.PP
+.Vb 3
+\& package TestApp::Controller::Root;
+\& use Moose;
+\& BEGIN { extends 'Catalyst::Component' }; # Or ::Controller, or whatever
+.Ve
+.PP
+Note that the \f(CW\*(C` extends \*(C'\fR declaration needs to occur in a begin block for
+attributes to operate correctly.
+.PP
+This way you do not inherit directly from \f(CW\*(C`Moose::Object\*(C'\fR
+yourself. Having components which do not inherit their constructor from
+\&\f(CW\*(C`Catalyst::Component\*(C'\fR is \fBunsupported\fR, and has never been recommended,
+therefore you're on your own if you're using this technique. You'll need
+to detect the version of Catalyst your application is running, and deal
+with it appropriately.
+.PP
+You also don't get the Moose::Object constructor, and therefore attribute
+initialization will not work as normally expected. If you want to use Moose
+attributes, then they need to be made lazy to correctly initialize.
+.PP
+Note that this only applies if your component needs to maintain component
+backwards compatibility for Catalyst versions before 5.71001 \- in 5.71001
+attributes work as expected, and the \s-1BUILD\s0 method is called normally
+(although \s-1BUILDARGS\s0 is not).
+.PP
+If you depend on Catalyst 5.8, then \fBall\fR Moose features work as expected.
+.PP
+You will also see this issue if you do the following:
+.PP
+.Vb 3
+\& package TestApp::Controller::Example;
+\& use Moose;
+\& use base 'Catalyst::Controller';
+.Ve
+.PP
+as \f(CW\*(C` use base \*(C'\fR appends to \f(CW@ISA\fR.
+.PP
+\fIuse Moose in MyApp\fR
+.IX Subsection "use Moose in MyApp"
+.PP
+Similar to the above, this will also fail:
+.PP
+.Vb 6
+\& package MyApp;
+\& use Moose;
+\& use Catalyst qw/
+\& ConfigLoader
+\& /;
+\& __PACKAGE__\->setup;
+.Ve
+.PP
+If you need to use Moose in your application class (e.g. for method modifiers
+etc.) then the correct technique is:
+.PP
+.Vb 3
+\& package MyApp;
+\& use Moose;
+\& use Catalyst;
+.Ve
+.PP
+.Vb 1
+\& extends 'Catalyst';
+.Ve
+.PP
+.Vb 4
+\& __PACKAGE__\->config( name => 'MyApp' );
+\& __PACKAGE__\->setup(qw/
+\& ConfigLoader
+\& /);
+.Ve
+.Sh "Anonymous closures installed directly into the symbol table"
+.IX Subsection "Anonymous closures installed directly into the symbol table"
+If you have any code which installs anonymous subroutine references directly
+into the symbol table, you may encounter breakages. The simplest solution is
+to use Sub::Name to name the subroutine. Example:
+.PP
+.Vb 3
+\& # Original code, likely to break:
+\& my $full_method_name = join('::', $package_name, $method_name);
+\& *$full_method_name = sub { ... };
+.Ve
+.PP
+.Vb 4
+\& # Fixed Code
+\& use Sub::Name 'subname';
+\& my $full_method_name = join('::',$package_name, $method_name);
+\& *$full_method_name = subname $full_method_name, sub { ... };
+.Ve
+.PP
+Additionally, you can take advantage of Catalyst's use of Class::MOP and
+install the closure using the appropriate metaclass. Example:
+.PP
+.Vb 3
+\& use Class::MOP;
+\& my $metaclass = Moose::Meta::Class\->initialize($package_name);
+\& $metaclass\->add_method($method_name => sub { ... });
+.Ve
+.Sh "Hooking into application setup"
+.IX Subsection "Hooking into application setup"
+To execute code during application start\-up, the following snippet in MyApp.pm
+used to work:
+.PP
+.Vb 5
+\& sub setup {
+\& my ($class, @args) = @_;
+\& $class\->NEXT::setup(@args);
+\& ... # things to do after the actual setup
+\& }
+.Ve
+.PP
+With Catalyst 5.80 this won't work anymore, because Catalyst no longer
+uses \s-1NEXT\s0.pm for method resolution. The functionality was only ever
+originally operational as \s-1NEXT\s0 remembers what methods have already
+been called, and will not call them again.
+.PP
+Using this now causes infinite recursion between MyApp::setup and
+Catalyst::setup, due to other backwards compatibility issues related to how
+plugin setup works. Moose method modifiers like \f(CW\*(C`before|after|around 'setup
+=> sub { ... };\*(C'\fR also will not operate correctly on the setup method.
+.PP
+The right way to do it is this:
+.PP
+.Vb 3
+\& after setup_finalize => sub {
+\& ... # things to do after the actual setup
+\& };
+.Ve
+.PP
+The setup_finalize hook was introduced as a way to avoid this issue.
+.Sh "Components with a new method which returns false"
+.IX Subsection "Components with a new method which returns false"
+Previously, if you had a component which inherited from Catalyst::COMPONENT,
+but overrode the new method to return false, then your class's configuration
+would be blessed into a hash on your behalf, and this would be returned from
+the \s-1COMPONENT\s0 method.
+.PP
+This behavior makes no sense, and so has been removed. Implementing your own
+\&\f(CW\*(C` new \*(C'\fR method in components is \fBhighly\fR discouraged. Instead, you should
+inherit the new method from Catalyst::Component, and use Moose's \s-1BUILD\s0
+functionality and/or Moose attributes to perform any construction work
+necessary for your class.
+.Sh "_\|_PACKAGE_\|_\->mk_accessor('meta');"
+.IX Subsection "__PACKAGE__->mk_accessor('meta');"
+Won't work due to a limitation of Moose. This is currently being fixed
+inside Moose.
+.Sh "Class::Data::Inheritable side effects"
+.IX Subsection "Class::Data::Inheritable side effects"
+Previously, writing to a class data accessor would copy the accessor method
+down into your package.
+.PP
+This behavior has been removed. While the class data is still stored
+per\-class, it is stored on the metaclass of the class defining the accessor.
+.PP
+Therefore anything relying on the side effect of the accessor being copied down
+will be broken.
+.PP
+The following test demonstrates the problem:
+.PP
+.Vb 5
+\& {
+\& package BaseClass;
+\& use base qw/Class::Data::Inheritable/;
+\& __PACKAGE__\->mk_classdata('foo');
+\& }
+.Ve
+.PP
+.Vb 4
+\& {
+\& package Child;
+\& use base qw/BaseClass/;
+\& }
+.Ve
+.PP
+.Vb 2
+\& BaseClass\->foo('base class');
+\& Child\->foo('sub class');
+.Ve
+.PP
+.Vb 2
+\& use Test::More;
+\& isnt(BaseClass\->can('foo'), Child\->can('foo'));
+.Ve
+.Sh "Extending Catalyst::Request or other classes in an ad-hoc manner using mk_accessors"
+.IX Subsection "Extending Catalyst::Request or other classes in an ad-hoc manner using mk_accessors"
+Previously, it was possible to add additional accessors to Catalyst::Request
+(or other classes) by calling the mk_accessors class method.
+.PP
+This is no longer supported \- users should make a subclass of the class whose
+behavior they would like to change, rather than globally polluting the
+Catalyst objects.
+.Sh "Confused multiple inheritance with Catalyst::Component::COMPONENT"
+.IX Subsection "Confused multiple inheritance with Catalyst::Component::COMPONENT"
+Previously, Catalyst's \s-1COMPONENT\s0 method would delegate to the method on
+the right hand side, which could then delegate back again with
+\&\s-1NEXT\s0. This is poor practice, and in addition, makes no sense with C3
+method dispatch order, and is therefore no longer supported.
+.PP
+If a \s-1COMPONENT\s0 method is detected in the inheritance hierarchy to the right
+hand side of Catalyst::Component::COMPONENT, then the following warning
+message will be emitted:
+.PP
+.Vb 2
+\& There is a COMPONENT method resolving after Catalyst::Component
+\& in ${next_package}.
+.Ve
+.PP
+The correct fix is to re-arrange your class's inheritance hierarchy so that the
+\&\s-1COMPONENT\s0 method you would like to inherit is the first (left\-hand most)
+\&\s-1COMPONENT\s0 method in your \f(CW@ISA\fR.
+.SH "WARNINGS"
+.IX Header "WARNINGS"
+.Sh "Actions in your application class"
+.IX Subsection "Actions in your application class"
+Having actions in your application class will now emit a warning at application
+startup as this is deprecated. It is highly recommended that these actions are moved
+into a MyApp::Controller::Root (as demonstrated by the scaffold application
+generated by catalyst.pl).
+.PP
+This warning, also affects tests. You should move actions in your test,
+creating a myTest::Controller::Root, like the following example:
+.PP
+.Vb 1
+\& package MyTest::Controller::Root;
+.Ve
+.PP
+.Vb 2
+\& use strict;
+\& use warnings;
+.Ve
+.PP
+.Vb 1
+\& use parent 'Catalyst::Controller';
+.Ve
+.PP
+.Vb 1
+\& __PACKAGE__\->config(namespace => '');
+.Ve
+.PP
+.Vb 4
+\& sub action : Local {
+\& my ( $self, $c ) = @_;
+\& $c\->do_something;
+\& }
+.Ve
+.PP
+.Vb 1
+\& 1;
+.Ve
+.Sh "::[\s-1MVC\s0]:: naming scheme"
+.IX Subsection "::[MVC]:: naming scheme"
+Having packages called MyApp::[\s-1MVC\s0]::XX is deprecated and can no longer be generated
+by catalyst.pl
+.PP
+This is still supported, but it is recommended that you rename your application
+components to Model/View/Controller.
+.PP
+A warning will be issued at application startup if the ::[\s-1MVC\s0]:: naming scheme is
+in use.
+.Sh "Catalyst::Base"
+.IX Subsection "Catalyst::Base"
+Any code using Catalyst::Base will now emit a warning; this
+module will be removed in a future release.
+.Sh "Methods in Catalyst::Dispatcher"
+.IX Subsection "Methods in Catalyst::Dispatcher"
+The following methods in Catalyst::Dispatcher are implementation
+details, which may change in the 5.8X release series, and therefore their use
+is highly deprecated.
+.IP "tree" 4
+.IX Item "tree"
+.PD 0
+.IP "dispatch_types" 4
+.IX Item "dispatch_types"
+.IP "registered_dispatch_types" 4
+.IX Item "registered_dispatch_types"
+.IP "method_action_class" 4
+.IX Item "method_action_class"
+.IP "action_hash" 4
+.IX Item "action_hash"
+.IP "container_hash" 4
+.IX Item "container_hash"
+.PD
+.PP
+The first time one of these methods is called, a warning will be emitted:
+.PP
+.Vb 2
+\& Class $class is calling the deprecated method Catalyst::Dispatcher::$public_method_name,
+\& this will be removed in Catalyst 5.9X
+.Ve
+.PP
+You should \fB\s-1NEVER\s0\fR be calling any of these methods from application code.
+.PP
+Plugin authors and maintainers whose plugins currently call these methods
+should change to using the public \s-1API\s0, or, if you do not feel the public \s-1API\s0
+adequately supports your use case, please email the development list to
+discuss what \s-1API\s0 features you need so that you can be appropriately supported.
+.Sh "Class files with names that don't correspond to the packages they define"
+.IX Subsection "Class files with names that don't correspond to the packages they define"
+In this version of Catalyst, if a component is loaded from disk, but no
+symbols are defined in that component's name space after it is loaded, this
+warning will be issued:
+.PP
+.Vb 1
+\& require $class was successful but the package is not defined.
+.Ve
+.PP
+This is to protect against confusing bugs caused by mistyping package names,
+and will become a fatal error in a future version.
+.PP
+Please note that 'inner packages' (via Devel::InnerPackage) are still fully
+supported; this warning is only issued when component file naming does not map
+to \fBany\fR of the packages defined within that component.
+.Sh "$c\->plugin method"
+.IX Subsection "$c->plugin method"
+Calling the plugin method is deprecated, and calling it at run time is \fBhighly
+deprecated\fR.
+.PP
+Instead you are recommended to use Catalyst::Model::Adaptor or similar to
+compose the functionality you need outside of the main application name space.
+.PP
+Calling the plugin method will not be supported past Catalyst 5.81.
projects / catagits/Gitalist.git / blobdiff