view release on metacpan or  search on metacpan

README  view on Meta::CPAN

NAME
    App::TaggedDirUtils - CLI utilities related to tagged directories

VERSION
    This document describes version 0.002 of App::TaggedDirUtils (from Perl
    distribution App-TaggedDirUtils), released on 2021-08-23.

SYNOPSIS
    See CLIs included in this distribution.

DESCRIPTION
    This distribution includes several utilities related to tagged
    directories:

    *   list-tagged-dirs

    A "tagged directory" is a directory which has one or more tags: usually
    empty files called .tag-TAGNAME, where *TAGNAME* is some tag name.

    You can backup, rsync, or do whatever you like with a tagged directory,
    just like a normal filesystem directory. The utilities provided in this
    distribution help you handle tagged directories.

FUNCTIONS
  list_tagged_dirs
    Usage:

     list_tagged_dirs(%args) -> [$status_code, $reason, $payload, \%result_meta]

    Search tagged directories recursively in a list of places.

    Note: when a tagged dir is found, its contents are no longer recursed to
    search for other tagged dirs.

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   detail => *bool*

    *   has_files => *array[filename]*

    *   has_tags => *array[str]*

    *   lacks_files => *array[filename]*

    *   lacks_tags => *array[str]*

    *   prefixes* => *array[dirname]*

        Locations to search for tagged directories.

        Location(s) to search for tagged subdirectories, i.e. directories
        which have some file with specific names in its root.

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (any)

FAQ
  Why tagged directories?
    With tagged directories, you can put them in various places and not just
    on a single parent directory. For example:

     media/
       2020/
         media-2020a/ -> a tagged dir
           .tag-media
           ...
         media-2020b/ -> a tagged dir