NAME
Text::VisualPrintf::Transform - transform and recover interface for text processing
SYNOPSIS
use Text::VisualPrintf::Transform;
my $xform = Text::VisualPrintf::Transform->new();
$xform->encode(@args);
$_ = foo(@args);
$xform->decode($_);
DESCRIPTION
This is a general interface to transform text data into desirable form, and recover the result after the process.
For example, Text::Tabs does not take care of Asian wide characters to calculate string width. So next program does not work as we wish.
use Text::Tabs;
print expand <>;
In this case, make transform object with length function which understand wide character width, and the pattern of string to be replaced.
use Text::VisualPrintf::Transform;
use Text::VisualWidth::PP;
my $xform = Text::VisualPrintf::Transform
->new(length => \&Text::VisualWidth::PP::width,
match => qr/\P{ASCII}+/);
Then next program encode data, call expand() function, and recover the result into original text.
my @lines = <>;
$xform->encode(@lines);
my @expanded = expand @lines;
$xform->decode(@expanded);
print @expanded;
Be aware that encode and decode method alter the values of given arguments. Because they return results as a list too, this can be done more simply.
print $xform->decode(expand($xform->encode(<>)));
Next program implements ANSI terminal sequence aware expand command.
use Text::ANSI::Fold::Util qw(ansi_width);
my $xform = Text::VisualPrintf::Transform
->new(length => \&ansi_width,
match => qr/[^\t\n]+/);
while (<>) {
print $xform->decode(expand($xform->encode($_)));
}
Giving many arguments to decode is not a good idea, because replacement cycle is performed against all items. So mix up the result into single string if possible.
print $xform->decode(join '', @expanded);
METHODS
- new
-
Create transform object. Takes following parameters.
- length => function
-
Function to calculate text width. Default is
length
. - match => regex
-
Specify text area to be replaced. Default is
qr/.+/s
. - test => regex or sub
-
Specify regex or subroutine to test if the argument is to be processed or not. Default is undef, so all arguments will be subject to replace.
- except => string
-
Transformation is done by replacing text with different string which can not be found in all arguments. This parameter gives additional string which also to be taken care of.
- encode
- decode
-
Encode/Decode arguments and return them. Given arguments will be altered.
LIMITATION
All arguments given to encode method have to appear in the same order in to-be-decoded string. Each argument can be shorter than the original, or it can even disappear.
If an argument is trimmed down into single byte in a result, and it have to be recovered to wide character, it is replaced by single space.
Replacement string is made of characters those can not be found in all arguments. So if they contains all characters from "\001"
to "\377"
, encode method does nothing. It requires at least two.
Minimum two characters is good enough to produce correct result if all arguments will appear in the same order. However, if even single argument is missing, it wor'n work correctly. Less characters, more confusion.
SEE ALSO
- Text::VisualPrintf, https://github.com/kaz-utashiro/Text-VisualPrintf
-
This module is originally implemented as a part of Text::VisualPrintf module.
AUTHOR
Kazumasa Utashiro
LICENSE
Copyright 2020 Kazumasa Utashiro.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.