X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Runtime.git;a=blobdiff_plain;f=README;h=387806f1dc42e323cfad2addbf35b652f52b0233;hp=402b2d10a847548be02048acf1ac3c5108a9d248;hb=0cf56dbcd3a060c815aa5e66a67709bb51efd80d;hpb=9c470869875115d965f5e8a84e8bcc532d9d2f72 diff --git a/README b/README index 402b2d1..387806f 100644 --- a/README +++ b/README @@ -3,21 +3,19 @@ NAME SYNOPSIS # use the helper to start a new application - catalyst MyApp + catalyst.pl MyApp cd 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 Something + script/myapp_create.pl view Stuff + script/myapp_create.pl controller Yada # built in testserver - perl bin/server + script/myapp_server.pl # command line interface - perl bin/test /yada - - See also L + script/myapp_test.pl /yada use Catalyst; @@ -27,77 +25,485 @@ SYNOPSIS use Catalyst qw/-Debug -Engine=CGI/; - __PACKAGE__->action( '!default' => sub { $_[1]->res->output('Hello') } ); + sub default : Private { $_[1]->res->output('Hello') } ); - __PACKAGE__->action( - 'index.html' => sub { - my ( $self, $c ) = @_; - $c->res->output('Hello'); - $c->forward('_foo'); - } - ); + sub index : Path('/index.html') { + my ( $self, $c ) = @_; + $c->res->output('Hello'); + $c->forward('foo'); + } - __PACKAGE__->action( - '/^product[_]*(\d*).html$/' => sub { - my ( $self, $c ) = @_; - $c->stash->{template} = 'product.tt'; - $c->stash->{product} = $c->req->snippets->[0]; - } - ); + sub product : Regex('^product[_]*(\d*).html$') { + my ( $self, $c ) = @_; + $c->stash->{template} = 'product.tt'; + $c->stash->{product} = $c->req->snippets->[0]; + } -DESCRIPTION - Catalyst is based upon Maypole, which you should consider for smaller - projects. + See also Catalyst::Manual::Intro +DESCRIPTION The key concept of Catalyst is DRY (Don't Repeat Yourself). See Catalyst::Manual for more documentation. - Omit the Catalyst::Plugin:: prefix from plugins. So - Catalyst::Plugin::My::Module becomes My::Module. + 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'; - You can also set special flags like -Debug and -Engine. + 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 the same order they appear. + they are loaded in exactly the order that they appear. - -Debug - use Catalyst '-Debug'; + The following flags are supported: - is equivalent to + -Debug + enables debug output, i.e.: - use Catalyst; - sub debug { 1 } + 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. + + 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->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->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->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. + + 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->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. - -Engine - Force Catalyst to use a specific engine. Omit the Catalyst::Engine:: - prefix. + $c->prepare(@arguments) + Turns the engine-specific request( Apache, CGI ... ) into a Catalyst + context . - use Catalyst '-Engine=CGI'; + $c->prepare_action + Prepare action. - METHODS - debug - Overload to enable debug messages. + $c->prepare_body + Prepare message body. - config - Returns a hashref containing your applications settings. + $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->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->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, Catalyst::Test, Catalyst::Request, Catalyst::Response, - Catalyst::Engine + 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 + + 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 + + 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.