view release on metacpan or  search on metacpan

bin/muter  view on Meta::CPAN

#!/usr/bin/env perl
# PODNAME: muter
#
# muter - a data transformation tool
#
# Copyright © 2017 brian m. carlson
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
# THE SOFTWARE.

=encoding UTF-8

=head1 NAME

muter - tool to convert between various formats

=head1 SYNOPSIS

B<muter> [B<-r>] B<-c> I<chain> [I<file>...]

B<muter> [B<--verbose>] B<--help>

=head1 DESCRIPTION

B<muter> is a tool to process data by encoding and decoding it in various
formats.  The series of transforms being used is described by the chain.

Like most Unix command line tools, B<muter> processes the files specified on the
command line, or standard input if no files are specified.  It produces output
to standard output.  Input and output are generally assumed to be a series of
bytes; where character interpretation is required, UTF-8 is used.

A chain is a series of transforms separated by colons.  A reverse transform
(decoding) is specified by preceding the transform with a C<-> character.  If a
transform takes parameters, they are separated by commas and follow the
transform either surrounded by parentheses or preceded by a comma.  Unknown
parameters are ignored.

Not all transforms have an reverse transforms.  For example, the I<hash>
transform, which implements cryptographic hashes, is not practically invertible
(we hope).  An exception will be thrown if you attempt to use an invalid
transform.

Generally, a reverse transform will decode any variant of the forward transform.
To preserve this invariant, related but incompatible transforms such as base64
and url64 are separate transforms.

In general, B<muter> expects the input to its decoders to be well-formed.
Passing broken or corrupt data will not generally produce useful results.  For
example, it isn't a good idea to try to decode URI-encoded data containing
unencoded newlines.  In other words, garbage in, garbage out.

=head1 OPTIONS

=over 4

=item B<-c> I<chain>, B<--chain>=I<chain>

Specify the chain of transforms.  This option is mandatory.

=item B<-r>, B<--reverse>

Reverse the chain of transforms and convert each forward transform to a reverse
transform, and vice versa.  Assuming all transforms can be inverted, running an
instance of B<muter> without this flag followed by an instance with this flag
and with the same chain returns the original data.

It is not valid to specify this flag with transforms that have no inverse.

=item B<--help>

List usage and all known transforms.

=item B<--verbose>

With B<--help>, provide a description for each transform parameter.

=back

=head1 BACKENDS

The following backends are included with muter; additional backends can be used
by creating modules under the C<App::Muter::Backend> namespace in C<@INC>.

=head2 ascii85

Implements the L<Ascii85 encoding|https://en.wikipedia.org/wiki/Ascii85>.

=head2 base16

Equivalent to the C<hex> backend with the C<upper> argument.  Implements the
L<RFC 4648|https://tools.ietf.org/html/rfc4648> Base16 encoding.

=head2 base32

Implements the L<RFC 4648|https://tools.ietf.org/html/rfc4648> Base32 encoding.

Accepts one option, C<manual>, which forces the use of the built-in encoder
instead of L<MIME::Base32>.  This built-in encoder is forced if L<MIME::Base32>
is missing or too old.