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

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.

SYNOPSIS
     use Text::Repository;

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

   (See EXAMPLES for more.)

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 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 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 fetch.

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

INSTANCE METHODS
 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.

   add_paths is an alias for add_path, and should be used wherever it makes
   the intent clearer. For example, use add_path to add a single path, but
   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.

 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).

 remove_path

   remove_path deletes a path from the instance's search path.

 replace_paths

   replace_paths provides a shortcut to reset the list of paths to a new
   value. It is equivalent to:

       for my $p ($rep->paths()) {
           $rep->remove_path($p);
       }
       $rep->clear_cache();
       $rep->add_paths(@new_paths);

   replace_paths returns the Text::Repository instance.

 reset

   The reset method returns the instance to the state it had when it was
   created. reset returns the Text::Repository instance.

 fetch(NAME)

   The fetch method does the actual fetching of the text.

   fetch is designed to be called with a keyword; this keyword is turned
   into a filename that gets appended to each directory in paths (as
   defined by $self->paths) in order until it finds a match.

   Once fetch finds a match, the contents of the file is returned as a
   single string.

   If the file is not found, fetch returns undef.

 clear_cache

   The clear_cache method clears out the internal cache. The only times
   this becomes necessary to call is when the internal paths are changed to
   the point where cached files will never be found again (they become
   orphaned, in this case). Note that replace_paths calls this method for
   you.

   This method returns the Text::Repository instance, for chaining.

CREATING TEXT FOR A REPOSITORY
   The files that can be retrieved using Text::Repository can be stored
   anywhere. Creating files in a path referenced by a Text::Repository
   instance can be done using any of the standard file creation or editing
   methods:

     $ echo 'Hello, %s!' > /tmp/Greeting
     $ perl -MText::Repository
     my $rep = Text::Repository->new("/tmp");
     print $rep->fetch("Greeting");
     printf $rep->fetch("Greeting"), "world";
     ^D
     Hello, %s!
     Hello, world!

   There are no methods for writing files using Text::Repository.

EXAMPLES
   Using Text::Repository to separate SQL statements from code:

     use DBI;
     use Text::Repository;

     my $rep = Text::Repository->new("$ENV{'HOME'}/sql", "/www/sql");
     my $dbh = DBI->connect(@DSN);

     my $search = $rep->fetch("search");
     my $sth = $dbh->prepare($search);
     # and so on

   Using Text::Repository to "skin" the output of a CGI script:

     use CGI;
     use Text::Repository;

     my $q = CGI->new;
     my $rep = Text::Repository->new("/www/repository");

     my $skin = $q->param("skin");
     my %components = (
       HEADER  => $rep->fetch("skins/$skin/header"),
       LINKBOX => $rep->fetch("linkbox"),
       FOOTER  => $rep->fetch("skins/$skin/footer"),
     );

     print $q->header("My Skinned Page"),
           $components{ HEADER },
           get_content($components{ LINKBOX }),
           $components{ FOOTER };

     sub get_content ($) {
     # and so on

   Using Text::Repository to feed into Template Toolkit

     use Template;
     use Text::Repository;

     my @rep_dirs = qw(/www/templates /usr/local/apache/htdocs);
     my $rep = Text::Repository->new(@rep_dirs);
     my $t = Template->new;

     my $login = $rep->fetch("login");
     $t->process(\$login);

TODO
SEE ALSO
   the Perl manpage, the Carp manpage, the IO::File manpage, the File::Spec
   manpage

AUTHOR
   darren chamberlain <[email protected]>

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.