README
1NAME
2 Text::Repository - A simple way to manage text without mixing it with
3 Perl
4
5ABSTRACT
6 Text::Repository attempts to simplify storing shared text between
7 multple Perl modules, scripts, templating systems, etc. It does this by
8 allowing chunks of text to be stored with symbolic names.
9 Text::Repository was originally designed to store SQL queries, but can
10 of course be used with any kind of text that needs to be shared.
11
12SYNOPSIS
13 use Text::Repository;
14
15 my @paths = ("/www/library", "$ENV{'HOME'}/text");
16 my $rep = Text::Repository->new(@paths);
17
18 (See EXAMPLES for more.)
19
20DESCRIPTION
21 Text::Repository provides the capability to store, use, and manage text
22 without having to mix them with Perl scripts and modules. These pieces
23 of text can then be shared by multiple modules, scripts, or templating
24 systems with a minimum of fuss.
25
26 Text::Repository uses a series of one or more directories (specified
27 either when the class is instantiated or when needed) as a search path;
28 when a piece of text is requested using the instance's fetch method,
29 Text::Repository looks in each of the directories in turn until it finds
30 a file with that name. If the file is found, it is opened and read, and
31 the contents are returned to the caller as a string. Furthermore, the
32 contents of the file are cached. Successive calls to fetch to retrieve
33 the same piece of text return this cached copy, provided the copy on
34 disk has not changed more recently than the copy in the cache.
35
36 Text::Repository was originally written to share complex SQL queries
37 among multiple modules; when the usage grew to include printf formats, I
38 realized it could be generalized to store any kind of text. Because no
39 processing is done on the text before it is returned, the text in the
40 file can have any kind of markup. In fact, the contents of the file
41 don't even have to be text; the caller decides how to use the results
42 returned from the fetch.
43
44CONSTRUCTOR
45 The constructor is called new, and can be optionally passed a list of
46 directories to be added to the search path (directories can also be
47 added using the add_path object method).
48
49INSTANCE METHODS
50 add_path
51
52 Adds a search path or paths to the instance. The search path defines
53 where the instance looks for text snippets. This can be called multiple
54 times, and this module imposes no limits on the number of search paths.
55
56 add_paths is an alias for add_path, and should be used wherever it makes
57 the intent clearer. For example, use add_path to add a single path, but
58 add_paths when assigning more than one:
59
60 $rep->add_paths($new_path);
61
62 $rep->add_paths(@new_paths);
63
64 Some steps are taken to ensure that a path only appears in the search
65 path once; any subsequent additions of an existing path are ignored.
66
67 paths
68
69 The paths method returns a list of the paths in the object (or a
70 reference to a list of the paths if called in scalar context).
71
72 remove_path
73
74 remove_path deletes a path from the instance's search path.
75
76 replace_paths
77
78 replace_paths provides a shortcut to reset the list of paths to a new
79 value. It is equivalent to:
80
81 for my $p ($rep->paths()) {
82 $rep->remove_path($p);
83 }
84 $rep->clear_cache();
85 $rep->add_paths(@new_paths);
86
87 replace_paths returns the Text::Repository instance.
88
89 reset
90
91 The reset method returns the instance to the state it had when it was
92 created. reset returns the Text::Repository instance.
93
94 fetch(NAME)
95
96 The fetch method does the actual fetching of the text.
97
98 fetch is designed to be called with a keyword; this keyword is turned
99 into a filename that gets appended to each directory in paths (as
100 defined by $self->paths) in order until it finds a match.
101
102 Once fetch finds a match, the contents of the file is returned as a
103 single string.
104
105 If the file is not found, fetch returns undef.
106
107 clear_cache
108
109 The clear_cache method clears out the internal cache. The only times
110 this becomes necessary to call is when the internal paths are changed to
111 the point where cached files will never be found again (they become
112 orphaned, in this case). Note that replace_paths calls this method for
113 you.
114
115 This method returns the Text::Repository instance, for chaining.
116
117CREATING TEXT FOR A REPOSITORY
118 The files that can be retrieved using Text::Repository can be stored
119 anywhere. Creating files in a path referenced by a Text::Repository
120 instance can be done using any of the standard file creation or editing
121 methods:
122
123 $ echo 'Hello, %s!' > /tmp/Greeting
124 $ perl -MText::Repository
125 my $rep = Text::Repository->new("/tmp");
126 print $rep->fetch("Greeting");
127 printf $rep->fetch("Greeting"), "world";
128 ^D
129 Hello, %s!
130 Hello, world!
131
132 There are no methods for writing files using Text::Repository.
133
134EXAMPLES
135 Using Text::Repository to separate SQL statements from code:
136
137 use DBI;
138 use Text::Repository;
139
140 my $rep = Text::Repository->new("$ENV{'HOME'}/sql", "/www/sql");
141 my $dbh = DBI->connect(@DSN);
142
143 my $search = $rep->fetch("search");
144 my $sth = $dbh->prepare($search);
145 # and so on
146
147 Using Text::Repository to "skin" the output of a CGI script:
148
149 use CGI;
150 use Text::Repository;
151
152 my $q = CGI->new;
153 my $rep = Text::Repository->new("/www/repository");
154
155 my $skin = $q->param("skin");
156 my %components = (
157 HEADER => $rep->fetch("skins/$skin/header"),
158 LINKBOX => $rep->fetch("linkbox"),
159 FOOTER => $rep->fetch("skins/$skin/footer"),
160 );
161
162 print $q->header("My Skinned Page"),
163 $components{ HEADER },
164 get_content($components{ LINKBOX }),
165 $components{ FOOTER };
166
167 sub get_content ($) {
168 # and so on
169
170 Using Text::Repository to feed into Template Toolkit
171
172 use Template;
173 use Text::Repository;
174
175 my @rep_dirs = qw(/www/templates /usr/local/apache/htdocs);
176 my $rep = Text::Repository->new(@rep_dirs);
177 my $t = Template->new;
178
179 my $login = $rep->fetch("login");
180 $t->process(\$login);
181
182TODO
183SEE ALSO
184 the Perl manpage, the Carp manpage, the IO::File manpage, the File::Spec
185 manpage
186
187AUTHOR
188 darren chamberlain <darren@cpan.org>
189
190