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 ) = @_;
275 # If infinite args, we always match
276 return 1 if $self->normalized_arg_number == ~0;
278 # There there are arg constraints, we must see to it that the constraints
279 # check positive for each arg in the list.
280 if($self->has_args_constraints) {
281 # If there is only one type constraint, and its a Ref or subtype of Ref,
282 # That means we expect a reference, so use the full args arrayref.
284 $self->args_constraint_count == 1 &&
286 $self->args_constraints->[0]->is_a_type_of('Ref') ||
287 $self->args_constraints->[0]->is_a_type_of('ClassName')
290 return $self->args_constraints->[0]->check($c->req->args);
291 # Removing coercion stuff for the first go
292 #if($self->args_constraints->[0]->coercion && $self->attributes->{Coerce}) {
293 # my $coerced = $self->args_constraints->[0]->coerce($c) || return 0;
294 # $c->req->args([$coerced]);
298 # Because of the way chaining works, we can expect args that are totally not
299 # what you'd expect length wise. When they don't match length, thats a fail
300 return 0 unless scalar( @{ $c->req->args } ) == $self->normalized_arg_number;
302 for my $i(0..$#{ $c->req->args }) {
303 $self->args_constraints->[$i]->check($c->req->args->[$i]) || return 0;
308 # Otherwise, we just need to match the number of args.
309 return scalar( @{ $c->req->args } ) == $self->normalized_arg_number;
314 my ($self, $c, $captures) = @_;
315 my @captures = @{$captures||[]};
317 return 1 unless scalar(@captures); # If none, just say its ok
319 if($self->has_captures_constraints) {
321 $self->captures_constraints_count == 1 &&
323 $self->captures_constraints->[0]->is_a_type_of('Ref') ||
324 $self->captures_constraints->[0]->is_a_type_of('ClassName')
327 return $self->captures_constraints->[0]->check($captures);
329 for my $i(0..$#captures) {
330 $self->captures_constraints->[$i]->check($captures[$i]) || return 0;
342 return $a1->normalized_arg_number <=> $a2->normalized_arg_number;
346 return exists $_[0]->attributes->{Scheme} ? $_[0]->attributes->{Scheme}[0] : undef;
349 sub list_extra_info {
352 Args => $self->normalized_arg_number,
353 CaptureArgs => $self->number_of_captures,
357 __PACKAGE__->meta->make_immutable;
367 The sub attributes that are set for this action, like Local, Path, Private
368 and so on. This determines how the action is dispatched to.
372 Returns the name of the component where this action is defined.
373 Derived by calling the L<catalyst_component_name|Catalyst::Component/catalyst_component_name>
374 method on each component.
378 Returns a code reference to this action.
380 =head2 dispatch( $c )
382 Dispatch this action against a context.
384 =head2 execute( $controller, $c, @args )
386 Execute this action's coderef against a given controller with a given
387 context and arguments
391 Check Args attribute, and makes sure number of args matches the setting.
392 Always returns true if Args is omitted.
394 =head2 match_captures ($c, $captures)
396 Can be implemented by action class and action role authors. If the method
397 exists, then it will be called with the request context and an array reference
398 of the captures for this action.
400 Returning true from this method causes the chain match to continue, returning
401 makes the chain not match (and alternate, less preferred chains will be attempted).
403 =head2 resolve_type_constraint
405 Trys to find a type constraint if you have on on a type constrained method.
409 Compares 2 actions based on the value of the C<Args> attribute, with no C<Args>
410 having the highest precedence.
414 Returns the private namespace this action lives in.
418 Returns the private path for this action.
422 Returns absolute private path for this action. Unlike C<reverse>, the
423 C<private_path> of an action is always suitable for passing to C<forward>.
427 Returns the sub name of this action.
429 =head2 number_of_args
431 Returns the number of args this action expects. This is 0 if the action doesn't
432 take any arguments and undef if it will take any number of arguments.
434 =head2 normalized_arg_number
436 For the purposes of comparison we normalize 'number_of_args' so that if it is
437 undef we mean ~0 (as many args are we can think of).
439 =head2 number_of_captures
441 Returns the number of captures this action expects for L<Chained|Catalyst::DispatchType::Chained> actions.
443 =head2 list_extra_info
445 A HashRef of key-values that an action can provide to a debugging screen
449 Any defined scheme for the action
457 Catalyst Contributors, see Catalyst.pm
461 This library is free software. You can redistribute it and/or modify it under
462 the same terms as Perl itself.