This file documents the revision history for Perl extension Catalyst.
5.57
+ - Reformatted documentation
- Renamed -nonew to -force
- Added PAR support
- Added keep-alive support and bug fixes to HTTP engine.
The following flags are supported:
-=over 4
-
-=item -Debug
+=head2 -Debug
Enables debug output.
-=item -Engine
+=head2 -Engine
Forces Catalyst to use a specific engine. Omit the
C<Catalyst::Engine::> prefix of the engine name, i.e.:
use Catalyst qw/-Engine=CGI/;
-=item -Home
+=head2 -Home
Forces Catalyst to use a specific home directory, e.g.:
use Catalyst qw[-Home=/usr/sri];
-=item -Log
+=head2 -Log
Specifies log level.
-=back
-
=head1 METHODS
=head2 Information about the current request
-=over 4
-
-=item $c->action
+=head2 $c->action
Returns a L<Catalyst::Action> object for the current action, which
stringifies to the action name. See L<Catalyst::Action>.
-=item $c->namespace
+=head2 $c->namespace
Returns the namespace of the current action, i.e., the uri prefix
corresponding to the controller of the current action. For example:
# in Controller::Foo::Bar
$c->namespace; # returns 'foo/bar';
-=item $c->request
+=head2 $c->request
-=item $c->req
+=head2 $c->req
Returns the current L<Catalyst::Request> object. See
L<Catalyst::Request>.
-=back
-
=head2 Processing and response to the current request
-=over 4
+=head2 $c->forward( $action [, \@arguments ] )
-=item $c->forward( $action [, \@arguments ] )
-
-=item $c->forward( $class, $method, [, \@arguments ] )
+=head2 $c->forward( $class, $method, [, \@arguments ] )
Forwards processing to a private action. If you give a class name but no
method, C<process()> is called. You may also optionally pass arguments
sub forward { my $c = shift; $c->dispatcher->forward( $c, @_ ) }
-=item $c->detach( $action [, \@arguments ] )
+=head2 $c->detach( $action [, \@arguments ] )
-=item $c->detach( $class, $method, [, \@arguments ] )
+=head2 $c->detach( $class, $method, [, \@arguments ] )
The same as C<forward>, but doesn't return.
sub detach { my $c = shift; $c->dispatcher->detach( $c, @_ ) }
-=item $c->error
+=head2 $c->error
-=item $c->error($error, ...)
+=head2 $c->error($error, ...)
-=item $c->error($arrayref)
+=head2 $c->error($arrayref)
Returns an arrayref containing error messages. If Catalyst encounters an
error while processing a request, it stores the error in $c->error. This
return $c->{error} || [];
}
-=item $c->response
+=head2 $c->response
-=item $c->res
+=head2 $c->res
Returns the current L<Catalyst::Response> object.
-=item $c->stash
+=head2 $c->stash
Returns a hashref to the stash, which may be used to store data and pass
it between components during a request. You can also set hash keys by
return $c->{stash};
}
-=item $c->state
+=head2 $c->state
Contains the return value of the last executed action.
-=back
-
=head2 Component Accessors
-=over 4
+=head2 $c->comp($name)
-=item $c->comp($name)
-
-=item $c->component($name)
+=head2 $c->component($name)
Gets a component object by name. This method is no longer recommended,
unless you want to get a specific component by full
return sort keys %{ $c->components };
}
-=item $c->controller($name)
+=head2 $c->controller($name)
Gets a L<Catalyst::Controller> instance by name.
return $c->comp("C::$name");
}
-=item $c->model($name)
+=head2 $c->model($name)
Gets a L<Catalyst::Model> instance by name.
return $c->comp("M::$name");
}
-=item $c->view($name)
+=head2 $c->view($name)
Gets a L<Catalyst::View> instance by name.
return $c->comp("V::$name");
}
-=back
-
=head2 Class data and helper classes
-=over 4
-
-=item $c->config
+=head2 $c->config
Returns or takes a hashref containing the application's configuration.
__PACKAGE__->config({ db => 'dsn:SQLite:foo.db' });
-=item $c->debug
+=head2 $c->debug
Overload to enable debug messages (same as -Debug option).
sub debug { 0 }
-=item $c->dispatcher
+=head2 $c->dispatcher
Returns the dispatcher instance. Stringifies to class name. See
L<Catalyst::Dispatcher>.
-=item $c->engine
+=head2 $c->engine
Returns the engine instance. Stringifies to the class name. See
L<Catalyst::Engine>.
-=item $c->log
+=head2 $c->log
Returns the logging object instance. Unless it is already set, Catalyst
sets this up with a L<Catalyst::Log> object. To use your own log class:
=cut
-=back
-
=head2 Utility methods
-=over 4
-
-=item $c->path_to(@path)
+=head2 $c->path_to(@path)
Merges C<@path> with C<$c-E<gt>config-E<gt>{home}> and returns a
L<Path::Class> object.
else { return file( $c->config->{home}, @path ) }
}
-=item $c->plugin( $name, $class, @args )
+=head2 $c->plugin( $name, $class, @args )
Helper method for plugins. It creates a classdata accessor/mutator and
loads and instantiates the given class.
if $class->debug;
}
-=item MyApp->setup
+=head2 MyApp->setup
Initializes the dispatcher and engine, loads any plugins, and loads the
model, view, and controller components. You may also specify an array
$class->log->_flush() if $class->log->can('_flush');
}
-=item $c->uri_for( $path, [ @args ] )
+=head2 $c->uri_for( $path, [ @args ] )
Merges path with C<$c-E<gt>request-E<gt>base> for absolute uri's and
with C<$c-E<gt>namespace> for relative uri's, then returns a
$base )->canonical;
}
-=item $c->welcome_message
+=head2 $c->welcome_message
Returns the Catalyst welcome HTML page.
EOF
}
-=back
-
=head1 INTERNAL METHODS
These methods are not meant to be used by end users.
-=over 4
-
-=item $c->components
+=head2 $c->components
Returns a hash of components.
-=item $c->context_class
+=head2 $c->context_class
Returns or sets the context class.
-=item $c->counter
+=head2 $c->counter
Returns a hashref containing coderefs and execution counts (needed for
deep recursion detection).
-=item $c->depth
+=head2 $c->depth
Returns the number of actions on the current internal execution stack.
-=item $c->dispatch
+=head2 $c->dispatch
Dispatches a request to actions.
sub dispatch { my $c = shift; $c->dispatcher->dispatch( $c, @_ ) }
-=item $c->dispatcher_class
+=head2 $c->dispatcher_class
Returns or sets the dispatcher class.
-=item $c->dump_these
+=head2 $c->dump_these
Returns a list of 2-element array references (name, structure) pairs
that will be dumped on the error page in debug mode.
[ Request => $c->req ], [ Response => $c->res ], [ Stash => $c->stash ],;
}
-=item $c->engine_class
+=head2 $c->engine_class
Returns or sets the engine class.
-=item $c->execute( $class, $coderef )
+=head2 $c->execute( $class, $coderef )
Execute a coderef in given class and catch exceptions. Errors are available
via $c->error.
return $c->state;
}
-=item $c->finalize
+=head2 $c->finalize
Finalizes the request.
return $c->response->status;
}
-=item $c->finalize_body
+=head2 $c->finalize_body
Finalizes body.
sub finalize_body { my $c = shift; $c->engine->finalize_body( $c, @_ ) }
-=item $c->finalize_cookies
+=head2 $c->finalize_cookies
Finalizes cookies.
sub finalize_cookies { my $c = shift; $c->engine->finalize_cookies( $c, @_ ) }
-=item $c->finalize_error
+=head2 $c->finalize_error
Finalizes error.
sub finalize_error { my $c = shift; $c->engine->finalize_error( $c, @_ ) }
-=item $c->finalize_headers
+=head2 $c->finalize_headers
Finalizes headers.
$c->response->{_finalized_headers} = 1;
}
-=item $c->finalize_output
+=head2 $c->finalize_output
An alias for finalize_body.
-=item $c->finalize_read
+=head2 $c->finalize_read
Finalizes the input after reading is complete.
sub finalize_read { my $c = shift; $c->engine->finalize_read( $c, @_ ) }
-=item $c->finalize_uploads
+=head2 $c->finalize_uploads
Finalizes uploads. Cleans up any temporary files.
sub finalize_uploads { my $c = shift; $c->engine->finalize_uploads( $c, @_ ) }
-=item $c->get_action( $action, $namespace )
+=head2 $c->get_action( $action, $namespace )
Gets an action in a given namespace.
sub get_action { my $c = shift; $c->dispatcher->get_action(@_) }
-=item $c->get_actions( $action, $namespace )
+=head2 $c->get_actions( $action, $namespace )
Gets all actions of a given name in a namespace and all parent
namespaces.
sub get_actions { my $c = shift; $c->dispatcher->get_actions( $c, @_ ) }
-=item handle_request( $class, @arguments )
+=head2 handle_request( $class, @arguments )
Called to handle each HTTP request.
return $status;
}
-=item $c->prepare( @arguments )
+=head2 $c->prepare( @arguments )
Creates a Catalyst context from an engine-specific request (Apache, CGI,
etc.).
return $c;
}
-=item $c->prepare_action
+=head2 $c->prepare_action
Prepares action.
sub prepare_action { my $c = shift; $c->dispatcher->prepare_action( $c, @_ ) }
-=item $c->prepare_body
+=head2 $c->prepare_body
Prepares message body.
}
}
-=item $c->prepare_body_chunk( $chunk )
+=head2 $c->prepare_body_chunk( $chunk )
Prepares a chunk of data before sending it to L<HTTP::Body>.
$c->engine->prepare_body_chunk( $c, @_ );
}
-=item $c->prepare_body_parameters
+=head2 $c->prepare_body_parameters
Prepares body parameters.
$c->engine->prepare_body_parameters( $c, @_ );
}
-=item $c->prepare_connection
+=head2 $c->prepare_connection
Prepares connection.
$c->engine->prepare_connection( $c, @_ );
}
-=item $c->prepare_cookies
+=head2 $c->prepare_cookies
Prepares cookies.
sub prepare_cookies { my $c = shift; $c->engine->prepare_cookies( $c, @_ ) }
-=item $c->prepare_headers
+=head2 $c->prepare_headers
Prepares headers.
sub prepare_headers { my $c = shift; $c->engine->prepare_headers( $c, @_ ) }
-=item $c->prepare_parameters
+=head2 $c->prepare_parameters
Prepares parameters.
$c->engine->prepare_parameters( $c, @_ );
}
-=item $c->prepare_path
+=head2 $c->prepare_path
Prepares path and base.
sub prepare_path { my $c = shift; $c->engine->prepare_path( $c, @_ ) }
-=item $c->prepare_query_parameters
+=head2 $c->prepare_query_parameters
Prepares query parameters.
}
}
-=item $c->prepare_read
+=head2 $c->prepare_read
Prepares the input for reading.
sub prepare_read { my $c = shift; $c->engine->prepare_read( $c, @_ ) }
-=item $c->prepare_request
+=head2 $c->prepare_request
Prepares the engine request.
sub prepare_request { my $c = shift; $c->engine->prepare_request( $c, @_ ) }
-=item $c->prepare_uploads
+=head2 $c->prepare_uploads
Prepares uploads.
}
}
-=item $c->prepare_write
+=head2 $c->prepare_write
Prepares the output for writing.
sub prepare_write { my $c = shift; $c->engine->prepare_write( $c, @_ ) }
-=item $c->request_class
+=head2 $c->request_class
Returns or sets the request class.
-=item $c->response_class
+=head2 $c->response_class
Returns or sets the response class.
-=item $c->read( [$maxlength] )
+=head2 $c->read( [$maxlength] )
Reads a chunk of data from the request body. This method is designed to
be used in a while loop, reading C<$maxlength> bytes on every call.
sub read { my $c = shift; return $c->engine->read( $c, @_ ) }
-=item $c->run
+=head2 $c->run
Starts the engine.
sub run { my $c = shift; return $c->engine->run( $c, @_ ) }
-=item $c->set_action( $action, $code, $namespace, $attrs )
+=head2 $c->set_action( $action, $code, $namespace, $attrs )
Sets an action in a given namespace.
sub set_action { my $c = shift; $c->dispatcher->set_action( $c, @_ ) }
-=item $c->setup_actions($component)
+=head2 $c->setup_actions($component)
Sets up actions for a component.
sub setup_actions { my $c = shift; $c->dispatcher->setup_actions( $c, @_ ) }
-=item $c->setup_components
+=head2 $c->setup_components
Sets up components.
}
}
-=item $c->setup_dispatcher
+=head2 $c->setup_dispatcher
Sets up dispatcher.
$class->dispatcher( $dispatcher->new );
}
-=item $c->setup_engine
+=head2 $c->setup_engine
Sets up engine.
$class->engine( $engine->new );
}
-=item $c->setup_home
+=head2 $c->setup_home
Sets up the home directory.
}
}
-=item $c->setup_log
+=head2 $c->setup_log
Sets up log.
}
}
-=item $c->setup_plugins
+=head2 $c->setup_plugins
Sets up plugins.
}
}
-=item $c->stack
+=head2 $c->stack
Returns the stack.
-=item $c->write( $data )
+=head2 $c->write( $data )
Writes $data to the output stream. When using this method directly, you
will need to manually set the C<Content-Length> header to the length of
return $c->engine->write( $c, @_ );
}
-=item version
+=head2 version
Returns the Catalyst version number. Mostly useful for "powered by"
messages in template systems.
sub version { return $Catalyst::VERSION }
-=back
-
=head1 INTERNAL ACTIONS
Catalyst uses internal actions like C<_DISPATCH>, C<_BEGIN>, C<_AUTO>,
=head1 SEE ALSO
-=over 4
-
-=item L<Catalyst::Manual> - The Catalyst Manual
-
-=item L<Catalyst::Component>, L<Catalyst::Base> - Base classes for components
+=head2 L<Catalyst::Manual> - The Catalyst Manual
-=item L<Catalyst::Engine> - Core engine
+=head2 L<Catalyst::Component>, L<Catalyst::Base> - Base classes for components
-=item L<Catalyst::Log> - Log class.
+=head2 L<Catalyst::Engine> - Core engine
-=item L<Catalyst::Request> - Request object
+=head2 L<Catalyst::Log> - Log class.
-=item L<Catalyst::Response> - Response object
+=head2 L<Catalyst::Request> - Request object
-=item L<Catalyst::Test> - The test suite.
+=head2 L<Catalyst::Response> - Response object
-=back
+=head2 L<Catalyst::Test> - The test suite.
=head1 CREDITS
=head1 METHODS
-=over 4
+=head2 attributes
-=item attributes
+=head2 class
-=item class
+=head2 code
-=item code
-
-=item execute
+=head2 execute
=cut
return $c->execute( $self->class, $self );
}
-=item namespace
-
-=item reverse
+=head2 namespace
-=item name
+=head2 reverse
-=back
+=head2 name
=head1 AUTHOR
=head1 METHODS
-=over 4
-
-=item get_action
+=head2 get_action
=cut
return;
}
-=item actions
-
-=item part
+=head2 actions
-=back
+=head2 part
=head1 AUTHOR
=head1 METHODS
-=over 4
+=head2 FETCH_CODE_ATTRIBUTES
-=item FETCH_CODE_ATTRIBUTES
-
-=item MODIFY_CODE_ATTRIBUTES
-
-=back
+=head2 MODIFY_CODE_ATTRIBUTES
=head1 SEE ALSO
=head1 METHODS
-=over 4
-
-=item $self->action_namespace($c)
+=head2 $self->action_namespace($c)
=cut
|| '';
}
-=item $self->register_actions($c)
+=head2 $self->register_actions($c)
=cut
return \%attributes;
}
-=back
-
=head1 SEE ALSO
L<Catalyst>, L<Catalyst::Controller>.
=head1 METHODS
-=over 4
-
-=item ACTION_install
+=head2 ACTION_install
=cut
$self->ACTION_install_extras;
}
-=item ACTION_fakeinstall
+=head2 ACTION_fakeinstall
=cut
$self->ACTION_install_extras;
}
-=item ACTION_install_extras
+=head2 ACTION_install_extras
=cut
return @files;
}
-=back
-
=head1 AUTHOR
Sebastian Riedel, C<sri@oook.de>
=head1 METHODS
-=over 4
-
-=item new($c)
+=head2 new($c)
=cut
return $self->NEXT::new( { %{ $self->config }, %{$arguments} } );
}
-# remember to leave blank lines between the consecutive =item's
-# otherwise the pod tools don't recognize the subsequent =items
+# remember to leave blank lines between the consecutive =head2's
+# otherwise the pod tools don't recognize the subsequent =head2s
-=item $c->config
+=head2 $c->config
-=item $c->config($hashref)
+=head2 $c->config($hashref)
-=item $c->config($key, $value, ...)
+=head2 $c->config($key, $value, ...)
=cut
return $self->_config;
}
-=item $c->process()
+=head2 $c->process()
=cut
. " did not override Catalyst::Component::process" );
}
-=back
-
=head1 SEE ALSO
L<Catalyst>, L<Catalyst::Model>, L<Catalyst::View>, L<Catalyst::Controller>.
=head1 METHODS
-=over 4
-
-=item $self->list($c)
+=head2 $self->list($c)
=cut
sub list { }
-=item $self->match( $c, $path )
+=head2 $self->match( $c, $path )
=cut
sub match { die "Abstract method!" }
-=item $self->register( $c, $action )
+=head2 $self->register( $c, $action )
=cut
sub register { }
-=back
-
=head1 AUTHOR
Matt S Trout
=head1 METHODS
-=over 4
-
-=item $self->match( $c, $path )
+=head2 $self->match( $c, $path )
=cut
return 0;
}
-=back
-
=head1 AUTHOR
Matt S Trout
=head1 METHODS
-=over 4
-
-=item $self->match( $c, $path )
+=head2 $self->match( $c, $path )
=cut
my $result = $c->get_action( 'index', $path );
if ($result) {
- $c->action( $result );
+ $c->action($result);
$c->namespace( $result->namespace );
$c->req->action('index');
$c->req->match( $c->req->path );
return 0;
}
-=back
-
=head1 AUTHOR
Sebastian Riedel, C<sri@cpan.org>
=head1 METHODS
-=over 4
-
-=item $self->list($c)
+=head2 $self->list($c)
=cut
if ( keys %{ $self->{paths} } );
}
-=item $self->match( $c, $path )
+=head2 $self->match( $c, $path )
=cut
return 0;
}
-=item $self->register( $c, $action )
+=head2 $self->register( $c, $action )
=cut
return 0;
}
-=item $self->register_path($c, $path, $action)
+=head2 $self->register_path($c, $path, $action)
=cut
$self->{paths}{$path} = $action;
}
-=back
-
=head1 AUTHOR
Matt S Trout
=head1 METHODS
-=over 4
-
-=item $self->list($c)
+=head2 $self->list($c)
=cut
if ( @{ $self->{compiled} } );
}
-=item $self->match( $c, $path )
+=head2 $self->match( $c, $path )
=cut
return 0;
}
-=item $self->register( $c, $action )
+=head2 $self->register( $c, $action )
=cut
return 0;
}
-=item $self->register_regex($c, $re, $action)
+=head2 $self->register_regex($c, $re, $action)
=cut
);
}
-=back
-
=head1 AUTHOR
Matt S Trout
=head1 METHODS
-=over 4
-
-=item $self->detach( $c, $command [, \@arguments ] )
+=head2 $self->detach( $c, $command [, \@arguments ] )
=cut
die $Catalyst::DETACH;
}
-=item $self->dispatch($c)
+=head2 $self->dispatch($c)
=cut
}
}
-=item $self->forward( $c, $command [, \@arguments ] )
+=head2 $self->forward( $c, $command [, \@arguments ] )
=cut
return $c->state;
}
-=item $self->prepare_action($c)
+=head2 $self->prepare_action($c)
=cut
if ( $c->debug && @args );
}
-=item $self->get_action( $action, $namespace )
+=head2 $self->get_action( $action, $namespace )
=cut
}
}
-=item $self->get_actions( $c, $action, $namespace )
+=head2 $self->get_actions( $c, $action, $namespace )
=cut
return map { $_->get_action($action) } @match;
}
-=item $self->get_containers( $namespace )
+=head2 $self->get_containers( $namespace )
=cut
return map { $_->getNodeValue } @match;
}
-=item $self->register( $c, $action )
+=head2 $self->register( $c, $action )
=cut
$parent->getNodeValue->actions->{ $action->name } = $action;
}
-=item $self->setup_actions( $class, $component )
+=head2 $self->setup_actions( $class, $component )
=cut
$_->list($c) for @{ $self->dispatch_types };
}
-=back
-
=head1 AUTHOR
Sebastian Riedel, C<sri@cpan.org>
=head1 METHODS
-=over 4
-
-=item $self->finalize_output
+=head2 $self->finalize_output
<obsolete>, see finalize_body
-=item $self->finalize_body($c)
+=head2 $self->finalize_body($c)
Finalize body. Prints the response output.
}
}
-=item $self->finalize_cookies($c)
+=head2 $self->finalize_cookies($c)
=cut
}
}
-=item $self->finalize_error($c)
+=head2 $self->finalize_error($c)
=cut
# For pretty dumps
local $Data::Dumper::Terse = 1;
- $error = join '',
- map { '<p><code class="error">' . encode_entities($_) . '</code></p>' }
- @{ $c->error };
+ $error = join '', map {
+ '<p><code class="error">'
+ . encode_entities($_)
+ . '</code></p>'
+ } @{ $c->error };
$error ||= 'No output';
$title = $name = "$name on Catalyst $Catalyst::VERSION";
$name = "<h1>$name</h1>";
}
-=item $self->finalize_headers($c)
+=head2 $self->finalize_headers($c)
=cut
sub finalize_headers { }
-=item $self->finalize_read($c)
+=head2 $self->finalize_read($c)
=cut
undef $self->{_prepared_read};
}
-=item $self->finalize_uploads($c)
+=head2 $self->finalize_uploads($c)
=cut
}
}
-=item $self->prepare_body($c)
+=head2 $self->prepare_body($c)
=cut
}
}
-=item $self->prepare_body_chunk($c)
+=head2 $self->prepare_body_chunk($c)
=cut
$c->request->{_body}->add($chunk);
}
-=item $self->prepare_body_parameters($c)
+=head2 $self->prepare_body_parameters($c)
=cut
$c->request->body_parameters( $c->request->{_body}->param );
}
-=item $self->prepare_connection($c)
+=head2 $self->prepare_connection($c)
=cut
sub prepare_connection { }
-=item $self->prepare_cookies($c)
+=head2 $self->prepare_cookies($c)
=cut
}
}
-=item $self->prepare_headers($c)
+=head2 $self->prepare_headers($c)
=cut
sub prepare_headers { }
-=item $self->prepare_parameters($c)
+=head2 $self->prepare_parameters($c)
=cut
}
}
-=item $self->prepare_path($c)
+=head2 $self->prepare_path($c)
=cut
sub prepare_path { }
-=item $self->prepare_request($c)
+=head2 $self->prepare_request($c)
-=item $self->prepare_query_parameters($c)
+=head2 $self->prepare_query_parameters($c)
=cut
}
}
-=item $self->prepare_read($c)
+=head2 $self->prepare_read($c)
=cut
$self->read_position(0);
}
-=item $self->prepare_request(@arguments)
+=head2 $self->prepare_request(@arguments)
=cut
sub prepare_request { }
-=item $self->prepare_uploads($c)
+=head2 $self->prepare_uploads($c)
=cut
}
}
-=item $self->prepare_write($c)
+=head2 $self->prepare_write($c)
=cut
sub prepare_write { }
-=item $self->read($c, [$maxlength])
+=head2 $self->read($c, [$maxlength])
=cut
}
}
-=item $self->read_chunk($c, $buffer, $length)
+=head2 $self->read_chunk($c, $buffer, $length)
Each engine inplements read_chunk as its preferred way of reading a chunk
of data.
sub read_chunk { }
-=item $self->read_length
+=head2 $self->read_length
The length of input data to be read. This is obtained from the Content-Length
header.
-=item $self->read_position
+=head2 $self->read_position
The amount of input data that has already been read.
-=item $self->run($c)
+=head2 $self->run($c)
=cut
sub run { }
-=item $self->write($c, $buffer)
+=head2 $self->write($c, $buffer)
=cut
print STDOUT $buffer;
}
-=back
-
=head1 AUTHORS
Sebastian Riedel, <sri@cpan.org>
use NEXT;
use URI;
-__PACKAGE__->mk_accessors( 'env' );
+__PACKAGE__->mk_accessors('env');
=head1 NAME
This class overloads some methods from C<Catalyst::Engine>.
-=over 4
-
-=item $self->finalize_headers($c)
+=head2 $self->finalize_headers($c)
=cut
print "\015\012";
}
-=item $self->prepare_connection($c)
+=head2 $self->prepare_connection($c)
=cut
sub prepare_connection {
my ( $self, $c ) = @_;
- local(*ENV) = $self->env || \%ENV;
+ local (*ENV) = $self->env || \%ENV;
$c->request->address( $ENV{REMOTE_ADDR} );
}
}
-=item $self->prepare_headers($c)
+=head2 $self->prepare_headers($c)
=cut
sub prepare_headers {
my ( $self, $c ) = @_;
- local(*ENV) = $self->env || \%ENV;
+ local (*ENV) = $self->env || \%ENV;
# Read headers from %ENV
while ( my ( $header, $value ) = each %ENV ) {
}
}
-=item $self->prepare_path($c)
+=head2 $self->prepare_path($c)
=cut
sub prepare_path {
my ( $self, $c ) = @_;
- local(*ENV) = $self->env || \%ENV;
+ local (*ENV) = $self->env || \%ENV;
my $scheme = $c->request->secure ? 'https' : 'http';
my $host = $ENV{HTTP_HOST} || $ENV{SERVER_NAME};
$c->request->base($base);
}
-=item $self->prepare_query_parameters($c)
+=head2 $self->prepare_query_parameters($c)
=cut
sub prepare_query_parameters {
my ( $self, $c ) = @_;
- local(*ENV) = $self->env || \%ENV;
-
+ local (*ENV) = $self->env || \%ENV;
+
if ( $ENV{QUERY_STRING} ) {
$self->SUPER::prepare_query_parameters( $c, $ENV{QUERY_STRING} );
}
}
-=item $self->prepare_request($c, (env => \%env))
+=head2 $self->prepare_request($c, (env => \%env))
=cut
my ( $self, $c, %args ) = @_;
if ( $args{env} ) {
- $self->env( $args{env} );
+ $self->env( $args{env} );
}
}
-=item $self->prepare_write($c)
+=head2 $self->prepare_write($c)
Enable autoflush on the output handle for CGI-based engines.
$self->NEXT::prepare_write($c);
}
-=item $self->read_chunk($c, $buffer, $length)
+=head2 $self->read_chunk($c, $buffer, $length)
=cut
sub read_chunk { shift; shift; *STDIN->sysread(@_); }
-=item $self->run
+=head2 $self->run
=cut
sub run { shift; shift->handle_request(@_) }
-=back
-
=head1 SEE ALSO
L<Catalyst> L<Catalyst::Engine>.
This class overloads some methods from C<Catalyst::Engine::CGI>.
-=over 4
-
-=item $self->run($c, $listen, { option => value, ... })
+=head2 $self->run($c, $listen, { option => value, ... })
Starts the FastCGI server. If C<$listen> is set, then it specifies a
location to listen for FastCGI requests;
if ($listen) {
$options->{manager} ||= "FCGI::ProcManager";
$options->{nproc} ||= 1;
-
+
$self->daemon_fork() if $options->{detach};
-
+
if ( $options->{manager} ) {
eval "use $options->{manager}; 1" or die $@;
- $proc_manager
- = $options->{manager}->new( {
+ $proc_manager = $options->{manager}->new(
+ {
n_processes => $options->{nproc},
pid_fname => $options->{pidfile},
- } );
-
+ }
+ );
+
# detach *before* the ProcManager inits
$self->daemon_detach() if $options->{detach};
}
elsif ( $options->{detach} ) {
$self->daemon_detach();
- }
+ }
}
while ( $request->Accept >= 0 ) {
}
}
-=item $self->write($c, $buffer)
+=head2 $self->write($c, $buffer)
=cut
*STDOUT->syswrite($buffer);
}
-=item $self->daemon_fork()
+=head2 $self->daemon_fork()
Performs the first part of daemon initialisation. Specifically,
forking. STDERR, etc are still connected to a terminal.
fork && exit;
}
-=item $self->daemon_detach( )
+=head2 $self->daemon_detach( )
Performs the second part of daemon initialisation. Specifically,
disassociates from the terminal.
sub daemon_detach {
my $self = shift;
print "FastCGI daemon started (pid $$)\n";
- open STDIN, "+</dev/null" or die $!;
- open STDOUT, ">&STDIN" or die $!;
- open STDERR, ">&STDIN" or die $!;
+ open STDIN, "+</dev/null" or die $!;
+ open STDOUT, ">&STDIN" or die $!;
+ open STDERR, ">&STDIN" or die $!;
POSIX::setsid();
}
1;
__END__
-=back
-
=head1 WEB SERVER CONFIGURATIONS
=head2 Apache 1.x, 2.x
use NEXT;
use Socket;
use IO::Socket::INET ();
-use IO::Select ();
+use IO::Select ();
# For PAR
require Catalyst::Engine::HTTP::Restarter;
=head1 METHODS
-=over 4
-
-=item $self->finalize_headers($c)
+=head2 $self->finalize_headers($c)
=cut
$self->NEXT::finalize_headers($c);
}
-=item $self->finalize_read($c)
+=head2 $self->finalize_read($c)
=cut
return $self->NEXT::finalize_read($c);
}
-=item $self->prepare_read($c)
+=head2 $self->prepare_read($c)
=cut
return $self->NEXT::prepare_read($c);
}
-=item $self->read_chunk($c, $buffer, $length)
+=head2 $self->read_chunk($c, $buffer, $length)
=cut
}
}
-=item run
+=head2 run
=cut
# Initialize CGI environment
local %ENV = (
- PATH_INFO => $path || '',
- QUERY_STRING => $query_string || '',
+ PATH_INFO => $path || '',
+ QUERY_STRING => $query_string || '',
REMOTE_ADDR => $sockdata->{peeraddr},
REMOTE_HOST => $sockdata->{peername},
REQUEST_METHOD => $method || '',
sub _inet_addr { unpack "N*", inet_aton( $_[0] ) }
-=back
-
=head1 SEE ALSO
L<Catalyst>, L<Catalyst::Engine>.
=head1 METHODS
-=over 4
-
-=item run
-
-=back
+=head2 run
=head1 SEE ALSO
use File::Spec;
use Time::HiRes qw/sleep/;
-__PACKAGE__->mk_accessors( qw/delay
- directory
- modified
- regex
- watch_list/ );
+__PACKAGE__->mk_accessors(
+ qw/delay
+ directory
+ modified
+ regex
+ watch_list/
+);
sub new {
my ( $class, %args ) = @_;
-
- my $self = { %args };
-
+
+ my $self = {%args};
+
bless $self, $class;
-
+
$self->_init;
-
+
return $self;
}
sub _init {
my $self = shift;
-
+
my $watch_list = $self->_index_directory;
- $self->watch_list( $watch_list );
-
+ $self->watch_list($watch_list);
+
$self->modified(
File::Modified->new(
method => 'mtime',
sub watch {
my $self = shift;
-
+
my @changes;
my @changed_files;
-
+
sleep $self->delay || 1;
-
+
eval { @changes = $self->modified->changed };
- if ( $@ ) {
+ if ($@) {
+
# File::Modified will die if a file is deleted.
my ($deleted_file) = $@ =~ /stat '(.+)'/;
push @changed_files, $deleted_file || 'unknown file';
}
-
- if ( @changes ) {
+
+ if (@changes) {
+
# update all mtime information
$self->modified->update;
-
+
# check if any files were changed
@changed_files = grep { -f $_ } @changes;
-
+
# Check if only directories were changed. This means
# a new file was created.
- unless ( @changed_files ) {
+ unless (@changed_files) {
+
# re-index to find new files
my $new_watch = $self->_index_directory;
-
+
# look through the new list for new files
my $old_watch = $self->watch_list;
- @changed_files = grep { ! defined $old_watch->{$_} }
- keys %{ $new_watch };
-
+ @changed_files = grep { !defined $old_watch->{$_} }
+ keys %{$new_watch};
+
return unless @changed_files;
}
# Test modified pm's
- for my $file ( @changed_files ) {
+ for my $file (@changed_files) {
next unless $file =~ /\.pm$/;
if ( my $error = $self->_test($file) ) {
- print STDERR
- qq/File "$file" modified, not restarting\n\n/;
+ print STDERR qq/File "$file" modified, not restarting\n\n/;
print STDERR '*' x 80, "\n";
print STDERR $error;
print STDERR '*' x 80, "\n";
}
}
}
-
+
return @changed_files;
}
sub _index_directory {
my $self = shift;
-
- my $dir = $self->directory || die "No directory specified";
- my $regex = $self->regex || '\.pm$';
+
+ my $dir = $self->directory || die "No directory specified";
+ my $regex = $self->regex || '\.pm$';
my %list;
-
+
finddepth(
{
wanted => sub {
return unless -f $file;
$file =~ s{/script/..}{};
$list{$file} = 1;
-
+
# also watch the directory for changes
my $cur_dir = File::Spec->rel2abs($File::Find::dir);
- $cur_dir =~ s{/script/..}{};
+ $cur_dir =~ s{/script/..}{};
$list{$cur_dir} = 1;
},
no_chdir => 1
sub _test {
my ( $self, $file ) = @_;
-
+
delete $INC{$file};
local $SIG{__WARN__} = sub { };
-
+
open my $olderr, '>&STDERR';
open STDERR, '>', File::Spec->devnull;
eval "require '$file'";
open STDERR, '>&', $olderr;
-
+
return ($@) ? $@ : 0;
-}
+}
1;
__END__
=head1 METHODS
-=over 4
+=head2 throw( $message )
-=item throw( $message )
+=head2 throw( message => $message )
-=item throw( message => $message )
-
-=item throw( error => $error )
+=head2 throw( error => $error )
Throws a fatal exception.
Carp::croak($message);
}
-=back
-
=head1 AUTHOR
Sebastian Riedel, C<sri@cpan.org>
=head1 METHODS
-=over 4
-
-=item default
+=head2 default
=cut
#
# Uncomment and modify this end action after adding a View component
#
-#=item end
+#=head2 end
#
#=cut
#
# $c->forward('View::') unless $c->response->body;
#}
-=back
-
=head1 AUTHOR
[% author %]
[% IF long_type == 'Controller' %]
=head1 METHODS
-=over 4
-
#
# Uncomment and modify this or add new actions to fit your needs
#
-#=item default
+#=head2 default
#
#=cut
#
# $c->response->body('[% class %] is on Catalyst!');
#}
-=back
-
[% END %]
=head1 AUTHOR
my $level = shift;
my $time = localtime(time);
my $message = join( "\n", @_ );
- $self->{body} .= sprintf( "[%s] [catalyst] [%s] %s\n",
- $time, $level, $message ) ;
+ $self->{body} .=
+ sprintf( "[%s] [catalyst] [%s] %s\n", $time, $level, $message );
}
sub _flush {
- my $self = shift;
- if ( $self->abort || ! $self->body ) {
- $self->abort(undef);
- } else {
- print( STDERR $self->body);
+ my $self = shift;
+ if ( $self->abort || !$self->body ) {
+ $self->abort(undef);
+ }
+ else {
+ print( STDERR $self->body );
}
$self->body(undef);
}
=head1 LOG LEVELS
-=over 4
-
-=item debug
+=head2 debug
$log->is_debug;
$log->debug($message);
-=item info
+=head2 info
$log->is_info;
$log->info($message);
-=item warn
+=head2 warn
$log->is_warn;
$log->warn($message);
-=item error
+=head2 error
$log->is_error;
$log->error($message);
-=item fatal
+=head2 fatal
$log->is_fatal;
$log->fatal($message);
-=back
-
=head1 METHODS
-=over 4
-
-=item new
+=head2 new
Constructor. Defaults to enable all levels unless levels are provided in
arguments.
$log = Catalyst::Log->new;
$log = Catalyst::Log->new( 'warn', 'error' );
-=item levels
+=head2 levels
Set log levels
$log->levels( 'warn', 'error', 'fatal' );
-=item enable
+=head2 enable
Enable log levels
$log->enable( 'warn', 'error' );
-=item disable
+=head2 disable
Disable log levels
$log->disable( 'warn', 'error' );
-=item is_debug
+=head2 is_debug
-=item is_error
+=head2 is_error
-=item is_fatal
+=head2 is_fatal
-=item is_info
+=head2 is_info
-=item is_warn
+=head2 is_warn
Is the log level active?
-=item abort
+=head2 abort
Should Catalyst emit logs for this request? Will be reset at the end of
each request.
$c->log->abort(1) if $c->log->can('abort');
-=back
-
-
-
=head1 SEE ALSO
L<Catalyst>.
=head1 METHODS
-=over 4
-
-=item $self->package(\%options)
+=head2 $self->package(\%options)
=cut
unlink $par_test;
}
-=back
-
=head1 AUTHOR
Sebastian Riedel, C<sri@oook.de>
=head1 METHODS
-=over 4
-
-=item $req->action
+=head2 $req->action
Returns the requested action as a L<Catalyst::Action> object.
-=item $req->address
+=head2 $req->address
Returns the IP address of the client.
-=item $req->arguments
+=head2 $req->arguments
Returns a reference to an array containing the arguments.
and the URI for the request was C<http://.../foo/moose/bah>, the string C<bah>
would be the first and only argument.
-=item $req->args
+=head2 $req->args
Shortcut for arguments.
-=item $req->base
+=head2 $req->base
Contains the URI base. This will always have a trailing slash.
return $self->{base};
}
-=item $req->body
+=head2 $req->body
Returns the message body of the request, unless Content-Type is
C<application/x-www-form-urlencoded> or C<multipart/form-data>.
return $self->{_body}->body;
}
-=item $req->body_parameters
+=head2 $req->body_parameters
Returns a reference to a hash containing body (POST) parameters. Values can
be either a scalar or an arrayref containing scalars.
These are the parameters from the POST part of the request, if any.
-=item $req->body_params
+=head2 $req->body_params
Shortcut for body_parameters.
return $self->{body_parameters};
}
-=item $req->content_encoding
+=head2 $req->content_encoding
Shortcut for $req->headers->content_encoding.
-=item $req->content_length
+=head2 $req->content_length
Shortcut for $req->headers->content_length.
-=item $req->content_type
+=head2 $req->content_type
Shortcut for $req->headers->content_type.
-=item $req->cookie
+=head2 $req->cookie
A convenient method to access $req->cookies.
}
}
-=item $req->cookies
+=head2 $req->cookies
Returns a reference to a hash containing the cookies.
The cookies in the hash are indexed by name, and the values are L<CGI::Cookie>
objects.
-=item $req->header
+=head2 $req->header
Shortcut for $req->headers->header.
-=item $req->headers
+=head2 $req->headers
Returns an L<HTTP::Headers> object containing the headers for the current request.
print $c->request->headers->header('X-Catalyst');
-=item $req->hostname
+=head2 $req->hostname
Returns the hostname of the client.
return $self->{hostname};
}
-=item $req->input
+=head2 $req->input
Alias for $req->body.
-=item $req->match
+=head2 $req->match
This contains the matching part of a Regex action. Otherwise
it returns the same as 'action'.
-=item $req->method
+=head2 $req->method
Contains the request method (C<GET>, C<POST>, C<HEAD>, etc).
-=item $req->param
+=head2 $req->param
Returns GET and POST parameters with a CGI.pm-compatible param method. This
is an alternative method for accessing parameters in $c->req->parameters.
}
}
-=item $req->parameters
+=head2 $req->parameters
Returns a reference to a hash containing GET and POST parameters. Values can
be either a scalar or an arrayref containing scalars.
This is the combination of C<query_parameters> and C<body_parameters>.
-=item $req->params
+=head2 $req->params
Shortcut for $req->parameters.
return $self->{parameters};
}
-=item $req->path
+=head2 $req->path
Returns the path, i.e. the part of the URI after $req->base, for the current request.
-=item $req->path_info
+=head2 $req->path_info
Alias for path, added for compability with L<CGI>.
return $path;
}
-=item $req->protocol
+=head2 $req->protocol
Returns the protocol (HTTP/1.0 or HTTP/1.1) used for the current request.
-=item $req->query_parameters
+=head2 $req->query_parameters
Returns a reference to a hash containing query string (GET) parameters. Values can
be either a scalar or an arrayref containing scalars.
print $c->request->query_parameters->{field};
print $c->request->query_parameters->{field}->[0];
-=item $req->read( [$maxlength] )
+=head2 $req->read( [$maxlength] )
Reads a chunk of data from the request body. This method is intended to be
used in a while loop, reading $maxlength bytes on every call. $maxlength
sub read { shift->{_context}->read(@_); }
-=item $req->referer
+=head2 $req->referer
Shortcut for $req->headers->referer. Returns the referring page.
-=item $req->secure
+=head2 $req->secure
Returns true or false, indicating whether the connection is secure (https).
-=item $req->snippets
+=head2 $req->snippets
Returns a reference to an array containing regex snippets.
my @snippets = @{ $c->request->snippets };
-=item $req->upload
+=head2 $req->upload
A convenient method to access $req->uploads.
}
}
-=item $req->uploads
+=head2 $req->uploads
Returns a reference to a hash containing uploads. Values can be either a
hashref or a arrayref containing L<Catalyst::Request::Upload> objects.
return $self->{uploads};
}
-=item $req->uri
+=head2 $req->uri
Returns a URI object for the current request. Stringifies to the URI text.
-=item $req->user
+=head2 $req->user
Returns the currently logged in user. Deprecated. The method recommended for
newer plugins is $c->user.
-=item $req->user_agent
+=head2 $req->user_agent
Shortcut to $req->headers->user_agent. Returns the user agent (browser)
version string.
-=back
-
=head1 AUTHORS
Sebastian Riedel, C<sri@cpan.org>
=head1 METHODS
-=over 4
-
-=item $upload->new
+=head2 $upload->new
Simple constructor.
-=item $upload->copy_to
+=head2 $upload->copy_to
Copies the temporary file using L<File::Copy>. Returns true for success,
false for failure.
return File::Copy::copy( $self->tempname, @_ );
}
-=item $upload->fh
+=head2 $upload->fh
Opens a temporary file (see tempname below) and returns an L<IO::File> handle.
return $fh;
}
-=item $upload->filename
+=head2 $upload->filename
Returns the client-supplied filename.
-=item $upload->headers
+=head2 $upload->headers
Returns an L<HTTP::Headers> object for the request.
-=item $upload->link_to
+=head2 $upload->link_to
Creates a hard link to the temporary file. Returns true for success,
false for failure.
return CORE::link( $self->tempname, $target );
}
-=item $upload->size
+=head2 $upload->size
Returns the size of the uploaded file in bytes.
-=item $upload->slurp
+=head2 $upload->slurp
Returns a scalar containing the contents of the temporary file.
return $content;
}
-=item $upload->tempname
+=head2 $upload->tempname
Returns the path to the temporary file.
-=item $upload->type
+=head2 $upload->type
Returns the client-supplied Content-Type.
-=back
-
=head1 AUTHORS
Sebastian Riedel, C<sri@cpan.org>
=head1 METHODS
-=over 4
-
-=item $res->body($text)
+=head2 $res->body($text)
$c->response->body('Catalyst rocks!');
Sets or returns the output (text or binary data).
-=item $res->content_encoding
+=head2 $res->content_encoding
Shortcut for $res->headers->content_encoding.
-=item $res->content_length
+=head2 $res->content_length
Shortcut for $res->headers->content_length.
-=item $res->content_type
+=head2 $res->content_type
Shortcut for $res->headers->content_type.
-=item $res->cookies
+=head2 $res->cookies
Returns a reference to a hash containing cookies to be set. The keys of the
hash are the cookies' names, and their corresponding values are hash
parameters of the same name, except they are used without a leading dash.
Possible parameters are:
-=over 4
-
-=item value
+=head2 value
-=item expires
+=head2 expires
-=item domain
+=head2 domain
-=item path
+=head2 path
-=item secure
+=head2 secure
-=back
-
-=item $res->header
+=head2 $res->header
Shortcut for $res->headers->header.
-=item $res->headers
+=head2 $res->headers
Returns an L<HTTP::Headers> object, which can be used to set headers.
$c->response->headers->header( 'X-Catalyst' => $Catalyst::VERSION );
-=item $res->output
+=head2 $res->output
Alias for $res->body.
-=item $res->redirect( $url, $status )
+=head2 $res->redirect( $url, $status )
Causes the response to redirect to the specified URL.
return $self->location;
}
-=item $res->status
+=head2 $res->status
Sets or returns the HTTP status.
$c->response->status(404);
-=item $res->write( $data )
+=head2 $res->write( $data )
Writes $data to the output stream.
sub write { shift->{_context}->write(@_); }
-=back
-
=head1 AUTHORS
Sebastian Riedel, C<sri@cpan.org>
=head2 METHODS
-=over 4
-
-=item get
+=head2 get
Returns the content.
my $content = get('foo/bar?test=1');
-=item request
+=head2 request
Returns a C<HTTP::Response> object.
*{"$caller\::get"} = $get;
}
-=item local_request
+=head2 local_request
=cut
my $agent;
-=item remote_request
+=head2 remote_request
Do an actual remote request using LWP.
return $agent->request($request);
}
-=back
-
=head1 SEE ALSO
L<Catalyst>.
=head1 METHODS
-=over 4
-
-=item appprefix($class)
+=head2 appprefix($class)
MyApp::Foo becomes myapp_foo
return $class;
}
-=item class2appclass($class);
+=head2 class2appclass($class);
MyApp::C::Foo::Bar becomes MyApp
My::App::C::Foo::Bar becomes My::App
return $appname;
}
-=item class2classprefix($class);
+=head2 class2classprefix($class);
MyApp::C::Foo::Bar becomes MyApp::C
My::App::C::Foo::Bar becomes My::App::C
return $prefix;
}
-=item class2classsuffix($class);
+=head2 class2classsuffix($class);
MyApp::C::Foo::Bar becomes C::Foo::Bar
return $class;
}
-=item class2env($class);
+=head2 class2env($class);
Returns the environment name for class.
return uc($class);
}
-=item class2prefix( $class, $case );
+=head2 class2prefix( $class, $case );
Returns the uri prefix for a class. If case is false the prefix is converted to lowercase.
return $prefix;
}
-=item class2tempdir( $class [, $create ] );
+=head2 class2tempdir( $class [, $create ] );
Returns a tempdir for a class. If create is true it will try to create the path.
return $tmpdir->stringify;
}
-=item home($class)
+=head2 home($class)
Returns home directory for given class.
return $home;
}
-=item prefix($class, $name);
+=head2 prefix($class, $name);
Returns a prefixed action.
return $name;
}
-=item request($uri)
+=head2 request($uri)
Returns an L<HTTP::Request> object for a uri.
return $request;
}
-=back
-
=head1 AUTHOR
Sebastian Riedel, C<sri@cpan.org>