GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  TEMPLATE::PLUGIN::STRING (3)

.ds Aq ’

NAME

Template::Plugin::String - Object oriented interface for string manipulation

CONTENTS

SYNOPSIS



    # 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...



DESCRIPTION

This module implements a String class for doing stringy things to text in an object-oriented way.

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  Dont 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  Dont 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



CONSTRUCTOR METHODS

These methods are used to create new String objects.

new()

Creates a new string using an initial value passed as a positional argument or the named parameter text.



    [% USE String %]
    [% msg = String.new(Hello World) %]
    [% msg = String.new( text => Hello World ) %]



copy()

Creates a new String object which contains a copy of the original string.



    [% msg2 = msg.copy %]



INSPECTOR METHODS

These methods are used to examine the string.

text()

Returns the internal text value of the string. The stringification operator is overloaded to call this method. Thus the following are equivalent:



    [% msg.text %]
    [% msg %]



length()

Returns the length of the string.



    [% USE String("foo") %]
    [% String.length %]   # => 3



    search($pattern)

Searches the string for the regular expression specified in $pattern returning true if found or false otherwise.



    [% item = String.new(foo bar baz wiz waz woz) %]
    [% item.search(wiz) ? WIZZY! :-) : not wizzy :-( %]



split($pattern, CW$limit)

Splits the string based on the delimiter $pattern and optional $limit. Delegates to Perl’s internal split() so the parameters are exactly the same.



    [% FOREACH item.split %]
         ...
    [% END %]

    [% FOREACH item.split(baz|waz) %]
         ...
    [% END %]



MUTATOR METHODS

These methods modify the internal value of the string. For example:



    [% 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) %]



Here are the methods:

    push($suffix, ...) / append($suffix, ...)

Appends all arguments to the end of the string. The append() method is provided as an alias for push().



    [% msg.push(foo, bar) %]
    [% msg.append(foo, bar) %]



    pop($suffix)

Removes the suffix passed as an argument from the end of the String.



    [% USE String foo bar %]
    [% String.pop( bar)   %]   # => foo



    unshift($prefix, ...) / prepend($prefix, ...)

Prepends all arguments to the beginning of the string. The prepend() method is provided as an alias for unshift().



    [% msg.unshift(foo , bar ) %]
    [% msg.prepend(foo , bar ) %]



    shift($prefix)

Removes the prefix passed as an argument from the start of the String.



    [% USE String foo bar %]
    [% String.shift(foo ) %]   # => bar



    left($pad)

If the length of the string is less than $pad then the string is left formatted and padded with spaces to $pad length.



    [% msg.left(20) %]



    right($pad)

As per left() but right padding the String to a length of $pad.



    [% msg.right(20) %]



    center($pad) / centre($pad)

As per left() and right() but formatting the String to be centered within a space padded string of length $pad. The centre() method is provided as an alias for center().



    [% msg.center(20) %]    # American spelling
    [% msg.centre(20) %]    # European spelling



    format($format)

Apply a format in the style of sprintf() to the string.



    [% USE String("world") %]
    [% String.format("Hello %s\n") %]  # => "Hello World\n"



upper()

Converts the string to upper case.



    [% USE String("foo") %]
    [% String.upper %]  # => FOO



lower()

Converts the string to lower case



    [% USE String("FOO") %]
    [% String.lower %]  # => foo



capital()

Converts the first character of the string to upper case.



    [% 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



chop()

Removes the last character from the string.



    [% USE String("foop") %]
    [% String.chop %]   # => foo



chomp()

Removes the trailing newline from the string.



    [% USE String("foo\n") %]
    [% String.chomp %]  # => foo



trim()

Removes all leading and trailing whitespace from the string



    [% USE String("   foo   \n\n ") %]
    [% String.trim %]   # => foo



collapse()

Removes all leading and trailing whitespace and collapses any sequences of multiple whitespace to a single space.



    [% USE String(" \n\r  \t  foo   \n \n bar  \n") %]
    [% String.collapse %]   # => "foo bar"



truncate($length, CW$suffix)

Truncates the string to $length characters.



    [% 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...



replace($search, CW$replace)

Replaces all occurrences of $search in the string with $replace.



    [% USE String(foo bar foo baz) %]
    [% String.replace(foo, wiz)  %]  # => wiz bar wiz baz



    remove($search)

Remove all occurrences of $search in the string.



    [% USE String(foo bar foo baz) %]
    [% String.remove(foo )  %]  # => bar baz



    repeat($count)

Repeats the string $count times.



    [% USE String(foo ) %]
    [% String.repeat(3)  %]  # => foo foo foo 



AUTHOR

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

COPYRIGHT

Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

Template::Plugin
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 TEMPLATE::PLUGIN::STRING (3) 2014-04-23

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.