Add built local::lib

[catagits/Gitalist.git] / local-lib5 / man / man3 / Catalyst::Helper.3pm

.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Catalyst::Helper 3"
.TH Catalyst::Helper 3 "2009-12-06" "perl v5.8.7" "User Contributed Perl Documentation"
.SH "NAME"
Catalyst::Helper \- Bootstrap a Catalyst application
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  catalyst.pl <myappname>
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module is used by \fBcatalyst.pl\fR to create a set of scripts for a
new catalyst application. The scripts each contain documentation and
will output help on how to use them if called incorrectly or in some
cases, with no arguments.
.PP
It also provides some useful methods for a Helper module to call when
creating a component. See \*(L"\s-1METHODS\s0\*(R".
.SH "SCRIPTS"
.IX Header "SCRIPTS"
.Sh "_create.pl"
.IX Subsection "_create.pl"
Used to create new components for a catalyst application at the
development stage.
.Sh "_server.pl"
.IX Subsection "_server.pl"
The catalyst test server, starts an \s-1HTTPD\s0 which outputs debugging to
the terminal.
.Sh "_test.pl"
.IX Subsection "_test.pl"
A script for running tests from the command\-line.
.Sh "_cgi.pl"
.IX Subsection "_cgi.pl"
Run your application as a \s-1CGI\s0.
.Sh "_fastcgi.pl"
.IX Subsection "_fastcgi.pl"
Run the application as a fastcgi app. Either by hand, or call this
from FastCgiServer in your http server config.
.SH "HELPERS"
.IX Header "HELPERS"
The \*(L"_create.pl\*(R" script creates application components using Helper
modules. The Catalyst team provides a good number of Helper modules
for you to use. You can also add your own.
.PP
Helpers are classes that provide two methods.
.PP
.Vb 2
\&    * mk_compclass \- creates the Component class
\&    * mk_comptest  \- creates the Component test
.Ve
.PP
So when you call \f(CW\*(C`scripts/myapp_create.pl view MyView TT\*(C'\fR, create
will try to execute Catalyst::Helper::View::TT\->mk_compclass and
Catalyst::Helper::View::TT\->mk_comptest.
.PP
See Catalyst::Helper::View::TT and
Catalyst::Helper::Model::DBIC::Schema for examples.
.PP
All helper classes should be under one of the following namespaces.
.PP
.Vb 3
\&    Catalyst::Helper::Model::
\&    Catalyst::Helper::View::
\&    Catalyst::Helper::Controller::
.Ve
.Sh "\s-1COMMON\s0 \s-1HELPERS\s0"
.IX Subsection "COMMON HELPERS"
.IP "\(bu" 4
Catalyst::Helper::Model::DBIC::Schema \- DBIx::Class models
.IP "\(bu" 4
Catalyst::Helper::View::TT \- Template Toolkit view
.IP "\(bu" 4
Catalyst::Helper::Model::LDAP
.IP "\(bu" 4
Catalyst::Helper::Model::Adaptor \- wrap any class into a Catalyst model
.PP
\fI\s-1NOTE\s0\fR
.IX Subsection "NOTE"
.PP
The helpers will read author name from /etc/passwd by default.
To override, please export the \s-1AUTHOR\s0 variable.
.SH "METHODS"
.IX Header "METHODS"
.Sh "mk_compclass"
.IX Subsection "mk_compclass"
This method in your Helper module is called with \f(CW$helper\fR
which is a Catalyst::Helper object, and whichever other arguments
the user added to the command\-line. You can use the \f(CW$helper\fR to call methods
described below.
.PP
If the Helper module does not contain a \f(CW\*(C`mk_compclass\*(C'\fR method, it
will fall back to calling \*(L"render_file\*(R", with an argument of
\&\f(CW\*(C`compclass\*(C'\fR.
.Sh "mk_comptest"
.IX Subsection "mk_comptest"
This method in your Helper module is called with \f(CW$helper\fR
which is a Catalyst::Helper object, and whichever other arguments
the user added to the command\-line. You can use the \f(CW$helper\fR to call methods
described below.
.PP
If the Helper module does not contain a \f(CW\*(C`mk_compclass\*(C'\fR method, it
will fall back to calling \*(L"render_file\*(R", with an argument of
\&\f(CW\*(C`comptest\*(C'\fR.
.Sh "mk_stuff"
.IX Subsection "mk_stuff"
This method is called if the user does not supply any of the usual
component types \f(CW\*(C`view\*(C'\fR, \f(CW\*(C`controller\*(C'\fR, \f(CW\*(C`model\*(C'\fR. It is passed the
\&\f(CW$helper\fR object (an instance of Catalyst::Helper), and any other
arguments the user typed.
.PP
There is no fallback for this method.
.SH "INTERNAL METHODS"
.IX Header "INTERNAL METHODS"
These are the methods that the Helper classes can call on the
<$helper> object passed to them.
.ie n .Sh "render_file ($file, $path\fP, \f(CW$vars)"
.el .Sh "render_file ($file, \f(CW$path\fP, \f(CW$vars\fP)"
.IX Subsection "render_file ($file, $path, $vars)"
Render and create a file from a template in \s-1DATA\s0 using Template
Toolkit. \f(CW$file\fR is the relevent chunk of the _\|_DATA_\|_ section, \f(CW$path\fR is
the path to the file and \f(CW$vars\fR is the hashref as expected by
Template Toolkit.
.ie n .Sh "get_file ($class, $file)"
.el .Sh "get_file ($class, \f(CW$file\fP)"
.IX Subsection "get_file ($class, $file)"
Fetch file contents from the \s-1DATA\s0 section. This is used internally by
\&\*(L"render_file\*(R".  \f(CW$class\fR is the name of the class to get the \s-1DATA\s0
section from.  _\|_PACKAGE_\|_ or ( \fIcaller\fR\|(0) )[0] might be sensible
values for this.
.Sh "mk_app"
.IX Subsection "mk_app"
Create the main application skeleton. This is called by catalyst.pl.
.Sh "mk_component ($app)"
.IX Subsection "mk_component ($app)"
This method is called by create.pl to make new components
for your application.
.Sh "mk_dir ($path)"
.IX Subsection "mk_dir ($path)"
Surprisingly, this function makes a directory.
.ie n .Sh "mk_file ($file, $content)"
.el .Sh "mk_file ($file, \f(CW$content\fP)"
.IX Subsection "mk_file ($file, $content)"
Writes content to a file. Called by \*(L"render_file\*(R".
.Sh "next_test ($test_name)"
.IX Subsection "next_test ($test_name)"
Calculates the name of the next numbered test file and returns it.
Don't give the number or the .t suffix for the test name.
.Sh "get_sharedir_file"
.IX Subsection "get_sharedir_file"
Method for getting a file out of share/
.Sh "render_file_contents"
.IX Subsection "render_file_contents"
Process a Template::Toolkit template.
.Sh "render_sharedir_file"
.IX Subsection "render_sharedir_file"
Render a template/image file from our share directory
.SH "NOTE"
.IX Header "NOTE"
The helpers will read author name from /etc/passwd by default.
To override, please export the \s-1AUTHOR\s0 variable.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Catalyst::Manual, Catalyst::Test, Catalyst::Request,
Catalyst::Response, Catalyst
.SH "AUTHORS"
.IX Header "AUTHORS"
Catalyst Contributors, see Catalyst.pm
.SH "LICENSE"
.IX Header "LICENSE"
This library is free software. You can redistribute it and/or modify
it under the same terms as Perl itself.