1 package Catalyst::Action;
5 Catalyst::Action - Catalyst Action
9 <form action="[%c.uri_for(c.action)%]">
11 $c->forward( $action->private_path );
15 This class represents a Catalyst Action. You can access the object for the
16 currently dispatched action via $c->action. See the L<Catalyst::Dispatcher>
17 for more information on how actions are dispatched. Actions are defined in
18 L<Catalyst::Controller> subclasses.
23 use Scalar::Util 'looks_like_number';
24 use Moose::Util::TypeConstraints ();
25 with 'MooseX::Emulate::Class::Accessor::Fast';
26 use namespace::clean -except => 'meta';
28 has class => (is => 'rw');
29 has namespace => (is => 'rw');
30 has 'reverse' => (is => 'rw');
31 has attributes => (is => 'rw');
32 has name => (is => 'rw');
33 has code => (is => 'rw');
35 reader => 'private_path',
39 default => sub { '/'.shift->reverse },
42 has number_of_args => (
48 builder=>'_build_number_of_args');
50 sub _build_number_of_args {
52 if( ! exists $self->attributes->{Args} ) {
53 # When 'Args' does not exist, that means we want 'any number of args'.
55 } elsif(!defined($self->attributes->{Args}[0])) {
56 # When its 'Args' that internal cue for 'unlimited'
59 scalar(@{$self->attributes->{Args}}) == 1 &&
60 looks_like_number($self->attributes->{Args}[0])
62 # 'Old school' numbered args (is allowed to be undef as well)
63 return $self->attributes->{Args}[0];
65 # New hotness named arg constraints
66 return $self->number_of_args_constraints;
70 sub normalized_arg_number {
71 return defined($_[0]->number_of_args) ? $_[0]->number_of_args : ~0;
74 has number_of_args_constraints => (
80 builder=>'_build_number_of_args_constraints');
82 sub _build_number_of_args_constraints {
84 return unless $self->has_args_constraints;
87 foreach my $tc( @{$self->args_constraints}) {
88 if($tc->is_a_type_of('Ref')) {
89 if($tc->can('parameters') && $tc->has_parameters) {
90 my $total_params = scalar(@{ $tc->parameters||[] });
91 $total = $total + $total_params;
93 # Its a Reftype but we don't know the number of params it
105 has args_constraints => (
112 builder=>'_build_args_constraints',
114 has_args_constraints => 'count',
115 args_constraint_count => 'count',
118 sub _build_args_constraints {
120 my @arg_protos = @{$self->attributes->{Args}||[]};
122 return [] unless scalar(@arg_protos);
123 return [] unless defined($arg_protos[0]);
125 # If there is only one arg and it looks like a number
126 # we assume its 'classic' and the number is the number of
130 scalar(@arg_protos) == 1 &&
131 looks_like_number($arg_protos[0])
136 map { my @tc = $self->resolve_type_constraint($_); scalar(@tc) ? @tc : die "$_ is not a constraint!" }
142 has number_of_captures_constraints => (
148 builder=>'_build_number_of_capture_constraints');
150 sub _build_number_of_capture_constraints {
152 return unless $self->has_captures_constraints;
155 foreach my $tc( @{$self->captures_constraints}) {
156 if($tc->is_a_type_of('Ref')) {
157 if($tc->can('parameters') && $tc->has_parameters) {
158 my $total_params = scalar(@{ $tc->parameters||[] });
159 $total = $total + $total_params;
161 # Its a Reftype but we don't know the number of params it
162 # actually validates. This is not currently permitted in
164 die "You cannot use CaptureArgs($tc) in ${\$self->reverse} because we cannot determined the number of its parameters";
174 has captures_constraints => (
181 builder=>'_build_captures_constraints',
183 has_captures_constraints => 'count',
184 captures_constraints_count => 'count',
187 sub _build_captures_constraints {
189 my @arg_protos = @{$self->attributes->{CaptureArgs}||[]};
191 return [] unless scalar(@arg_protos);
192 return [] unless defined($arg_protos[0]);
193 # If there is only one arg and it looks like a number
194 # we assume its 'classic' and the number is the number of
198 scalar(@arg_protos) == 1 &&
199 looks_like_number($arg_protos[0])
204 map { my @tc = $self->resolve_type_constraint($_); scalar(@tc) ? @tc : die "$_ is not a constraint!" }
211 sub resolve_type_constraint {
212 my ($self, $name) = @_;
213 my @tc = eval "package ${\$self->class}; $name";
214 return @tc if $tc[0];
215 return Moose::Util::TypeConstraints::find_or_parse_type_constraint($name);
218 has number_of_captures => (
224 builder=>'_build_number_of_captures');
226 sub _build_number_of_captures {
228 if( ! exists $self->attributes->{CaptureArgs} ) {
229 # If there are no defined capture args, thats considered 0.
231 } elsif(!defined($self->attributes->{CaptureArgs}[0])) {
232 # If you fail to give a defined value, that's also 0
235 scalar(@{$self->attributes->{CaptureArgs}}) == 1 &&
236 looks_like_number($self->attributes->{CaptureArgs}[0])
238 # 'Old school' numbered captures
239 return $self->attributes->{CaptureArgs}[0];
241 # New hotness named arg constraints
242 return $self->number_of_captures_constraints;
249 # Stringify to reverse for debug output etc.
250 q{""} => sub { shift->{reverse} },
252 # Codulate to execute to invoke the encapsulated action coderef
253 '&{}' => sub { my $self = shift; sub { $self->execute(@_); }; },
255 # Make general $stuff still work
260 no warnings 'recursion';
262 sub dispatch { # Execute ourselves against a context
263 my ( $self, $c ) = @_;
264 return $c->execute( $self->class, $self );
273 my ( $self, $c ) = @_;
277 # If infinite args, we always match
278 return 1 if $self->normalized_arg_number == ~0;
280 # There there are arg constraints, we must see to it that the constraints
281 # check positive for each arg in the list.
282 if($self->has_args_constraints) {
283 # If there is only one type constraint, and its a Ref or subtype of Ref,
284 # That means we expect a reference, so use the full args arrayref.
286 $self->args_constraint_count == 1 &&
288 $self->args_constraints->[0]->is_a_type_of('Ref') ||
289 $self->args_constraints->[0]->is_a_type_of('ClassName')
292 return $self->args_constraints->[0]->check($c->req->args);
293 # Removing coercion stuff for the first go
294 #if($self->args_constraints->[0]->coercion && $self->attributes->{Coerce}) {
295 # my $coerced = $self->args_constraints->[0]->coerce($c) || return 0;
296 # $c->req->args([$coerced]);
300 # Because of the way chaining works, we can expect args that are totally not
301 # what you'd expect length wise. When they don't match length, thats a fail
302 return 0 unless scalar( @{ $c->req->args } ) == $self->normalized_arg_number;
304 for my $i(0..$#{ $c->req->args }) {
305 $self->args_constraints->[$i]->check($c->req->args->[$i]) || return 0;
310 # Otherwise, we just need to match the number of args.
311 return scalar( @{ $c->req->args } ) == $self->normalized_arg_number;
316 my ($self, $c, $captures) = @_;
317 my @captures = @{$captures||[]};
319 return 1 unless scalar(@captures); # If none, just say its ok
321 if($self->has_captures_constraints) {
323 $self->captures_constraints_count == 1 &&
325 $self->captures_constraints->[0]->is_a_type_of('Ref') ||
326 $self->captures_constraints->[0]->is_a_type_of('ClassName')
329 return $self->captures_constraints->[0]->check($captures);
331 for my $i(0..$#captures) {
332 $self->captures_constraints->[$i]->check($captures[$i]) || return 0;
344 return $a1->normalized_arg_number <=> $a2->normalized_arg_number;
348 return exists $_[0]->attributes->{Scheme} ? $_[0]->attributes->{Scheme}[0] : undef;
351 sub list_extra_info {
354 Args => $self->normalized_arg_number,
355 CaptureArgs => $self->number_of_captures,
359 __PACKAGE__->meta->make_immutable;
369 The sub attributes that are set for this action, like Local, Path, Private
370 and so on. This determines how the action is dispatched to.
374 Returns the name of the component where this action is defined.
375 Derived by calling the L<catalyst_component_name|Catalyst::Component/catalyst_component_name>
376 method on each component.
380 Returns a code reference to this action.
382 =head2 dispatch( $c )
384 Dispatch this action against a context.
386 =head2 execute( $controller, $c, @args )
388 Execute this action's coderef against a given controller with a given
389 context and arguments
393 Check Args attribute, and makes sure number of args matches the setting.
394 Always returns true if Args is omitted.
396 =head2 match_captures ($c, $captures)
398 Can be implemented by action class and action role authors. If the method
399 exists, then it will be called with the request context and an array reference
400 of the captures for this action.
402 Returning true from this method causes the chain match to continue, returning
403 makes the chain not match (and alternate, less preferred chains will be attempted).
405 =head2 resolve_type_constraint
407 Trys to find a type constraint if you have on on a type constrained method.
411 Compares 2 actions based on the value of the C<Args> attribute, with no C<Args>
412 having the highest precedence.
416 Returns the private namespace this action lives in.
420 Returns the private path for this action.
424 Returns absolute private path for this action. Unlike C<reverse>, the
425 C<private_path> of an action is always suitable for passing to C<forward>.
429 Returns the sub name of this action.
431 =head2 number_of_args
433 Returns the number of args this action expects. This is 0 if the action doesn't
434 take any arguments and undef if it will take any number of arguments.
436 =head2 normalized_arg_number
438 For the purposes of comparison we normalize 'number_of_args' so that if it is
439 undef we mean ~0 (as many args are we can think of).
441 =head2 number_of_captures
443 Returns the number of captures this action expects for L<Chained|Catalyst::DispatchType::Chained> actions.
445 =head2 list_extra_info
447 A HashRef of key-values that an action can provide to a debugging screen
451 Any defined scheme for the action
459 Catalyst Contributors, see Catalyst.pm
463 This library is free software. You can redistribute it and/or modify it under
464 the same terms as Perl itself.