NAME
CPAN::PackageDetails - Create or read 02packages.details.txt.gz
SYNOPSIS
use
CPAN::PackageDetails;
# read an existing file #####################
my
$package_details
= CPAN::PackageDetails->
read
(
$filename
);
my
$count
=
$package_details
->count;
my
$records
=
$package_details
->entries->get_hash;
foreach
my
$record
(
@$records
)
{
# See CPAN::PackageDetails::Entry too
# print join "\t", map { $record->$_() } ('package name', 'version', 'path')
join
"\t"
,
map
{
$record
->
$_
() }
$package_details
->columns_as_list;
}
# not yet implemented, but would be really, really cool eh?
my
$records
=
$package_details
->entries(
logic
=>
'OR'
,
# but that could be AND, which is the default
package
=>
qr/^Test::/
,
# or a string
author
=>
'OVID'
,
# case insenstive
path
=>
qr/foo/
,
);
# create a new file #####################
my
$package_details
= CPAN::PackageDetails->new(
file
=>
"02packages.details.txt"
,
description
=>
"Package names for my private CPAN"
,
columns
=>
"package name, version, path"
,
intended_for
=>
"My private CPAN"
,
written_by
=>
"$0 using CPAN::PackageDetails $CPAN::PackageDetails::VERSION"
,
last_updated
=> CPAN::PackageDetails->format_date,
allow_packages_only_once
=> 1,
disallow_alpha_versions
=> 1,
);
$package_details
->add_entry(
package_name
=>
$package
,
version
=>
$package
->VERSION;
path
=>
$path
,
);
"About to write "
,
$package_details
->count,
" entries\n"
;
$package_details
->write_file(
$file
);
# OR ...
$package_details
->write_fh( \
*STDOUT
)
DESCRIPTION
CPAN uses an index file, 02packages.details.txt.gz, to map package names to distribution files. Using this module, you can get a data structure of that file, or create your own.
There are two parts to the 02packages.details.txt.gz: a header and the index. This module uses a top-level CPAN::PackageDetails
object to control everything and comprise an CPAN::PackageDetails::Header
and CPAN::PackageDetails::Entries
object. The CPAN::PackageDetails::Entries
object is a collection of CPAN::PackageDetails::Entry
objects.
For the most common uses, you don't need to worry about the insides of what class is doing what. You'll call most of the methods on the top-level CPAN::PackageDetails
object and it will make sure that it gets to the right place.
Methods
These methods are in the top-level object, and there are more methods for this class in the sections that cover the Header, Entries, and Entry objects.
- new
-
Create a new 02packages.details.txt.gz file. The
default_headers
method shows you which values you can pass tonew
. For instance:my
$package_details
= CPAN::PackageDetails->new(
url
=>
$url
,
columns
=>
'author, package name, version, path'
,
)
If you specify the
allow_packages_only_once
option with a true value and you try to add that package twice, the object will die. Seeadd_entry
inCPAN::PackageDetails::Entries
.If you specify the
disallow_alpha_versions
option with a true value and you try to add that package twice, the object will die. Seeadd_entry
inCPAN::PackageDetails::Entries
. - init
-
Sets up the object.
new
calls this automatically for you. - default_headers
-
Returns the hash of header fields and their default values:
file
"02packages.details.txt"
description
"Package names for my private CPAN"
columns
"package name, version, path"
intended_for
"My private CPAN"
written_by
"$0 using CPAN::PackageDetails $CPAN::PackageDetails::VERSION"
last_updated format_date()
In the header, these fields show up with the underscores turned into hyphens, and the letters at the beginning or after a hyphen are uppercase.
- read( FILE )
-
Read an existing 02packages.details.txt.gz file.
While parsing, it modifies the field names to map them to Perly identifiers. The field is lowercased, and then hyphens become underscores. For instance:
Written-By ---> written_by
- source_file
-
Returns the original file path for objects created through the
read
method. - write_file( OUTPUT_FILE )
-
Formats the object as a string and writes it to a temporary file and gzips the output. When everything is complete, it renames the temporary file to its final name.
write_file
carps and returns nothing if you pass it no arguments, if it cannot open OUTPUT_FILE for writing, or if it cannot rename the file. - write_fh( FILEHANDLE )
-
Formats the object as a string and writes it to FILEHANDLE
- check_file( FILE, CPAN_PATH )
-
This method takes an existing 02packages.details.txt.gz named in FILE and the the CPAN root at CPAN_PATH (to append to the relative paths in the index), then checks the file for several things:
1. That there are entries in the file
2. The number of entries matches those declared in the Line-Count header
3. All paths listed in the file exist under CPAN_PATH
4. All distributions under CPAN_PATH have an entry (not counting older versions)
If any of these checks fail,
check_file
croaks with a hash reference with these keys:# present in every error object
filename the FILE you passed in
cpan_path the CPAN_PATH you passed in
cwd the current working directory
error_count
# if FILE is missing
missing_file
exists
and true
if
FILE doesn't exist
# if the entry count in the file is wrong
# that is, the actual line count and header disagree
entry_count_mismatch true
line_count the line count declared in the header
entry_count the actual count
# if some distros in CPAN_HOME are missing in FILE
missing_in_file anonymous array of missing paths
# if some entries in FILE are missing the file in CPAN_HOME
missing_in_repo anonymous array of missing paths
- check_for_missing_dists_in_repo( CPAN_PATH )
-
Given an object and a CPAN_PATH, return an anonymous array of the distributions in the object that are not in CPAN_PATH. That is, complain when the object has extra distributions.
check_file
calls this for you and adds the result to its error output. - check_for_missing_dists_in_file( CPAN_PATH )
-
Given an object and a CPAN_PATH, return an anonymous array of the distributions in CPAN_PATH that do not show up in the object. That is, complain when the object doesn't have all the dists.
check_file
calls this for you and adds the result to its error output.
Methods in CPAN::PackageDetails
- header_class
-
Returns the class that
CPAN::PackageDetails
uses to create the header object. - header
-
Returns the header object.
Methods in CPAN::PackageDetails::Header
Entries
Entries are the collection of the items describing the package details. It comprises all of the Entry object.
Methods is CPAN::PackageDetails
- entries_class
-
Returns the class to use for the Entries object.
To use a different Entries class, tell
new
which class you want to use by passing theentries_class
option:CPAN::PackageDetails->new(
...,
entries_class
=>
$class
,
);
Note that you are responsible for loading the right class yourself.
- count
-
Returns the number of entries.
This dispatches to the
count
in CPAN::PackageDetails::Entries. These are the same:$package_details
->count;
$package_details
->entries->count;
- entries
-
Returns the entries object.
- entry_class
-
Returns the class to use for each Entry object.
To use a different Entry class, tell
new
which class you want to use by passing theentry_class
option:CPAN::PackageDetails->new(
...,
entry_class
=>
$class
,
)
Note that you are responsible for loading the right class yourself.
TO DO
SEE ALSO
SOURCE AVAILABILITY
This source is in Github:
AUTHOR
brian d foy, <bdfoy@cpan.org>
COPYRIGHT AND LICENSE
Copyright © 2009-2018, brian d foy <bdfoy@cpan.org>. All rights reserved.
You may redistribute this under the terms of the Artistic License 2.0.