X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Runtime.git;a=blobdiff_plain;f=README;h=b8f4f88f68782b702b8c12f9de229782bed570e4;hp=a9e783dec84cb85340feb865e37fa332e5a98611;hb=24d0c6d2eca02cc36ceae9e7fc4747b0150e8bcd;hpb=7833fdfca73ff8a03769523ec85c2343a3994360

diff --git a/README b/README
index a9e783d..b8f4f88 100644
--- a/README
+++ b/README
@@ -3,101 +3,589 @@ NAME
 
 SYNOPSIS
         # use the helper to start a new application
-        perl /path/to/catalyst MyApp
-        cd MyApp
+        catalyst.pl MyApp
 
         # add models, views, controllers
-        perl bin/create model Something
-        perl bin/create view Stuff
-        perl bin/create controller Yada
+        script/myapp_create.pl model Database DBIC dbi:SQLite:/path/to/db
+        script/myapp_create.pl view TT TT
+        script/myapp_create.pl controller Search
+
+        # built in testserver -- use -r to restart automatically on changes
+        script/myapp_server.pl
+
+        # command line testing interface
+        script/myapp_test.pl /yada
+
+        ### in MyApp.pm
+        use Catalyst qw/-Debug/; # include plugins here as well
+    
+        sub foo : Global { # called for /foo, /foo/1, /foo/1/2, etc.
+            my ( $self, $c, @args ) = @_; # args are qw/on you/ for /foo/on/you
+            $c->stash->{template} = 'foo.tt';
+            # lookup something from db -- stash vars are passed to TT
+            $c->stash->{data} = MyApp::Model::Database::Foo->search;
+            if ( $c->req->params->{bar} ) { # access GET or POST parameters
+                $c->forward( 'bar' ); # process another action
+                # do something else after forward returns            
+            }
+        }
+    
+        # The foo.tt TT template can easily use the stash data from the database
+        [% WHILE (item = data.next) %]
+            [% item.foo %]
+        [% END %]
+    
+        # called for /bar/of/soap, /bar/of/soap/10, etc.
+        sub bar : Path('/bar/of/soap') { ... }
+
+        # called for all actions, from the top-most controller inwards
+        sub auto : Private { 
+            my ( $self, $c ) = @_;
+            if ( !$c->user ) {
+                $c->res->redirect( '/login' ); # require login
+                return 0; # abort request and go immediately to end()
+            }
+            return 1;
+        }
+    
+        # called after the main action is finished
+        sub end : Private { 
+            my ( $self, $c ) = @_;
+            if ( scalar @{ $c->error } ) { ... } # handle errors
+            return if $c->res->body; # already have a response
+            $c->forward( 'MyApp::View::TT' ); # render template
+        }
+
+        ### in MyApp/Controller/Foo.pm
+        # called for /foo/bar
+        sub bar : Local { ... }
+    
+        # called for /blargle
+        sub blargle : Global { ... }
+    
+        # an index action matches /foo, but not /foo/1, etc.
+        sub index : Private { ... }
+    
+        ### in MyApp/Controller/Foo/Bar.pm
+        # called for /foo/bar/baz
+        sub baz : Local { ... }
+    
+        # first MyApp auto is called, then Foo auto, then this
+        sub auto : Private { ... }
+    
+        # powerful regular expression paths are also possible
+        sub details : Regex('^product/(\w+)/details$') {
+            my ( $self, $c ) = @_;
+            # extract the (\w+) from the URI
+            my $product = $c->req->snippets->[0];
+        }
+
+    See Catalyst::Manual::Intro for additional information.
 
