txt: ## dist_zef-finanalyst-Pod-From-Cache.md
  ```
      # Pod::From::Cache
  
  ```
  
  
  
  ## Table of Contents
  
  [Description](#description)  
  [Caution Caution](#caution-caution)  
  [Synopsis](#synopsis)  
  [Initialisation](#initialisation)  
  [Progress](#progress)  
  [Ignore Files](#ignore-files)  
  [Exceptions](#exceptions)  
  [Examples / testing](#examples--testing)
  
  ---
  
  # Description
  
  This is a replacement for *Pod::To::Cached*, which will be mothballed. The module 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.
  
      # if the sources are within a git repository, then the following have an effect
  
      say $cache.last-edited('doc/Language/intro.rakudoc')
      # returns the date git reports for the file from the log with format C<%cs>.
  
      say $cache.source-last-commit
      # provides the git commit id for the repository
  
  
  ```
  
  # 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 list 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.
  
  # Examples / testing
  
  Examples for use can be seen in the extra tests. Set the `NoDelete` environment variable to prevent the test directories from being deleted for inspection. Make sure to run the xt tests again without the `NoDelete` variable to clean the test directory.
  
  ```
  NoDelete=1 prove6 -I. xt/
  
  ```
  
  ---
  
  Rendered from README at 2024-04-13T16:50:23Z
  