Templat...irectory(3)

💖 NAME 💖

Template::Plugin::Directory — bestie, it's literally the plugin that generates directory listings, no cap 🫶

So the manual name is Templat...irectory(3) (yes, it's truncated like that, iconic) and it lives in the User Contributed Perl Documentation. Let's get into it ✨

---

✨ SYNOPSIS ✨

Okay so here's the whole vibe in one go — don't panic, we'll walk through it 💅

[% 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) %]

See? files, dirs, list, and a whole VIEW situation. It's giving organized 🌸

---

🦋 DESCRIPTION 🦋

So this Template Toolkit plugin gives you a simple interface to directory listings. It's 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 Template::Plugin::Directory instances. It's basically File's sibling but with more main character energy 💅

The constructor expects a directory name as an argument. Like:

[% USE dir = Directory('/tmp') %]

Then it provides access to the files and sub-directories contained within the directory. Obsessed:

# 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 %]

🫶 Real talk: the plugin constructor will throw a Directory error 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 nostat option can be set to disable all file/directory checks and directory scanning. That's the whole tea ☕

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 recurse flag is set, then those directories will contain further nested entries, and so on. With the recurse 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 scan() method is explicitly called. The isdir 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. Slay.

[% FOREACH file = dir.list %]
   [% IF file.isdir %]
      * Directory: [% file.name %]
   [% ELSE %]
      * File: [% file.name %]
   [% END %]
[% END %]

This next 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. Yes bestie, you gotta do it manually 😭

[% 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 — look at that tree structure, it ate 💅

* test/dir
    - file1
    - file2
    * sub_one
        - bar
        - foo
    * sub_two
        - waz.html
        - wiz.html
    - xyzfile

The recurse flag can be set (disabled by default) to cause the constructor to automatically recurse down into all sub-directories, creating a new Template::Plugin::Directory object for each one and filling it with any further content. In this case there is no need to explicitly call the scan() method. Lowkey a lifesaver 🧚

[% 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 ... END block and should contain BLOCK definitions for files (file) and directories (directory). It's giving structured content, periodt 🎀

[% VIEW myview %]
[% BLOCK file %]
   - [% item.name %]
[% END %]

[% BLOCK directory %]
   * [% item.name %]
     [% item.content(myview) FILTER indent %]
[% END %]
[% END %]

The view print() method can then be called, passing the Directory object as an argument. Easy peasy:

[% 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 directory BLOCK within the myview VIEW is processed. The item variable will be set to alias the Directory object. Main character variable behavior, honestly 👑

[% 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 directory block, and files will be mapped to the file block. It's literally a whole mapping moment 🌈

With the recurse option disabled, as it is by default, the directory block should explicitly call a scan() on each directory. Don't forget, bestie — it won't do it for you 💀

[% 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) %]

---

👑 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 VIEW support, and made a few other minor tweaks. We stan both of them fr fr 🫶

---

🌸 COPYRIGHT 🌸

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. Periodt 💅

---

⭐ SEE ALSO ⭐

• Template::Plugin
• Template::Plugin::File
• Template::View

Go read those next, iykyk 📚

---

And that's the page, bestie ✨ Cute little sign-off: this was Templat...irectory(3) from the User Contributed Perl Documentation, sitting at perl v5.42.0 with a date of 2024-06-23. No cap, that's the whole thing 🌈💖