16 Aug 2022 07:02:05 UTC
- Distribution: Template-Toolkit
- Module version: 3.100
- Source (raw)
- Browse (raw)
- How to Contribute
- Issues (74)
- Testers (1304 / 27 / 0)
- KwaliteeBus factor: 3
- % Coverage
- License: perl_5
- Download (503.85KB)
- MetaCPAN Explorer
- Subscribe to distribution
- This version
- Latest version++ed by:65 non-PAUSE users
- Andy Wardley
Template::Plugin::Directory - Plugin for generating directory listings
[% USE dir = Directory(dirpath) %] # files returns list of regular files [% FOREACH file = dir.files %] [% file.name %] [% file.path %] ... [% END %] # dirs returns list of sub-directories [% FOREACH subdir = dir.dirs %] [% subdir.name %] [% subdir.path %] ... [% END %] # list returns both interleaved in order [% FOREACH item = dir.list %] [% IF item.isdir %] Directory: [% item.name %] [% ELSE %] File: [% item.name %] [% END %] [% END %] # define a VIEW to display dirs/files [% VIEW myview %] [% BLOCK file %] File: [% item.name %] [% END %] [% BLOCK directory %] Directory: [% item.name %] [% item.content(myview) | indent -%] [% END %] [% END %] # display directory content using view [% myview.print(dir) %]
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
The constructor expects a directory name as an argument.
[% USE dir = Directory('/tmp') %]
It then provides access to the files and sub-directories contained within the directory.
# regular files (not directories) [% FOREACH file IN dir.files %] [% file.name %] [% END %] # directories only [% FOREACH file IN dir.dirs %] [% file.name %] [% END %] # files and/or directories [% FOREACH file IN dir.list %] [% file.name %] ([% file.isdir ? 'directory' : 'file' %]) [% END %]
The plugin constructor will throw a
Directoryerror if the specified path does not exist, is not a directory or fails to
stat()(see Template::Plugin::File). Otherwise, it will scan the directory and create lists named '
files' containing files, '
dirs' containing directories and '
list' containing both files and directories combined. The
nostatoption can be set to disable all file/directory checks and directory scanning.
Each file in the directory will be represented by a Template::Plugin::File object instance, and each directory by another
Template::Plugin::Directory. If the
recurseflag is set, then those directories will contain further nested entries, and so on. With the
recurseflag 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
scan()method is explicitly called. The
isdirflag can be tested against files and/or directories, returning true if the item is a directory or false if it is a regular file.
[% FOREACH file = dir.list %] [% IF file.isdir %] * Directory: [% file.name %] [% ELSE %] * File: [% file.name %] [% END %] [% END %]
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
scan()method on each directory, to force it to lookup files and further sub-directories contained within.
[% USE dir = Directory(dirpath) %] * [% dir.path %] [% INCLUDE showdir %] [% 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 %]
This example is adapted (with some re-formatting for clarity) from a test in t/directry.t which produces the following output:
* test/dir - file1 - file2 * sub_one - bar - foo * sub_two - waz.html - wiz.html - xyzfile
recurseflag can be set (disabled by default) to cause the constructor to automatically recurse down into all sub-directories, creating a new
Template::Plugin::Directoryobject for each one and filling it with any further content. In this case there is no need to explicitly call the
[% USE dir = Directory(dirpath, recurse=1) %] ... [% IF file.isdir -%] * [% file.name %] [% INCLUDE showdir dir=file FILTER indent(4) -%] [% ELSE -%] ...
The directory plugin also provides support for views. A view can be defined as a
VIEW ... ENDblock and should contain
BLOCKdefinitions for files ('
file') and directories ('
[% VIEW myview %] [% BLOCK file %] - [% item.name %] [% END %] [% BLOCK directory %] * [% item.name %] [% item.content(myview) FILTER indent %] [% END %] [% END %]
print()method can then be called, passing the
Directoryobject as an argument.
[% USE dir = Directory(dirpath, recurse=1) %] [% myview.print(dir) %]
When a directory is presented to a view, either as
[% myview.print(dir) %]or
[% dir.present(view) %], then the
VIEWis processed. The
itemvariable will be set to alias the
[% BLOCK directory %] * [% item.name %] [% item.content(myview) FILTER indent %] [% END %]
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
directoryblock, and files will be mapped to the
With the recurse option disabled, as it is by default, the
directoryblock should explicitly call a
scan()on each directory.
[% VIEW myview %] [% BLOCK file %] - [% item.name %] [% END %] [% BLOCK directory %] * [% item.name %] [% item.scan %] [% item.content(myview) FILTER indent %] [% END %] [% END %] [% USE dir = Directory(dirpath) %] [% myview.print(dir) %]
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
VIEWsupport, and made a few other minor tweaks.
Copyright (C) 2000-2022 Michael Stevens, Andy Wardley.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Module Install Instructions
To install Template::Toolkit, copy and paste the appropriate command in to your terminal.
perl -MCPAN -e shell install Template::Toolkit
For more information on module installation, please visit the detailed CPAN module installation guide.
|s||Focus search bar|
|?||Bring up this help dialog|
|g p||Go to pull requests|
|g i||go to github issues (only if github is preferred repository)|
|g a||Go to author|
|g c||Go to changes|
|g i||Go to issues|
|g d||Go to dist|
|g r||Go to repository/SCM|
|g s||Go to source|
|g b||Go to file browse|