Add built local::lib

[catagits/Gitalist.git] / local-lib5 / man / man3 / Template::Plugin::Directory.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 "Template::Plugin::Directory 3"
.TH Template::Plugin::Directory 3 "2008-11-13" "perl v5.8.7" "User Contributed Perl Documentation"
.SH "NAME"
Template::Plugin::Directory \- Plugin for generating directory listings
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    [% USE dir = Directory(dirpath) %]
.Ve
.PP
.Vb 4
\&    # files returns list of regular files
\&    [% FOREACH file = dir.files %]
\&       [% file.name %] [% file.path %] ...
\&    [% END %]
.Ve
.PP
.Vb 4
\&    # dirs returns list of sub\-directories
\&    [% FOREACH subdir = dir.dirs %]
\&       [% subdir.name %] [% subdir.path %] ...
\&    [% END %]
.Ve
.PP
.Vb 8
\&    # list returns both interleaved in order
\&    [% FOREACH item = dir.list %]
\&       [% IF item.isdir %]
\&          Directory: [% item.name %]
\&       [% ELSE %]
\&          File: [% item.name %]
\&       [% END %]
\&    [% END %]
.Ve
.PP
.Vb 5
\&    # define a VIEW to display dirs/files
\&    [% VIEW myview %]
\&       [% BLOCK file %]
\&       File: [% item.name %]
\&       [% END %]
.Ve
.PP
.Vb 5
\&       [% BLOCK directory %]
\&       Directory: [% item.name %] 
\&       [% item.content(myview) | indent \-%]
\&       [% END %]
\&    [% END %]
.Ve
.PP
.Vb 2
\&    # display directory content using view
\&    [% myview.print(dir) %]
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This Template Toolkit plugin provides a simple interface to directory
listings.  It is derived from the Template::Plugin::File module and
uses Template::Plugin::File object instances to represent files within
a directory.  Sub-directories within a directory are represented by
further \f(CW\*(C`Template::Plugin::Directory\*(C'\fR instances.
.PP
The constructor expects a directory name as an argument.
.PP
.Vb 1
\&    [% USE dir = Directory('/tmp') %]
.Ve
.PP
It then provides access to the files and sub-directories contained within 
the directory.
.PP
.Vb 4
\&    # regular files (not directories)
\&    [% FOREACH file IN dir.files %]
\&       [% file.name %]
\&    [% END %]
.Ve
.PP
.Vb 4
\&    # directories only
\&    [% FOREACH file IN dir.dirs %]
\&       [% file.name %]
\&    [% END %]
.Ve
.PP
.Vb 4
\&    # files and/or directories
\&    [% FOREACH file IN dir.list %]
\&       [% file.name %] ([% file.isdir ? 'directory' : 'file' %])
\&    [% END %]
.Ve
.PP
The plugin constructor will throw a \f(CW\*(C`Directory\*(C'\fR error if the specified
path does not exist, is not a directory or fails to \f(CW\*(C`stat()\*(C'\fR (see
Template::Plugin::File).  Otherwise, it will scan the directory and
create lists named '\f(CW\*(C`files\*(C'\fR' containing files, '\f(CW\*(C`dirs\*(C'\fR' containing
directories and '\f(CW\*(C`list\*(C'\fR' containing both files and directories combined.
The \f(CW\*(C`nostat\*(C'\fR option can be set to disable all file/directory checks
and directory scanning.
.PP
Each file in the directory will be represented by a
Template::Plugin::File object instance, and each directory by another
\&\f(CW\*(C`Template::Plugin::Directory\*(C'\fR.  If the \f(CW\*(C`recurse\*(C'\fR flag is set, then those
directories will contain further nested entries, and so on.  With the
\&\f(CW\*(C`recurse\*(C'\fR flag unset, as it is by default, then each is just a place
marker for the directory and does not contain any further content
unless its \f(CW\*(C`scan()\*(C'\fR method is explicitly called.  The \f(CW\*(C`isdir\*(C'\fR flag can
be tested against files and/or directories, returning true if the item
is a directory or false if it is a regular file.
.PP
.Vb 7
\&    [% FOREACH file = dir.list %]
\&       [% IF file.isdir %]
\&          * Directory: [% file.name %]
\&       [% ELSE %]
\&          * File: [% file.name %]
\&       [% END %]
\&    [% END %]
.Ve
.PP
This example shows how you might walk down a directory tree, displaying 
content as you go.  With the recurse flag disabled, as is the default, 
we need to explicitly call the \f(CW\*(C`scan()\*(C'\fR method on each directory, to force
it to lookup files and further sub-directories contained within. 
.PP
.Vb 3
\&    [% USE dir = Directory(dirpath) %]
\&    * [% dir.path %]
\&    [% INCLUDE showdir %]
.Ve
.PP
.Vb 11
\&    [% BLOCK showdir \-%]
\&      [% FOREACH file = dir.list \-%]
\&        [% IF file.isdir \-%]
\&        * [% file.name %]
\&          [% file.scan \-%]
\&          [% INCLUDE showdir dir=file FILTER indent(4) \-%]
\&        [% ELSE \-%]
\&        \- [% f.name %]
\&        [% END \-%]
\&      [% END \-%]
\&     [% END %]
.Ve
.PP
This example is adapted (with some re-formatting for clarity) from
a test in \fIt/directry.t\fR which produces the following output:
.PP
.Vb 10
\&    * test/dir
\&        \- file1
\&        \- file2
\&        * sub_one
\&            \- bar
\&            \- foo
\&        * sub_two
\&            \- waz.html
\&            \- wiz.html
\&        \- xyzfile
.Ve
.PP
The \f(CW\*(C`recurse\*(C'\fR flag can be set (disabled by default) to cause the
constructor to automatically recurse down into all sub\-directories,
creating a new \f(CW\*(C`Template::Plugin::Directory\*(C'\fR object for each one and 
filling it with any further content.  In this case there is no need
to explicitly call the \f(CW\*(C`scan()\*(C'\fR method.
.PP
.Vb 2
\&    [% USE dir = Directory(dirpath, recurse=1) %]
\&       ...
.Ve
.PP
.Vb 5
\&        [% IF file.isdir \-%]
\&        * [% file.name %]
\&          [% INCLUDE showdir dir=file FILTER indent(4) \-%]
\&        [% ELSE \-%]
\&           ...
.Ve
.PP
The directory plugin also provides support for views. A view can be defined as
a \f(CW\*(C`VIEW ... END\*(C'\fR block and should contain \f(CW\*(C`BLOCK\*(C'\fR definitions for files
('\f(CW\*(C`file\*(C'\fR') and directories ('\f(CW\*(C`directory\*(C'\fR').
.PP
.Vb 4
\&    [% VIEW myview %]
\&    [% BLOCK file %]
\&       \- [% item.name %]
\&    [% END %]
.Ve
.PP
.Vb 5
\&    [% BLOCK directory %]
\&       * [% item.name %]
\&         [% item.content(myview) FILTER indent %]
\&    [% END %]
\&    [% END %]
.Ve
.PP
The view \f(CW\*(C`print()\*(C'\fR method can then be called, passing the
\&\f(CW\*(C`Directory\*(C'\fR object as an argument.
.PP
.Vb 2
\&    [% USE dir = Directory(dirpath, recurse=1) %]
\&    [% myview.print(dir) %]
.Ve
.PP
When a directory is presented to a view, either as \f(CW\*(C`[% myview.print(dir) %]\*(C'\fR
or \f(CW\*(C`[% dir.present(view) %]\*(C'\fR, then the \f(CW\*(C`directory\*(C'\fR \f(CW\*(C`BLOCK\*(C'\fR within the
\&\f(CW\*(C`myview\*(C'\fR \f(CW\*(C`VIEW\*(C'\fR is processed. The \f(CW\*(C`item\*(C'\fR variable will be set to alias the
\&\f(CW\*(C`Directory\*(C'\fR object.
.PP
.Vb 4
\&    [% BLOCK directory %]
\&       * [% item.name %]
\&         [% item.content(myview) FILTER indent %]
\&    [% END %]
.Ve
.PP
In this example, the directory name is first printed and the content(view)
method is then called to present each item within the directory to the view.
Further directories will be mapped to the \f(CW\*(C`directory\*(C'\fR block, and files will be
mapped to the \f(CW\*(C`file\*(C'\fR block.
.PP
With the recurse option disabled, as it is by default, the \f(CW\*(C`directory\*(C'\fR
block should explicitly call a \f(CW\*(C`scan()\*(C'\fR on each directory.
.PP
.Vb 4
\&    [% VIEW myview %]
\&    [% BLOCK file %]
\&       \- [% item.name %]
\&    [% END %]
.Ve
.PP
.Vb 6
\&    [% BLOCK directory %]
\&       * [% item.name %]
\&         [% item.scan %]
\&         [% item.content(myview) FILTER indent %]
\&    [% END %]
\&    [% END %]
.Ve
.PP
.Vb 2
\&    [% USE dir = Directory(dirpath) %]
\&    [% myview.print(dir) %]
.Ve
.SH "AUTHORS"
.IX Header "AUTHORS"
Michael Stevens wrote the original Directory plugin on which this is based.
Andy Wardley split it into separate File and
Directory plugins, added some extra code and
documentation for \f(CW\*(C`VIEW\*(C'\fR support, and made a few other minor tweaks.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2000\-2007 Michael Stevens, Andy Wardley.
.PP
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Template::Plugin, Template::Plugin::File, Template::View