MyProject's Libraries

Description manuals and libraries
MyProject's Libraries > Perl Modules > CPAN-Mini-ProjectDocs
Source

NAME ^

CPAN::Mini::ProjectDocs - Generates nice module documentation from you CPAN mini

SYNOPSIS ^

see the mcd command for a full example.

DESCRIPTION ^

This module and associated script mcd let you display a nice looking documentation for the modules in you CPAN mini. The script also allows you to search for modules in you Cpan Mini.

DOCUMENTATION ^

You most probably want to run the mcd script, use the --help option for help.

SUBROUTINES/METHODS ^

get_mcd_paths($cpan_mini, $mcd_cache)

[Source]


sub get_mcd_paths
{

=head2 get_mcd_paths($cpan_mini, $mcd_cache)

Given a CPAN mini location and a cache location, computes a list containing the paths used by CPAN::Mini::ProjectDocs.

I

=over 2 

=item $cpan_mini - Location of the CPAN::MINI repository

=item $mcd_cache - Location of the cache maintained by CPAN::Mini::ProjectDocs

=back

I - A list containing the paths used by CPAN::Mini::ProjectDocs

I - None

=cut

my ($cpan_mini, $mcd_cache) = @_ ;

my $modules_details_file = "$cpan_mini/modules/02packages.details.txt.gz" ;
my $modules_details_txt_md5_file = "$mcd_cache/packages.details.md5.txt" ;
my $modules_details_cache_file = "$mcd_cache/packages.details.cache" ;
my $modules_details_cache_all_names = "${modules_details_cache_file}_all_names.txt" ;

return
	(
	$modules_details_file,
	$modules_details_txt_md5_file,
	$modules_details_cache_file,
	$modules_details_cache_all_names
	) ;
} 

Given a CPAN mini location and a cache location, computes a list containing the paths used by CPAN::Mini::ProjectDocs.

Arguments

$cpan_mini - Location of the CPAN::MINI repository
$mcd_cache - Location of the cache maintained by CPAN::Mini::ProjectDocs

Returns - A list containing the paths used by CPAN::Mini::ProjectDocs

Exceptions - None

generate_html($cpan_mini, $mcd_cache, $distribution)

[Source]


sub generate_html
{

=head2 generate_html($cpan_mini, $mcd_cache, $distribution)

Generates the HTML documentation for $distribution. The generation is performed only if the
documentation does not exist in the cache.

I

=over 2 

=item $cpan_mini - Location of the CPAN::MINI repository

=item $mcd_cache - Location of the cache maintained by CPAN::Mini::ProjectDocs

=item $distribution - Location of the distribution containing the module to display

=back

I - $html_documentation_location

I - problems with the distribution extraction, write errors on the file system, ...

=cut

my ($cpan_mini, $mcd_cache, $distribution) = @_ ;

my ($module_directory) = $distribution =~ /([^\/]+)\.tar.gz$/ ;
my $html_directory = "$mcd_cache/generated_html/$module_directory" ;
my $html_directory_md5 = "$html_directory/md5.txt" ;

my $regenerate_html = 0 ;

my ($modules_details_file) = get_mcd_paths($cpan_mini, $mcd_cache) ;
my $modules_details_txt_md5 = get_file_MD5($modules_details_file) ;

#check if the html was already generated
if(-e $html_directory)
	{
	eval
		{
		my  $mcd_cache_md5 = read_file($html_directory_md5) ;
		$regenerate_html++ if $mcd_cache_md5 ne $modules_details_txt_md5 ;
		} ;
		
	$regenerate_html++ if  $@ ; # file not found
	}
else
	{
	$regenerate_html++ ;
	}
	
if($regenerate_html)
	{
	my $tar = Archive::Tar->new($distribution) ;
	$tar->setcwd($mcd_cache);
	$tar->extract() ;
	
	mkdir "$mcd_cache/generated_html/" ;
	mkdir $html_directory ;
	
	Pod::ProjectDocs->new
		(
		outroot => $html_directory,
		libroot => -e "$mcd_cache/$module_directory/lib" ? "$mcd_cache/$module_directory/lib" : "$mcd_cache/$module_directory",
		title   => 'mcd generated documentation',
		)->gen() ;
	
	write_file($html_directory_md5, $modules_details_txt_md5) ;
	}
	
my $html_documentation_location = "$mcd_cache/generated_html/$module_directory/index.html" ;
return $html_documentation_location;
}

