# создание объектов String с помощью директивы USE
    [% USE String %]
    [% USE String 'initial text' %]
    [% USE String text => 'initial text' %]

    # или из существующего объекта String через new()
    [% newstring = String.new %]
    [% newstring = String.new('newstring text') %]
    [% newstring = String.new( text => 'newstring text' ) %]

    # или из существующего объекта String через copy()
    [% newstring = String.copy %]

    # добавление текста к строке
    [% String.append('text to append') %]

    # форматирование с выравниванием влево, вправо или по центру
    [% String.left(20) %]
    [% String.right(20) %]
    [% String.center(20) %]   # американская нотация
    [% String.centre(20) %]   # европейская нотация

    # и ряд других методов...

Этот модуль реализует класс String для выполнения строковых операций с текстом в объектно-ориентированном стиле.

Создать объект String можно с помощью директивы USE, добавив любой начальный текст в качестве аргумента или именованного параметра 'text'.

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

По умолчанию имя полученного объекта 'String', но объекту можно назначить другое имя переменной:

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

Созданный объект String можно использовать в качестве прототипа для создания других объектов String посредством метода new().

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

Методу new() также можно передать начальный текст в качестве аргумента или именованного параметра 'text'.

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

Можно вызвать метод copy(), чтобы создать новый объект String как копию оригинала.

    [% greet2 = greeting.copy %]

Объект String имеет метод text(), который возвращает содержимое строки.

    [% greeting.text %]

Тем не менее, можно просто вывести строку по имени объекта, позволив перегруженному оператору стрингификации (stringification) вызвать метод text() автоматически.

    [% greeting %]

Таким образом, можно рассматривать объекты String в значительной степени как обычный текст, интерполируя его в другие строки, например:

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

Кроме того доступно множество других методов для манипуляций со строками.

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

Обратите внимание, что все методы оперируют и изменяют содержимое самой строки. Если необходимо работать с копией, необходимо предварительно её создать:

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

Эти методы возвращают ссылку на сам объект String. Это позволяет строить цепочки из нескольких методов.

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

Это также означает, что в приведённых примерах в результате получается объект String, который приводит к вызову метода text() и, как следствие, выводу нового значения строки. Чтобы подавить вывод строки, можно использовать директиву CALL.

    [% foo = String.new('foo') %]

    [% foo.append('bar') %]         # выводится "foobar"

    [% CALL foo.append('bar') %]    # ничего не выводится

Следующие методы используются для создания новых объектов String.

• new()
  

  Создает новую строку, используя начальное значение, передаваемое как позиционный аргумент или именованный параметр 'text'.

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

• copy()
  

  Создает новый объект String, который содержит копию оригинальной строки.

      [% msg2 = msg.copy %]

Эти методы используются для исследования содержимого строки или других параметров, связанных со строкой.

• text()
  

  Возвращает внутреннее значение строки. Оператор стрингификации (stringification) перегружен на вызов этого метода. Таким образом, следующие вызовы эквивалентны:

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

• length()
  

  Возвращает длину строки.

      [% USE String("foo") %]

      [% String.length %]   # => 3

• search($pattern)
  

  Осуществляет в строке поиск регулярного выражения, заданного в $pattern, и возвращает истинное или ложное значение в зависимости от результата поиска.

      [% item = String.new('foo bar baz wiz waz woz') %]

      [% item.search('wiz') ? 'WIZZY! :-)' : 'not wizzy :-(' %]

• split($pattern, $limit)
  

  Разбивает строку по разделителю $pattern и опциональному параметру $limit (максимальное количество частей, на которые требуется разбить строку). Использует внутреннюю функцию Perl split(), поэтому параметры точно такие же.

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

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

Эти методы модифицируют внутреннее значение строки. Например:

    [% USE str=String('foobar') %]

    [% str.append('.html') %]	# str => 'foobar.html'

Значение String-объекта 'str' теперь 'foobar.html'. Если не требуется изменять строку, нужно предварительно сделать её копию.

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

Все эти методы возвращают ссылку на сам объект String. Это даёт два важных преимущества. Первое заключается в том, что в приведённом примере String-объект 'str', возвращаемый методом append() будет преобразован в строку вызовом собственного метода text(). Это возвратит новое модифицированное значение строки. Другими словами, следующая директива:

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

