#!/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 (<FILE>) {
    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 d
+elimited
#    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 existi
+ng
 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) fil
+e.

 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 le
+vel of the value
passed on the command line. Default value is off (debug == 0). A setti
+ng 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 commen
+t 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 speci
+fied 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 tha
+t 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 r
+isk 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 de
+limited
    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
[download]