Change all classes to Moose

[catagits/Catalyst-Action-REST.git] / lib / Catalyst / Controller / REST.pm

diff --git a/lib/Catalyst/Controller/REST.pm b/lib/Catalyst/Controller/REST.pm
index 2cd5f47..f2c6a3f 100644 (file)
--- a/lib/Catalyst/Controller/REST.pm
+++ b/lib/Catalyst/Controller/REST.pm
@@ -1,8 +1,8 @@
 package Catalyst::Controller::REST;
-use strict;
-use warnings;
+use Moose;
+use namespace::autoclean;
 
-our $VERSION = '0.78';
+our $VERSION = '0.79';
 $VERSION = eval $VERSION;
 
 =head1 NAME
@@ -12,8 +12,10 @@ Catalyst::Controller::REST - A RESTful controller
 =head1 SYNOPSIS
 
     package Foo::Controller::Bar;
-
-    use base 'Catalyst::Controller::REST';
+    use Moose;
+    use namespace::autoclean;
+    
+    BEGIN { extends 'Catalyst::Controller::REST' }
 
     sub thing : Local : ActionClass('REST') { }
 
@@ -34,8 +36,16 @@ Catalyst::Controller::REST - A RESTful controller
 
     # Answer PUT requests to "thing"
     sub thing_PUT {
-      ... some action ...
-    }
+        $radiohead = $req->data->{radiohead};
+        
+        $self->status_created(
+            $c,
+            location => $c->req->uri->as_string,
+            entity => {
+                radiohead => $radiohead,
+            }
+        );
+    }     
 
 =head1 DESCRIPTION
 
@@ -67,21 +77,23 @@ The serialization format will be selected based on the content-type
 of the incoming request.  It is probably easier to use the L<STATUS HELPERS>,
 which are described below.
 
-The HTTP POST, PUT, and OPTIONS methods will all automatically deserialize the
-contents of $c->request->body based on the requests content-type header.
-A list of understood serialization formats is below.
+"The HTTP POST, PUT, and OPTIONS methods will all automatically
+L<deserialize|Catalyst::Action::Deserialize> the contents of
+C<< $c->request->body >> into the C<< $c->request->data >> hashref", based on 
+the request's C<Content-type> header. A list of understood serialization
+formats is L<below|/AVAILABLE SERIALIZERS>.
 
 If we do not have (or cannot run) a serializer for a given content-type, a 415
 "Unsupported Media Type" error is generated.
 
 To make your Controller RESTful, simply have it
 
-  BEGIN {extends 'Catalyst::Controller::REST'; }
-
-Or if you use pre-Moose Catalyst versions,
+  BEGIN { extends 'Catalyst::Controller::REST' }
 
-  use parent 'Catalyst::Controller::REST';
+=head1 CONFIGURATION
 
+See L<Catalyst::Action::Serialize/CONFIGURATION>. Note that the C<serialize>
+key has been deprecated.
 
 =head1 SERIALIZATION
 
@@ -90,7 +102,7 @@ responses, and deserialize any POST, PUT or OPTIONS requests. It evaluates
 which serializer to use by mapping a content-type to a Serialization module.
 We select the content-type based on:
 
-=over 2
+=over
 
 =item B<The Content-Type Header>
 
@@ -107,7 +119,6 @@ it and use the best-ranked choice.
 
 =back
 
-
 =head1 AVAILABLE SERIALIZERS
 
 A given serialization mechanism is only available if you have the underlying
@@ -174,12 +185,37 @@ you serialize be a HASHREF, we transform outgoing data to be in the form of:
 =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:
+C<text/html> and C<text/xml> views rendered by TT, set:
+
+  __PACKAGE__->config(
+      map => {
+          'text/html' => [ 'View', 'TT' ],
+          'text/xml'  => [ 'View', 'XML' ],
+      }
+  );
 
-  'text/html' => [ 'View', 'TT' ],
-  'text/xml'  => [ 'View', 'XML' ],
+Your views should have a C<process> method like this:
 
-Will do the trick nicely.
+  sub process {
+      my ( $self, $c, $stash_key ) = @_;
+
+      my $output;
+      eval {
+          $output = $self->serialize( $c->stash->{$stash_key} );
+      };
+      return $@ if $@;
+
+      $c->response->body( $output );
+      return 1;  # important
+  }
+  
+  sub serialize {
+      my ( $self, $data ) = @_;
+
+      my $serialized = ... process $data here ...
+
+      return $serialized;
+  }
 
 =back
 
@@ -188,7 +224,7 @@ 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';
+  __PACKAGE__->config(default => 'text/x-yaml');
 
 would make it always fall back to the serializer plugin defined for
 C<text/x-yaml>.
@@ -215,11 +251,11 @@ refer to it at: L<http://www.w3.org/Protocols/rfc2616/rfc2616.txt>.
 These routines are all implemented as regular subroutines, and as
 such require you pass the current context ($c) as the first argument.
 
-=over 4
+=over
 
 =cut
 
-use base 'Catalyst::Controller';
+BEGIN { extends 'Catalyst::Controller' }
 use Params::Validate qw(SCALAR OBJECT);
 
 __PACKAGE__->mk_accessors(qw(serialize));
@@ -486,8 +522,11 @@ method uses L<Catalyst::Action::Serialize>.  If you want to override
 either behavior, simply implement your own C<begin> and C<end> actions
 and use MRO::Compat:
 
-  my Foo::Controller::Monkey;
-  use base qw(Catalyst::Controller::REST);
+  package Foo::Controller::Monkey;
+  use Moose;
+  use namespace::autoclean;
+  
+  BEGIN { extends 'Catalyst::Controller::REST' }
 
   sub begin :Private {
     my ($self, $c) = @_;
@@ -524,15 +563,9 @@ Wikipedia! http://en.wikipedia.org/wiki/Representational_State_Transfer
 
 The REST Wiki: http://rest.blueoxen.net/cgi-bin/wiki.pl?FrontPage
 
-=head1 AUTHOR
-
-Adam Jacob <adam@stalecoffee.org>, with lots of help from mst and jrockway
-
-Marchex, Inc. paid me while I developed this module.  (http://www.marchex.com)
-
-=head1 MAINTAINER
+=head1 AUTHORS
 
-J. Shirley <jshirley@cpan.org>
+See L<Catalyst::Action::REST> for authors.
 
 =head1 LICENSE