обновит строку и выведет её новое значение. Если нужно только обновить строку без вывода нового значения, следует использовать CALL.

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

Другое преимущество заключается в том, что можно связать в цепочку любое количество различных методов объекта String. Например:

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

Ниже приведены методы:

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

  Добавляет все аргументы в конец строки. Метод append() предоставляется в качестве псевдонима к push().

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

• pop($suffix)
  

  Удаляет с конца строки суффикс, передаваемый в качестве аргумента.

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

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

  Добавляет все аргументы в начало строки. Метод prepend() предоставляется в качестве псевдонима к unshift().

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

• shift($prefix)
  

  Удаляет с начала строки префикс, передаваемый в качестве аргумента.

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

• left($pad)
  

  Если длина строки меньше чем $pad, строка выравнивается влево и дополняется пробелами до длины $pad.

      [% msg.left(20) %]

• right($pad)
  

  Аналогично left(), но строка выравнивается вправо и дополняется слева пробелами до длины $pad.

      [% msg.right(20) %]

• center($pad) / centre($pad)
  

  Аналогично left() и right(), но строка выравнивается по центру и дополняется пробелами слева и справа до длины $pad. Метод centre() предоставляется в качестве псевдонима к center(), чтобы все были счастливы.

      [% msg.center(20) %]    # американская нотация
      [% msg.centre(20) %]    # европейская нотация

• format($format)
  

  Применяет к строке формат в стиле sprintf().

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

• upper()
  

  Преобразует строку в верхний регистр.

      [% USE String("foo") %]

      [% String.upper %]  # => 'FOO'

• lower()
  

  Преобразует строку в нижний регистр.

      [% USE String("FOO") %]

      [% String.lower %]  # => 'foo'

• capital()
  

  Преобразует в верхний регистр первый символ строки.

      [% USE String("foo") %]

      [% String.capital %]  # => 'Foo'

  Остальная часть строки остаётся без изменений. Гарантировано преобразовать всю строку в нижний регистр, а первую букву - в верхний, можно следующим образом:

      [% USE String("FOO") %]

      [% String.lower.capital %]  # => 'Foo'

• chop()
  

  Удаляет последний символ в строке.

      [% USE String("foop") %]

      [% String.chop %]	# => 'foo'

• chomp()
  

  Удаляет завершающий символ новой строки.

      [% USE String("foo\n") %]

      [% String.chomp %]	# => 'foo'

• trim()
  

  Удаляет начальные и завершающие пробельные символы в строке.

      [% USE String("   foo   \n\n ") %]

      [% String.trim %]	# => 'foo'

• collapse()
  

  Удаляет начальные и завершающие пробельные символы в строке, а также сжимает в строке последовательности из нескольких пробельных символов в один пробел.

      [% USE String(" \n\r  \t  foo   \n \n bar  \n") %]

      [% String.collapse %]   # => "foo bar"

• truncate($length, $suffix)
  

  Обрезает строку до длины $length символов.

      [% USE String('long string') %]
      [% String.truncate(4) %]  # => 'long'

  Если указан $suffix, он будет добавлен к обрезанной строке. В этом случае, строка будет дополнительно укорочена на длину суффикса, чтобы модифицированная строка с суффиксом имела точно длину $length символов.

      [% USE msg = String('Hello World') %]
      [% msg.truncate(8, '...') %]   # => 'Hello...'

• replace($search, $replace)
  

  Заменяет все вхождения $search в строке на $replace.

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

• remove($search)
  

  Удаляет все вхождения $search в строке.

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

• repeat($count)
  

  Повторяет строку $count раз.

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

Энди Уардли (Andy Wardley <abw@andywardley.com>)

http://www.andywardley.com/

2.34, поставляется в составе Template Toolkit версии 2.14, дата релиза - 4 октября 2004.

  Copyright (C) 1996-2004 Andy Wardley.  All Rights Reserved.
  Copyright (C) 1998-2002 Canon Research Centre Europe Ltd.

Этот модуль является свободно-распространяемым программным обеспечением; вы можете распространять и/или модифицировать его на тех же условиях, что и Perl.

Template::Plugin