Generates the HTML documentation for $distribution. The generation is performed only if the documentation does not exist in the cache.

Arguments

$cpan_mini - Location of the CPAN::MINI repository
$mcd_cache - Location of the cache maintained by CPAN::Mini::ProjectDocs
$distribution - Location of the distribution containing the module to display

Returns - $html_documentation_location

Exceptions - problems with the distribution extraction, write errors on the file system, ...

get_module_distribution($cpan_mini, $mcd_cache, $module)

[Source]


sub get_module_distribution
{

=head2 get_module_distribution($cpan_mini, $mcd_cache, $module)

Finds the distribution containing the module.

  my $distribution = get_module_distribution($cpan_mini, $mcd_cache, $module) ;

I

=over 2 

=item $cpan_mini - Location of the CPAN::MINI repository

=item $mcd_cache - Location of the cache maintained by CPAN::Mini::ProjectDocs

=item $module - Name of the module to display

=back

I - The location of the distribution containing the module to display

I - read error if the cache is not already generated

=cut

my ($cpan_mini, $mcd_cache, $module) = @_ ;

my (undef, undef, $modules_details_cache_file) = get_mcd_paths($cpan_mini, $mcd_cache) ;
my $first_letter = substr($module, 0, 1) ;
my $cache_file = "${modules_details_cache_file}_$first_letter.txt" ;

my $module_details  = do $cache_file or carp "Error: Invalid '$cache_file'\n" ;;

my $distribution ;

for my $record ( @{$module_details->{entries}{entries}})
	{
	if($record->{'package name'} eq $module)
		{
		$distribution = "$cpan_mini/authors/id/$record->{'path'}" ;
		last ;
		}
	}

return $distribution ;
}

Finds the distribution containing the module.

  my $distribution = get_module_distribution($cpan_mini, $mcd_cache, $module) ;

Arguments

$cpan_mini - Location of the CPAN::MINI repository
$mcd_cache - Location of the cache maintained by CPAN::Mini::ProjectDocs
$module - Name of the module to display

Returns - The location of the distribution containing the module to display

Exceptions - read error if the cache is not already generated

generate_cache($cpan_mini, $mcd_cache)

[Source]


sub generate_cache
{

=head2 generate_cache($cpan_mini, $mcd_cache)

Checks the state of the B cache and regenerates it if necessary.

I

=over 2 

=item $cpan_mini - Location of the CPAN::MINI repository

=item $mcd_cache - Location of the cache maintained by CPAN::Mini::ProjectDocs

=back

I - Nothing

I - None

=cut

my ($cpan_mini, $mcd_cache) = @_ ;

my ($modules_details_file, $modules_details_txt_md5_file, $modules_details_cache_file) = get_mcd_paths($cpan_mini, $mcd_cache) ;
my $modules_details_txt_md5 = get_file_MD5($modules_details_file) ;

if(-e $modules_details_txt_md5_file)
	{
	my  $mcd_cache_md5 = read_file($modules_details_txt_md5_file) ;
	
	if($mcd_cache_md5 ne $modules_details_txt_md5)
		{
		regenerate_cache($cpan_mini, $mcd_cache) ;
		}
	}
else
	{
	regenerate_cache($cpan_mini, $mcd_cache) ;
	}

return ;
}

Checks the state of the CPAN::Mini::ProjectDocs cache and regenerates it if necessary.

Arguments

$cpan_mini - Location of the CPAN::MINI repository
$mcd_cache - Location of the cache maintained by CPAN::Mini::ProjectDocs

Returns - Nothing

Exceptions - None

regenerate_cache($cpan_mini, $mcd_cache)

[Source]


