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 args_constraints => (
81 builder=>'_build_args_constraints',
83 has_args_constraints => 'count',
84 number_of_args_constraints => 'count',
87 sub _build_args_constraints {
89 my @arg_protos = @{$self->attributes->{Args}||[]};
91 return [] unless scalar(@arg_protos);
92 # If there is only one arg and it looks like a number
93 # we assume its 'classic' and the number is the number of
97 scalar(@arg_protos) == 1 &&
98 looks_like_number($arg_protos[0])
103 map { $self->resolve_type_constraint($_) || die "$_ is not a constraint!" }
110 has captures_constraints => (
117 builder=>'_build_captures_constraints',
119 has_captures_constraints => 'count',
120 number_of_captures_constraints => 'count',
123 sub _build_captures_constraints {
125 my @arg_protos = @{$self->attributes->{CaptureArgs}||[]};
127 return [] unless scalar(@arg_protos);
128 # If there is only one arg and it looks like a number
129 # we assume its 'classic' and the number is the number of
133 scalar(@arg_protos) == 1 &&
134 looks_like_number($arg_protos[0])
139 map { $self->resolve_type_constraint($_) || die "$_ is not a constraint!" }
146 sub resolve_type_constraint {
147 my ($self, $name) = @_;
148 my $tc = eval "package ${\$self->class}; $name" || undef;
149 return $tc || Moose::Util::TypeConstraints::find_or_parse_type_constraint($name);
152 has number_of_captures => (
158 builder=>'_build_number_of_captures');
160 sub _build_number_of_captures {
162 if( ! exists $self->attributes->{CaptureArgs} ) {
163 # If there are no defined capture args, thats considered 0.
165 } elsif(!defined($self->attributes->{CaptureArgs}[0])) {
166 # If you fail to give a defined value, that's also 0
169 scalar(@{$self->attributes->{CaptureArgs}}) == 1 &&
170 looks_like_number($self->attributes->{CaptureArgs}[0])
172 # 'Old school' numbered captures
173 return $self->attributes->{CaptureArgs}[0];
175 # New hotness named arg constraints
176 return $self->number_of_captures_constraints;
183 # Stringify to reverse for debug output etc.
184 q{""} => sub { shift->{reverse} },
186 # Codulate to execute to invoke the encapsulated action coderef
187 '&{}' => sub { my $self = shift; sub { $self->execute(@_); }; },
189 # Make general $stuff still work
194 no warnings 'recursion';
196 sub dispatch { # Execute ourselves against a context
197 my ( $self, $c ) = @_;
198 return $c->execute( $self->class, $self );
207 my ( $self, $c ) = @_;
209 # If infinite args, we always match
210 return 1 if $self->normalized_arg_number == ~0;
212 # There there are arg constraints, we must see to it that the constraints
213 # check positive for each arg in the list.
214 if($self->has_args_constraints) {
215 # If there is only one type constraint, and its a Ref or subtype of Ref,
216 # That means we expect a reference, so use the full args arrayref.
218 $self->number_of_args_constraints == 1 &&
220 $self->args_constraints->[0]->is_a_type_of('Ref') ||
221 $self->args_constraints->[0]->is_a_type_of('ClassName')
224 return 1 if $self->args_constraints->[0]->check($c->req->args);
225 # Removing coercion stuff for the first go
226 #if($self->args_constraints->[0]->coercion && $self->attributes->{Coerce}) {
227 # my $coerced = $self->args_constraints->[0]->coerce($c) || return 0;
228 # $c->req->args([$coerced]);
232 # Because of the way chaining works, we can expect args that are totally not
233 # what you'd expect length wise. When they don't match length, thats a fail
234 return 0 unless scalar( @{ $c->req->args } ) == $self->normalized_arg_number;
236 for my $i(0..$#{ $c->req->args }) {
237 $self->args_constraints->[$i]->check($c->req->args->[$i]) || return 0;
242 # Otherwise, we just need to match the number of args.
243 return scalar( @{ $c->req->args } ) == $self->normalized_arg_number;
248 my ($self, $c, $captures) = @_;
249 my @captures = @{$captures||[]};
251 return 1 unless scalar(@captures); # If none, just say its ok
253 if($self->has_captures_constraints) {
255 $self->number_of_captures_constraints == 1 &&
257 $self->captures_constraints->[0]->is_a_type_of('Ref') ||
258 $self->captures_constraints->[0]->is_a_type_of('ClassName')
261 return 1 if $self->captures_constraints->[0]->check($c->req->args);
263 for my $i(0..$#captures) {
264 $self->captures_constraints->[$i]->check($captures[$i]) || return 0;
276 return $a1->normalized_arg_number <=> $a2->normalized_arg_number;
280 return exists $_[0]->attributes->{Scheme} ? $_[0]->attributes->{Scheme}[0] : undef;
283 sub list_extra_info {
286 Args => $self->normalized_arg_number,
287 CaptureArgs => $self->number_of_captures,
291 __PACKAGE__->meta->make_immutable;
301 The sub attributes that are set for this action, like Local, Path, Private
302 and so on. This determines how the action is dispatched to.
306 Returns the name of the component where this action is defined.
307 Derived by calling the L<catalyst_component_name|Catalyst::Component/catalyst_component_name>
308 method on each component.
312 Returns a code reference to this action.
314 =head2 dispatch( $c )
316 Dispatch this action against a context.
318 =head2 execute( $controller, $c, @args )
320 Execute this action's coderef against a given controller with a given
321 context and arguments
325 Check Args attribute, and makes sure number of args matches the setting.
326 Always returns true if Args is omitted.
328 =head2 match_captures ($c, $captures)
330 Can be implemented by action class and action role authors. If the method
331 exists, then it will be called with the request context and an array reference
332 of the captures for this action.
334 Returning true from this method causes the chain match to continue, returning
335 makes the chain not match (and alternate, less preferred chains will be attempted).
337 =head2 resolve_type_constraint
339 Trys to find a type constraint if you have on on a type constrained method.
343 Compares 2 actions based on the value of the C<Args> attribute, with no C<Args>
344 having the highest precedence.
348 Returns the private namespace this action lives in.
352 Returns the private path for this action.
356 Returns absolute private path for this action. Unlike C<reverse>, the
357 C<private_path> of an action is always suitable for passing to C<forward>.
361 Returns the sub name of this action.
363 =head2 number_of_args
365 Returns the number of args this action expects. This is 0 if the action doesn't
366 take any arguments and undef if it will take any number of arguments.
368 =head2 normalized_arg_number
370 For the purposes of comparison we normalize 'number_of_args' so that if it is
371 undef we mean ~0 (as many args are we can think of).
373 =head2 number_of_captures
375 Returns the number of captures this action expects for L<Chained|Catalyst::DispatchType::Chained> actions.
377 =head2 list_extra_info
379 A HashRef of key-values that an action can provide to a debugging screen
383 Any defined scheme for the action
391 Catalyst Contributors, see Catalyst.pm
395 This library is free software. You can redistribute it and/or modify it under
396 the same terms as Perl itself.