NAME

File::AptFetch::Simple - convenience wrapper over File::AptFetch

SYNOPSIS

# TODO:

DESCRIPTION

When File::AptFetch was started it was believed that it must be bare-bone simple. Then RL came (refer to v0.0.8 for details). Besides F::AF needed loads of handling on user's side of code. Thus File::AptFetch::Simple was born.

The sole purpose of F::AF::S is to reach unimaginable simplicity to limits of being usable in one-liner (and beyond). To further convinience there's only one method what is also a constructor. That combine has name "request()". Just like in parent class. Only -- it won't return unless all transfers are finished; and it returns object; and it croaks on errors.

Enjoy.

API

request()

Has two modes: constructor and utility. In either case a F::AF::S blessed object is returned. Unless base F::AF object reported any problem, then croaks. However, if that's a condition the parent doesn't care about (as a matter of fact, F::AF doesn't care that much about consistency of messages and such) but it looks terrible (and probably would lead to eventual timeout) such conditions are carped.

Constructor Mode

# complete CM -- cCM
$fafs = File::AptFetch::Simple->request( { %options }, @uris );
# simplified CM -- sCM
$fafs = File::AptFetch::Simple->request( $method, @uris );

%options are some parameters what will be somehow processed upon construction and mostly saved for later use. However, if defaults are ok then only one required parameter (that is $options{method}) can be passed as first scalar. Known keys (and $method) are described a bit later.

@uris is a list of scalars. If empty, then constructor just blows through construction and returns (it doesn't mean it's in vein, the requested method is initialized). In detail description of %options a bit later.

Utility Mode

# complete UM -- cUM
$fafs->request( { %options }, @uris );
# simplified UM -- sUM
$fafs->request( @uris );

If first argument isn't a HASH, then reqeust() believes that %options is omitted. However, there's a quirk. Due implementation idiosyncrasy, if first argument is FALSE it's ignored completely. Consider those are reserved (even if they are not). Are we cool now?

If @uris is empty then silently succeedes. In detail description of @uris a bit later.

%options

Unless explicitly noted: any option used in cCM sets defaults for this instance; any option used in cUM sets for this invocation.

$options{beat}

(optional, TRUE.) That's the first progress reporting option -- this one is user-friendly. (note) It's totally underdeveloped right now -- nothing to document yet. (bug) Default should depend on STDERR being visible in terminal.

$options{location}

(optional, CWD.) Sets dirname where acquired file will be placed.

(caveat) When applied $options{location} will be expanded to be absolute (as required by APT method API). However, that expansion is performed with each request() and, as mentioned above, transparently. Thus if *you* set $options{location} to non-absolute dirname, than request() once, then *your* script changes CWD, then request() again, then those request()s will put results in two different dirctories.

(bug) Neither checks nor makes sure $options{location} is anyway usable.

(bug) Passively resists setting to value 0.

$options{method}

$method

In [cs]CM required, otherwise silently ignored. If there's no such method installed croaks immeidately. file is silengtly replaced with copy; copy is passed through.

(note) You should understand. F::AF::S is a convenience wrapper about F::AF. Second, F::AF interfaces with APT methods what are all Debian. It's reasonable to foresee that URIs will be constructed from those found in /etc/apt/sources.list (and, probably, nothing else). But there's no URI of copy: type, you should do that substitution yourself. Else F::AF::S could do it for you.

$options{wink}

(optional, TRUE.) That's the second progress reporting option -- this one is log-friendly. Overwrites $options{beat}'s output (unless $options{beat} is disabled). Tries to be terminal saving too. (bug) Should actually detect if there's any terminal on STDERR.

@uris

Requirements for %source described in F::AF still apply. Shortly: full pathnames, no schema, one (local mehtods) or two (remote methods) leading slashes. (bug) That's not convinient in any reasonable way.

$target (of underlying request() of F::AF) isn't required. It's constructed from requested URI: current value of $options{location} will be concatenated with a basename of currently processed $uris[]. The separator is slash. (What else, it's *nix, for kernel's sake.) (bug) As a matter of fact there's no way it can be anyhow affected.

Diagnostics (fatal conditions are specially marked) (all errors that come from the parent are fatal by definition, refer for F::AF for details):

{$options{method}} is required

(fatal) (cCM) There's %options HASH in @_. Unfortunately method is FALSE. No way to proceede with this. (caveat) That hopes that there won't be a method named 0. BTW parent will croak on 0 anyway.

either {$method} of {%options} is required

(fatal) ([cs]CM) During construction a method has to be initialized what means it has to be picked up. Invoking code must provide a method's name; It didn't. As a matter of fact @_ is totally empty.

first must be either {$method} of {%options}

(fatal) ([cs]CM) In this case @_ isn't empty, but its leader is neither scalar ({$method}) nor HASH ({%options}). Initialization code has no way to handle this.

got (%s) for (%s) without [request]

([cs]UM) Something wrong. A message came in about $uri (the latter %s) (it has $status (the former %s)). It's surprise, that $uri was never requested. (bug) Should dump the message.

got (%s) without {URI:}

([cs]UM) Something wrong. A message just came in and it has no $uri (it has $status (%s)). It's surprise, I've never seen messages without that identification. (bug) Should dump the damn message.

_read_callback()

This does all required sampling for "_select_callback()". Routine for _read is provided by parent's callback.

_select_callback()

This one does actual beat indicator. Unless forbidden (beat of %opts of "request()") then harmless.

SEE ALSO

File::AptFetch

AUTHOR

Eric Pozharski, <whynot@cpan.org>

COPYRIGHT & LICENSE

Copyright 2014 by Eric Pozharski

This library is free in sense: AS-IS, NO-WARANRTY, HOPE-TO-BE-USEFUL. This library is released under GNU LGPLv3.