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 manipu‐
7       lation
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 text
36       in an object-oriented way.
37
38       You can create a String object via the USE directive, adding any ini‐
39       tial 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 cre‐
51       ate 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 or
57       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 origi‐
62       nal.
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 over‐
72       loaded stringification operator call the text() method automatically
73       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 which
99       causes the text() method to be called, which results in the new value
100       of the string being printed.  To suppress printing of the string, you
101       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

METHODS

110       Construction Methods
111
112       The following methods are used to create new String objects.
113
114       new()
115           Creates a new string using an initial value passed as a positional
116           argument or the named parameter 'text'.
117
118               [% USE String %]
119               [% msg = String.new('Hello World') %]
120               [% msg = String.new( text => 'Hello World' ) %]
121
122       copy()
123           Creates a new String object which contains a copy of the original
124           string.
125
126               [% msg2 = msg.copy %]
127
128       Inspection Methods
129
130       These methods are used to inspect the string content or other parame‐
131       ters relevant to the string.
132
133       text()
134           Returns the internal text value of the string.  The stringification
135           operator is overloaded to call this method.  Thus the following are
136           equivalent:
137
138               [% msg.text %]
139               [% msg %]
140
141       length()
142           Returns the length of the string.
143
144               [% USE String("foo") %]
145
146               [% String.length %]   # => 3
147
148       search($pattern)
149           Searches the string for the regular expression specified in $pat‐
150           tern returning true if found or false otherwise.
151
152               [% item = String.new('foo bar baz wiz waz woz') %]
153
154               [% item.search('wiz') ? 'WIZZY! :-)' : 'not wizzy :-(' %]
155
156       split($pattern, $limit)
157           Splits the string based on the delimiter $pattern and optional
158           $limit.  Delegates to Perl's internal split() so the parameters are
159           exactly the same.
160
161               [% FOREACH item.split %]
162                    ...
163               [% END %]
164
165               [% FOREACH item.split('baz⎪waz') %]
166                    ...
167               [% END %]
168
169       substr($offset, $length, $replacement)
170           Returns a substring starting at $offset, for $length characters.
171
172               [% str = String.new('foo bar baz wiz waz woz') %]
173               [% str.substr(4, 3) %]    # bar
174
175           If $length is not specified then it returns everything from the
176           $offset to the end of the string.
177
178               [% str.substr(12) %]      # wiz waz woz
179
180           If both $length and $replacement are specified, then the method
181           replaces everything from $offset for $length characters with
182           $replacement.  The substring removed from the string is then
183           returned.
184
185               [% str.substr(0, 11, 'FOO') %]   # foo bar baz
186               [% str %]                        # FOO wiz waz woz
187
188       Mutation Methods
189
190       These methods modify the internal value of the string.  For example:
191
192           [% USE str=String('foobar') %]
193
194           [% str.append('.html') %]   # str => 'foobar.html'
195
196       The value of the String 'str' is now 'foobar.html'.  If you don't want
197       to modify the string then simply take a copy first.
198
199           [% str.copy.append('.html') %]
200
201       These methods all return a reference to the String object itself.  This
202       has two important benefits.  The first is that when used as above, the
203       String object 'str' returned by the append() method will be stringified
204       with a call to its text() method.  This will return the newly modified
205       string content.  In other words, a directive like:
206
207           [% str.append('.html') %]
208
209       will update the string and also print the new value.  If you just want
210       to update the string but not print the new value then use CALL.
211
212           [% CALL str.append('.html') %]
213
214       The other benefit of these methods returning a reference to the String
215       is that you can chain as many different method calls together as you
216       like.  For example:
217
218           [% String.append('.html').trim.format(href) %]
219
220       Here are the methods:
221
222       push($suffix, ...) / append($suffix, ...)
223           Appends all arguments to the end of the string.  The append()
224           method is provided as an alias for push().
225
226               [% msg.push('foo', 'bar') %]
227               [% msg.append('foo', 'bar') %]
228
229       pop($suffix)
230           Removes the suffix passed as an argument from the end of the
231           String.
232
233               [% USE String 'foo bar' %]
234               [% String.pop(' bar')   %]   # => 'foo'
235
236       unshift($prefix, ...) / prepend($prefix, ...)
237           Prepends all arguments to the beginning of the string.  The
238           prepend() method is provided as an alias for unshift().
239
240               [% msg.unshift('foo ', 'bar ') %]
241               [% msg.prepend('foo ', 'bar ') %]
242
243       shift($prefix)
244           Removes the prefix passed as an argument from the start of the
245           String.
246
247               [% USE String 'foo bar' %]
248               [% String.shift('foo ') %]   # => 'bar'
249
250       left($pad)
251           If the length of the string is less than $pad then the string is
252           left formatted and padded with spaces to $pad length.
253
254               [% msg.left(20) %]
255
256       right($pad)
257           As per left() but right padding the String to a length of $pad.
258
259               [% msg.right(20) %]
260
261       center($pad) / centre($pad)
262           As per left() and right() but formatting the String to be centered
263           within a space padded string of length $pad.  The centre() method
264           is provided as an alias for center() to keep Yanks and Limeys
265           happy.
266
267               [% msg.center(20) %]    # American spelling
268               [% msg.centre(20) %]    # European spelling
269
270       format($format)
271           Apply a format in the style of sprintf() to the string.
272
273               [% USE String("world") %]
274               [% String.format("Hello %s\n") %]  # => "Hello World\n"
275
276       upper()
277           Converts the string to upper case.
278
279               [% USE String("foo") %]
280
281               [% String.upper %]  # => 'FOO'
282
283       lower()
284           Converts the string to lower case
285
286               [% USE String("FOO") %]
287
288               [% String.lower %]  # => 'foo'
289
290       capital()
291           Converts the first character of the string to upper case.
292
293               [% USE String("foo") %]
294
295               [% String.capital %]  # => 'Foo'
296
297           The remainder of the string is left untouched.  To force the string
298           to be all lower case with only the first letter capitalised, you
299           can do something like this:
300
301               [% USE String("FOO") %]
302
303               [% String.lower.capital %]  # => 'Foo'
304
305       chop()
306           Removes the last character from the string.
307
308               [% USE String("foop") %]
309
310               [% String.chop %]   # => 'foo'
311
312       chomp()
313           Removes the trailing newline from the string.
314
315               [% USE String("foo\n") %]
316
317               [% String.chomp %]  # => 'foo'
318
319       trim()
320           Removes all leading and trailing whitespace from the string
321
322               [% USE String("   foo   \n\n ") %]
323
324               [% String.trim %]   # => 'foo'
325
326       collapse()
327           Removes all leading and trailing whitespace and collapses any
328           sequences of multiple whitespace to a single space.
329
330               [% USE String(" \n\r  \t  foo   \n \n bar  \n") %]
331
332               [% String.collapse %]   # => "foo bar"
333
334       truncate($length, $suffix)
335           Truncates the string to $length characters.
336
337               [% USE String('long string') %]
338               [% String.truncate(4) %]  # => 'long'
339
340           If $suffix is specified then it will be appended to the truncated
341           string.  In this case, the string will be further shortened by the
342           length of the suffix to ensure that the newly constructed string
343           complete with suffix is exactly $length characters long.
344
345               [% USE msg = String('Hello World') %]
346               [% msg.truncate(8, '...') %]   # => 'Hello...'
347
348       replace($search, $replace)
349           Replaces all occurences of $search in the string with $replace.
350
351               [% USE String('foo bar foo baz') %]
352               [% String.replace('foo', 'wiz')  %]  # => 'wiz bar wiz baz'
353
354       remove($search)
355           Remove all occurences of $search in the string.
356
357               [% USE String('foo bar foo baz') %]
358               [% String.remove('foo ')  %]  # => 'bar baz'
359
360       repeat($count)
361           Repeats the string $count times.
362
363               [% USE String('foo ') %]
364               [% String.repeat(3)  %]  # => 'foo foo foo '
365

AUTHOR

367       Andy Wardley <abw@wardley.org>
368
369       <http://wardley.org/⎪http://wardley.org/>
370

VERSION

372       2.4, distributed as part of the Template Toolkit version 2.18, released
373       on 09 February 2007.
374

COPYRIGHT

376         Copyright (C) 1996-2007 Andy Wardley.  All Rights Reserved.
377
378       This module is free software; you can redistribute it and/or modify it
379       under the same terms as Perl itself.
380