/ 
File-AptFetch-v0.1.15
River stage zero No dependents
/ File::AptFetch::Simple

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, v0.1.5/v0.1.11.) That's the first progress reporting option -- this one is user-friendly. "_select_callback()" has detailed description. (bug) Default should depend on STDERR being visible in terminal.

$options{force_file}

(optional, FALSE, v0.1.6/v0.1.12.) Disables file: schema special handling ("$options{method}" has more). It's for setting in cCM and is retained forever, in cUM silently ignored. (caveat) (probably bug) Doesn't affect "$options{beat}" and "$options{wink}".

$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. Seealso "$options{force_file}".

$options{wink}

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

Hints for filename and what APT method has said about it. Not much.

@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.

_gain_callback()

This finishes size sampling for "_select_callback()" (if applicable). Also does a significant number of assertions (most probably useless).

_read_callback()

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

get_oscillator()

Service routine for "_select_callback()". It's public (in contrary with) because one day it will accept configuration for oscillator. Returns five bytes that somehow represent transfer went sleep.

_select_callback()

This one does actual beat indicator, unless forbidden (beat of %opts of "request()"). Even if forbidden statistics is collected anyway. Beat looks like this

[24.00K/s] [17.60K/s  4.36M/s  3.13M/s] [ 4.17h  0.99m  1.37m]

(bug) Beats are output completely terminal blind -- no cleanups, no width checks; simple leading \r.

Beats are made with each $tick. The very last beat (before finish wink) is left visisble.

In brackets are:

  • Speed over last tick.

  • SMA of speed calculated over 5sec, 1min, and 5min. As long as a subset haven't been accumulated they won't be shown (however, due timer early initialization 5sec SMA will probably appear instantly). Subsets are package wide -- probably bug (problem is sampling is made in "_read_callback()" what doesn't know about object). Subsets are kept between invocations; what gives, different transports obviously perform differently, transfers over different paths obviously perform differently -- that doesn't mix well. But being an eye candy, well, it could stay this way forever.

    If transfer get stuck then speed is present with an oscillator -- you really don't want to know what it is, you gonna hate it. (note) Now, when transfer speed goes to ground so does SMA (that's what SMA is by design after all); then, if transfer stalls long enough with probability ~50% SMA will hit through 0 and go negative (rounding errors); it was decided to present it with oscillator (that one you already hate). And when it stays positive it will be 0.00b/s. (Those rounding errors are really small -- ~0.5e-8 small.)

    Speeds are based on 1024. Format is %5.2f. With prefixes only -- no unit; unless there should not be any prefix -- then lone b is used. Supported prefixes are: kilo, mega, giga, tera, peta, exa, zetta, and yotta (or kibi, mebi, gibi, tebi, pebi, exbi, zibi, and yebi, to make IEC happy) (hard to imagine speeds like that).

  • SMAs are used to estimate times to finish. Because SMAs are running and run differently so estimations will be different too (it's fun to watch them).

    In some circumstances estimations can get really high or negative (that's an example, there's no way it could be for real):

    [1MEGAy 99.99y  0.00s]

    Those are placeholders and should be ignored (I just can't think a better way to handle those corner cases). (bug) As of negative estimations I can't debug them right now -- ought to do my homework first.

    Estimations are expressed in up to 30sec, 30min, 6hour, or forever (10hour is really forever if you think about it).

(bug) Subset ranges should be configurable.

(bug) Final performance isn't left visible for further eye candy.

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.