NAME

Ecosystem::Cache - maintain a local cache of an ecosystem

SYNOPSIS

use Ecosystem::Cache;

my $ec = Ecosystem::Cache.new;  # defaults to REA

$ec.update;  # make sure all distributions are up-to-date

DESCRIPTION

The Ecosystem::Cache distribution provides the logic to maintain a local cache of the most recent distributions in a Raku ecosystem.

Its use is mainly intended to serve as an area in which searches can be performed, such as with App::Rak.

SCRIPTS

$ update-ecosystem-cache

The update-ecosystem-cache script will update the REA cache and output any statistics when appropriate.

MAIN METHODS

new

use Ecosystem::Cache;

my $ec = Ecosystem::Cache.new(:update);  # defaults to REA

The new method instantiates the Ecosystem::Cache object, and optionally refreshes the information about the ecosystem (instead of using the information already cached by zef). It takes the following named arguments:

:ecosystem

Optional. The Ecosystem object for which to set up / update a cache. Defaults to whatever ecosystem in instantiated with Ecosystem.new (which is currently the "rea" ecosystem).

After instantion, the Ecosystem object used can be obtained by the ecosystem method.

:cache

Optional. An IO::Path indicating the directory where distribution files should be stored. From there, a directory will be added with the ecosystem name.

Defaults to what is either specified by:

the RAKU_ECOSYSTEM_CACHE environment variable
the subdirectory .ecosystem/cache in $*HOME
the subdirectory .ecosystem/cache in $*TMPDIR

In the most common case, this will default to ~/.ecosystem/cache.

After instantion, the IO::Path used can be obtained by the cache method.

:update

Optional. If specified with a true value, will call the .update method on the underlying Ecosystem object, causing the meta list of the ecosystem to be fetched from the Internet (rather than using the meta list cached by zef).

update

$ec.update(my @new, my @gone, my %erred);
say "Added @new.elems(), removed @gone.elems(), failed %erred.elems()";

The update method updates the cache with the latest distributions of that ecosystem. If this is the first call to this method for a given cache, it may take quite some time before it is done (at the moment of this writing more than 2200 distributions, totalling to 1.1 GB will be downloaded and handled then). Any calls later will only update new distributions and remove any distributions that are no longer the latest.

The update method takes 3 optional positional arguments:

an array for storing the identities that were added
an array for storing the identities that were removed
a hash for storing the identities that had a failure message, keyed to the identity

HELPER METHODS

name

say $ec.name;

Returns the name of the ecosystem to which this cache applies.

archive-URL

say $ec.archive-URL($identity);

Returns the URL for downloading the distribution of the given identity.

cache

say $ec.cache;             # root dir of cache info

say $ec.cache($identity);  # dir of given identity

Returns the IO::Path object for the directory of the given identity in the cache, or the IO::Path object for the root directory of the cache if no identity was given.

provides

say $ec.provides;             # IO of paths to files that are provided

.say for $ec.provides.lines;  # list all provided files

Returns an IO::Path object for the file that contains all of the absolute paths of the files that occurred in the "provides" section of the META information of all the distributions.

tests

say $ec.tests;             # IO of paths to test-files

.say for $ec.tests.lines;  # list all provided test-files

Returns an IO::Path object for the file that contains all of the absolute paths of the test-files (as defined by either having the ".t" or ".rakutest extension, inside of a "t" or "xt" directory).

scripts

say $ec.scripts;             # IO of paths to scripts

.say for $ec.scripts.lines;  # list all provided scripts

Returns an IO::Path object for the file that contains all of the absolute paths of the scripts (files inside a "bin" directory).

code

say $ec.code;             # IO of paths to files with Raku code

.say for $ec.code.lines;  # list all provided files with Raku code

Returns an IO::Path object for the file that contains all of the absolute paths of the files that contain Raku code (the summation of the files in provides, tests and scripts).

doc

say $ec.doc;             # IO of paths to files with documentation

.say for $ec.doc.lines;  # list all provided files with documentation

Returns an IO::Path object for the file that contains all of the absolute paths of the files that contain documentation.

update-identity

say $ec.update-identity($identity);

Updates the given identity in the cache. Returns either:

True if identity was not yet in the cache, and successfully fetched
Nil if identity was already in the cache
Str error message if fetching identity failed

AUTHOR

Elizabeth Mattijsen liz@raku.rocks

Source can be located at: https://github.com/lizmat/Ecosystem-Cache . Comments and Pull Requests are welcome.

If you like this module, or what I'm doing more generally, committing to a small sponsorship would mean a great deal to me!

COPYRIGHT AND LICENSE

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