C:>com2pod -h
Usage:
com2pod [options] filespec
Options:
-debug set debug level, default is off
-help brief help message
-man full documentation
-sort ouput sub pod ordered by name, default is by occurance
-version version number
Where:
filespec is a .pl or .pm (or any file containing commented subs) file.
Switches that don't define a value can be done in long or short form.
e.g.:
com2pod --man
com2pod -m
Options:
-debug Display debug information as program is executed. Control is set
by level of the value passed on the command line. Default value
is off (debug == 0). A setting of 1 or greater will dump the
data structure rather than printing the pod.
-help Print a brief help message and exit.
-man Print the manual page (full documentation) and exit.
-sort Without this option, com2pod will generate pod in the order the
comment blocks are parsed. With this option, the blocks will be
ordered by the 'Name' comment. Un-named blocks will float to the
top in 'as found' order. Default order is 'as found' for all
blocks.
-version
Print the version number and exit.
####
#
# Name:
# Description:
# Parameters:
# Returns:
# Notes:
# Usage:
#
####
#!/usr/bin/perl
# com2pod.pl -- Simple minded comment to pod system.
use strict;
use warnings;
use diagnostics;
use Data::Dumper::Simple;
use Getopt::Long;
use Pod::Usage;
our $VERSION = '0.02';
$0 =~ /.*(?:\\|\/)(.*)$/;
my $filename = ( $1 || 'unknown' );
GetOptions(
'debug=i' => \( my $debug = 0 ),
'help|?' => \( my $opt_help ),
'man' => \( my $opt_man ),
'sort' => \( my $opt_sort ),
'version' => \( my $opt_version ),
)
or pod2usage(2);
if ($opt_version) {
print "$filename vrs. $VERSION\n";
exit;
}
pod2usage(1) if $opt_help;
pod2usage( -verbose => 2 ) if $opt_man;
pod2usage("$filename: No file given.") if @ARGV == 0;
pod2usage("$filename: Too many arguments.") if @ARGV > 1;
my @subs;
my $rec = {};
my $flag;
my $tag = '00001';
open( FILE, $ARGV[0] ) or die "Couldn't open $ARGV[0]: $!";
while () {
chomp;
next if /^\#\s*$/;
if (/^\#/) {
if (/^\# (\w+):/) {
$flag = $1;
push( @{ $rec->{$flag} }, $1 ) if /: (.*)/;
}
else {
push( @{ $rec->{$flag} }, $1 ) if $flag and /^\#\s(.*)/;
}
}
else {
$flag = '';
if ( %{$rec} ) {
unless ( exists( $rec->{'Name'} ) ) {
push( @{ $rec->{'Name'} }, 'Unnamed.' . $tag++ );
}
push( @subs, $rec );
$rec = {};
}
}
}
close(FILE);
podify(@subs);
#
# Name: podify
# Description:
# Given a hash with the comment headers parsing, print to STDOUT
# the resulting POD.
# Parameters:
# @subs An array of hashes of arrays where the keys are the colon delimited
# comment headings and the values are the associated parsed lines.
# Returns: None.
# Notes: Sub will dump the data structure if $debug > 0.
# Usage:
# podify(@subs);
#
sub podify {
my (@subs) = @_;
@subs = sort { lc($a->{'Name'}[0]) cmp lc($b->{'Name'}[0]) } @subs
if $opt_sort and @subs > 1;
print "=head1 SUBROUTINES\n";
print "\n";
for (@subs) {
my %data = %{$_};
print "=head2 $data{Name}[0]\n";
print "\n";
for
my $which ( 'Description', 'Parameters', 'Returns', 'Notes', 'Usage' )
{
print " $which\n" unless $which eq 'Description';
for ( @{ $data{$which} } ) {
if (/\S/) {
unless ( $which eq 'Usage' ) {
s/\s*//;
$_ = " $_" unless $which eq 'Description';
}
else {
s/^\s*/ / unless /^\s{4,}/;
}
print "$_\n";
}
}
print "\n";
}
}
}
__END__
=head1 NAME
com2pod - Given a perl file, use com2pod to create the pod for existing
subroutines.
=head1 SYNOPSIS
com2pod [options] filespec
Options:
-debug set debug level, default is off
-help brief help message
-man full documentation
-sort ouput sub pod ordered by name, default is by occurance
-version version number
Where:
filespec is a .pl or .pm (or any file containing commented subs) file.
Switches that don't define a value can be done in long or short form.
e.g.:
com2pod --man
com2pod -m
=head1 OPTIONS
=over 8
=item B<-debug>
Display debug information as program is executed. Control is set by level of the value
passed on the command line. Default value is off (debug == 0). A setting of 1 or
greater will dump the data structure rather than printing the pod.
=item B<-help>
Print a brief help message and exit.
=item B<-man>
Print the manual page (full documentation) and exit.
=item B<-sort>
Without this option, com2pod will generate pod in the order the comment blocks are parsed.
With this option, the blocks will be ordered by the 'Name' comment. Un-named blocks will
float to the top in 'as found' order. Default order is 'as found' for all block.
=item B<-version>
Print the version number and exit.
=back
=head1 DESCRIPTION
com2pod is a simple minded comment to pod system using a loosely specified colon
delimited keyword approach. The typical comment block the program was designed
around looks like:
#
# Name:
# Description:
# Parameters:
# Returns:
# Notes:
# Usage:
#
'Name', 'Description' and 'Usage' are hard coded, the rest are not. Of the keywords
that are hard coded, only 'Name' is in any sense required and even that will fail quietly
if not found. The lack of rigor means among other things that it is no problem to
change or add to the keywords parsed, do so at your own pleasure (or risk for that
matter!)
=head1 SUBROUTINES
=head2 podify
Given a hash with the comment headers parsing, print to STDOUT
the resulting POD.
Parameters
@subs An array of hashes of arrays where the keys are the colon delimited
comment headings and the values are the associated parsed lines.
Returns
None.
Notes
Sub will dump the data structure if $debug > 0.
Usage
podify(@subs);
=head1 AUTHOR
Hugh S. Myers
hsmyers@sdragons.com
=head1 BUGS
Mon Mar 14 09:14:45 2005 Fixed sort to ignore case.
Mon Mar 14 09:19:21 2005 Fixed padding for Usage text.
=head1 TODO
Not yet, just started!
=head1 UPDATES
Sat Mar 12 09:39:04 2005 Initial version.
=cut