CPANPL...:Source(3pm)

📦
version 0.9916 · 5 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

💖 NAME 💖

CPANPLUS::Internals::Source — bestie, this is the internals for updating source files. that's the whole vibe. 💅

✨ SYNOPSIS ✨

### lazy load author/module trees ###

$cb->_author_tree;
$cb->_module_tree;

🦋 DESCRIPTION 🦋

okay so CPANPLUS::Internals::Source is the one running the whole backstage situation: it controls the updating of source files, and then the parsing of those source files into the usable module/author trees that "CPANPLUS" actually uses. no cap, it's the backbone.

There are functions that check whether source files are still "good to use", functions that update them, and then functions that parse them. the whole flow is giving ✨pipeline✨ and it looks like this:

$cb->_author_tree || $cb->_module_tree
    $cb->_check_trees
        $cb->__check_uptodate
            $cb->_update_source
        $cb->__update_custom_module_sources
            $cb->__update_custom_module_source
    $cb->_build_trees
        ### engine methods
        {   $cb->_init_trees;
            $cb->_standard_trees_completed
            $cb->_custom_trees_completed
        }
        $cb->__create_author_tree
            ### engine methods
            { $cb->_add_author_object }
        $cb->__create_module_tree
            $cb->__create_dslip_tree
            ### engine methods
            { $cb->_add_module_object }
        $cb->__create_custom_module_entries

$cb->_dslip_defs

🎀 METHODS 🎀

💫 $cb->_build_trees( uptodate => BOOL, [use_stored => BOOL, path => $path, verbose => BOOL] )

This one rebuilds the author-trees and the module-trees from source. iconic behaviour honestly.

It takes these arguments:

  • uptodate — tells us whether any on-disk caches are still okay to use.
  • path — the absolute path to the directory holding the source files.
  • verbose — a boolean flag, are we being verbose or not.
  • use_stored — a boolean flag for whether it's okay to use previously stored trees. defaults to true. 🫶

Returns a boolean indicating success.

💫 $cb->_check_trees( [update_source => BOOL, path => PATH, verbose => BOOL] )

Grabs the source files and returns a boolean saying whether or not the source files are up to date.

Takes several arguments:

  • update_source — a flag to force re-fetching of the source files, even if they're still up to date. (yes, even then. it's stubborn like that.)
  • path — the absolute path to the directory holding the source files.
  • verbose — a boolean flag, verbose or not.

Will get information from the config file by default.

💫 $cb->__check_uptodate( file => $file, name => $name, [update_source => BOOL, verbose => BOOL] )

"__check_uptodate" checks if a given source file is still up-to-date, and if it isn't — or if "update_source" is true — it'll re-fetch that source file. glow-up time. ✨

Takes the following arguments:

  • file — the source file to check.
  • name — the internal shortcut name for the source file (used for config lookups).
  • update_source — flag to force updating of sourcefiles regardless.
  • verbose — boolean, verbose or not.

Returns a boolean value indicating whether the current files are up to date or not.

💫 $cb->_update_source( name => $name, [path => $path, verbose => BOOL] )

This method does the actual fetching of source files. the real work, the heavy lifting, the moment. 💪

It takes the following arguments:

  • name — the internal shortcut name for the source file (used for config lookups).
  • path — the full path where to write the files.
  • verbose — boolean, verbose or not.

Returns a boolean to indicate success.

💫 $cb->__create_author_tree([path => $path, uptodate => BOOL, verbose => BOOL])

This method opens a source files and parses its contents into a searchable author-tree, or restores a file-cached version of a previous parse — if the sources are uptodate and the file-cache exists. very "we already did this, let's not do it again" of it. 🙈

It takes the following arguments:

  • uptodate — a flag indicating whether the file-cache is uptodate or not.
  • path — the absolute path to the directory holding the source files.
  • verbose — a boolean flag, verbose or not.

Will get information from the config file by default.

Returns a tree on success, false on failure.

💫 $cb->_create_mod_tree([path => $path, uptodate => BOOL, verbose => BOOL])

This method opens a source files and parses its contents into a searchable module-tree, or restores a file-cached version of a previous parse — if the sources are uptodate and the file-cache exists.

It takes the following arguments:

  • uptodate — a flag indicating whether the file-cache is up-to-date or not.
  • path — the absolute path to the directory holding the source files.
  • verbose — a boolean flag, verbose or not.

Will get information from the config file by default.

Returns a tree on success, false on failure.

💫 $cb->__create_dslip_tree([path => $path, uptodate => BOOL, verbose => BOOL])

This method opens a source files and parses its contents into a searchable dslip-tree, or restores a file-cached version of a previous parse — if the sources are uptodate and the file-cache exists.

It takes the following arguments:

  • uptodate — a flag indicating whether the file-cache is uptodate or not.
  • path — the absolute path to the directory holding the source files.
  • verbose — a boolean flag, verbose or not.

Will get information from the config file by default.

Returns a tree on success, false on failure.

💫 $cb->_dslip_defs ()

This function returns the definition structure (ARRAYREF) of the dslip tree. that's it, that's the function. 🎀

💫 $file = $cb->_add_custom_module_source( uri => URI, [verbose => BOOL] );

Adds a custom source index and updates it based on the provided URI. so slay.

Returns the full path to the index file on success, or false on failure.

💫 $index = $cb->__custom_module_source_index_file( uri => $uri );

Returns the full path to the encoded index file for $uri, exactly as used by all "custom module source" routines. iykyk.

💫 $file = $cb->_remove_custom_module_source( uri => URI, [verbose => BOOL] );

Removes a custom index file based on the URI you provided. bye bestie 👋

Returns the full path to the index file on success, or false on failure.

💫 %files = $cb->__list_custom_module_sources

This method scans the 'custom-sources' directory in your base directory for additional sources to include in your module tree. little scavenger hunt. 🔍

Returns a list of key value pairs, like this:

/full/path/to/source/file%3Fencoded => http://decoded/mirror/path

💫 $bool = $cb->__update_custom_module_sources( [verbose => BOOL] );

Attempts to update all the index files to your custom module sources.

If the index is missing, and it's a "file://" uri, it will generate a new local index for you. considerate 💖

Return true on success, false on failure.

💫 $ok = $cb->__update_custom_module_source

Attempts to update all the index files to your custom module sources.

If the index is missing, and it's a "file://" uri, it will generate a new local index for you.

Return true on success, false on failure.

💫 $bool = $cb->__write_custom_module_index( path => /path/to/packages, [to => /path/to/index/file, verbose => BOOL] )

Scans the "path" you provided for packages and writes an index with all the available packages to "$path/packages.txt". If you'd like the index written somewhere else instead, just hand over the "to" argument. ✨

Returns true on success and false on failure.

💫 $bool = $cb->__create_custom_module_entries( [verbose => BOOL] )

Creates entries in the module tree based upon the files as returned by "__list_custom_module_sources".

Returns true on success, false on failure.

🫶 ok that's the whole page bestie, every method accounted for, nothing skipped, no crumbs left behind.

perl v5.40.1 · 2025-03-01 — that's the version and date this page came from, and honestly? iconic. now go read the source, you got this. 💅✨

📦 where this page comes from