[%# # IMPORTANT NOTE # This documentation is generated automatically from source # templates. Any changes you make here may be lost. # # The 'docsrc' documentation source bundle is available for download # from http://www.template-toolkit.org/docs.html and contains all # the source templates, XML files, scripts, etc., from which the # documentation for the Template Toolkit is built. -%] [% META book = 'Modules' page = 'Plugin_String' %] [% WRAPPER toc; PROCESS tocitem title ="SYNOPSIS" subs = []; PROCESS tocitem title ="DESCRIPTION" subs = []; PROCESS tocitem title ="METHODS" subs = [ "Construction Methods", "Inspection Methods", "Mutation Methods" ]; PROCESS tocitem title ="AUTHOR" subs = []; PROCESS tocitem title ="VERSION" subs = []; PROCESS tocitem title ="COPYRIGHT" subs = []; PROCESS tocitem title ="SEE ALSO" subs = []; END %] [% WRAPPER section title="SYNOPSIS" -%]
    # create String objects via USE directive
    [% tt_start_tag %] USE String [% tt_end_tag %]
    [% tt_start_tag %] USE String 'initial text' [% tt_end_tag %]
    [% tt_start_tag %] USE String text => 'initial text' [% tt_end_tag %]
    # or from an existing String via new()
    [% tt_start_tag %] newstring = String.new [% tt_end_tag %]
    [% tt_start_tag %] newstring = String.new('newstring text') [% tt_end_tag %]
    [% tt_start_tag %] newstring = String.new( text => 'newstring text' ) [% tt_end_tag %]
    # or from an existing String via copy()
    [% tt_start_tag %] newstring = String.copy [% tt_end_tag %]
    # append text to string
    [% tt_start_tag %] String.append('text to append') [% tt_end_tag %]
    # format left, right or center/centre padded
    [% tt_start_tag %] String.left(20) [% tt_end_tag %]
    [% tt_start_tag %] String.right(20) [% tt_end_tag %]
    [% tt_start_tag %] String.center(20) [% tt_end_tag %]   # American spelling
    [% tt_start_tag %] String.centre(20) [% tt_end_tag %]   # European spelling
    # and various other methods...
[%- END %] [% WRAPPER section title="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'.

    [% tt_start_tag %] USE String [% tt_end_tag %]
    [% tt_start_tag %] USE String 'initial text' [% tt_end_tag %]
    [% tt_start_tag %] USE String text='initial text' [% tt_end_tag %]

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:

    [% tt_start_tag %] USE greeting = String 'Hello World' [% tt_end_tag %]

Once you've got a String object, you can use it as a prototype to create other String objects with the new() method.

    [% tt_start_tag %] USE String [% tt_end_tag %]
    [% tt_start_tag %] greeting = String.new('Hello World') [% tt_end_tag %]

The new() method also accepts an initial text string as an argument or the named parameter 'text'.

    [% tt_start_tag %] greeting = String.new( text => 'Hello World' ) [% tt_end_tag %]

You can also call copy() to create a new String as a copy of the original.

    [% tt_start_tag %] greet2 = greeting.copy [% tt_end_tag %]

The String object has a text() method to return the content of the string.

    [% tt_start_tag %] greeting.text [% tt_end_tag %]

However, it is sufficient to simply print the string and let the overloaded stringification operator call the text() method automatically for you.

    [% tt_start_tag %] greeting [% tt_end_tag %]

Thus, you can treat String objects pretty much like any regular piece of text, interpolating it into other strings, for example:

    [% tt_start_tag %] msg = "It printed '$greeting' and then dumped core\n" [% tt_end_tag %]

You also have the benefit of numerous other methods for manipulating the string.

    [% tt_start_tag %] msg.append("PS  Don't eat the yellow snow") [% tt_end_tag %]

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:

    [% tt_start_tag %] msg.copy.append("PS  Don't eat the yellow snow") [% tt_end_tag %]

These methods return a reference to the String object itself. This allows you to chain multiple methods together.

    [% tt_start_tag %] msg.copy.append('foo').right(72) [% tt_end_tag %]

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.

    [% tt_start_tag %] foo = String.new('foo') [% tt_end_tag %]
    [% tt_start_tag %] foo.append('bar') [% tt_end_tag %]         # prints "foobar"
    [% tt_start_tag %] CALL foo.append('bar') [% tt_end_tag %]    # nothing
[%- END %] [% WRAPPER section title="METHODS" -%][% WRAPPER subsection title = "Construction Methods" -%]

The following methods are used to create new String objects.

[%- END %] [% WRAPPER subsection title = "Inspection Methods" -%]

These methods are used to inspect the string content or other parameters relevant to the string.

[%- END %] [% WRAPPER subsection title = "Mutation Methods" -%]

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

    [% tt_start_tag %] USE str=String('foobar') [% tt_end_tag %]
    [% tt_start_tag %] str.append('.html') [% tt_end_tag %]	# str => 'foobar.html'

The value of the String 'str' is now 'foobar.html'. If you don't want to modify the string then simply take a copy first.

    [% tt_start_tag %] str.copy.append('.html') [% tt_end_tag %]

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:

    [% tt_start_tag %] str.append('.html') [% tt_end_tag %]

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.

    [% tt_start_tag %] CALL str.append('.html') [% tt_end_tag %]

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:

    [% tt_start_tag %] String.append('.html').trim.format(href) [% tt_end_tag %]

Here are the methods:

[%- END %] [%- END %] [% WRAPPER section title="AUTHOR" -%]

Andy Wardley <abw@wardley.org>

[% ttlink('http://wardley.org/', 'http://wardley.org/') -%]

[%- END %] [% WRAPPER section title="VERSION" -%]

2.4, distributed as part of the Template Toolkit version 2.19, released on 27 April 2007.

[%- END %] [% WRAPPER section title="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.

[%- END %] [% WRAPPER section title="SEE ALSO" -%]

[% ttlink('Template::Plugin', 'Template::Plugin') -%]

[%- END %]