view release on metacpan or  search on metacpan

Repository.pm  view on Meta::CPAN

Text::Repository - A simple way to manage text without mixing it with Perl

=head1 ABSTRACT

Text::Repository attempts to simplify storing shared text between
multple Perl modules, scripts, templating systems, etc.  It does this
by allowing chunks of text to be stored with symbolic names.
Text::Repository was originally designed to store SQL queries, but can
of course be used with any kind of text that needs to be shared.

=head1 SYNOPSIS

  use Text::Repository;

  my @paths = ("/www/library", "$ENV{'HOME'}/text");
  my $rep = Text::Repository->new(@paths);

(See EXAMPLES for more.)

=head1 DESCRIPTION

Text::Repository provides the capability to store, use, and manage
text without having to mix them with Perl scripts and modules.  These
pieces of text can then be shared by multiple modules, scripts, or
templating systems with a minimum of fuss.

Text::Repository uses a series of one or more directories (specified
either when the class is instantiated or when needed) as a search
path; when a piece of text is requested using the instance's B<fetch>
method, Text::Repository looks in each of the directories in turn
until it finds a file with that name.  If the file is found, it is
opened and read, and the contents are returned to the caller as a
string.  Furthermore, the contents of the file are cached. Successive
calls to B<fetch> to retrieve the same piece of text return this
cached copy, provided the copy on disk has not changed more recently
than the copy in the cache.

Text::Repository was originally written to share complex SQL queries
among multiple modules; when the usage grew to include printf formats,
I realized it could be generalized to store any kind of text.  Because
no processing is done on the text before it is returned, the text in
the file can have any kind of markup.  In fact, the contents of the
file don't even have to be text; the caller decides how to use the
results returned from the B<fetch>.

=head1 CONSTRUCTOR

The constructor is called B<new>, and can be optionally passed a list
of directories to be added to the search path (directories can also be
added using the B<add_path> object method).

=cut

#
# Instantiates a new instance.  There is very little setup here;
# all the work (adding paths, etc) is handled by add_path.
#
sub new {
    my $class = shift;
    my $self = bless [ { }, [ ], \@_, ] => $class;
    $self->add_path(@_);

    return $self;
}

=head1 INSTANCE METHODS

=head2 B<add_path>

Adds a search path or paths to the instance.  The search path defines
where the instance looks for text snippets.  This can be called
multiple times, and this module imposes no limits on the number of
search paths.

B<add_paths> is an alias for B<add_path>, and should be used wherever
it makes the intent clearer.  For example, use B<add_path> to add a
single path, but B<add_paths> when assigning more than one:

    $rep->add_paths($new_path);

    $rep->add_paths(@new_paths);

Some steps are taken to ensure that a path only appears in the search
path once; any subsequent additions of an existing path are ignored.

=cut

# 
# add_path pushes one or more paths onto the object; these are
# searched when fetch is called.  Should add_path check -d first?
#
sub add_path {
    my $self = shift;
    my $paths = isa($_[0], "ARRAY") ? shift : \@_;
    my %paths;

    @{$self->[PATHS]} =
        grep { -d }
        grep { ++$paths{$_} == 1 }
        (@{$self->[PATHS]}, @{$paths});

    return $self;
}
*add_paths = *add_path;

=head2 B<paths> 

The paths method returns a list of the paths in the object (or a
reference to a list of the paths if called in scalar context).

=cut

sub paths {
    my $self = shift;
    return   @{$self->[PATHS]} if wantarray;
    return [ @{$self->[PATHS]} ];
}

=head2 B<remove_path>