view release on metacpan or  search on metacpan

bin/wax  view on Meta::CPAN

#!/usr/bin/env perl

use strict;
use warnings;

use App::Wax;

exit App::Wax->new->run(\@ARGV);

# FIXME reconcile the need for a) GitHub doc display and b) Pod::Usage
# discoverability by duplicating wax.pod here :-(

__END__

=head1 NAME

wax - webify your CLI

=head1 SYNOPSIS

    wax [OPTIONS] program [OPTIONS] ...

e.g.:

    $ wax vim -R https://registry.npmjs.org/left-pad/-/left-pad-1.2.0.tgz

runs:

    $ vim -R /tmp/wax_abcd1234.tgz

=head1 DESCRIPTION

C<wax> is a command-line program which runs other command-line programs and
converts their URL arguments to local file paths. By default, the files are
removed after the command has exited.

As well as adding transparent support for remote resources to commands that
don't support them natively, wax can be used to:

=over

=item *

add support for HTTPS (and any other protocols supported by L<LWP>) to programs
that only support HTTP

=item *

add a mirroring layer to network requests (remote resources are only fetched if
they've been updated)

=item *

add a caching layer to network requests (remote resources are only fetched
once)

=back

=head1 OPTIONS

The following C<wax> options can be supplied before the command name.
Subsequent options are passed to the command verbatim, apart from URLs, which
are converted to paths to the corresponding files. URL arguments can be
excluded from the conversion process by supplying a separator token (default
C<-->). Arguments after this are no longer processed by C<wax> and are passed
through verbatim, e.g.:

    $ wax --cache cmd https://example.com/foo -- --referrer https://example.com

Note that the C<--cache> and C<--mirror> options are mutually exclusive, i.e.
only one (or neither) should be supplied. Supplying both will cause C<wax> to
terminate with an error.

=head2 -c, --cache

Don't remove the downloaded file(s) after the command exits. Subsequent
invocations will resolve the URL(s) to the cached files(s) (if still available)
rather than hitting the network.

If a local file no longer exists, the resource is re-downloaded.

Note: by default, files are saved to the system's temp directory, which is
typically cleared when the system restarts. To save files to another directory,
use the C<--directory> or C<--default-directory> option.

=head2 -d, --dir, --directory STRING

Specify the directory to download files to. Default: the system's
L<temp directory|https://en.wikipedia.org/wiki/Temporary_folder>.

If the directory doesn't exist, it is created if its parent directory exists.
Otherwise, an error is raised.

=head2 -D, --default-directory

Download files to C<$XDG_CACHE_HOME/wax> or C<$HOME/.cache/wax> rather than the
system's temp directory. Can be overriden by C<--directory>.

If the directory doesn't exist, it is created if its parent directory exists.
Otherwise, an error is raised.

=head2 -h, -?, --help

Display this documentation.

=head2 -m, --mirror

Like the C<--cache> option, this keeps the downloaded file(s) after the command
exits. In addition, a HEAD request is issued for each resource to see if it has
been updated. If so, the latest version is downloaded; otherwise, the cached
version is used (if still available).

If a local file no longer exists, the resource is re-downloaded.

=head2 -s, --separator STRING

Override the default separator-token (C<-->) used to mark the end of waxable
options, e.g.:

    $ wax --cache --separator :: cmd https://example.com/foo :: --referrer https://example.com

Note: the separator token is removed from the list of arguments passed to the
command.

=head2 -S, --no-separator

Disable separator-token handling, i.e. leave the default separator (C<-->) to be
handled by the command.

=head2 -t, --timeout INTEGER

Set the timeout for network requests in seconds. Default: 60.

=head2 -u, --user-agent STRING

Set the user-agent string for network requests.

=head2 -v, --verbose

Print diagnostic information to STDERR.

=head2 -V, --version

Print the version and exit.

=head1 EXAMPLES

=head2 espeak

    $ alias espeak="wax espeak"
    $ espeak -f http://www.setec.org/mel.txt

=head2 grep

    $ wax grep -B1 demons http://www.mplayerhq.hu/DOCS/man/en/mplayer.1.txt

=head2 jsview

Browse files in Node module tarballs

    #!/bin/sh

    # usage: jsview <module> e.g. jsview left-pad
    wax --cache vim -R $(npm info --json "$@" | jq -r .dist.tarball)

=head2 nman

Node.js man-page viewer

    #!/bin/sh