view release on metacpan or  search on metacpan

lib/Simple.pm  view on Meta::CPAN

Known keys (and I<$method>) are described a bit later.

I<@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 I<%options> a bit later.

=item Utility Mode

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

If first argument isn't a HASH,
then B<reqeust()> believes that I<%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 I<@uris> is empty then silently succeedes.
In detail description of I<@uris> a bit later.

=item I<%options>

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

=over

=item I<$options{beat}>

(optional, TRUE, I<v0.1.5>/I<v0.1.11>.)
That's the first progress reporting option --
this one is user-friendly.
L</B<_select_callback()>> has detailed description.
B<(bug)>
Default should depend on I<STDERR> being visible in terminal.

=item I<$options{force_file}>

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

=item I<$options{location}>

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

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

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

B<(bug)>
Passively resists setting to value C<0>.

=item I<$options{method}>

=item I<$method>

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

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

=item I<$options{wink}>

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

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

=back

=item I<@uris>

Requirements for I<%source> described in L<B<F::AF>|File::AptFetch/request()>
still apply.
Shortly:
full pathnames,
no schema,
one (local mehtods) or two (remote methods) leading slashes.
B<(bug)>
That's not convinient in any reasonable way.

I<$target> (of underlying B<request()> of B<F::AF>) isn't required.