## ----------------------------------------------------------------------------
#  String::Gsub::Functions
# -----------------------------------------------------------------------------
# Mastering programmed by YAMASHINA Hio
#
# Copyright 2006 YAMASHINA Hio
# -----------------------------------------------------------------------------
# $Id$
# -----------------------------------------------------------------------------
package String::Gsub::Functions;
use warnings;
use strict;
use String::Gsub::Matcher;

use base qw(Exporter);
our @EXPORT_OK = qw(gsub gsubx subs subsx);

1;

# -----------------------------------------------------------------------------
# gsub($str, $regex, $replacement);
#   $regex is qr// or "string".
#   $replacement is sub{} or "string".
#   returns new value.
#
sub gsub($$$)
{
	splice(@_, 0, 1, $_[0]); # copy.
	&gsubx;
}

# -----------------------------------------------------------------------------
# gsubx($str, $regex, $replacement);
#   $regex is qr// or "string".
#   $replacement is sub{} or "string".
#   returns new value and $str is replaced with result too.
sub gsubx($$$)
{
	#my $str = $_[0];
	my $re  = $_[1];
	my $sub = $_[2];
	
	ref($re)  or $re  = qr/\Q$re\E/;
	ref($sub) or $sub = do{ my$tmpl=$sub; sub{ shift->expand($tmpl); }; };
	$_[0] =~ s{$re}
	{
		my $match = String::Gsub::Matcher->new($_[0]);
		$sub->($match);
	}ge;
	$_[0];
}

# -----------------------------------------------------------------------------
# subs($str, $regex, $replacement);
#   $regex is qr// or "string".
#   $replacement is sub{} or "string".
#   returns new value.
#
sub subs($$$)
{
	splice(@_, 0, 1, $_[0]); # copy.
	&subsx;
}

# -----------------------------------------------------------------------------
# subsx($str, $regex, $replacement);
#   $regex is qr// or "string".
#   $replacement is sub{} or "string".
#   returns new value and $str is replaced with result too.
sub subsx($$$)
{
	#my $str = $_[0];
	my $re  = $_[1];
	my $sub = $_[2];
	
	ref($re)  or $re  = qr/\Q$re\E/;
	ref($sub) or $sub = do{ my$tmpl=$sub; sub{ shift->expand($tmpl); }; };
	$_[0] =~ s{$re}
	{
		my $match = String::Gsub::Matcher->new($_[0]);
		$sub->($match);
	}e;
	$_[0];
}

__END__

=head1 NAME

String::Gsub::Functions - core functions of String::Gsub

=head1 SYNOPSIS

 use String::Gsub::Functions qw(gsub);
 
 print gsub("abcabc", qr/(b)/,sub{uc$1}); # ==> "aBcaBc"
 
 gsubx(my $str = "abcabc", qr/(b)/, sub{uc $1});
 print $str; # ==> "aBcaBc";

=head1 DESCRIPTION

This module has folloing functions:

 gsub ($str, $regexp, $replacement)
 gsubx($str, $regexp, $replacement)
 subs ($str, $regexp, $replacement)
 subsx($str, $regexp, $replacement)

C<$regexp> is regular expression (C<qr//>). 
And C<$replacement> is code reference, which is invoked at replacement.
In C<$replacement> subroutine, match variables (C<$1>, C<$2>, ...)
are avaiable like replacement part of C<s/PATTERN/REPLACEMENT/>.

Both C<$regexp> and C<$replacement> can be string, 
but there are difference from usual part.

String passed on C<$regexp> is not treated as regular expression
, just string. special chars will be escaped.

String passwd on C<$replacement> will be replaced some substrings
with match strings and used as replacement string.
C<\&>, C<\`> and C<\'> are also did.

=head1 EXPORT

This module can export C<gsub>, C<gsubx>, C<subs>, C<subsx>.

=head1 FUNCTIONS

=head2 gsub($str, $regexp, $replacement)

process global substitute, and return new string.

=head2 gsubx($str, $regexp, $replacement)

like gsub, but replace self string and return itself.

=head2 subs($str, $regexp, $replacement)

process one substitute, and return new string.

=head2 subsx($str, $regexp, $replacement)

like subs, but replace self string and return itself.

=head1 SEE ALSO

L<String::Gsub>

=cut

# -----------------------------------------------------------------------------
# End of File.
# -----------------------------------------------------------------------------