NAME

String::Tools - Various tools for handling strings.

VERSION

version 0.14.150

SYNOPSIS

use String::Tools qw(define is_blank shrink stitch stitcher subst trim);

my $val = define undef; # ''

say is_blank(undef);    # 1  (true)
say is_blank('');       # 1  (true)
say is_blank("\t\n\0"); # 1  (true)
say is_blank("0");      # '' (false)

say shrink("  This is  a    test\n");  # 'This is a test'

## stitch ##
say stitch( qw(This is a test) );  # "This is a test"
say stitch(
   qw(This is a test), "\n",
   qw(of small proportions)
);  # "This is a test\nof small proportions"

# Format some other language in a more readable format,
# yet keep the resulting string small for transport across the network.
say stitch(qw(
   SELECT *
     FROM table
    WHERE foo = ?
      AND bar = ?
));
# "SELECT * FROM table WHERE foo = ? AND bar = ?"

## subst ##
my $date = 'Today is ${ day } of $month, in the year $year';
say subst( $date,   day => '15th', month => 'August', year => 2013   );
# OR
say subst( $date, { day => '15th', month => 'August', year => 2013 } );
# OR
say subst( $date, [ day => '15th', month => 'August', year => 2013 ] );

my $lookfor = 'The thing you're looking for is $_.';
say               subst( $lookfor, 'this' );
say 'No, wait! ', subst( $lookfor, _ => 'that' );

say trim("  This is  a    test\n");    # 'This is  a    test'

# Describe what to trim:
say trim("  This is  a    test\n",
         l => '\s+', r => '\n+');      # 'This is  a    test'

DESCRIPTION

String::Tools is a collection of tools to manipulate strings.

Variables

$THREAD

The default thread to use while stitching a string together. Defaults to a single space, ' '. Used in "shrink( $string = $_ )" and "stitch( @list )".

$BLANK

The default regular expression character class to determine if a string component is blank. Defaults to [[:cntrl:][:space:]]. Used in "is_blank( $string = $_ )", "shrink( $string = $_ )", "stitch( @list )", and "trim( $string, qr/l/ = qr/$BLANK+/, qr/r/ = $l )".

Functions

define( $scalar = $_ )

Returns $scalar if it is defined, or the empty string if it's undefined. Useful in avoiding the 'Use of uninitialized value' warnings. $scalar defaults to $_ if not specified.

is_blank( $string = $_ )

Return true if $string is blank. A blank $string is undefined, the empty string, or a string that conisists entirely of "$BLANK" characters. $string defaults to $_ if not specified.

shrink( $string = $_ )

Combine multiple consecutive $BLANK characters into one $THREAD character throughout $string. $string defaults to $_ if not specified.

stitch( @list )

Stitch together the elements of list with "$THREAD". If an item in @list is blank (as measured by "is_blank( $string = $_ )"), then the item is stitched without "$THREAD".

This approach is more intuitive than join:

say   join( ' ' => qw( 1 2 3 ... ), "\n", qw( Can anybody hear? ) );
# "1 2 3 ... \n Can anybody hear?"
say   join( ' ' => qw( 1 2 3 ... ) );
say   join( ' ' => qw( Can anybody hear? ) );
# "1 2 3 ...\nCan anybody hear?"
#
say stitch( ' ' => qw( 1 2 3 ... ), "\n", qw( Can anybody hear? ) );
# "1 2 3 ...\nCan anybody hear?"

say   join( ' ' => $user, qw( home dir is /home/ ),     $user );
# "$user home dir is /home/ $user"
say   join( ' ' => $user, qw( home dir is /home/ ) ) .  $user;
# "$user home dir is /home/$user"
#
say stitch( ' ' => $user, qw( home dir is /home/ ), '', $user );
# "$user home dir is /home/$user"

stitcher( $thread => @list )

Stitch together the elements of list with $thread in place of "$THREAD".

subst( $string, %variables = ( _ => $_ ) )

Take in $string, and do a search and replace of all the variables named in %variables with the associated values.

The %variables parameter can be a hash, hash reference, array reference, list, scalar, or empty. The single scalar is treated as if the name is the underscore. The empty case is handled by using underscore as the name, and $_ as the value.

If you really want to replace nothing in the string, then pass in an empty hash reference or empty array reference, as an empty hash or empty list will be treated as the empty case.

Only names which are in %variables will be replaced. This means that substitutions that are in $string which are not mentioned in %variables are simply ignored and left as is.

Returns the string with substitutions made.

trim( $string, qr/l/ = qr/$BLANK+/, qr/r/ = $l )

Trim string of leading and trailing characters. $string defaults to $_ if not specified. The paramters l (lead) and r (rear) are both optional, and can be specified positionally, or as key-value pairs. If l is undefined, the default pattern is /$BLANK+/, matched at the beginning of the string. If r is undefined, the default pattern is the value of l, matched at the end of the string.

If you don't want to trim the start or end of a string, set the corresponding parameter to the empty string ''.

say map trim, @strings;

say trim('  This is a test  ')
# 'This is a test'

say trim('--This is a test==', qr/-/, qr/=/);
# '-This is a test='

say trim('  This is a test!!', r => qr/[.?!]+/, l => qr/\s+/);
# 'This is a test'

BUGS

None known.

TODO

Nothing?

AUTHOR

Bob Kleemann

SEE ALSO

"join" in perlfunc, Any templating system.