sub regenerate_cache
{

=head2 regenerate_cache($cpan_mini, $mcd_cache)

Generates the B cache.

I

=over 2 

=item $cpan_mini - Location of the CPAN::MINI repository

=item $mcd_cache - Location of the cache maintained by CPAN::Mini::ProjectDocs

=back

I - Nothing

I - File sytem related errors if any

=cut

my ($cpan_mini, $mcd_cache) = @_ ;

warn "Generating cache.\n" ;

my ($modules_details_file, $modules_details_txt_md5_file, $modules_details_cache_file, $modules_details_cache_all_names) 
	= get_mcd_paths($cpan_mini, $mcd_cache) ;
	
my $modules_details_txt_md5 = get_file_MD5($modules_details_file) ;

my $module_details = CPAN::PackageDetails->read( $modules_details_file );

my $count = $module_details->count;
warn "$count records found.\n" ;

my $entries_lookup = {} ;
my @modules ;

my $entries  = $module_details->{entries};
my $records  = $entries->{entries};
for my $record ( @{$records})
	{
	push @modules, $record->{'package name'} ;
	
	my $first_letter = substr($record->{'package name'}, 0, 1) ;
	push @{$entries_lookup->{$first_letter}}, $record ;
	}

#----------------------------------

local $Data::Dumper::Purity = 1 ;
local $Data::Dumper::Indent = 0 ;

for(keys %{$entries_lookup})
	{
	$module_details->{entries}{entries} = $entries_lookup->{$_} ;
	write_file "${modules_details_cache_file}_$_.txt", Dumper($module_details) , "\n\$VAR1 ;\n" ;
	}

write_file $modules_details_cache_all_names, Dumper(\@modules), "\n\$VAR1 ;\n"  ;
write_file($modules_details_txt_md5_file, $modules_details_txt_md5) ;

return ;
}

Generates the CPAN::Mini::ProjectDocs cache.

Arguments

$cpan_mini - Location of the CPAN::MINI repository
$mcd_cache - Location of the cache maintained by CPAN::Mini::ProjectDocs

Returns - Nothing

Exceptions - File sytem related errors if any

search_modules($cpan_mini, $mcd_cache, $module)

[Source]


sub search_modules
{

=head2 search_modules($cpan_mini, $mcd_cache, $module)

Matches I<$module> to all the modules in the CPAN mini repository and displays the match results.

I

=over 2 

=item $cpan_mini - Location of the CPAN::MINI repository

=item $mcd_cache - Location of the cache maintained by CPAN::Mini::ProjectDocs

=item $module - Name of the module to match

=back

I - Nothing

I

=cut

my ($cpan_mini, $mcd_cache, $module) = @_ ;

my ($modules_details_file, $modules_details_txt_md5_file, $modules_details_cache_file, $modules_details_cache_all_names) 
	= get_mcd_paths($cpan_mini, $mcd_cache) ;

my $modules = do $modules_details_cache_all_names or carp "Error: Invalid '$modules_details_cache_all_names'!\n";

for (@{$modules})
	{
	print "$_\n" if(/$module/i) ;
	}

#~ use Text::Soundex ;
#~ my $soundex =  soundex($module) ;

#~ for(@{$module_details->{entries}{entries}})
	#~ {
	#~ my $possible_package_soundex =  soundex($_->{'package name'}) ;
	
	#~ print "\t$_->{'package name'}\n" if $soundex eq $possible_package_soundex ;
	#~ }
	
return ;	
}

Matches $module to all the modules in the CPAN mini repository and displays the match results.

Arguments

$cpan_mini - Location of the CPAN::MINI repository
$mcd_cache - Location of the cache maintained by CPAN::Mini::ProjectDocs
$module - Name of the module to match

Returns - Nothing

Exceptions

get_file_MD5($file)

[Source]


sub get_file_MD5
{

=head2 get_file_MD5($file)

Returns the MD5 of the I<$file> argument.

I

=over 2 

=item $file - The location of the file to compute an MD5 for

=back

I - A string containing the file md5

I - fails if the file can't be open

=cut

my ($file) = @_ ;
open(FILE, $file) or croak "Can't open '$file': $!";
binmode(FILE);
return Digest::MD5->new->addfile(*FILE)->hexdigest ;
}

Returns the MD5 of the $file argument.

Arguments

$file - The location of the file to compute an MD5 for

Returns - A string containing the file md5

Exceptions - fails if the file can't be open

BUGS AND LIMITATIONS ^

None so far.

AUTHOR ^

	Nadim ibn hamouda el Khemir
	CPAN ID: NH
	mailto: nadim@cpan.org

LICENSE AND COPYRIGHT ^

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

SUPPORT ^

You can find documentation for this module with the perldoc command.

    perldoc CPAN::Mini::ProjectDocs

You can also look for information at:

* AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/CPAN-Mini-ProjectDocs

* RT: CPAN's request tracker

Please report any bugs or feature requests to L <bug-cpan-mini-projectdocs@rt.cpan.org>.

We will be notified, and then you'll automatically be notified of progress on your bug as we make changes.

* Search CPAN

http://search.cpan.org/dist/CPAN-Mini-ProjectDocs

SEE ALSO ^

CPAN::Mini::Webserver