Pod::From::Cache

Table of Contents

Description
Caution Caution
Synopsis
Initialisation
Progress
Ignore Files
Exceptions

Description

This is a replacement for Pod::To::Cached, which will be mothballed. It provides only two methods and has far fewer dependencies. It relies only on the CompUnit Modules.

Caution Caution

Pod::From::Cache relies on the Precomp Modules which are designed to provide precompiled code as quickly as possible. Once a cache has been loaded it is difficult to make changes to the cache in the same program. Consequently it is not possible to change a source on file and for the change to be detected in the same program.

Synopsis

    use v6.d;
    use Pod::From::Cache;

    my $cache = Pod::From::Cache.new;
    # used the default values of
    # - :extensions = <rakudoc rakumod pod pod6 p6 pm pm6>
    # - :doc-source = 'docs',
    # - :cache-path = 'rakudoc_cache'

    say "Files changed since the cache was last refreshed";
    say '(None)' unless +$cache.list-files;
    .say for $cache.list-files;

    # Get and use pod in a source
    dd $cache.pod( $cache.sources[0] );

    rm-cache( 'rakudoc_cache' );
    # removes the cache directory using OS dependent methods.

Initialisation

When an instance of Pod::From::Cache is created, it recursively descends the directory starting at :doc-source and extracts all files that match the extensions in the list given by :extensions.

If a Precomp repository exists under the directory given by :cache-path, then any source that is newer than the source in the cache is renewed, and a list of refreshed-pods is collected.

If a repository does not exist, then all files will be added to it.

The list of refreshed files can be obtained as either

• $cache.list-files or

• $cache.refreshed-pods

All of the files found by the recursive descent can be found in $cache.sources.

Once $cache is instantiated, then the pod for a source file can be obtained as

$cache.pod( 'Language/Raku-101.pod' );

Progress

my Pod::From::Cache $p .= new( :progress( &count ) );
# somewhere else
sub count(:$start, :$end) { # show a start, then decrease, or inverse thereof }

Optionally a closure with signature (:start, :end) can be provided that will show progress in some way. This is provided because large Pod6 files take considerable time to process.

• :start is the number of files to be processed.

• :dec is when a file has been processed.

Ignore Files

It is possible to place a file .ignore-cache in the directory specified by :doc-source (by default docs). An ignore list can be provided via :ignore when the object is instantiated.

Each line should be the name of a file (and the path relative to the :doc-source directory) that is to be ignored.

Any file exactly matching a file in .ignore-cache will not be included in the sources added to the cache.

If the .pod method is called with a file matching a name in .ignore-cache, it will return Nil, rather than a pod tree.

Exceptions

The following exceptions are thrown.

• X::Pod::From::Cache::NoPodInCache

  • An attempt has been made to extract pod from a file not in Sources

• X::Pod::From::Cache::NoSources

  • No sources matching extensions were found under doc-sources directory

• X::Pod::From::Cache::BadSource

  • An error was caught when compiling a file. Probably a compile error. The error is given in the Exception message.

Rendered from README at 2022-07-11T22:37:37Z