-        # built in testserver
-        perl bin/server
+DESCRIPTION
+    The key concept of Catalyst is DRY (Don't Repeat Yourself).
 
-        # command line interface
-        perl bin/test /yada
+    See Catalyst::Manual for more documentation.
 
-        See also L<Catalyst::Manual::Intro>
+    Catalyst plugins can be loaded by naming them as arguments to the "use
+    Catalyst" statement. Omit the "Catalyst::Plugin::" prefix from the
+    plugin name, i.e., "Catalyst::Plugin::My::Module" becomes "My::Module".
 
-        use Catalyst;
+        use Catalyst qw/My::Module/;
 
-        use Catalyst qw/My::Module My::OtherModule/;
+    Special flags like -Debug and -Engine can also be specified as arguments
+    when Catalyst is loaded:
 
-        use Catalyst '-Debug';
+        use Catalyst qw/-Debug My::Module/;
 
-        use Catalyst qw/-Debug -Engine=CGI/;
+    The position of plugins and flags in the chain is important, because
+    they are loaded in exactly the order that they appear.
 
-        __PACKAGE__->action( '!default' => sub { $_[1]->res->output('Hello') } );
+    The following flags are supported:
 
-        __PACKAGE__->action(
-            'index.html' => sub {
-                my ( $self, $c ) = @_;
-                $c->res->output('Hello');
-                $c->forward('_foo');
-            }
-        );
+    -Debug
+        Enables debug output.
 
-        __PACKAGE__->action(
-            '/^product[_]*(\d*).html$/' => sub {
-                my ( $self, $c ) = @_;
-                $c->stash->{template} = 'product.tt';
-                $c->stash->{product} = $c->req->snippets->[0];
-            }
-        );
+    -Engine
+        Forces Catalyst to use a specific engine. Omit the
+        "Catalyst::Engine::" prefix of the engine name, i.e.:
 
-DESCRIPTION
-    Catalyst is based upon Maypole, which you should consider for smaller
-    projects.
+            use Catalyst qw/-Engine=CGI/;
 
-    The key concept of Catalyst is DRY (Don't Repeat Yourself).
+    -Home
+        Forces Catalyst to use a specific home directory.
 
-    See Catalyst::Manual for more documentation.
+    -Log
+        Specifies log level.
 
-    Omit the Catalyst::Plugin:: prefix from plugins. So
-    Catalyst::Plugin::My::Module becomes My::Module.
+METHODS
+  Information about the current request
+    $c->action
+        Returns a Catalyst::Action object for the current action, which
+        stringifies to the action name.
 
-        use Catalyst 'My::Module';
+    $c->namespace
+        Returns the namespace of the current action, i.e., the uri prefix
+        corresponding to the controller of the current action.
 
-    You can also set special flags like -Debug and -Engine.
+    $c->request
+    $c->req
+        Returns the current Catalyst::Request object.
 
-        use Catalyst qw/-Debug My::Module/;
+  Processing and response to the current request
+    $c->forward( $action [, \@arguments ] )
+    $c->forward( $class, $method, [, \@arguments ] )
+        Forwards processing to a private action. If you give a class name
+        but no method, process() is called. You may also optionally pass
+        arguments in an arrayref. The action will receive the arguments in
+        @_ and $c->req->args. Upon returning from the function,
+        $c->req->args will be restored to the previous values.
 
-    The position of plugins and flags in the chain is important, because
-    they are loaded in the same order they appear.
+            $c->forward('/foo');
+            $c->forward('index');
+            $c->forward(qw/MyApp::Model::CDBI::Foo do_stuff/);
+            $c->forward('MyApp::View::TT');
+
+    $c->detach( $action [, \@arguments ] )
+    $c->detach( $class, $method, [, \@arguments ] )
+        The same as "forward", but doesn't return.
+
+    $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');
+
+        Clear errors.
+
+            $c->error(0);
+
+    $c->response
+    $c->res
+        Returns the current Catalyst::Response object.
+
+    $c->stash
+        Returns a hashref to the stash, which may be used to store data and
+        pass it between components. You can also set hash keys by passing
+        arguments. The stash is automatically sent to the view.
+
+            $c->stash->{foo} = $bar;
+            $c->stash( { moose => 'majestic', qux => 0 } );
+            $c->stash( bar => 1, gorch => 2 ); # equivalent to passing a hashref
+    
+            # stash is automatically passed to the view for use in a template
+            $c->forward( 'MyApp::V::TT' );
+
+    $c->state
+        Contains the return value of the last executed action.
+
+  Component Accessors
+    $c->comp($name)
+    $c->component($name)
+        Gets a component object by name. This method is no longer
+        recommended. $c->controller, $c->model, and $c->view should be used
+        instead.
+
+    $c->controller($name)
+        Gets a Catalyst::Controller instance by name.
+
+            $c->controller('Foo')->do_stuff;
+
+    $c->model($name)
+        Gets a Catalyst::Model instance by name.
+
+            $c->model('Foo')->do_stuff;
+
+    $c->view($name)
+        Gets a Catalyst::View instance by name.
+
+            $c->view('Foo')->do_stuff;
+
+  Class data and helper classes
+    $c->config
+        Returns or takes a hashref containing the application's
+        configuration.
+
+            __PACKAGE__->config({ db => 'dsn:SQLite:foo.db' });
+
+    $c->debug
+        Overload to enable debug messages (same as -Debug option).
+
+    $c->dispatcher
+        Returns the dispatcher instance. Stringifies to class name.
+
+    $c->engine
+        Returns the engine instance. Stringifies to the class name.
+
+    $c->log
+        Returns the logging object instance. 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.
+
+  Utility methods
+    $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->plugin( $name, $class, @args )
+        Helper method for plugins. It creates a classdata accessor/mutator
+        and loads and instantiates the given class.
+
+            MyApp->plugin( 'prototype', 'HTML::Prototype' );
+
+            $c->prototype->define_javascript_functions;
+
+    MyApp->setup
+        Initializes the dispatcher and engine, loads any plugins, and loads
+        the model, view, and controller components. You may also specify an
+        array of plugins to load here, if you choose to not load them in the
+        "use Catalyst" line.
+
+            MyApp->setup;
+            MyApp->setup( qw/-Debug/ );
+
+    $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->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
+        Returns a hash of components.
+
+    $c->context_class
+        Returns or sets the context class.
+
+    $c->counter
+        Returns a hashref containing coderefs and execution counts (needed
+        for deep recursion detection).
+
+    $c->depth
+        Returns the number of actions on the current internal execution
+        stack.
+
+    $c->dispatch
+        Dispatches a request to actions.
+
+    $c->dispatcher_class
+        Returns or sets the dispatcher class.
+
+    $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.
+
+    $c->engine_class
+        Returns or sets the engine class.
+
+    $c->execute( $class, $coderef )
+        Execute a coderef in given class and catch exceptions. Errors are
+        available via $c->error.
+
+    $c->finalize
+        Finalizes the request.
+
+    $c->finalize_body
+        Finalizes body.
+
+    $c->finalize_cookies
+        Finalizes cookies.
+
+    $c->finalize_error
+        Finalizes error.
+
+    $c->finalize_headers
+        Finalizes headers.
+
+    $c->finalize_output
+        An alias for finalize_body.
+
+    $c->finalize_read
+        Finalizes the input after reading is complete.
+
+    $c->finalize_uploads
+        Finalizes uploads. Cleans up any temporary files.
+
+    $c->get_action( $action, $namespace )
+        Gets an action in a given namespace.
+
+    $c->get_actions( $action, $namespace )
+        Gets all actions of a given name in a namespace and all parent
+        namespaces.
+
+    handle_request( $class, @arguments )
+        Called to handle each HTTP request.
+
+    $c->prepare( @arguments )
+        Creates a Catalyst context from an engine-specific request (Apache,
+        CGI, etc.).
 
-  -Debug
-        use Catalyst '-Debug';
+    $c->prepare_action
+        Prepares action.
 
-    is equivalent to
+    $c->prepare_body
+        Prepares message body.
 
-        use Catalyst;
-        sub debug { 1 }
+    $c->prepare_body_chunk( $chunk )
+        Prepares a chunk of data before sending it to HTTP::Body.
 
-  -Engine
-    Force Catalyst to use a specific engine. Omit the Catalyst::Engine::
-    prefix.
+    $c->prepare_body_parameters
+        Prepares body parameters.
 
-        use Catalyst '-Engine=CGI';
+    $c->prepare_connection
+        Prepares connection.
 
-  METHODS
-   debug
-    Overload to enable debug messages.
+    $c->prepare_cookies
+        Prepares cookies.
 
-   config
-    Returns a hashref containing your applications settings.
+    $c->prepare_headers
+        Prepares headers.
+
+    $c->prepare_parameters
+        Prepares parameters.
+
+    $c->prepare_path
+        Prepares path and base.
+
+    $c->prepare_query_parameters
+        Prepares query parameters.
+
+    $c->prepare_read
+        Prepares the input for reading.
+
+    $c->prepare_request
+        Prepares the engine request.
+
+    $c->prepare_uploads
+        Prepares uploads.
+
+    $c->prepare_write
+        Prepares the output for writing.
+
+    $c->request_class
+        Returns or sets the request class.
+
+    $c->response_class
+        Returns or sets the response class.
+
+    $c->read( [$maxlength] )
+        Reads 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 )
+        Sets an action in a given namespace.
+
+    $c->setup_actions($component)
+        Sets up actions for a component.
+
+    $c->setup_components
+        Sets up components.
+
+    $c->setup_dispatcher
+    $c->setup_engine
+    $c->setup_home
+    $c->setup_log
+    $c->setup_plugins
+    $c->stack
+        Returns 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 make them visible with a config parameter.
+
+        MyApp->config->{show_internal_actions} = 1;
+
+CASE SENSITIVITY
+    By default Catalyst is not case sensitive, so "MyApp::C::FOO::Bar" is
+    mapped to "/foo/bar". You can activate case sensitivity with a config
+    parameter.
+
+        MyApp->config->{case_sensitive} = 1;
+
+    This causes "MyApp::C::Foo::Bar" to map to "/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 that the user connected through.
+
+    Catalyst will automatically detect this situation when you are running
+    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 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
+
+    Wiki:
+
+        http://dev.catalyst.perl.org
 
 SEE ALSO
-    Catalyst::Manual, Catalyst::Test, Catalyst::Request, Catalyst::Response,
-    Catalyst::Engine
+    Catalyst::Manual - The Catalyst Manual
+    Catalyst::Component, Catalyst::Base - Base classes for components
+    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 Kamholz
+
+    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"
 
-THANK YOU
-    Danijel Milicevic, David Naughton, Gary Ashton Jones, Jesse Sheidlower,
-    Johan Lindstrom, Marcus Ramberg and all the others who've helped.
-
 LICENSE
-    This library is free software . You can redistribute it and/or modify it
-    under the same terms as perl itself.
+    This library is free software, you can redistribute it and/or modify it
+    under the same terms as Perl itself.