# create String objects via USE directive [% USE String %] [% USE String 'initial text' %] [% USE String text => 'initial text' %] # or from an existing String via new() [% newstring = String.new %] [% newstring = String.new('newstring text') %] [% newstring = String.new( text => 'newstring text' ) %] # or from an existing String via copy() [% newstring = String.copy %] # append text to string [% String.append('text to append') %] # format left, right or center/centre padded [% String.left(20) %] [% String.right(20) %] [% String.center(20) %] # American spelling [% String.centre(20) %] # European spelling # and various other methods...
You can create a "String" object via the "USE" directive, adding any initial text value as an argument or as the named parameter "text".
[% USE String %] [% USE String 'initial text' %] [% USE String text='initial text' %]
The object created will be referenced as "String" by default, but you can provide a different variable name for the object to be assigned to:
[% USE greeting = String 'Hello World' %]
Once you've got a "String" object, you can use it as a prototype to create other "String" objects with the "new()" method.
[% USE String %] [% greeting = String.new('Hello World') %]
The "new()" method also accepts an initial text string as an argument or the named parameter "text".
[% greeting = String.new( text => 'Hello World' ) %]
You can also call "copy()" to create a new "String" as a copy of the original.
[% greet2 = greeting.copy %]
The "String" object has a "text()" method to return the content of the string.
[% greeting.text %]
However, it is sufficient to simply print the string and let the overloaded stringification operator call the "text()" method automatically for you.
[% greeting %]
Thus, you can treat "String" objects pretty much like any regular piece of text, interpolating it into other strings, for example:
[% msg = "It printed '$greeting' and then dumped core\n" %]
You also have the benefit of numerous other methods for manipulating the string.
[% msg.append("PS Don't eat the yellow snow") %]
Note that all methods operate on and mutate the contents of the string itself. If you want to operate on a copy of the string then simply take a copy first:
[% msg.copy.append("PS Don't eat the yellow snow") %]
These methods return a reference to the "String" object itself. This allows you to chain multiple methods together.
[% msg.copy.append('foo').right(72) %]
It also means that in the above examples, the "String" is returned which causes the "text()" method to be called, which results in the new value of the string being printed. To suppress printing of the string, you can use the "CALL" directive.
[% foo = String.new('foo') %] [% foo.append('bar') %] # prints "foobar" [% CALL foo.append('bar') %] # nothing
[% USE String %] [% msg = String.new('Hello World') %] [% msg = String.new( text => 'Hello World' ) %]
[% msg2 = msg.copy %]
[% msg.text %] [% msg %]
[% USE String("foo") %] [% String.length %] # => 3
[% item = String.new('foo bar baz wiz waz woz') %] [% item.search('wiz') ? 'WIZZY! :-)' : 'not wizzy :-(' %]
[% FOREACH item.split %] ... [% END %] [% FOREACH item.split('baz|waz') %] ... [% END %]
[% USE str=String('foobar') %] [% str.append('.html') %] # str => 'foobar.html'
The value of "str" is now '"foobar.html"'. If you don't want to modify the string then simply take a copy first.
[% str.copy.append('.html') %]
These methods all return a reference to the "String" object itself. This has two important benefits. The first is that when used as above, the "String" object '"str"' returned by the "append()" method will be stringified with a call to its "text()" method. This will return the newly modified string content. In other words, a directive like:
[% str.append('.html') %]
will update the string and also print the new value. If you just want to update the string but not print the new value then use "CALL".
[% CALL str.append('.html') %]
The other benefit of these methods returning a reference to the "String" is that you can chain as many different method calls together as you like. For example:
[% String.append('.html').trim.format(href) %]
[% msg.push('foo', 'bar') %] [% msg.append('foo', 'bar') %]
[% USE String 'foo bar' %] [% String.pop(' bar') %] # => 'foo'
[% msg.unshift('foo ', 'bar ') %] [% msg.prepend('foo ', 'bar ') %]
[% USE String 'foo bar' %] [% String.shift('foo ') %] # => 'bar'
[% msg.left(20) %]
[% msg.right(20) %]
[% msg.center(20) %] # American spelling [% msg.centre(20) %] # European spelling
[% USE String("world") %] [% String.format("Hello %s\n") %] # => "Hello World\n"
[% USE String("foo") %] [% String.upper %] # => 'FOO'
[% USE String("FOO") %] [% String.lower %] # => 'foo'
[% USE String("foo") %] [% String.capital %] # => 'Foo'
The remainder of the string is left untouched. To force the string to be all lower case with only the first letter capitalised, you can do something like this:
[% USE String("FOO") %] [% String.lower.capital %] # => 'Foo'
[% USE String("foop") %] [% String.chop %] # => 'foo'
[% USE String("foo\n") %] [% String.chomp %] # => 'foo'
[% USE String(" foo \n\n ") %] [% String.trim %] # => 'foo'
[% USE String(" \n\r \t foo \n \n bar \n") %] [% String.collapse %] # => "foo bar"
[% USE String('long string') %] [% String.truncate(4) %] # => 'long'
If $suffix is specified then it will be appended to the truncated string. In this case, the string will be further shortened by the length of the suffix to ensure that the newly constructed string complete with suffix is exactly $length characters long.
[% USE msg = String('Hello World') %] [% msg.truncate(8, '...') %] # => 'Hello...'
[% USE String('foo bar foo baz') %] [% String.replace('foo', 'wiz') %] # => 'wiz bar wiz baz'
[% USE String('foo bar foo baz') %] [% String.remove('foo ') %] # => 'bar baz'
[% USE String('foo ') %] [% String.repeat(3) %] # => 'foo foo foo '
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.