Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  TEXT::REPOSITORY (3)

.ds Aq ’


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



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.


  use Text::Repository;

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

(See EXAMPLES for more.)


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


The constructor is called <B>newB>, 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_pathB> object method).



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_pathsB> is an alias for <B>add_pathB>, and should be used wherever it makes the intent clearer. For example, use <B>add_pathB> to add a single path, but <B>add_pathsB> when assigning more than one:



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.


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 deletes a path from the instance’s search path.


<B>replace_pathsB> provides a shortcut to reset the list of paths to a new value. It is equivalent to:

    for my $p ($rep->paths()) {

<B>replace_pathsB> returns the Text::Repository instance.


The <B>resetB> method returns the instance to the state it had when it was created. <B>resetB> returns the Text::Repository instance.


The <B>fetchB> method does the actual fetching of the text.

<B>fetchB> 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, <B>fetchB> returns undef.


The <B>clear_cacheB> 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 <B>replace_pathsB> calls this method for you.

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


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";
  Hello, %s!
  Hello, world!

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


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");



Perl, Carp, IO::File, File::Spec


darren chamberlain <>
Search for    or go to Top of page |  Section 3 |  Main Index

perl v5.20.3 REPOSITORY (3) 2002-01-18

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.