File Coverage

blib/lib/String/Compile/Tr.pm

Criterion	Covered	Total	%
statement	30	30	100.0
branch	8	10	80.0
condition	3	3	100.0
subroutine	7	7	100.0
pod	1	1	100.0
total	49	51	96.0

use 5.010;
use strict;
use warnings;

package String::Compile::Tr;

=encoding UTF-8

=head1 NAME

String::Compile::Tr - compile tr/// expressions

=head1 VERSION

Version 0.06

=cut

our
$VERSION = '0.06';


=head1 SYNOPSIS

    use String::Compile::Tr;

    my $search = '/+=';
    my $replace = '-_';
    my $s = 'De/0xv5y3w8BpLF8ubOo+w==';
    trgen($search, $replace, 'd')->($s);
    # $s = 'De-0xv5y3w8BpLF8ubOo_w'

=head1 DESCRIPTION

The usual approach when operands of a C
variables is to apply C on a string to interpolate the operands.
The drawback of this approach are possible unwanted side effects induced
by the variables' content, e.g.

    $search = '//,warn-trapped,$@=~tr/';
    eval "tr/$search//d";

C offers an alternative where the content of a
variable can be used as operand without C'ing it.
Instead the operands of a C
inside a constant C.

C compiles an anonymous sub that
performs almost the same operation as C
but allows variable operands.

C is imported by default by C.


=head1 FUNCTIONS

=head2 trgen

    trgen(search, replace, [options])

C returns an anonymous subroutine that performs an almost identical
operation as C
The C
or is the default input C<$_> otherwise.


=head1 ERRORS

C will throw an exception if an invalid option is specified
or the C

=head1 EXAMPLES

Proposed usages of this module are:

    use String::Compile::Tr;

    my $search = 'abc';
    my $replace = '123';
    my $tr = trgen($search, $replace);
    my $s = 'fedcba';
    $tr->($s);
    # $s is 'fed321' now

    my @list = qw(axy bxy cxy);
    $tr->() for @list;
    # @list is now ('1xy', '2xy', '3xy');

    print trgen($search, $replace, 'r')->('fedcba'); # 'fed321'

=head1 RESTRICTIONS

Character ranges are not supported in the search and replace lists.
All characters are interpreted literally.
This is caused by the fact that C
It's the compiler that expands character ranges in C
before handing them over.

Overloading constants in C requires perl v5.10.

=head1 AUTHOR

Jörg Sommrey, C<<  >>

=head1 LICENSE AND COPYRIGHT

This software is copyright (c) 2025 by Jörg Sommrey.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=head1 SEE ALSO

L

L

L

L provides a similar functionality, though this C's
its oprands.

=cut

use Carp;
use String::Compile::Tr::Overload;

use Exporter::Shiny our @EXPORT = qw(trgen);

*search = *String::Compile::Tr::Overload::search;
*replace = *String::Compile::Tr::Overload::replace;

sub trgen {
    local our ($search, $replace);
    my $options;
    ($search, $replace, $options) = @_;
    $replace = '' unless defined $replace;
    $options = '' unless defined $options;
    my ($opt) = $options =~ /^([cdsr]*)$/;
    $opt = '' unless defined $opt;
    croak "options invalid: $options" if $options && $options ne $opt;
    my $ret;
    my $template = <<'EOS';
    $ret = sub {
        local *_ = \$_[0] if @_;
        tr/:search:/:replace:/%s;
    }; 1
EOS
    my $code = sprintf $template, $opt;

    eval $code or croak $@;
    $ret;
}

1;