Utils doc patch from ningu

[catagits/Catalyst-Runtime.git] / README

NAME
    Catalyst - The Elegant MVC Web Application Framework

SYNOPSIS
        # use the helper to start a new application
        catalyst.pl MyApp
        cd MyApp

        # add models, views, controllers
        script/myapp_create.pl model Something
        script/myapp_create.pl view Stuff
        script/myapp_create.pl controller Yada

        # built in testserver
        script/myapp_server.pl

        # command line interface
        script/myapp_test.pl /yada

        use Catalyst;

        use Catalyst qw/My::Module My::OtherModule/;

        use Catalyst '-Debug';

        use Catalyst qw/-Debug -Engine=CGI/;

        sub default : Private { $_[1]->res->output('Hello') } );

        sub index : Path('/index.html') {
            my ( $self, $c ) = @_;
            $c->res->output('Hello');
            $c->forward('foo');
        }

        sub product : Regex('^product[_]*(\d*).html$') {
            my ( $self, $c ) = @_;
            $c->stash->{template} = 'product.tt';
            $c->stash->{product} = $c->req->snippets->[0];
        }

    See also Catalyst::Manual::Intro

DESCRIPTION
    The key concept of Catalyst is DRY (Don't Repeat Yourself).

    See Catalyst::Manual for more documentation.

    Catalyst plugins can be loaded by naming them as arguments to the "use
    Catalyst" statement. Omit the "Catalyst::Plugin::" prefix from the
    plugin name, so "Catalyst::Plugin::My::Module" becomes "My::Module".

        use Catalyst 'My::Module';

    Special flags like -Debug and -Engine can also be specified as arguments
    when Catalyst is loaded:

        use Catalyst qw/-Debug My::Module/;

    The position of plugins and flags in the chain is important, because
    they are loaded in exactly the order that they appear.

    The following flags are supported:

    -Debug
        enables debug output, i.e.:

            use Catalyst '-Debug';

        this is equivalent to:

            use Catalyst;
            sub debug { 1 }

    -Dispatcher
        Force Catalyst to use a specific dispatcher.

    -Engine
        Force Catalyst to use a specific engine. Omit the
        "Catalyst::Engine::" prefix of the engine name, i.e.:

            use Catalyst '-Engine=CGI';

    -Home
        Force Catalyst to use a specific home directory.

    -Log
        Specify log level.

METHODS
    $c->action
        Accessor for the current action

    $c->comp($name)
    $c->component($name)
        Get a component object by name.

            $c->comp('MyApp::Model::MyModel')->do_stuff;

    config
        Returns a hashref containing your applications settings.

    $c->controller($name)
        Get a Catalyst::Controller instance by name.

            $c->controller('Foo')->do_stuff;

    debug
        Overload to enable debug messages.

    $c->detach( $command [, \@arguments ] )
        Like "forward" but doesn't return.

    $c->dispatcher
        Contains the dispatcher instance. Stringifies to class.

    $c->forward( $command [, \@arguments ] )
        Forward processing to a private action or a method from a class. If
        you define a class without method it will default to process(). also
        takes an optional arrayref containing arguments to be passed to the
        new function. $c->req->args will be reset upon returning from the
        function.

            $c->forward('/foo');
            $c->forward('index');
            $c->forward(qw/MyApp::Model::CDBI::Foo do_stuff/);
            $c->forward('MyApp::View::TT');

    $c->model($name)
        Get a Catalyst::Model instance by name.

            $c->model('Foo')->do_stuff;

    $c->namespace
        Accessor to the namespace of the current action

    $c->path_to(@path)
        Merges @path with $c->config->{home} and returns a Path::Class
        object.

        For example:

            $c->path_to( 'db', 'sqlite.db' );

    $c->setup
        Setup.

            $c->setup;

    $c->uri_for($path,[@args])
        Merges path with $c->request->base for absolute uri's and with
        $c->request->match for relative uri's, then returns a normalized URI
        object. If any args are passed, they are added at the end of the
        path.

    $c->error
    $c->error($error, ...)
    $c->error($arrayref)
        Returns an arrayref containing error messages.

            my @error = @{ $c->error };

        Add a new error.

            $c->error('Something bad happened');

        Clean errors.

            $c->error(0);

    $c->engine
        Contains the engine instance. Stringifies to the class.

    $c->log
        Contains the logging object. Unless it is already set Catalyst sets
        this up with a "Catalyst::Log" object. To use your own log class:

            $c->log( MyLogger->new );
            $c->log->info("now logging with my own logger!");

        Your log class should implement the methods described in the
        "Catalyst::Log" man page.

    $c->plugin( $name, $class, @args )
        Instant plugins for Catalyst. Classdata accessor/mutator will be
        created, class loaded and instantiated.

            MyApp->plugin( 'prototype', 'HTML::Prototype' );

            $c->prototype->define_javascript_functions;

    $c->request
    $c->req
        Returns a "Catalyst::Request" object.

            my $req = $c->req;

    $c->response
    $c->res
        Returns a "Catalyst::Response" object.

            my $res = $c->res;

    $c->state
        Contains the return value of the last executed action.

    $c->stash
        Returns a hashref containing all your data.

            print $c->stash->{foo};

        Keys may be set in the stash by assigning to the hash reference, or
        by passing either a single hash reference or a list of key/value
        pairs as arguments.

        For example:

            $c->stash->{foo} ||= 'yada';
            $c->stash( { moose => 'majestic', qux => 0 } );
            $c->stash( bar => 1, gorch => 2 );

    $c->view($name)
        Get a Catalyst::View instance by name.

            $c->view('Foo')->do_stuff;

    $c->welcome_message
        Returns the Catalyst welcome HTML page.

INTERNAL METHODS
    $c->benchmark($coderef)
        Takes a coderef with arguments and returns elapsed time as float.

            my ( $elapsed, $status ) = $c->benchmark( sub { return 1 } );
            $c->log->info( sprintf "Processing took %f seconds", $elapsed );

    $c->components
        Contains the components.

    $c->context_class($class)
        Contains the context class.

    $c->counter
        Returns a hashref containing coderefs and execution counts. (Needed
        for deep recursion detection)

    $c->depth
        Returns the actual forward depth.

    $c->dispatch
        Dispatch request to actions.

    $c->dispatcher_class($class)
        Contains the dispatcher class.

    dump_these
        Returns a list of 2-element array references (name, structure) pairs
        that will be dumped on the error page in debug mode.

    $c->engine_class($class)
        Contains the engine class.

    $c->execute($class, $coderef)
        Execute a coderef in given class and catch exceptions. Errors are
        available via $c->error.

    $c->finalize
        Finalize request.

    $c->finalize_body
        Finalize body.

    $c->finalize_cookies
        Finalize cookies.

    $c->finalize_error
        Finalize error.

    $c->finalize_headers
        Finalize headers.

    $c->finalize_output
        An alias for finalize_body.

    $c->finalize_read
        Finalize the input after reading is complete.

    $c->finalize_uploads
        Finalize uploads. Cleans up any temporary files.

    $c->get_action( $action, $namespace )
        Get an action in a given namespace.

    $c->get_actions( $action, $namespace )
        Get all actions of a given name in a namespace and all base
        namespaces.

    handle_request( $class, @arguments )
        Handles the request.

    $c->prepare(@arguments)
        Turns the engine-specific request( Apache, CGI ... ) into a Catalyst
        context .

    $c->prepare_action
        Prepare action.

    $c->prepare_body
        Prepare message body.

    $c->prepare_body_chunk( $chunk )
        Prepare a chunk of data before sending it to HTTP::Body.

    $c->prepare_body_parameters
        Prepare body parameters.

    $c->prepare_connection
        Prepare connection.

    $c->prepare_cookies
        Prepare cookies.

    $c->prepare_headers
        Prepare headers.

    $c->prepare_parameters
        Prepare parameters.

    $c->prepare_path
        Prepare path and base.

    $c->prepare_query_parameters
        Prepare query parameters.

    $c->prepare_read
        Prepare the input for reading.

    $c->prepare_request
        Prepare the engine request.

    $c->prepare_uploads
        Prepare uploads.

    $c->prepare_write
        Prepare the output for writing.

    $c->request_class($class)
        Contains the request class.

    $c->response_class($class)
        Contains the response class.

    $c->read( [$maxlength] )
        Read a chunk of data from the request body. This method is designed
        to be used in a while loop, reading $maxlength bytes on every call.
        $maxlength defaults to the size of the request if not specified.

        You have to set MyApp->config->{parse_on_demand} to use this
        directly.

    $c->run
        Starts the engine.

    $c->set_action( $action, $code, $namespace, $attrs )
        Set an action in a given namespace.

    $c->setup_actions($component)
        Setup actions for a component.

    $c->setup_components
        Setup components.

    $c->setup_dispatcher
    $c->setup_engine
    $c->setup_home
    $c->setup_log
    $c->setup_plugins
    $c->stack
        Contains the stack.

    $c->write( $data )
        Writes $data to the output stream. When using this method directly,
        you will need to manually set the Content-Length header to the
        length of your output data, if known.

    version
        Returns the Catalyst version number. mostly useful for powered by
        messages in template systems.

INTERNAL ACTIONS
    Catalyst uses internal actions like "_DISPATCH", "_BEGIN", "_AUTO"
    "_ACTION" and "_END", these are by default not shown in the private
    action table.

    But you can deactivate this with a config parameter.

        MyApp->config->{show_internal_actions} = 1;

CASE SENSITIVITY
    By default Catalyst is not case sensitive, so "MyApp::C::FOO::Bar"
    becomes "/foo/bar".

    But you can activate case sensitivity with a config parameter.

        MyApp->config->{case_sensitive} = 1;

    So "MyApp::C::Foo::Bar" becomes "/Foo/Bar".

ON-DEMAND PARSER
    The request body is usually parsed at the beginning of a request, but if
    you want to handle input yourself or speed things up a bit you can
    enable on-demand parsing with a config parameter.

        MyApp->config->{parse_on_demand} = 1;
    
PROXY SUPPORT
    Many production servers operate using the common double-server approach,
    with a lightweight frontend web server passing requests to a larger
    backend server. An application running on the backend server must deal
    with two problems: the remote user always appears to be '127.0.0.1' and
    the server's hostname will appear to be 'localhost' regardless of the
    virtual host the user connected through.

    Catalyst will automatically detect this situation when you are running
    both the frontend and backend servers on the same machine. The following
    changes are made to the request.

        $c->req->address is set to the user's real IP address, as read from the
        HTTP_X_FORWARDED_FOR header.
    
        The host value for $c->req->base and $c->req->uri is set to the real host,
        as read from the HTTP_X_FORWARDED_HOST header.

    Obviously, your web server must support these 2 headers for this to
    work.

    In a more complex server farm environment where you may have your
    frontend proxy server(s) on different machines, you will need to set a
    configuration option to tell Catalyst to read the proxied data from the
    headers.

        MyApp->config->{using_frontend_proxy} = 1;
    
    If you do not wish to use the proxy support at all, you may set:

        MyApp->config->{ignore_frontend_proxy} = 1;

THREAD SAFETY
    Catalyst has been tested under Apache 2's threading mpm_worker,
    mpm_winnt, and the standalone forking HTTP server on Windows. We believe
    the Catalyst core to be thread-safe.

    If you plan to operate in a threaded environment, remember that all
    other modules you are using must also be thread-safe. Some modules, most
    notably DBD::SQLite, are not thread-safe.

SUPPORT
    IRC:

        Join #catalyst on irc.perl.org.

    Mailing-Lists:

        http://lists.rawmode.org/mailman/listinfo/catalyst
        http://lists.rawmode.org/mailman/listinfo/catalyst-dev

    Web:

        http://catalyst.perl.org

SEE ALSO
    Catalyst::Manual - The Catalyst Manual
    Catalyst::Engine - Core Engine
    Catalyst::Log - The Log Class.
    Catalyst::Request - The Request Object
    Catalyst::Response - The Response Object
    Catalyst::Test - The test suite.

CREDITS
    Andy Grundman

    Andy Wardley

    Andreas Marienborg

    Andrew Bramble

    Andrew Ford

    Andrew Ruthven

    Arthur Bergman

    Autrijus Tang

    Brian Cassidy

    Christian Hansen

    Christopher Hicks

    Dan Sully

    Danijel Milicevic

    David Naughton

    Gary Ashton Jones

    Geoff Richards

    Jesse Sheidlower

    Jesse Vincent

    Jody Belka

    Johan Lindstrom

    Juan Camacho

    Leon Brocard

    Marcus Ramberg

    Matt S Trout

    Robert Sedlacek

    Sam Vilain

    Sascha Kiefer

    Tatsuhiko Miyagawa

    Ulf Edvinsson

    Yuval Kogman

AUTHOR
    Sebastian Riedel, "sri@oook.de"

LICENSE
    This library is free software, you can redistribute it and/or modify it
    under the same terms as Perl itself.