1Template::Plugin::StrinUgs(e3r)Contributed Perl DocumentTaetmipolnate::Plugin::String(3)
2
3
4
6 Template::Plugin::String - Object oriented interface for string
7 manipulation
8
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
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
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
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
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 occurrences 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 occurrences 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
329 Andy Wardley <abw@wardley.org> <http://wardley.org/>
330
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
338 Template::Plugin
339
340
341
342perl v5.32.1 2021-01-27 Template::Plugin::String(3)