Template::Plugin::String(3pm)

1Template::Plugin::StrinUgs(e3r)Contributed Perl DocumentTaetmipolnate::Plugin::String(3)
2
3
4

NAME

6       Template::Plugin::String - Object oriented interface for string
7       manipulation
8

SYNOPSIS

10           # create String objects via USE directive
11           [% USE String %]
12           [% USE String 'initial text' %]
13           [% USE String text => 'initial text' %]
14
15           # or from an existing String via new()
16           [% newstring = String.new %]
17           [% newstring = String.new('newstring text') %]
18           [% newstring = String.new( text => 'newstring text' ) %]
19
20           # or from an existing String via copy()
21           [% newstring = String.copy %]
22
23           # append text to string
24           [% String.append('text to append') %]
25
26           # format left, right or center/centre padded
27           [% String.left(20) %]
28           [% String.right(20) %]
29           [% String.center(20) %]   # American spelling
30           [% String.centre(20) %]   # European spelling
31
32           # and various other methods...
33

DESCRIPTION

35       This module implements a "String" class for doing stringy things to
36       text in an object-oriented way.
37
38       You can create a "String" object via the "USE" directive, adding any
39       initial text value as an argument or as the named parameter "text".
40
41           [% USE String %]
42           [% USE String 'initial text' %]
43           [% USE String text='initial text' %]
44
45       The object created will be referenced as "String" by default, but you
46       can provide a different variable name for the object to be assigned to:
47
48           [% USE greeting = String 'Hello World' %]
49
50       Once you've got a "String" object, you can use it as a prototype to
51       create other "String" objects with the "new()" method.
52
53           [% USE String %]
54           [% greeting = String.new('Hello World') %]
55
56       The "new()" method also accepts an initial text string as an argument
57       or the named parameter "text".
58
59           [% greeting = String.new( text => 'Hello World' ) %]
60
61       You can also call "copy()" to create a new "String" as a copy of the
62       original.
63
64           [% greet2 = greeting.copy %]
65
66       The "String" object has a "text()" method to return the content of the
67       string.
68
69           [% greeting.text %]
70
71       However, it is sufficient to simply print the string and let the
72       overloaded stringification operator call the "text()" method
73       automatically for you.
74
75           [% greeting %]
76
77       Thus, you can treat "String" objects pretty much like any regular piece
78       of text, interpolating it into other strings, for example:
79
80           [% msg = "It printed '$greeting' and then dumped core\n" %]
81
82       You also have the benefit of numerous other methods for manipulating
83       the string.
84
85           [% msg.append("PS  Don't eat the yellow snow") %]
86
87       Note that all methods operate on and mutate the contents of the string
88       itself.  If you want to operate on a copy of the string then simply
89       take a copy first:
90
91           [% msg.copy.append("PS  Don't eat the yellow snow") %]
92
93       These methods return a reference to the "String" object itself.  This
94       allows you to chain multiple methods together.
95
96           [% msg.copy.append('foo').right(72) %]
97
98       It also means that in the above examples, the "String" is returned
99       which causes the "text()" method to be called, which results in the new
100       value of the string being printed.  To suppress printing of the string,
101       you can use the "CALL" directive.
102
103           [% foo = String.new('foo') %]
104
105           [% foo.append('bar') %]         # prints "foobar"
106
107           [% CALL foo.append('bar') %]    # nothing
108

CONSTRUCTOR METHODS

110       These methods are used to create new "String" objects.
111
112   new()
113       Creates a new string using an initial value passed as a positional
114       argument or the named parameter "text".
115
116           [% USE String %]
117           [% msg = String.new('Hello World') %]
118           [% msg = String.new( text => 'Hello World' ) %]
119
120   copy()
121       Creates a new "String" object which contains a copy of the original
122       string.
123
124           [% msg2 = msg.copy %]
125

INSPECTOR METHODS

127       These methods are used to examine the string.
128
129   text()
130       Returns the internal text value of the string.  The stringification
131       operator is overloaded to call this method.  Thus the following are
132       equivalent:
133
134           [% msg.text %]
135           [% msg %]
136
137   length()
138       Returns the length of the string.
139
140           [% USE String("foo") %]
141           [% String.length %]   # => 3
142
143   search($pattern)
144       Searches the string for the regular expression specified in $pattern
145       returning true if found or false otherwise.
146
147           [% item = String.new('foo bar baz wiz waz woz') %]
148           [% item.search('wiz') ? 'WIZZY! :-)' : 'not wizzy :-(' %]
149
150   split($pattern, $limit)
151       Splits the string based on the delimiter $pattern and optional $limit.
152       Delegates to Perl's internal "split()" so the parameters are exactly
153       the same.
154
155           [% FOREACH item.split %]
156                ...
157           [% END %]
158
159           [% FOREACH item.split('baz|waz') %]
160                ...
161           [% END %]
162

MUTATOR METHODS

