Skip to content

Commit

Permalink
Cosmetic changes to C::C::REST POD
Browse files Browse the repository at this point in the history
  • Loading branch information
@dandv
dandv committed Dec 10, 2009
1 parent f3394d8 commit 9531846
Showing 1 changed file with 53 additions and 51 deletions.
104 changes: 53 additions & 51 deletions lib/Catalyst/Controller/REST.pm
View file
Expand Up @@ -34,7 +34,7 @@ Catalyst::Controller::REST - A RESTful controller
# Answer PUT requests to "thing"
sub thing_PUT {
.. some action ..
... some action ...
}
=head1 DESCRIPTION
Expand Down Expand Up @@ -76,7 +76,12 @@ If we do not have (or cannot run) a serializer for a given content-type, a 415
To make your Controller RESTful, simply have it
use base 'Catalyst::Controller::REST';
BEGIN {extends 'Catalyst::Controller::REST'; }
Or if you use pre-Moose Catalyst versions,
use parent 'Catalyst::Controller::REST';
=head1 SERIALIZATION
Expand All @@ -102,70 +107,71 @@ it and use the best-ranked choice.
=back
=head1 AVAILABLE SERIALIZERS
A given serialization mechanism is only available if you have the underlying
modules installed. For example, you can't use XML::Simple if it's not already
installed.
In addition, each serializer has it's quirks in terms of what sorts of data
In addition, each serializer has its quirks in terms of what sorts of data
structures it will properly handle. L<Catalyst::Controller::REST> makes
no attempt to save you from yourself in this regard. :)
=over 2
=item C<text/x-yaml> => C<YAML::Syck>
=item * C<text/x-yaml> => C<YAML::Syck>
Returns YAML generated by L<YAML::Syck>.
=item C<text/html> => C<YAML::HTML>
=item * C<text/html> => C<YAML::HTML>
This uses L<YAML::Syck> and L<URI::Find> to generate YAML with all URLs turned
to hyperlinks. Only useable for Serialization.
=item C<application/json> => C<JSON>
=item * C<application/json> => C<JSON>
Uses L<JSON> to generate JSON output. It is strongly advised to also have
L<JSON::XS> installed. The C<text/x-json> content type is supported but is
deprecated and you will receive warnings in your log.
=item C<text/x-data-dumper> => C<Data::Serializer>
=item * C<text/x-data-dumper> => C<Data::Serializer>
Uses the L<Data::Serializer> module to generate L<Data::Dumper> output.
=item C<text/x-data-denter> => C<Data::Serializer>
=item * C<text/x-data-denter> => C<Data::Serializer>
Uses the L<Data::Serializer> module to generate L<Data::Denter> output.
=item C<text/x-data-taxi> => C<Data::Serializer>
=item * C<text/x-data-taxi> => C<Data::Serializer>
Uses the L<Data::Serializer> module to generate L<Data::Taxi> output.
=item C<application/x-storable> => C<Data::Serializer>
=item * C<application/x-storable> => C<Data::Serializer>
Uses the L<Data::Serializer> module to generate L<Storable> output.
=item C<application/x-freezethaw> => C<Data::Serializer>
=item * C<application/x-freezethaw> => C<Data::Serializer>
Uses the L<Data::Serializer> module to generate L<FreezeThaw> output.
=item C<text/x-config-general> => C<Data::Serializer>
=item * C<text/x-config-general> => C<Data::Serializer>
Uses the L<Data::Serializer> module to generate L<Config::General> output.
=item C<text/x-php-serialization> => C<Data::Serializer>
=item * C<text/x-php-serialization> => C<Data::Serializer>
Uses the L<Data::Serializer> module to generate L<PHP::Serialization> output.
=item C<text/xml> => C<XML::Simple>
=item * C<text/xml> => C<XML::Simple>
Uses L<XML::Simple> to generate XML output. This is probably not suitable
for any real heavy XML work. Due to L<XML::Simple>s requirement that the data
you serialize be a HASHREF, we transform outgoing data to be in the form of:
{ data => $yourdata }
=item L<View>
=item * L<View>
Uses a regular Catalyst view. For example, if you wanted to have your
C<text/html> and C<text/xml> views rendered by TT:
Expand All @@ -177,25 +183,26 @@ Will do the trick nicely.
=back
By default, L<Catalyst::Controller::REST> will return a C<415 Unsupported Media Type>
response if an attempt to use an unsupported content-type is made. You
can ensure that something is always returned by setting the C<default>
config option:
By default, L<Catalyst::Controller::REST> will return a
C<415 Unsupported Media Type> response if an attempt to use an unsupported
content-type is made. You can ensure that something is always returned by
setting the C<default> config option:
__PACKAGE__->config->{'default'} = 'text/x-yaml';
Would make it always fall back to the serializer plugin defined for text/x-yaml.
Implementing new Serialization formats is easy! Contributions
are most welcome! See L<Catalyst::Action::Serialize> and
L<Catalyst::Action::Deserialize> for more information.
would make it always fall back to the serializer plugin defined for
C<text/x-yaml>.
=head1 CUSTOM SERIALIZERS
If you would like to implement a custom serializer, you should create two new
modules in the L<Catalyst::Action::Serialize> and
L<Catalyst::Action::Deserialize> namespace. Then assign your new class
to the content-type's you want, and you're done.
Implementing new Serialization formats is easy! Contributions
are most welcome! If you would like to implement a custom serializer,
you should create two new modules in the L<Catalyst::Action::Serialize>
and L<Catalyst::Action::Deserialize> namespace. Then assign your new
class to the content-type's you want, and you're done.
See L<Catalyst::Action::Serialize> and L<Catalyst::Action::Deserialize>
for more information.
=head1 STATUS HELPERS
Expand Down Expand Up @@ -228,9 +235,9 @@ __PACKAGE__->config(
'text/x-data-dumper' => [ 'Data::Serializer', 'Data::Dumper' ],
'text/x-data-denter' => [ 'Data::Serializer', 'Data::Denter' ],
'text/x-data-taxi' => [ 'Data::Serializer', 'Data::Taxi' ],
'application/x-storable' => [ 'Data::Serializer', 'Storable' ],
'application/x-freezethaw' => [ 'Data::Serializer', 'FreezeThaw' ],
'text/x-config-general' => [ 'Data::Serializer', 'Config::General' ],
'application/x-storable' => [ 'Data::Serializer', 'Storable' ],
'application/x-freezethaw' => [ 'Data::Serializer', 'FreezeThaw' ],
'text/x-config-general' => [ 'Data::Serializer', 'Config::General' ],
'text/x-php-serialization' => [ 'Data::Serializer', 'PHP::Serialization' ],
},
);
Expand Down Expand Up @@ -452,26 +459,21 @@ L<Catalyst::Action::Serialize> and L<Catalyst::Action::Deserialize>. It should
This class provides a default configuration for Serialization. It is currently:
__PACKAGE__->config(
serialize => {
'stash_key' => 'rest',
'map' => {
'text/html' => 'YAML::HTML',
'text/xml' => 'XML::Simple',
'text/x-yaml' => 'YAML',
'application/json' => 'JSON',
'text/x-json' => 'JSON',
'text/x-data-dumper' => [ 'Data::Serializer', 'Data::Dumper' ],
'text/x-data-denter' => [ 'Data::Serializer', 'Data::Denter' ],
'text/x-data-taxi' => [ 'Data::Serializer', 'Data::Taxi' ],
'application/x-storable' => [ 'Data::Serializer', 'Storable'
],
'application/x-freezethaw' => [ 'Data::Serializer', 'FreezeThaw'
],
'text/x-config-general' => [ 'Data::Serializer', 'Config::General' ]
,
'text/x-php-serialization' => [ 'Data::Serializer', 'PHP::Serialization' ],
},
}
'stash_key' => 'rest',
'map' => {
'text/html' => 'YAML::HTML',
'text/xml' => 'XML::Simple',
'text/x-yaml' => 'YAML',
'application/json' => 'JSON',
'text/x-json' => 'JSON',
'text/x-data-dumper' => [ 'Data::Serializer', 'Data::Dumper' ],
'text/x-data-denter' => [ 'Data::Serializer', 'Data::Denter' ],
'text/x-data-taxi' => [ 'Data::Serializer', 'Data::Taxi' ],
'application/x-storable' => [ 'Data::Serializer', 'Storable' ],
'application/x-freezethaw' => [ 'Data::Serializer', 'FreezeThaw' ],
'text/x-config-general' => [ 'Data::Serializer', 'Config::General' ],
'text/x-php-serialization' => [ 'Data::Serializer', 'PHP::Serialization' ],
},
);
You can read the full set of options for this configuration block in
Expand Down

0 comments on commit 9531846

Please sign in to comment.