lib/Catalyst/Action.pm

   1 package Catalyst::Action;
   2
   3 =head1 NAME
   4
   5 Catalyst::Action - Catalyst Action
   6
   7 =head1 SYNOPSIS
   8
   9     <form action="[%c.uri_for(c.action)%]">
  10
  11     $c->forward( $action->private_path );
  12
  13 =head1 DESCRIPTION
  14
  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.
  19
  20 =cut
  21
  22 use Moose;
  23 use Scalar::Util 'looks_like_number';
  24 with 'MooseX::Emulate::Class::Accessor::Fast';
  25 use namespace::clean -except => 'meta';
  26
  27 has class => (is => 'rw');
  28 has namespace => (is => 'rw');
  29 has 'reverse' => (is => 'rw');
  30 has attributes => (is => 'rw');
  31 has name => (is => 'rw');
  32 has code => (is => 'rw');
  33 has private_path => (
  34   reader => 'private_path',
  35   isa => 'Str',
  36   lazy => 1,
  37   required => 1,
  38   default => sub { '/'.shift->reverse },
  39 );
  40
  41 use overload (
  42
  43     # Stringify to reverse for debug output etc.
  44     q{""} => sub { shift->{reverse} },
  45
  46     # Codulate to execute to invoke the encapsulated action coderef
  47     '&{}' => sub { my $self = shift; sub { $self->execute(@_); }; },
  48
  49     # Make general $stuff still work
  50     fallback => 1,
  51
  52 );
  53
  54
  55
  56 no warnings 'recursion';
  57
  58 sub dispatch {    # Execute ourselves against a context
  59     my ( $self, $c ) = @_;
  60     return $c->execute( $self->class, $self );
  61 }
  62
  63 sub execute {
  64   my $self = shift;
  65   $self->code->(@_);
  66 }
  67
  68 sub match {
  69     my ( $self, $c ) = @_;
  70     #would it be unreasonable to store the number of arguments
  71     #the action has as its own attribute?
  72     #it would basically eliminate the code below.  ehhh. small fish
  73     return 1 unless exists $self->attributes->{Args};
  74     my $args = $self->attributes->{Args}[0];
  75     return 1 unless defined($args) && length($args);
  76     return scalar( @{ $c->req->args } ) == $args;
  77 }
  78
  79 sub compare {
  80     my ($a1, $a2) = @_;
  81
  82     my ($a1_args) = @{ $a1->attributes->{Args} || [] };
  83     my ($a2_args) = @{ $a2->attributes->{Args} || [] };
  84
  85     $_ = looks_like_number($_) ? $_ : ~0
  86         for $a1_args, $a2_args;
  87
  88     return $a1_args <=> $a2_args;
  89 }
  90
  91 sub number_of_args {
  92     my ( $self ) = @_;
  93     return 0 unless exists $self->attributes->{Args};
  94     return $self->attributes->{Args}[0];
  95 }
  96
  97 sub number_of_captures {
  98     my ( $self ) = @_;
  99
 100     return 0 unless exists $self->attributes->{CaptureArgs};
 101     return $self->attributes->{CaptureArgs}[0] || 0;
 102 }
 103
 104 __PACKAGE__->meta->make_immutable;
 105
 106 1;
 107
 108 __END__
 109
 110 =head1 METHODS
 111
 112 =head2 attributes
 113
 114 The sub attributes that are set for this action, like Local, Path, Private
 115 and so on. This determines how the action is dispatched to.
 116
 117 =head2 class
 118
 119 Returns the name of the component where this action is defined.
 120 Derived by calling the L<Catalyst::Component/catalyst_component_name|catalyst_component_name>
 121 method on each component.
 122
 123 =head2 code
 124
 125 Returns a code reference to this action.
 126
 127 =head2 dispatch( $c )
 128
 129 Dispatch this action against a context.
 130
 131 =head2 execute( $controller, $c, @args )
 132
 133 Execute this action's coderef against a given controller with a given
 134 context and arguments
 135
 136 =head2 match( $c )
 137
 138 Check Args attribute, and makes sure number of args matches the setting.
 139 Always returns true if Args is omitted.
 140
 141 =head2 compare
 142
 143 Compares 2 actions based on the value of the C<Args> attribute, with no C<Args>
 144 having the highest precedence.
 145
 146 =head2 namespace
 147
 148 Returns the private namespace this action lives in.
 149
 150 =head2 reverse
 151
 152 Returns the private path for this action.
 153
 154 =head2 private_path
 155
 156 Returns absolute private path for this action. Unlike C<reverse>, the
 157 C<private_path> of an action is always suitable for passing to C<forward>.
 158
 159 =head2 name
 160
 161 Returns the sub name of this action.
 162
 163 =head2 number_of_args
 164
 165 Returns the number of args this action expects. This is 0 if the action doesn't take any arguments and undef if it will take any number of arguments.
 166
 167 =head2 number_of_captures
 168
 169 Returns the number of captures this action expects for L<Chained|Catalyst::DispatchType::Chained> actions.
 170
 171 =head2 meta
 172
 173 Provided by Moose.
 174
 175 =head1 OPTIONAL METHODS
 176
 177 =head2 match_captures
 178
 179 Can be implemented by action class and action role authors. If the method
 180 exists, then it will be called with the request context and an array reference
 181 of the captures for this action.
 182
 183 Returning true from this method causes the chain match to continue, returning
 184 makes the chain not match (and alternate, less preferred chains will be attempted).
 185
 186 =head1 AUTHORS
 187
 188 Catalyst Contributors, see Catalyst.pm
 189
 190 =head1 COPYRIGHT
 191
 192 This library is free software. You can redistribute it and/or modify it under
 193 the same terms as Perl itself.
 194
 195 =cut