added synopsis to Engine subclassed and documented a couple of methods to make podcov...
[catagits/Catalyst-Runtime.git] / lib / Catalyst / Engine.pm
index 9560889..7b07f5d 100644 (file)
@@ -18,7 +18,7 @@ require Module::Pluggable::Fast;
 $Data::Dumper::Terse = 1;
 
 __PACKAGE__->mk_classdata($_) for qw/actions components tree/;
-__PACKAGE__->mk_accessors(qw/request response/);
+__PACKAGE__->mk_accessors(qw/request response state/);
 
 __PACKAGE__->actions(
     { plain => {}, private => {}, regex => {}, compiled => {}, reverse => {} }
@@ -68,59 +68,27 @@ sub action {
     $_[1] ? ( $action = {@_} ) : ( $action = shift );
     if ( ref $action eq 'HASH' ) {
         while ( my ( $name, $code ) = each %$action ) {
-            my $class = caller(0);
-            if ( $name =~ /^\?(.*)$/ ) {
-                my $prefix = $1 || '';
-                $name = $2;
-                $name = $prefix . _prefix( $class, $name );
-                $self->actions->{plain}->{$name} = [ $class, $code ];
-            }
-            if ( $name =~ /^\/(.*)\/$/ ) {
-                my $regex = $1;
-                $self->actions->{compiled}->{qr#$regex#} = $name;
-                $self->actions->{regex}->{$name} = [ $class, $code ];
-            }
-            elsif ( $name =~ /^\!(.*)$/ ) {
-                $name = $1;
-                my $parent  = $self->tree;
-                my $visitor = Tree::Simple::Visitor::FindByPath->new;
-                for my $part ( split '/', _class2prefix($class) ) {
-                    $visitor->setSearchPath($part);
-                    $parent->accept($visitor);
-                    my $child = $visitor->getResult;
-                    unless ($child) {
-                        $child = $parent->addChild( Tree::Simple->new($part) );
-                        $visitor->setSearchPath($part);
-                        $parent->accept($visitor);
-                        $child = $visitor->getResult;
-                    }
-                    $parent = $child;
-                }
-                my $uid = $parent->getUID;
-                $self->actions->{private}->{$uid}->{$name} = [ $class, $code ];
-            }
-            else { $self->actions->{plain}->{$name} = [ $class, $code ] }
-            $self->actions->{reverse}->{"$code"} = $name;
-            $self->log->debug(qq/"$class" defined "$name" as "$code"/)
-              if $self->debug;
+            $self->set_action( $name, $code, caller(0) );
         }
     }
     return 1;
 }
 
-=item $c->find_action( $name, $namespace )
+=item $c->get_action( $action, $namespace )
 
-Find an action in a given namespace.
+Get an action in a given namespace.
 
 =cut
 
-sub find_action {
+sub get_action {
     my ( $c, $action, $namespace ) = @_;
     $namespace ||= '';
     if ( $action =~ /^\!(.*)/ ) {
         $action = $1;
-        my $parent  = $c->tree;
-        my $result  = $c->actions->{private}->{ $parent->getUID }->{$action};
+        my $parent = $c->tree;
+        my @results;
+        my $result = $c->actions->{private}->{ $parent->getUID }->{$action};
+        push @results, [$result] if $result;
         my $visitor = Tree::Simple::Visitor::FindByPath->new;
         for my $part ( split '/', $namespace ) {
             $visitor->setSearchPath($part);
@@ -128,13 +96,13 @@ sub find_action {
             my $child = $visitor->getResult;
             my $uid   = $child->getUID if $child;
             my $match = $c->actions->{private}->{$uid}->{$action} if $uid;
-            $result = $match if $match;
+            push @results, [$match] if $match;
             $parent = $child if $child;
         }
-        return [$result] if $result;
+        return \@results;
     }
-    elsif ( my $p = $c->actions->{plain}->{$action} ) { return [$p] }
-    elsif ( my $r = $c->actions->{regex}->{$action} ) { return [$r] }
+    elsif ( my $p = $c->actions->{plain}->{$action} ) { return [ [$p] ] }
+    elsif ( my $r = $c->actions->{regex}->{$action} ) { return [ [$r] ] }
     else {
         for my $regex ( keys %{ $c->actions->{compiled} } ) {
             my $name = $c->actions->{compiled}->{$regex};
@@ -145,11 +113,64 @@ sub find_action {
                     last unless ${$i};
                     push @snippets, ${$i};
                 }
-                return [ $c->actions->{regex}->{$name}, $name, \@snippets ];
+                return [ [ $c->actions->{regex}->{$name}, $name, \@snippets ] ];
+            }
+        }
+    }
+    return [];
+}
+
+=item $c->set_action( $action, $code, $namespace )
+
+Set an action in a given namespace.
+
+=cut
+
+sub set_action {
+    my ( $c, $action, $code, $namespace ) = @_;
+
+    my $prefix = '';
+    if ( $action =~ /^\?(.*)$/ ) {
+        my $prefix = $1 || '';
+        $action = $2;
+        $action = $prefix . _prefix( $namespace, $action );
+        $c->actions->{plain}->{$action} = [ $namespace, $code ];
+    }
+    if ( $action =~ /^\/(.*)\/$/ ) {
+        my $regex = $1;
+        $c->actions->{compiled}->{qr#$regex#} = $action;
+        $c->actions->{regex}->{$action} = [ $namespace, $code ];
+    }
+    elsif ( $action =~ /^\!(.*)$/ ) {
+        $action = $1;
+        my $parent  = $c->tree;
+        my $visitor = Tree::Simple::Visitor::FindByPath->new;
+        $prefix = _class2prefix($namespace);
+        for my $part ( split '/', $prefix ) {
+            $visitor->setSearchPath($part);
+            $parent->accept($visitor);
+            my $child = $visitor->getResult;
+            unless ($child) {
+                $child = $parent->addChild( Tree::Simple->new($part) );
+                $visitor->setSearchPath($part);
+                $parent->accept($visitor);
+                $child = $visitor->getResult;
             }
+            $parent = $child;
         }
+        my $uid = $parent->getUID;
+        $c->actions->{private}->{$uid}->{$action} = [ $namespace, $code ];
+        $action = "!$action";
+    }
+    else { 
+       $c->actions->{plain}->{$action} = [ $namespace, $code ];
     }
-    return 0;
+
+    my $reverse = $prefix ? "$action ($prefix)" : $action;
+    $c->actions->{reverse}->{"$code"} = $reverse;
+
+    $c->log->debug(qq/"$namespace" defined "$action" as "$code"/)
+      if $c->debug;
 }
 
 =item $c->benchmark($coderef)
@@ -377,24 +398,35 @@ sub forward {
     if ( $command =~ /^\!/ ) {
         $namespace = _class2prefix($caller);
     }
-    my ( $class, $code );
-    if ( my $action = $c->find_action( $command, $namespace ) ) {
-        if ( $action->[2] ) {
-            $c->log->debug(qq/Couldn't forward "$command" to regex action/)
-              if $c->debug;
-            return 0;
+    if ( my $results = $c->get_action( $command, $namespace ) ) {
+        if ( $command =~ /^\!/ ) {
+            for my $result ( @{$results} ) {
+                my ( $class, $code ) = @{ $result->[0] };
+                $c->state( $c->process( $class, $code ) );
+            }
+        }
+        else {
+            return 0 unless my $result = $results->[0];
+            if ( $result->[2] ) {
+                $c->log->debug(qq/Couldn't forward "$command" to regex action/)
+                  if $c->debug;
+                return 0;
+            }
+            my ( $class, $code ) = @{ $result->[0] };
+            $class = $c->components->{$class} || $class;
+            $c->state( $c->process( $class, $code ) );
         }
-        ( $class, $code ) = @{ $action->[0] };
     }
     else {
-        $class = $command;
+        my $class = $command;
         if ( $class =~ /[^\w\:]/ ) {
             $c->log->debug(qq/Couldn't forward to "$class"/) if $c->debug;
             return 0;
         }
         my $method = shift || 'process';
-        if ( $code = $class->can($method) ) {
+        if ( my $code = $class->can($method) ) {
             $c->actions->{reverse}->{"$code"} = "$class->$method";
+            $c->state( $c->process( $class, $code ) );
         }
         else {
             $c->log->debug(qq/Couldn't forward to "$class->$method"/)
@@ -402,8 +434,7 @@ sub forward {
             return 0;
         }
     }
-    $class = $c->components->{$class} || $class;
-    return $c->process( $class, $code );
+    return $c->state;
 }
 
 =item $c->handler($r)
@@ -424,15 +455,21 @@ sub handler {
             my $namespace = '';
             $namespace = join '/', @{ $c->req->args } if $action eq '!default';
             unless ($namespace) {
-                if ( my $result = $c->find_action($action) ) {
-                    $namespace = _class2prefix( $result->[0]->[0] );
+                if ( my $result = $c->get_action($action) ) {
+                    $namespace = _class2prefix( $result->[0]->[0]->[0] );
                 }
             }
-            if ( my $begin = $c->find_action( '!begin', $namespace ) ) {
-                $c->process( @{ $begin->[0] } );
-            }
-            if ( my $default = $c->find_action( '!default', $namespace ) ) {
-                $c->process( @{ $default->[0] } );
+            my $results = $c->get_action( $action, $namespace );
+            if ( @{$results} ) {
+                for my $begin ( @{ $c->get_action( '!begin', $namespace ) } ) {
+                    $c->state( $c->process( @{ $begin->[0] } ) );
+                }
+                for my $result ( @{ $c->get_action( $action, $namespace ) } ) {
+                    $c->state( $c->process( @{ $result->[0] } ) );
+                }
+                for my $end ( @{ $c->get_action( '!end', $namespace ) } ) {
+                    $c->state( $c->process( @{ $end->[0] } ) );
+                }
             }
             else {
                 my $path  = $c->req->path;
@@ -442,9 +479,6 @@ sub handler {
                 $c->log->error($error) if $c->debug;
                 $c->errors($error);
             }
-            if ( my $end = $c->find_action( '!end', $namespace ) ) {
-                $c->process( @{ $end->[0] } );
-            }
             return $c->finalize;
         };
         if ( $class->debug ) {
@@ -486,7 +520,8 @@ sub prepare {
         response => Catalyst::Response->new(
             { cookies => {}, headers => HTTP::Headers->new, status => 200 }
         ),
-        stash => {}
+        stash => {},
+        state => 0
     }, $class;
     if ( $c->debug ) {
         my $secs = time - $START || 1;
@@ -535,7 +570,7 @@ sub prepare_action {
     $c->req->args( \my @args );
     while (@path) {
         $path = join '/', @path;
-        if ( my $result = $c->find_action($path) ) {
+        if ( my $result = ${ $c->get_action($path) }[0] ) {
 
             # It's a regex
             if ($#$result) {
@@ -566,7 +601,7 @@ sub prepare_action {
       if ( $c->debug && @args );
 }
 
-=item $c->prepare_connection;
+=item $c->prepare_connection
 
 Prepare connection.
 
@@ -574,7 +609,7 @@ Prepare connection.
 
 sub prepare_connection { }
 
-=item $c->prepare_cookies;
+=item $c->prepare_cookies
 
 Prepare cookies.
 
@@ -654,6 +689,14 @@ sub process {
     return $status;
 }
 
+=item $c->run
+
+Starts the engine.
+
+=cut
+
+sub run { }
+
 =item $c->request
 
 =item $c->req
@@ -751,8 +794,8 @@ sub _prefix {
 }
 
 sub _class2prefix {
-    my $class = shift;
-    $class =~ /^.*::([MVC]|Model|View|Controller)+::(.*)$/;
+    my $class = shift || '';
+    $class =~ /^.*::([MVC]|Model|View|Controller)?::(.*)$/;
     my $prefix = lc $2 || '';
     $prefix =~ s/\:\:/\//g;
     return $prefix;