minor doc improvements

[catagits/Catalyst-Runtime.git] / lib / Catalyst.pm

diff --git a/lib/Catalyst.pm b/lib/Catalyst.pm
index 981b20f..a43be27 100644 (file)
--- a/lib/Catalyst.pm
+++ b/lib/Catalyst.pm
@@ -17,7 +17,7 @@ use Text::SimpleTable;
 use Path::Class;
 use Time::HiRes qw/gettimeofday tv_interval/;
 use URI;
-use Scalar::Util qw/weaken/;
+use Scalar::Util qw/weaken blessed/;
 use Tree::Simple qw/use_weak_refs/;
 use Tree::Simple::Visitor::FindByUID;
 use attributes;
@@ -219,7 +219,7 @@ Specifies log level.
 
 =head1 METHODS
 
-=head2 Information about the current request
+=head2 INFORMATION ABOUT THE CURRENT REQUEST
 
 =head2 $c->action
 
@@ -241,7 +241,7 @@ corresponding to the controller of the current action. For example:
 Returns the current L<Catalyst::Request> object. See
 L<Catalyst::Request>.
 
-=head2 Processing and response to the current request
+=head2 PROCESSING AND RESPONSE TO THE CURRENT REQUEST
 
 =head2 $c->forward( $action [, \@arguments ] )
 
@@ -346,7 +346,60 @@ sub stash {
 
 Contains the return value of the last executed action.
 
-=head2 Component Accessors
+=cut
+
+# search via regex
+sub _comp_search {
+    my ($c, @names) = @_;
+
+    foreach my $name (@names) {
+        foreach my $component ( keys %{ $c->components } ) {
+            my $comp = $c->components->{$component} if $component =~ /$name/i;
+            if ($comp) {
+                if ( eval { $comp->can('ACCEPT_CONTEXT'); } ) {
+                    return $comp->ACCEPT_CONTEXT($c);
+                }
+                else { return $comp }
+            }
+        }
+    }
+
+    return undef;
+}
+
+# try explicit component names
+sub _comp_explicit {
+    my ($c, @names) = @_;
+
+    foreach my $try (@names) {
+        if ( exists $c->components->{$try} ) {
+            my $comp = $c->components->{$try};
+            if ( eval { $comp->can('ACCEPT_CONTEXT'); } ) {
+                return $comp->ACCEPT_CONTEXT($c);
+            }
+            else { return $comp }
+        }
+    }
+
+    return undef;
+}
+
+# like component, but try just these prefixes before regex searching,
+#  and do not try to return "sort keys %{ $c->components }"
+sub _comp_prefixes {
+    my ($c, $name, @prefixes) = @_;
+
+    my $appclass = ref $c || $c;
+
+    my @names = map { "${appclass}::${_}::${name}" } @prefixes;
+
+    my $comp = $c->_comp_explicit(@names);
+    return $comp if defined($comp);
+    $comp = $c->_comp_search($name);
+    return $comp;
+}
+
+=head2 COMPONENT ACCESSORS
 
 =head2 $c->comp($name)
 
@@ -374,29 +427,11 @@ sub component {
               qw/Model M Controller C View V/
         );
 
-        foreach my $try (@names) {
-
-            if ( exists $c->components->{$try} ) {
-
-                my $comp = $c->components->{$try};
-                if ( eval { $comp->can('ACCEPT_CONTEXT'); } ) {
-                    return $comp->ACCEPT_CONTEXT($c);
-                }
-                else { return $comp }
-            }
-        }
-
-        foreach my $component ( keys %{ $c->components } ) {
-            my $comp;
-            $comp = $c->components->{$component} if $component =~ /$name/i;
-            if ($comp) {
-                if ( ref $comp && $comp->can('ACCEPT_CONTEXT') ) {
-                    return $comp->ACCEPT_CONTEXT($c);
-                }
-                else { return $comp }
-            }
-        }
+        my $comp = $c->_comp_explicit(@names);
+        return $comp if defined($comp);
 
+        $comp = $c->_comp_search($name);
+        return $comp if defined($comp);
     }
 
     return sort keys %{ $c->components };
@@ -412,9 +447,7 @@ Gets a L<Catalyst::Controller> instance by name.
 
 sub controller {
     my ( $c, $name ) = @_;
-    my $controller = $c->comp("Controller::$name");
-    return $controller if defined $controller;
-    return $c->comp("C::$name");
+    return $c->_comp_prefixes($name, qw/Controller C/);
 }
 
 =head2 $c->model($name)
