X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=README.mkdn;h=6eec9eae5af45273e1afb98f321cc4ef9e853ac5;hb=feaaa3d438b9b71a9d577dfefbfc2fc1262e9f16;hp=f30025cae2efee41b0a6962a850e3e03a809d512;hpb=9e7f288e0bd785c69c8e54c77d951b2e878f5b8f;p=catagits%2FCatalyst-Runtime.git
diff --git a/README.mkdn b/README.mkdn
index f30025c..6eec9ea 100644
--- a/README.mkdn
+++ b/README.mkdn
@@ -2,13 +2,6 @@
Catalyst - The Elegant MVC Web Application Framework
-
-
# SYNOPSIS
See the [Catalyst::Manual](https://metacpan.org/pod/Catalyst::Manual) distribution for comprehensive
@@ -291,7 +284,7 @@ the relationship between
`$c->go` will perform a full dispatch on the specified action or method,
with localized `$c->action` and `$c->namespace`. Like `detach`,
`go` escapes the processing of the current request chain on completion, and
-does not return to its cunless blessed $cunless blessed $caller.
+does not return to its caller.
@arguments are arguments to the final destination of $action. @captures are
arguments to the intermediate steps, if any, on the way to the final sub of
@@ -357,6 +350,11 @@ Contains the return value of the last executed action.
Note that << $c->state >> operates in a scalar context which means that all
values it returns are scalar.
+Please note that if an action throws an exception, the value of state
+should no longer be considered the return if the last action. It is generally
+going to be 0, which indicates an error state. Examine $c->error for error
+details.
+
## $c->clear\_errors
Clear errors. You probably don't want to clear the errors unless you are
@@ -373,11 +371,17 @@ Returns true if you have errors
## $c->last\_error
Returns the most recent error in the stack (the one most recently added...)
-or nothing if there are no errors.
+or nothing if there are no errors. This does not modify the contents of the
+error stack.
## shift\_errors
-shifts the most recently added error off the error stack and returns if. Returns
+shifts the most recently added error off the error stack and returns it. Returns
+nothing if there are no more errors.
+
+## pop\_errors
+
+pops the most recently added error off the error stack and returns it. Returns
nothing if there are no more errors.
## COMPONENT ACCESSORS
@@ -632,11 +636,11 @@ Example:
## do stuff here..
};
-## $c->uri\_for( $path?, @args?, \\%query\_values? )
+## $c->uri\_for( $path?, @args?, \\%query\_values?, \\$fragment? )
-## $c->uri\_for( $action, \\@captures?, @args?, \\%query\_values? )
+## $c->uri\_for( $action, \\@captures?, @args?, \\%query\_values?, \\$fragment? )
-## $c->uri\_for( $action, \[@captures, @args\], \\%query\_values? )
+## $c->uri\_for( $action, \[@captures, @args\], \\%query\_values?, \\$fragment? )
Constructs an absolute [URI](https://metacpan.org/pod/URI) object based on the application root, the
provided path, and the additional arguments and query parameters provided.
@@ -654,6 +658,15 @@ relative to the application root (if it does). It is then merged with
`$c->request->base`; any `@args` are appended as additional path
components; and any `%query_values` are appended as `?foo=bar` parameters.
+**NOTE** If you are using this 'stringy' first argument, we skip encoding and
+allow you to declare something like:
+
+ $c->uri_for('/foo/bar#baz')
+
+Where 'baz' is a URI fragment. We consider this first argument string to be
+'expert' mode where you are expected to create a valid URL and we for the most
+part just pass it through without a lot of internal effort to escape and encode.
+
If the first argument is a [Catalyst::Action](https://metacpan.org/pod/Catalyst::Action) it represents an action which
will have its path resolved using `$c->dispatcher->uri_for_action`. The
optional `\@captures` argument (an arrayref) allows passing the captured
@@ -714,7 +727,7 @@ constraints.
- \\@captures\_and\_args?
- Optional array reference of Captures (i.e. `captures>)
+ Optional array reference of Captures (i.e. `CaptureArgs` or `$c->req->captures`)
and arguments to the request. Usually used with [Catalyst::DispatchType::Chained](https://metacpan.org/pod/Catalyst::DispatchType::Chained)
to interpolate all the parameters in the URI.
@@ -971,7 +984,26 @@ Returns or sets the request class. Defaults to [Catalyst::Request](https://metac
## $app->request\_class\_traits
-An arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s which are applied to the request class.
+An arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s which are applied to the request class. You can
+name the full namespace of the role, or a namespace suffix, which will then
+be tried against the following standard namespace prefixes.
+
+ $MyApp::TraitFor::Request::$trait_suffix
+ Catalyst::TraitFor::Request::$trait_suffix
+
+So for example if you set:
+
+ MyApp->request_class_traits(['Foo']);
+
+We try each possible role in turn (and throw an error if none load)
+
+ Foo
+ MyApp::TraitFor::Request::Foo
+ Catalyst::TraitFor::Request::Foo
+
+The namespace part 'TraitFor::Request' was chosen to assist in backwards
+compatibility with [CatalystX::RoleApplicator](https://metacpan.org/pod/CatalystX::RoleApplicator) which previously provided
+these features in a stand alone package.
## $app->composed\_request\_class
@@ -983,7 +1015,26 @@ Returns or sets the response class. Defaults to [Catalyst::Response](https://met
## $app->response\_class\_traits
-An arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s which are applied to the response class.
+An arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s which are applied to the response class. You can
+name the full namespace of the role, or a namespace suffix, which will then
+be tried against the following standard namespace prefixes.
+
+ $MyApp::TraitFor::Response::$trait_suffix
+ Catalyst::TraitFor::Response::$trait_suffix
+
+So for example if you set:
+
+ MyApp->response_class_traits(['Foo']);
+
+We try each possible role in turn (and throw an error if none load)
+
+ Foo
+ MyApp::TraitFor::Response::Foo
+ Catalyst::TraitFor::Responset::Foo
+
+The namespace part 'TraitFor::Response' was chosen to assist in backwards
+compatibility with [CatalystX::RoleApplicator](https://metacpan.org/pod/CatalystX::RoleApplicator) which previously provided
+these features in a stand alone package.
## $app->composed\_response\_class
@@ -1109,7 +1160,7 @@ component or component object. Example:
my $config = MyApp->config_for('MyApp::Model::Foo');
-In this case $config is the hashref ` {a=`1, b=>2} >.
+In this case $config is the hashref `{a=>1, b=>2}`.
This is also handy for looking up configuration for a plugin, to make sure you follow
existing [Catalyst](https://metacpan.org/pod/Catalyst) standards for where a plugin should put its configuration.
@@ -1186,15 +1237,44 @@ Sets up the input/output encoding. See [ENCODING](https://metacpan.org/pod/ENCOD
## handle\_unicode\_encoding\_exception
-Hook to let you customize how encoding errors are handled. By default
-we just throw an exception. Receives a hashref of debug information.
-Example:
+Hook to let you customize how encoding errors are handled. By default
+we just throw an exception and the default error page will pick it up.
+Receives a hashref of debug information. Example of call (from the
+Catalyst internals):
- $c->handle_unicode_encoding_exception({
- param_value => $value,
- error_msg => $_,
- encoding_step => 'params',
- });
+ my $decoded_after_fail = $c->handle_unicode_encoding_exception({
+ param_value => $value,
+ error_msg => $_,
+ encoding_step => 'params',
+ });
+
+The calling code expects to receive a decoded string or an exception.
+
+You can override this for custom handling of unicode errors. By
+default we just die. If you want a custom response here, one approach
+is to throw an HTTP style exception, instead of returning a decoded
+string or throwing a generic exception.
+
+ sub handle_unicode_encoding_exception {
+ my ($c, $params) = @_;
+ HTTP::Exception::BAD_REQUEST->throw(status_message=>$params->{error_msg});
+ }
+
+Alternatively you can 'catch' the error, stash it and write handling code later
+in your application:
+
+ sub handle_unicode_encoding_exception {
+ my ($c, $params) = @_;
+ $c->stash(BAD_UNICODE_DATA=>$params);
+ # return a dummy string.
+ return 1;
+ }
+
+NOTE:</b> Please keep in mind that once an error like this occurs,
+the request setup is still ongoing, which means the state of `$c` and
+related context parts like the request and response may not be setup
+up correctly (since we haven't finished the setup yet). If you throw
+an exception the setup is aborted.
## $c->setup\_log
@@ -1325,14 +1405,14 @@ only two default data handlers, for 'application/json' and an alternative to
[CGI::Struct](https://metacpan.org/pod/CGI::Struct) or via [CGI::Struct::XS](https://metacpan.org/pod/CGI::Struct::XS) IF you've installed it.
The 'application/json' data handler is used to parse incoming JSON into a Perl
-data structure. It used either [JSON::MaybeXS](https://metacpan.org/pod/JSON::MaybeXS) or [JSON](https://metacpan.org/pod/JSON), depending on which
-is installed. This allows you to fail back to [JSON:PP](JSON:PP), which is a Pure Perl
-JSON decoder, and has the smallest dependency impact.
+data structure. It uses [JSON::MaybeXS](https://metacpan.org/pod/JSON::MaybeXS). This allows you to fail back to
+[JSON::PP](https://metacpan.org/pod/JSON::PP), which is a Pure Perl JSON decoder, and has the smallest dependency
+impact.
Because we don't wish to add more dependencies to [Catalyst](https://metacpan.org/pod/Catalyst), if you wish to
-use this new feature we recommend installing [JSON](https://metacpan.org/pod/JSON) or [JSON::MaybeXS](https://metacpan.org/pod/JSON::MaybeXS) in
-order to get the best performance. You should add either to your dependency
-list (Makefile.PL, dist.ini, cpanfile, etc.)
+use this new feature we recommend installing [Cpanel::JSON::XS](https://metacpan.org/pod/Cpanel::JSON::XS) in order to get
+the best performance. You should add either to your dependency list
+(Makefile.PL, dist.ini, cpanfile, etc.)
## $c->stack
@@ -1346,7 +1426,7 @@ Returns the current timing statistics object. By default Catalyst uses
[stats\_class](#c-stats_class).
Even if [-Stats](#stats) is not enabled, the stats object is still
-available. By enabling it with ` $c-`stats->enabled(1) >, it can be used to
+available. By enabling it with `$c->stats->enabled(1)`, it can be used to
profile explicitly, although MyApp.pm still won't profile nor output anything
by itself.
@@ -1360,7 +1440,26 @@ A arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s that are appl
## $app->composed\_stats\_class
-this is the stats\_class composed with any 'stats\_class\_traits'.
+this is the stats\_class composed with any 'stats\_class\_traits'. You can
+name the full namespace of the role, or a namespace suffix, which will then
+be tried against the following standard namespace prefixes.
+
+ $MyApp::TraitFor::Stats::$trait_suffix
+ Catalyst::TraitFor::Stats::$trait_suffix
+
+So for example if you set:
+
+ MyApp->stats_class_traits(['Foo']);
+
+We try each possible role in turn (and throw an error if none load)
+
+ Foo
+ MyApp::TraitFor::Stats::Foo
+ Catalyst::TraitFor::Stats::Foo
+
+The namespace part 'TraitFor::Stats' was chosen to assist in backwards
+compatibility with [CatalystX::RoleApplicator](https://metacpan.org/pod/CatalystX::RoleApplicator) which previously provided
+these features in a stand alone package.
## $c->use\_stats
@@ -1464,18 +1563,19 @@ This has been done since not all people need this feature and we wish to restric
- `abort_chain_on_error_fix`
- When there is an error in an action chain, the default behavior is to continue
- processing the remaining actions and then catch the error upon chain end. This
- can lead to running actions when the application is in an unexpected state. If
- you have this issue, setting this config value to true will promptly exit a
- chain when there is an error raised in any action (thus terminating the chain
- early.)
+ Defaults to true.
+
+ When there is an error in an action chain, the default behavior is to
+ abort the processing of the remaining actions to avoid running them
+ when the application is in an unexpected state.
- use like:
+ Before version 5.90070, the default used to be false. To keep the old
+ behaviour, you can explicitly set the value to false. E.g.
- __PACKAGE__->config(abort_chain_on_error_fix => 1);
+ __PACKAGE__->config(abort_chain_on_error_fix => 0);
- In the future this might become the default behavior.
+ If this setting is set to false, then the remaining actions are
+ performed and the error is caught at the end of the chain.
- `use_hash_multivalue_in_request`
@@ -1497,7 +1597,7 @@ This has been done since not all people need this feature and we wish to restric
- `skip_complex_post_part_handling`
- When creating body parameters from a POST, if we run into a multpart POST
+ When creating body parameters from a POST, if we run into a multipart POST
that does not contain uploads, but instead contains inlined complex data
(very uncommon) we cannot reliably convert that into field => value pairs. So
instead we create an instance of [Catalyst::Request::PartData](https://metacpan.org/pod/Catalyst::Request::PartData). If this causes
@@ -1515,30 +1615,29 @@ This has been done since not all people need this feature and we wish to restric
- `do_not_decode_query`
If true, then do not try to character decode any wide characters in your
- request URL query or keywords. Most readings of the relevent specifications
+ request URL query or keywords. Most readings of the relevant specifications
suggest these should be UTF-\* encoded, which is the default that [Catalyst](https://metacpan.org/pod/Catalyst)
- will use, hwoever if you are creating a lot of URLs manually or have external
+ will use, however if you are creating a lot of URLs manually or have external
evil clients, this might cause you trouble. If you find the changes introduced
in Catalyst version 5.90080+ break some of your query code, you may disable
the UTF-8 decoding globally using this configuration.
- This setting takes precedence over `default_query_encoding` and
- `decode_query_using_global_encoding`
+ This setting takes precedence over `default_query_encoding`
+
+- `do_not_check_query_encoding`
+
+ Catalyst versions 5.90080 - 5.90106 would decode query parts of an incoming
+ request but would not raise an exception when the decoding failed due to
+ incorrect unicode. It now does, but if this change is giving you trouble
+ you may disable it by setting this configuration to true.
- `default_query_encoding`
By default we decode query and keywords in your request URL using UTF-8, which
- is our reading of the relevent specifications. This setting allows one to
+ is our reading of the relevant specifications. This setting allows one to
specify a fixed value for how to decode your query. You might need this if
you are doing a lot of custom encoding of your URLs and not using UTF-8.
- This setting take precedence over `decode_query_using_global_encoding`.
-
-- `decode_query_using_global_encoding`
-
- Setting this to true will default your query decoding to whatever your
- general global encoding is (the default is UTF-8).
-
- `use_chained_args_0_special_case`
In older versions of Catalyst, when more than one action matched the same path
@@ -1553,15 +1652,15 @@ This has been done since not all people need this feature and we wish to restric
- `data_handlers` - See ["DATA HANDLERS"](#data-handlers).
- `stats_class_traits`
- An arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s that get componsed into your stats class.
+ An arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s that get composed into your stats class.
- `request_class_traits`
- An arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s that get componsed into your request class.
+ An arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s that get composed into your request class.
- `response_class_traits`
- An arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s that get componsed into your response class.
+ An arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s that get composed into your response class.
- `inject_components`
@@ -1717,7 +1816,7 @@ that parses that content type into something Perl can readily access.
package MyApp::Web;
use Catalyst;
- use JSON::Maybe;
+ use JSON::MaybeXS;
__PACKAGE__->config(
data_handlers => {
@@ -1729,7 +1828,7 @@ that parses that content type into something Perl can readily access.
__PACKAGE__->setup;
By default [Catalyst](https://metacpan.org/pod/Catalyst) comes with a generic JSON data handler similar to the
-example given above, which uses [JSON::Maybe](https://metacpan.org/pod/JSON::Maybe) to provide either [JSON::PP](https://metacpan.org/pod/JSON::PP)
+example given above, which uses [JSON::MaybeXS](https://metacpan.org/pod/JSON::MaybeXS) to provide either [JSON::PP](https://metacpan.org/pod/JSON::PP)
(a pure Perl, dependency free JSON parser) or [Cpanel::JSON::XS](https://metacpan.org/pod/Cpanel::JSON::XS) if you have
it installed (if you want the faster XS parser, add it to you project Makefile.PL
or dist.ini, cpanfile, etc.)
@@ -1899,6 +1998,11 @@ the encoding configuration to undef.
This is recommended for temporary backwards compatibility only.
+To turn it off for a single request use the [clear\_encoding](https://metacpan.org/pod/clear_encoding)
+method to turn off encoding for this request. This can be useful
+when you are setting the body to be an arbitrary block of bytes,
+especially if that block happens to be a block of UTF8 text.
+
Encoding is automatically applied when the content-type is set to
a type that can be encoded. Currently we encode when the content type
matches the following regular expression:
@@ -2009,7 +2113,7 @@ acme: Leon Brocard
abraxxa: Alexander Hartmaier
-andrewalker: André Walker
+andrewalker: André Walker
Andrew Bramble
@@ -2027,17 +2131,19 @@ Caelum: Rafael Kitover
chansen: Christian Hansen
+Chase Venters
+
chicks: Christopher Hicks
-Chisel Wright `pause@herlpacker.co.uk`
+Chisel Wright
-Danijel Milicevic `me@danijel.de`
+Danijel Milicevic
davewood: David Schmidt
David Kamholz
-David Naughton, `naughton@umn.edu`
+David Naughton
David E. Wheeler
@@ -2059,7 +2165,7 @@ gabb: Danijel Milicevic
Gary Ashton Jones
-Gavin Henry `ghenry@perl.me.uk`
+Gavin Henry
Geoff Richards
@@ -2067,11 +2173,11 @@ groditi: Guillermo Roditi
hobbs: Andrew Rodland
-ilmari: Dagfinn Ilmari Mannsåker
+ilmari: Dagfinn Ilmari Mannsåker
jcamacho: Juan Camacho
-jester: Jesse Sheidlower `jester@panix.com`
+jester: Jesse Sheidlower
jhannah: Jay Hannah
@@ -2081,9 +2187,9 @@ Johan Lindstrom
jon: Jon Schutz
-Jonathan Rockway ``
+Jonathan Rockway
-Kieren Diment `kd@totaldatasolution.com`
+Kieren Diment
konobi: Scott McWhirter
@@ -2119,7 +2225,9 @@ rafl: Florian Ragwitz
random: Roland Lammel
-Robert Sedlacek ``
+revmischa: Mischa Spiegelmock
+
+Robert Sedlacek
SpiceMan: Marcel Montes
@@ -2133,17 +2241,17 @@ Ulf Edvinsson
vanstyn: Henry Van Styn
-Viljo Marrandi `vilts@yahoo.com`
+Viljo Marrandi
-Will Hawes `info@whawes.co.uk`
+Will Hawes
willert: Sebastian Willert
wreis: Wallace Reis
-Yuval Kogman, `nothingmuch@woobling.org`
+Yuval Kogman
-rainboxx: Matthias Dietrich, `perl@rainboxx.de`
+rainboxx: Matthias Dietrich
dd070: Dhaval Dhanani