X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Runtime.git;a=blobdiff_plain;f=README;h=1438432076cc0a6c7b97ae639b564fab3ef33b87;hp=387806f1dc42e323cfad2addbf35b652f52b0233;hb=gsoc_breadboard;hpb=60b53d078b97c5f90a870f46bef70b889d857701 diff --git a/README b/README index 387806f..1438432 100644 --- a/README +++ b/README @@ -1,509 +1,14 @@ -NAME - Catalyst - The Elegant MVC Web Application Framework +Catalyst-Runtime +================ +This is the Runtime distribution for the Catalyst MVC framework. +For more information about Catalyst, write -SYNOPSIS - # use the helper to start a new application - catalyst.pl MyApp - cd MyApp +$ perldoc Catalyst - # 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. - - 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. - - $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->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 - 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" - -LICENSE - This library is free software, you can redistribute it and/or modify it - under the same terms as Perl itself. +at the command line, or visit http://www.catalystframework.org/. +You can also install Catalyst::Manual from CPAN for more +comprehensive information. +If you are going to write your own Catalyst application, you will +need to install Catalyst::Devel. Afterwards run catalyst.pl +for more information about creating your first app.