#!/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 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