Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Repository(3)	      User Contributed Perl Documentation	 Repository(3)

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
       Perl, Carp, IO::File, File::Spec

AUTHOR
       darren chamberlain <darren@cpan.org>

perl v5.32.1			  2002-01-18			 Repository(3)

NAME | ABSTRACT | SYNOPSIS | DESCRIPTION | CONSTRUCTOR | INSTANCE METHODS | CREATING TEXT FOR A REPOSITORY | EXAMPLES | TODO | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Text::Repository&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help