summaryrefslogtreecommitdiff
path: root/lib/Template/Plugin/String.pm
diff options
context:
space:
mode:
Diffstat (limited to 'lib/Template/Plugin/String.pm')
-rw-r--r--lib/Template/Plugin/String.pm796
1 files changed, 796 insertions, 0 deletions
diff --git a/lib/Template/Plugin/String.pm b/lib/Template/Plugin/String.pm
new file mode 100644
index 0000000..34dd007
--- /dev/null
+++ b/lib/Template/Plugin/String.pm
@@ -0,0 +1,796 @@
+#============================================================= -*-Perl-*-
+#
+# Template::Plugin::String
+#
+# DESCRIPTION
+# Template Toolkit plugin to implement a basic String object.
+#
+# AUTHOR
+# Andy Wardley <abw@kfs.org>
+#
+# COPYRIGHT
+# Copyright (C) 2001 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.
+#
+# REVISION
+# $Id: String.pm,v 2.33 2004/01/13 16:20:38 abw Exp $
+#
+#============================================================================
+
+package Template::Plugin::String;
+
+require 5.004;
+
+use strict;
+use Template::Plugin;
+use Template::Exception;
+
+use base qw( Template::Plugin );
+use vars qw( $VERSION $ERROR);
+use overload q|""| => "text",
+ fallback => 1;
+
+$VERSION = sprintf("%d.%02d", q$Revision: 2.33 $ =~ /(\d+)\.(\d+)/);
+$ERROR = '';
+
+*centre = \*center;
+*append = \*push;
+*prepend = \*unshift;
+
+#------------------------------------------------------------------------
+
+sub new {
+ my ($class, @args) = @_;
+ my $context = ref $class ? undef : shift(@args);
+ my $config = @args && ref $args[-1] eq 'HASH' ? pop(@args) : { };
+
+ $class = ref($class) || $class;
+
+ my $text = defined $config->{ text }
+ ? $config->{ text }
+ : (@args ? shift(@args) : '');
+
+# print STDERR "text: [$text]\n";
+# print STDERR "class: [$class]\n";
+
+ my $self = bless {
+ text => $text,
+ filters => [ ],
+ _CONTEXT => $context,
+ }, $class;
+
+ my $filter = $config->{ filter } || $config->{ filters };
+
+ # install any output filters specified as 'filter' or 'filters' option
+ $self->output_filter($filter)
+ if $filter;
+
+ return $self;
+}
+
+
+sub text {
+ my $self = shift;
+ return $self->{ text } unless @{ $self->{ filters } };
+
+ my $text = $self->{ text };
+ my $context = $self->{ _CONTEXT };
+
+ foreach my $dispatch (@{ $self->{ filters } }) {
+ my ($name, $args) = @$dispatch;
+ my $code = $context->filter($name, $args)
+ || $self->throw($context->error());
+ $text = &$code($text);
+ }
+ return $text;
+}
+
+
+sub copy {
+ my $self = shift;
+ $self->new($self->{ text });
+}
+
+
+sub throw {
+ my $self = shift;
+
+ die (Template::Exception->new('String', join('', @_)));
+}
+
+
+#------------------------------------------------------------------------
+# output_filter($filter)
+#
+# Install automatic output filter(s) for the string. $filter can a list:
+# [ 'name1', 'name2' => [ ..args.. ], name4 => { ..args.. } ] or a hash
+# { name1 => '', name2 => [ args ], name3 => { args } }
+#------------------------------------------------------------------------
+
+sub output_filter {
+ my ($self, $filter) = @_;
+ my ($name, $args, $dispatch);
+ my $filters = $self->{ filters };
+ my $count = 0;
+
+ if (ref $filter eq 'HASH') {
+ $filter = [ %$filter ];
+ }
+ elsif (ref $filter ne 'ARRAY') {
+ $filter = [ split(/\s*\W+\s*/, $filter) ];
+ }
+
+ while (@$filter) {
+ $name = shift @$filter;
+
+ # args may follow as a reference (or empty string, e.g. { foo => '' }
+ if (@$filter && (ref($filter->[0]) || ! length $filter->[0])) {
+ $args = shift @$filter;
+ if ($args) {
+ $args = [ $args ] unless ref $args eq 'ARRAY';
+ }
+ else {
+ $args = [ ];
+ }
+ }
+ else {
+ $args = [ ];
+ }
+
+# $self->DEBUG("adding output filter $name(@$args)\n");
+
+ push(@$filters, [ $name, $args ]);
+ $count++;
+ }
+
+ return '';
+}
+
+
+#------------------------------------------------------------------------
+
+sub push {
+ my $self = shift;
+ $self->{ text } .= join('', @_);
+ return $self;
+}
+
+
+sub unshift {
+ my $self = shift;
+ $self->{ text } = join('', @_) . $self->{ text };
+ return $self;
+}
+
+
+sub pop {
+ my $self = shift;
+ my $strip = shift || return $self;
+ $self->{ text } =~ s/$strip$//;
+ return $self;
+}
+
+
+sub shift {
+ my $self = shift;
+ my $strip = shift || return $self;
+ $self->{ text } =~ s/^$strip//;
+ return $self;
+}
+
+#------------------------------------------------------------------------
+
+sub center {
+ my ($self, $width) = @_;
+ my $text = $self->{ text };
+ my $len = length $text;
+ $width ||= 0;
+
+ if ($len < $width) {
+ my $lpad = int(($width - $len) / 2);
+ my $rpad = $width - $len - $lpad;
+ $self->{ text } = (' ' x $lpad) . $self->{ text } . (' ' x $rpad);
+ }
+
+ return $self;
+}
+
+
+sub left {
+ my ($self, $width) = @_;
+ my $len = length $self->{ text };
+ $width ||= 0;
+
+ $self->{ text } .= (' ' x ($width - $len))
+ if $width > $len;
+
+ return $self;
+}
+
+
+sub right {
+ my ($self, $width) = @_;
+ my $len = length $self->{ text };
+ $width ||= 0;
+
+ $self->{ text } = (' ' x ($width - $len)) . $self->{ text }
+ if $width > $len;
+
+ return $self;
+}
+
+
+sub format {
+ my ($self, $format) = @_;
+ $format = '%s' unless defined $format;
+ $self->{ text } = sprintf($format, $self->{ text });
+ return $self;
+}
+
+
+sub filter {
+ my ($self, $name, @args) = @_;
+
+ my $context = $self->{ _CONTEXT };
+
+ my $code = $context->filter($name, \@args)
+ || $self->throw($context->error());
+ return &$code($self->{ text });
+}
+
+
+#------------------------------------------------------------------------
+
+sub upper {
+ my $self = CORE::shift;
+ $self->{ text } = uc $self->{ text };
+ return $self;
+}
+
+
+sub lower {
+ my $self = CORE::shift;
+ $self->{ text } = lc $self->{ text };
+ return $self;
+}
+
+
+sub capital {
+ my $self = CORE::shift;
+ $self->{ text } =~ s/^(.)/\U$1/;
+ return $self;
+}
+
+#------------------------------------------------------------------------
+
+sub chop {
+ my $self = CORE::shift;
+ chop $self->{ text };
+ return $self;
+}
+
+
+sub chomp {
+ my $self = CORE::shift;
+ chomp $self->{ text };
+ return $self;
+}
+
+
+sub trim {
+ my $self = CORE::shift;
+ for ($self->{ text }) {
+ s/^\s+//;
+ s/\s+$//;
+ }
+ return $self;
+}
+
+
+sub collapse {
+ my $self = CORE::shift;
+ for ($self->{ text }) {
+ s/^\s+//;
+ s/\s+$//;
+ s/\s+/ /g
+ }
+ return $self;
+
+}
+
+#------------------------------------------------------------------------
+
+sub length {
+ my $self = CORE::shift;
+ return length $self->{ text };
+}
+
+
+sub truncate {
+ my ($self, $length, $suffix) = @_;
+ return $self unless defined $length;
+ $suffix ||= '';
+ return $self if CORE::length $self->{ text } <= $length;
+ $self->{ text } = substr($self->{ text }, 0,
+ $length - CORE::length($suffix)) . $suffix;
+ return $self;
+}
+
+
+sub repeat {
+ my ($self, $n) = @_;
+ return $self unless defined $n;
+ $self->{ text } = $self->{ text } x $n;
+ return $self;
+}
+
+
+sub replace {
+ my ($self, $search, $replace) = @_;
+ return $self unless defined $search;
+ $replace = '' unless defined $replace;
+ $self->{ text } =~ s/$search/$replace/g;
+ return $self;
+}
+
+
+sub remove {
+ my ($self, $search) = @_;
+ $search = '' unless defined $search;
+ $self->{ text } =~ s/$search//g;
+ return $self;
+}
+
+
+sub split {
+ my $self = CORE::shift;
+ my $split = CORE::shift;
+ my $limit = CORE::shift || 0;
+ $split = '\s+' unless defined $split;
+ return [ split($split, $self->{ text }, $limit) ];
+}
+
+
+sub search {
+ my ($self, $pattern) = @_;
+ return $self->{ text } =~ /$pattern/;
+}
+
+
+sub equals {
+ my ($self, $comparison) = @_;
+ return $self->{ text } eq $comparison;
+}
+
+
+1;
+
+__END__
+
+
+#------------------------------------------------------------------------
+# 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.
+#------------------------------------------------------------------------
+
+=head1 NAME
+
+Template::Plugin::String - Object oriented interface for string manipulation
+
+=head1 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...
+
+=head1 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 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
+
+=head1 METHODS
+
+=head2 Construction Methods
+
+The following methods are used to create new String objects.
+
+=over 4
+
+=item 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' ) %]
+
+=item copy()
+
+Creates a new String object which contains a copy of the original string.
+
+ [% msg2 = msg.copy %]
+
+=back
+
+=head2 Inspection Methods
+
+These methods are used to inspect the string content or other parameters
+relevant to the string.
+
+=over 4
+
+=item 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 %]
+
+=item length()
+
+Returns the length of the string.
+
+ [% USE String("foo") %]
+
+ [% String.length %] # => 3
+
+=item 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 :-(' %]
+
+=item split($pattern, $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 %]
+
+=back
+
+=head2 Mutation 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 the String '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:
+
+=over 4
+
+=item 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') %]
+
+=item pop($suffix)
+
+Removes the suffix passed as an argument from the end of the String.
+
+ [% USE String 'foo bar' %]
+ [% String.pop(' bar') %] # => 'foo'
+
+=item 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 ') %]
+
+=item shift($prefix)
+
+Removes the prefix passed as an argument from the start of the String.
+
+ [% USE String 'foo bar' %]
+ [% String.shift('foo ') %] # => 'bar'
+
+=item 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) %]
+
+=item right($pad)
+
+As per left() but right padding the String to a length of $pad.
+
+ [% msg.right(20) %]
+
+=item 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() to keep Yanks and Limeys happy.
+
+ [% msg.center(20) %] # American spelling
+ [% msg.centre(20) %] # European spelling
+
+=item format($format)
+
+Apply a format in the style of sprintf() to the string.
+
+ [% USE String("world") %]
+ [% String.format("Hello %s\n") %] # => "Hello World\n"
+
+=item upper()
+
+Converts the string to upper case.
+
+ [% USE String("foo") %]
+
+ [% String.upper %] # => 'FOO'
+
+=item lower()
+
+Converts the string to lower case
+
+ [% USE String("FOO") %]
+
+ [% String.lower %] # => 'foo'
+
+=item 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'
+
+=item chop()
+
+Removes the last character from the string.
+
+ [% USE String("foop") %]
+
+ [% String.chop %] # => 'foo'
+
+=item chomp()
+
+Removes the trailing newline from the string.
+
+ [% USE String("foo\n") %]
+
+ [% String.chomp %] # => 'foo'
+
+=item trim()
+
+Removes all leading and trailing whitespace from the string
+
+ [% USE String(" foo \n\n ") %]
+
+ [% String.trim %] # => 'foo'
+
+=item 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"
+
+=item truncate($length, $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...'
+
+=item replace($search, $replace)
+
+Replaces all occurences of $search in the string with $replace.
+
+ [% USE String('foo bar foo baz') %]
+ [% String.replace('foo', 'wiz') %] # => 'wiz bar wiz baz'
+
+=item remove($search)
+
+Remove all occurences of $search in the string.
+
+ [% USE String('foo bar foo baz') %]
+ [% String.remove('foo ') %] # => 'bar baz'
+
+=item repeat($count)
+
+Repeats the string $count times.
+
+ [% USE String('foo ') %]
+ [% String.repeat(3) %] # => 'foo foo foo '
+
+=back
+
+=head1 AUTHOR
+
+Andy Wardley E<lt>abw@andywardley.comE<gt>
+
+L<http://www.andywardley.com/|http://www.andywardley.com/>
+
+
+
+
+=head1 VERSION
+
+2.33, distributed as part of the
+Template Toolkit version 2.13, released on 30 January 2004.
+
+=head1 COPYRIGHT
+
+ Copyright (C) 1996-2004 Andy Wardley. All Rights Reserved.
+ Copyright (C) 1998-2002 Canon Research Centre Europe Ltd.
+
+This module is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself.
+
+=head1 SEE ALSO
+
+L<Template::Plugin|Template::Plugin>
+
+=cut
+
+# Local Variables:
+# mode: perl
+# perl-indent-level: 4
+# indent-tabs-mode: nil
+# End:
+#
+# vim: expandtab shiftwidth=4:
generated by cgit v1.2.3 (git 2.25.1) at 2026-03-04 13:31:34 +0000