164       These methods modify the internal value of the string.  For example:
165
166           [% USE str=String('foobar') %]
167           [% str.append('.html') %]   # str => 'foobar.html'
168
169       The value of "str" is now '"foobar.html"'.  If you don't want to modify
170       the string then simply take a copy first.
171
172           [% str.copy.append('.html') %]
173
174       These methods all return a reference to the "String" object itself.
175       This has two important benefits.  The first is that when used as above,
176       the "String" object '"str"' returned by the "append()" method will be
177       stringified with a call to its "text()" method.  This will return the
178       newly modified string content.  In other words, a directive like:
179
180           [% str.append('.html') %]
181
182       will update the string and also print the new value.  If you just want
183       to update the string but not print the new value then use "CALL".
184
185           [% CALL str.append('.html') %]
186
187       The other benefit of these methods returning a reference to the
188       "String" is that you can chain as many different method calls together
189       as you like.  For example:
190
191           [% String.append('.html').trim.format(href) %]
192
193       Here are the methods:
194
195   push($suffix, ...) / append($suffix, ...)
196       Appends all arguments to the end of the string.  The "append()" method
197       is provided as an alias for "push()".
198
199           [% msg.push('foo', 'bar') %]
200           [% msg.append('foo', 'bar') %]
201
202   pop($suffix)
203       Removes the suffix passed as an argument from the end of the String.
204
205           [% USE String 'foo bar' %]
206           [% String.pop(' bar')   %]   # => 'foo'
207
208   unshift($prefix, ...) / prepend($prefix, ...)
209       Prepends all arguments to the beginning of the string.  The "prepend()"
210       method is provided as an alias for "unshift()".
211
212           [% msg.unshift('foo ', 'bar ') %]
213           [% msg.prepend('foo ', 'bar ') %]
214
215   shift($prefix)
216       Removes the prefix passed as an argument from the start of the String.
217
218           [% USE String 'foo bar' %]
219           [% String.shift('foo ') %]   # => 'bar'
220
221   left($pad)
222       If the length of the string is less than $pad then the string is left
223       formatted and padded with spaces to $pad length.
224
225           [% msg.left(20) %]
226
227   right($pad)
228       As per left() but right padding the "String" to a length of $pad.
229
230           [% msg.right(20) %]
231
232   center($pad) / centre($pad)
233       As per left() and right() but formatting the "String" to be centered
234       within a space padded string of length $pad.  The "centre()" method is
235       provided as an alias for "center()".
236
237           [% msg.center(20) %]    # American spelling
238           [% msg.centre(20) %]    # European spelling
239
240   format($format)
241       Apply a format in the style of "sprintf()" to the string.
242
243           [% USE String("world") %]
244           [% String.format("Hello %s\n") %]  # => "Hello World\n"
245
246   upper()
247       Converts the string to upper case.
248
249           [% USE String("foo") %]
250           [% String.upper %]  # => 'FOO'
251
252   lower()
253       Converts the string to lower case
254
255           [% USE String("FOO") %]
256           [% String.lower %]  # => 'foo'
257
258   capital()
259       Converts the first character of the string to upper case.
260
261           [% USE String("foo") %]
262           [% String.capital %]  # => 'Foo'
263
264       The remainder of the string is left untouched.  To force the string to
265       be all lower case with only the first letter capitalised, you can do
266       something like this:
267
268           [% USE String("FOO") %]
269           [% String.lower.capital %]  # => 'Foo'
270
271   chop()
272       Removes the last character from the string.
273
274           [% USE String("foop") %]
275           [% String.chop %]   # => 'foo'
276
277   chomp()
278       Removes the trailing newline from the string.
279
280           [% USE String("foo\n") %]
281           [% String.chomp %]  # => 'foo'
282
283   trim()
284       Removes all leading and trailing whitespace from the string
285
286           [% USE String("   foo   \n\n ") %]
287           [% String.trim %]   # => 'foo'
288
289   collapse()
290       Removes all leading and trailing whitespace and collapses any sequences
291       of multiple whitespace to a single space.
292
293           [% USE String(" \n\r  \t  foo   \n \n bar  \n") %]
294           [% String.collapse %]   # => "foo bar"
295
296   truncate($length, $suffix)
297       Truncates the string to $length characters.
298
299           [% USE String('long string') %]
300           [% String.truncate(4) %]  # => 'long'
301
302       If $suffix is specified then it will be appended to the truncated
303       string.  In this case, the string will be further shortened by the
304       length of the suffix to ensure that the newly constructed string
305       complete with suffix is exactly $length characters long.
306
307           [% USE msg = String('Hello World') %]
308           [% msg.truncate(8, '...') %]   # => 'Hello...'
309
310   replace($search, $replace)
311       Replaces all occurences of $search in the string with $replace.
312
313           [% USE String('foo bar foo baz') %]
314           [% String.replace('foo', 'wiz')  %]  # => 'wiz bar wiz baz'
315
316   remove($search)
317       Remove all occurences of $search in the string.
318
319           [% USE String('foo bar foo baz') %]
320           [% String.remove('foo ')  %]  # => 'bar baz'
321
322   repeat($count)
323       Repeats the string $count times.
324
325           [% USE String('foo ') %]
326           [% String.repeat(3)  %]  # => 'foo foo foo '
327

AUTHOR

329       Andy Wardley <abw@wardley.org> <http://wardley.org/>
330

COPYRIGHT

332       Copyright (C) 1996-2007 Andy Wardley.  All Rights Reserved.
333
334       This module is free software; you can redistribute it and/or modify it
335       under the same terms as Perl itself.
336