--- name: "CPANPLUS::Internals::Source" section: "3pm" platform: "linux" package: "perl-cpanplus" version: "0.9916-3" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/CPANPLUS::Internals::Source/3pm" --- # CPANPLUS::Internals::Source(3pm) internals for updating source files ## NAME CPANPLUS::Internals::Source - internals for updating source files ## SYNOPSIS ``` ### lazy load author/module trees ### $cb->_author_tree; $cb->_module_tree; ``` ## DESCRIPTION CPANPLUS::Internals::Source controls the updating of source files and the parsing of them into usable module/author trees to be used by `"CPANPLUS"`. Functions exist to check if source files are still `"good to use"` as well as update them, and then parse them. The flow 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 method rebuilds the author- and module-trees from source. It takes the following arguments: - uptodate Indicates whether any on disk caches are still ok to use. - path The absolute path to the directory holding the source files. - verbose A boolean flag indicating whether or not to be verbose. - use\_stored A boolean flag indicating whether or not it is ok to use previously stored trees. Defaults to true. Returns a boolean indicating success. ### $cb-\>\_check\_trees( \[update\_source =\> BOOL, path =\> PATH, verbose =\> BOOL\] ) Retrieve source files and return a boolean indicating 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 are still up to date. - path The absolute path to the directory holding the source files. - verbose A boolean flag indicating whether or not to be verbose. 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 not, or when `"update_source"` is true, will re-fetch the source file. 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 to indicate whether to be 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. 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 to indicate whether to be 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. 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 indicating whether or not to be verbose. 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 indicating whether or not to be verbose. 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 indicating whether or not to be verbose. 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. ### $file = $cb-\>\_add\_custom\_module\_source( uri =\> URI, \[verbose =\> BOOL\] ); Adds a custom source index and updates it based on the provided URI. 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`, as used by all `"custom module source"` routines. ### $file = $cb-\>\_remove\_custom\_module\_source( uri =\> URI, \[verbose =\> BOOL\] ); Removes a custom index file based on the URI provided. 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. Returns a list of key value pairs as follows: ``` /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. 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 to be written to a different file, provide 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.