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
95 warn "Your type constraint '$tc' is a reference type but I cannot determine its number of parameters in action ${\$self->private_path}";
106 has args_constraints => (
113 builder=>'_build_args_constraints',
115 has_args_constraints => 'count',
116 args_constraint_count => 'count',
119 sub _build_args_constraints {
121 my @arg_protos = @{$self->attributes->{Args}||[]};
123 return [] unless scalar(@arg_protos);
124 return [] unless defined($arg_protos[0]);
126 # If there is only one arg and it looks like a number
127 # we assume its 'classic' and the number is the number of
131 scalar(@arg_protos) == 1 &&
132 looks_like_number($arg_protos[0])
137 map { my @tc = $self->resolve_type_constraint($_); scalar(@tc) ? @tc : die "$_ is not a constraint!" }
143 has number_of_captures_constraints => (
149 builder=>'_build_number_of_capture_constraints');
151 sub _build_number_of_capture_constraints {
153 return unless $self->has_captures_constraints;
156 foreach my $tc( @{$self->captures_constraints}) {
157 if($tc->is_a_type_of('Ref')) {
158 if($tc->can('parameters') && $tc->has_parameters) {
159 my $total_params = scalar(@{ $tc->parameters||[] });
160 $total = $total + $total_params;
162 # Its a Reftype but we don't know the number of params it
163 # actually validates. This is not currently permitted in
165 die "You cannot use CaptureArgs($tc) in ${\$self->reverse} because we cannot determined the number of its parameters";
175 has captures_constraints => (
182 builder=>'_build_captures_constraints',
184 has_captures_constraints => 'count',
185 captures_constraints_count => 'count',
188 sub _build_captures_constraints {
190 my @arg_protos = @{$self->attributes->{CaptureArgs}||[]};
192 return [] unless scalar(@arg_protos);
193 return [] unless defined($arg_protos[0]);
194 # If there is only one arg and it looks like a number
195 # we assume its 'classic' and the number is the number of
199 scalar(@arg_protos) == 1 &&
200 looks_like_number($arg_protos[0])
205 map { my @tc = $self->resolve_type_constraint($_); scalar(@tc) ? @tc : die "$_ is not a constraint!" }
212 sub resolve_type_constraint {
213 my ($self, $name) = @_;
214 my @tc = eval "package ${\$self->class}; $name";
216 return map { ref($_) ? $_ : Moose::Util::TypeConstraints::find_or_parse_type_constraint($_) } @tc;
222 has number_of_captures => (
228 builder=>'_build_number_of_captures');
230 sub _build_number_of_captures {
232 if( ! exists $self->attributes->{CaptureArgs} ) {
233 # If there are no defined capture args, thats considered 0.
235 } elsif(!defined($self->attributes->{CaptureArgs}[0])) {
236 # If you fail to give a defined value, that's also 0
239 scalar(@{$self->attributes->{CaptureArgs}}) == 1 &&
240 looks_like_number($self->attributes->{CaptureArgs}[0])
242 # 'Old school' numbered captures
243 return $self->attributes->{CaptureArgs}[0];
245 # New hotness named arg constraints
246 return $self->number_of_captures_constraints;
253 # Stringify to reverse for debug output etc.
254 q{""} => sub { shift->{reverse} },
256 # Codulate to execute to invoke the encapsulated action coderef
257 '&{}' => sub { my $self = shift; sub { $self->execute(@_); }; },
259 # Make general $stuff still work
264 no warnings 'recursion';
266 sub dispatch { # Execute ourselves against a context
267 my ( $self, $c ) = @_;
268 return $c->execute( $self->class, $self );
277 my ( $self, $c ) = @_;
278 return $self->match_args($c, $c->req->args);
282 my ($self, $c, $args) = @_;
283 my @args = @{$args||[]};
285 # If infinite args, we always match
286 return 1 if $self->normalized_arg_number == ~0;
288 # There there are arg constraints, we must see to it that the constraints
289 # check positive for each arg in the list.
290 if($self->has_args_constraints) {
291 # If there is only one type constraint, and its a Ref or subtype of Ref,
292 # That means we expect a reference, so use the full args arrayref.
294 $self->args_constraint_count == 1 &&
296 $self->args_constraints->[0]->is_a_type_of('Ref') ||
297 $self->args_constraints->[0]->is_a_type_of('ClassName')
300 return $self->args_constraints->[0]->check($args);
301 # Removing coercion stuff for the first go
302 #if($self->args_constraints->[0]->coercion && $self->attributes->{Coerce}) {
303 # my $coerced = $self->args_constraints->[0]->coerce($c) || return 0;
304 # $c->req->args([$coerced]);
308 # Because of the way chaining works, we can expect args that are totally not
309 # what you'd expect length wise. When they don't match length, thats a fail
310 return 0 unless scalar( @args ) == $self->normalized_arg_number;
312 for my $i(0..$#args) {
313 $self->args_constraints->[$i]->check($args[$i]) || return 0;
318 # Otherwise, we just need to match the number of args.
319 return scalar( @args ) == $self->normalized_arg_number;
324 my ($self, $c, $captures) = @_;
325 my @captures = @{$captures||[]};
327 return 1 unless scalar(@captures); # If none, just say its ok
329 if($self->has_captures_constraints) {
331 $self->captures_constraints_count == 1 &&
333 $self->captures_constraints->[0]->is_a_type_of('Ref') ||
334 $self->captures_constraints->[0]->is_a_type_of('ClassName')
337 return $self->captures_constraints->[0]->check($captures);
339 for my $i(0..$#captures) {
340 $self->captures_constraints->[$i]->check($captures[$i]) || return 0;
352 return $a1->normalized_arg_number <=> $a2->normalized_arg_number;
356 return exists $_[0]->attributes->{Scheme} ? $_[0]->attributes->{Scheme}[0] : undef;
359 sub list_extra_info {
362 Args => $self->normalized_arg_number,
363 CaptureArgs => $self->number_of_captures,
367 __PACKAGE__->meta->make_immutable;
377 The sub attributes that are set for this action, like Local, Path, Private
378 and so on. This determines how the action is dispatched to.
382 Returns the name of the component where this action is defined.
383 Derived by calling the L<catalyst_component_name|Catalyst::Component/catalyst_component_name>
384 method on each component.
388 Returns a code reference to this action.
390 =head2 dispatch( $c )
392 Dispatch this action against a context.
394 =head2 execute( $controller, $c, @args )
396 Execute this action's coderef against a given controller with a given
397 context and arguments
401 Check Args attribute, and makes sure number of args matches the setting.
402 Always returns true if Args is omitted.
404 =head2 match_captures ($c, $captures)
406 Can be implemented by action class and action role authors. If the method
407 exists, then it will be called with the request context and an array reference
408 of the captures for this action.
410 Returning true from this method causes the chain match to continue, returning
411 makes the chain not match (and alternate, less preferred chains will be attempted).
413 =head2 match_args($c, $args)
415 Does the Args match or not?
417 =head2 resolve_type_constraint
419 Trys to find a type constraint if you have on on a type constrained method.
423 Compares 2 actions based on the value of the C<Args> attribute, with no C<Args>
424 having the highest precedence.
428 Returns the private namespace this action lives in.
432 Returns the private path for this action.
436 Returns absolute private path for this action. Unlike C<reverse>, the
437 C<private_path> of an action is always suitable for passing to C<forward>.
441 Returns the sub name of this action.
443 =head2 number_of_args
445 Returns the number of args this action expects. This is 0 if the action doesn't
446 take any arguments and undef if it will take any number of arguments.
448 =head2 normalized_arg_number
450 For the purposes of comparison we normalize 'number_of_args' so that if it is
451 undef we mean ~0 (as many args are we can think of).
453 =head2 number_of_captures
455 Returns the number of captures this action expects for L<Chained|Catalyst::DispatchType::Chained> actions.
457 =head2 list_extra_info
459 A HashRef of key-values that an action can provide to a debugging screen
463 Any defined scheme for the action
471 Catalyst Contributors, see Catalyst.pm
475 This library is free software. You can redistribute it and/or modify it under
476 the same terms as Perl itself.