NAME

App::Wax - webify your CLI

SYNOPSIS

    use App::Wax;

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

DESCRIPTION

App::Wax is the helper library for wax, a command-line program which runs other command-line programs and converts their URL arguments to local file paths.

See the wax documentation for more details.

ATTRIBUTES

app_name

Type: Str, rw, default: "wax".

The application name used in debug and error messages.

app_version

Type: Str, ro.

The application version displayed in the output of the --version option e.g.:

    $ wax --version # v1.2.3 (App::Wax v3.0.0)

The version is passed as a constructor argument by the command e.g.:

    App::Wax->new({ app_version: 'v1.2.3' })

If not supplied, it defaults to the module version.

cache

Type: Bool, rw, default: false.

If set to true, the remote resource is saved to a persistent file whose path is substituted for the resource's URL on subsequent invocations of the command.

If cache and "mirror" are both set to true, an exception is thrown.

directory

Type: Str, rw, optional.

The directory to download remote resources to. If not supplied, the system's temporary directory is used.

Can be checked with has_directory.

keep

Type: Bool, ro, default: false.

True if "cache" or "mirror" are true, false otherwise. Used to determine which "resolve" method to use.

mime_types

Type: Mime::Types, rw.

An instance of Mime::Types used to help determine an extension for the file.

mirror

Type: Bool, rw, default: false.

If set to true, the remote resource is saved to a persistent file. On subsequent invocations, the resource is re-downloaded if it has been updated, and its path is substituted for the resource's URL.

If "cache" and "mirror" are both set to true, an exception is thrown.

separator

Type: Str, rw, default: "--".

A optional token used to mark the end of wax's options.

Can be cleared with clear_separator and checked with has_separator.

template

Type: Str, rw.

The template format string supplied as the TEMPLATE parameter to File::Temp->new().

timeout

Type: Int, rw, default: 60.

The timeout (in seconds) for HTTP requests.

user_agent

Type: Str, rw.

The value of the HTTP client's User-Agent header.

verbose

Type: Bool, rw, default: false.

If set to true, diagnostic messages are printed to STDERR.

METHODS

content_type

Signature: [ $url: Str, $url_index: Int ] -> $content_type: Str

Returns the value of the HTTP Content-Type header for the supplied URL e.g. text/html.

debug

Signature: $message: Str -> None

Logs the message to STDERR if "verbose" is set to true.

Signature: $template: Str, @args: List[Str] -> None

Interpolates the arguments into the sprintf template and logs the message to STDERR if "verbose" is set to true.

download

Signature: [ $url: Str, $url_index: Int ], $path: Str -> Maybe[Str]

Saves the contents of the URL to the path. Returns the error message if an error ocurred.

dump_command

Signature: $command: ArrayRef[Str] -> Str

Returns a string representation of the supplied command.

extension

Signature: [ $url: Str, $url_index: Int ] -> $extension: Str

Returns the file extension for the given URL (e.g. .html) if one can be determined from the resource's Content-Type header or the path component of the URL if it's text/plain or application/octet-stream. Otherwise, returns an empty string.

is_url

Signature: $param: Str -> $components: ArrayRef[Str] | Undef

Returns a true value (a reference to an array of URL components returned by "uri_split" in URI::Split) if the supplied string is a valid absolute URL, false otherwise.

log

Signature: $level: Str, $message: Str -> None

Logs the message, with the level prefixed, to STDERR.

Signature: $level: Str, $template: Str, @args: List[Str] -> None

Interpolates the arguments into the sprintf template and logs the message, with the level prefixed, to STDERR.

resolve

Signature: [ $url: Str, $url_index: Int ] -> ($path: Str, $error: Maybe[Str]): List|ArrayRef

Takes a URL and returns a list (list context) or ArrayRef (scalar context) containing the file path corresponding to the URL, and an optional error message if the download or I/O failed.

The path is returned by "resolve_keep" if "keep" is true, or "resolve_temp" otherwise.

resolve_keep

Signature: [ $url: Str, $url_index: Int ] -> ($filename: Str, $error: Maybe[Str])

Returns the path the cached or mirrored URL should be saved to/retrieved from and an optional error message if creation of the index file failed.

resolve_keep uses an additional file to store the resource's extension. If this file can't be created, the error message is returned as the second element of the list. Otherwise, it's undef.

resolve_temp

Signature: [ $url: Str, $url_index: Int ] -> ($path: Str, $error: Maybe[Str])

Returns the path of the temporary file the URL should be saved to and an optional error message if creation of the temporary file failed.

run

Signature: $command: ArrayRef[Str] -> $exit_code: Int

Takes a command and runs it with filenames substituted for URLs. Returns the command's exit code.

EXPORT

None by default.

VERSION

3.1.0

SEE ALSO

AUTHOR

chocolateboy <chocolate@cpan.org>

COPYRIGHT AND LICENSE

Copyright (c) 2010-2018 by chocolateboy.

This is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.