@@ -427,9 +460,7 @@ Gets a L<Catalyst::Model> instance by name.
 
 sub model {
     my ( $c, $name ) = @_;
-    my $model = $c->comp("Model::$name");
-    return $model if defined $model;
-    return $c->comp("M::$name");
+    return $c->_comp_prefixes($name, qw/Model M/);
 }
 
 =head2 $c->view($name)
@@ -442,9 +473,7 @@ Gets a L<Catalyst::View> instance by name.
 
 sub view {
     my ( $c, $name ) = @_;
-    my $view = $c->comp("View::$name");
-    return $view if defined $view;
-    return $c->comp("V::$name");
+    return $c->_comp_prefixes($name, qw/View V/);
 }
 
 =head2 Class data and helper classes
@@ -509,7 +538,7 @@ L<Catalyst::Log> man page.
 
 =cut
 
-=head2 Utility methods
+=head2 UTILITY METHODS
 
 =head2 $c->path_to(@path)
 
@@ -942,19 +971,22 @@ sub execute {
     $class = $c->component($class) || $class;
     $c->state(0);
 
+    if ($c->depth >= $RECURSION) {
+        my $action = "$code";
+        $action = "/$action" unless $action =~ /\-\>/;
+        my $error = qq/Deep recursion detected calling "$action"/;
+        $c->log->error($error);
+        $c->error($error);
+        $c->state(0);
+        return $c->state;
+    }
+
+
     if ( $c->debug ) {
         my $action = "$code";
         $action = "/$action" unless $action =~ /\-\>/;
         $c->counter->{"$code"}++;
 
-        if ( $c->counter->{"$code"} > $RECURSION ) {
-            my $error = qq/Deep recursion detected in "$action"/;
-            $c->log->error($error);
-            $c->error($error);
-            $c->state(0);
-            return $c->state;
-        }
-
         # determine if the call was the result of a forward
         # this is done by walking up the call stack and looking for a calling
         # sub of Catalyst::forward before the eval
@@ -1136,7 +1168,7 @@ sub finalize_headers {
     if ( $c->response->body && !$c->response->content_length ) {
 
         # get the length from a filehandle
-        if ( ref $c->response->body && $c->response->body->can('read') ) {
+        if ( blessed($c->response->body) && $c->response->body->can('read') ) {
             if ( my $stat = stat $c->response->body ) {
                 $c->response->content_length( $stat->size );
             }
@@ -1200,7 +1232,7 @@ namespaces.
 
 sub get_actions { my $c = shift; $c->dispatcher->get_actions( $c, @_ ) }
 
-=head2 handle_request( $class, @arguments )
+=head2 $c->handle_request( $class, @arguments )
 
 Called to handle each HTTP request.
 
@@ -1863,14 +1895,13 @@ the plugin name does not begin with C<Catalyst::Plugin::>.
 =cut
 
 {
-    my %PLUGINS;
 
     sub registered_plugins {
         my $proto = shift;
-        return sort keys %PLUGINS unless @_;
+        return sort keys %{$proto->_plugins} unless @_;
         my $plugin = shift;
-        return 1 if exists $PLUGINS{$plugin};
-        return exists $PLUGINS{"Catalyst::Plugin::$plugin"};
+        return 1 if exists $proto->_plugins->{$plugin};
+        return exists $proto->_plugins->{"Catalyst::Plugin::$plugin"};
     }
 
     sub _register_plugin {
@@ -1885,7 +1916,7 @@ the plugin name does not begin with C<Catalyst::Plugin::>.
                 message => qq/Couldn't load ${type}plugin "$plugin", $error/ );
         }
 
-        $PLUGINS{$plugin} = 1;
+        $proto->_plugins->{$plugin} = 1;        
         unless ($instant) {
             no strict 'refs';
             unshift @{"$class\::ISA"}, $plugin;
@@ -1896,6 +1927,7 @@ the plugin name does not begin with C<Catalyst::Plugin::>.
     sub setup_plugins {
         my ( $class, $plugins ) = @_;
 
+        $class->_plugins( {} ) unless $class->_plugins;
         $plugins ||= [];
         for my $plugin ( reverse @$plugins ) {
 
@@ -1910,7 +1942,8 @@ the plugin name does not begin with C<Catalyst::Plugin::>.
 
 =head2 $c->stack
 
-Returns the stack.
+Returns an arrayref of the internal execution stack (actions that are currently
+executing).
 
 =head2 $c->write( $data )
 
@@ -2063,6 +2096,8 @@ Autrijus Tang
 
 Brian Cassidy
 
+Carl Franks
+
 Christian Hansen
 
 Christopher Hicks