/ 
CPAN-InGit-0.000_001
/ CPAN::InGit::ArchiveTree

NAME

CPAN::InGit::ArchiveTree - An object managing a CPAN file structure in a Git Tree

DESCRIPTION

This object represents a tree of files matching the layout of CPAN. It may be an actual mirror of an upstream CPAN/DarkPAN, or it may be a local curated collection of modules intended to provide pinned versions for an application. Mirrors (meaning *every* package from upstream is listed in the index and fetched on demand) are represented by the subclass MirrorTree which implements the fetching of files from upstream. This class only contains methods to import distributions from other Git branches.

Distributions in authors/id/X/XX/XXXXX should be kept identical to the public CPAN copy. Local changes/patches to those files should be given a new distribution name under authors/id/local. The "provides" list (of modules) of a public CPAN distribution will be kept the same as reported by public CPAN (for security, so that a dist without permission to index a module still can't claim that name) but the "provides" list of a local distribution will always take precedence in the indexing.

ATTRIBUTES

name

A human-readable name for this ArchiveTree instance. Defaults to the branch name, when loaded from a branch.

config

A hashref of configuration stored in the tree, and lazily-loaded.

config_blob

Returns the Blob of the cpan_ingit.conf file, or undef if it doesn't exist.

canonical_url

The URL to be advertised in 02packages.details.txt, when written by this module.

default_import_sources

List of other branch names which the "import_modules" should search.

corelist_perl_version

Version of perl which should be considered when deciding whether a module already exists in the core distribution or whether it should be fetched from CPAN.

package_details

The parsed contents of modules/02package_details.txt:

{
  last_update => # Time::Piece of last-update
  by_module   => { $module_name => [ $mod, $ver, $path ] },
  by_dist     => { $author_path => [ [ $mod, $ver, $path ], ... ] },
}

The by_module and by_dist hashres refer to the same row arrayrefs.

METHODS

load_config

%attrs= $archive_tree->load_config();

Load the configuration of this ArchiveTree from the config file within the git tree. (path /cpan_ingit.json)

write_config

$archive_tree->write_config($config);

Create a new /cpan_ingit.json from the "config" attribute of this ArchiveTree. By default This stages the change (see CPAN::InGit::MutableTree) but does not commit it.

package_details_blob

Returns the Blob of the modules/02packages.details.txt file, or undef if it doesn't exist.

parse_package_details

Parse modules/02packages.details.txt.gz into a structure matching the description in attribute "package_details".

write_package_details

Write modules/02packages.details.txt from the current value of attribute "package_details". This adds it to the pending changes to the tree, but does not commit it.

has_module

$bool= $atree->has_module($mod_name);
$bool= $atree->has_module($mod_name, $version_requirement);

get_module_version

$ver= $atree->get_module_version($mod_name);

get_module_dist

$ver= $atree->get_module_dist($mod_name);

meta_path_for_dist

$author_path= $atree->meta_path_for_dist($author_path);

Return the author path for the .meta file corresponding with the distribution at an author path. This is just a simple replacement of file extension that accounts for some special cases.

import_dist

$archive_tree->import_dist($peer_tree, $author_path, %options);

Fetch an $author_path from another tree, and update the module index to assign ownership of the same modules as this dist had in the other tree. The tree is written, but not committed. This can change ownership of modules to this dist from another dist that claimed them.

get_dist_meta

$prereqs= $archive_tree->get_dist_meta($author_path);

Return the CPAN::Meta for the distribution, or undef if unknown.

import_modules

$snapshot->import_modules(\%module_version_spec);
# {
#   'Example::Module' => '>=0.011',
#   'Some::Module'    => '',   # any version
# }

This method processes a list of module requirements to pull in matching modules and only as many dependencies as are required. It starts by checking whether this branch contains a module that meets the requirements. If not, it checks the mirror branches listed in "import_sources". If this or any "import_source" branch has an "upstream_url", it may pull from remote into that branch.

The intended workflow is that you have one branch tracking www.cpan.org and pulling in packages automatically as needed, and then perhaps a branch where you review the modules before importing them, and maybe a branch where you upload private DarkPAN modules, and then any number of application branches that import from the reviewed branch or the DarkPAN branch. This way you separate the process of building an application's module collection from the process of reviewing public modules.

All changes will be pulled into this MutableTree object, but not committed. If this is the working branch, the index also gets updated.

VERSION

version 0.000_001

AUTHOR

Michael Conrad <mike@nrdvana.net>

COPYRIGHT AND LICENSE

This software is copyright (c) 2025 by Michael Conrad, and IntelliTree Solutions.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.