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 ) = @_;
274 return $self->match_args($c, $c->req->args);
278 my ($self, $c, $args) = @_;
279 my @args = @{$args||[]};
281 # If infinite args, we always match
282 return 1 if $self->normalized_arg_number == ~0;
284 # There there are arg constraints, we must see to it that the constraints
285 # check positive for each arg in the list.
286 if($self->has_args_constraints) {
287 # If there is only one type constraint, and its a Ref or subtype of Ref,
288 # That means we expect a reference, so use the full args arrayref.
290 $self->args_constraint_count == 1 &&
292 $self->args_constraints->[0]->is_a_type_of('Ref') ||
293 $self->args_constraints->[0]->is_a_type_of('ClassName')
296 return $self->args_constraints->[0]->check($args);
297 # Removing coercion stuff for the first go
298 #if($self->args_constraints->[0]->coercion && $self->attributes->{Coerce}) {
299 # my $coerced = $self->args_constraints->[0]->coerce($c) || return 0;
300 # $c->req->args([$coerced]);
304 # Because of the way chaining works, we can expect args that are totally not
305 # what you'd expect length wise. When they don't match length, thats a fail
306 return 0 unless scalar( @args ) == $self->normalized_arg_number;
308 for my $i(0..$#args) {
309 $self->args_constraints->[$i]->check($args[$i]) || return 0;
314 # Otherwise, we just need to match the number of args.
315 return scalar( @args ) == $self->normalized_arg_number;
320 my ($self, $c, $captures) = @_;
321 my @captures = @{$captures||[]};
323 return 1 unless scalar(@captures); # If none, just say its ok
325 if($self->has_captures_constraints) {
327 $self->captures_constraints_count == 1 &&
329 $self->captures_constraints->[0]->is_a_type_of('Ref') ||
330 $self->captures_constraints->[0]->is_a_type_of('ClassName')
333 return $self->captures_constraints->[0]->check($captures);
335 for my $i(0..$#captures) {
336 $self->captures_constraints->[$i]->check($captures[$i]) || return 0;
348 return $a1->normalized_arg_number <=> $a2->normalized_arg_number;
352 return exists $_[0]->attributes->{Scheme} ? $_[0]->attributes->{Scheme}[0] : undef;
355 sub list_extra_info {
358 Args => $self->normalized_arg_number,
359 CaptureArgs => $self->number_of_captures,
363 __PACKAGE__->meta->make_immutable;
373 The sub attributes that are set for this action, like Local, Path, Private
374 and so on. This determines how the action is dispatched to.
378 Returns the name of the component where this action is defined.
379 Derived by calling the L<catalyst_component_name|Catalyst::Component/catalyst_component_name>
380 method on each component.
384 Returns a code reference to this action.
386 =head2 dispatch( $c )
388 Dispatch this action against a context.
390 =head2 execute( $controller, $c, @args )
392 Execute this action's coderef against a given controller with a given
393 context and arguments
397 Check Args attribute, and makes sure number of args matches the setting.
398 Always returns true if Args is omitted.
400 =head2 match_captures ($c, $captures)
402 Can be implemented by action class and action role authors. If the method
403 exists, then it will be called with the request context and an array reference
404 of the captures for this action.
406 Returning true from this method causes the chain match to continue, returning
407 makes the chain not match (and alternate, less preferred chains will be attempted).
409 =head2 match_args($c, $args)
411 Underlying feature that does the 'match' work, but doesn't require a context to
412 work (like 'match' does.).
414 =head2 resolve_type_constraint
416 Trys to find a type constraint if you have on on a type constrained method.
420 Compares 2 actions based on the value of the C<Args> attribute, with no C<Args>
421 having the highest precedence.
425 Returns the private namespace this action lives in.
429 Returns the private path for this action.
433 Returns absolute private path for this action. Unlike C<reverse>, the
434 C<private_path> of an action is always suitable for passing to C<forward>.
438 Returns the sub name of this action.
440 =head2 number_of_args
442 Returns the number of args this action expects. This is 0 if the action doesn't
443 take any arguments and undef if it will take any number of arguments.
445 =head2 normalized_arg_number
447 For the purposes of comparison we normalize 'number_of_args' so that if it is
448 undef we mean ~0 (as many args are we can think of).
450 =head2 number_of_captures
452 Returns the number of captures this action expects for L<Chained|Catalyst::DispatchType::Chained> actions.
454 =head2 list_extra_info
456 A HashRef of key-values that an action can provide to a debugging screen
460 Any defined scheme for the action
468 Catalyst Contributors, see Catalyst.pm
472 This library is free software. You can redistribute it and/or modify it under
473 the same terms as Perl itself.