docgen

#!/usr/bin/env perl

use warnings;
use strict;

use POSIX qw(strftime);

my $OUTPUT = 'md';

# Global variable to track if we are inside a code block
my $inCodeBlock = 0;

sub formatout {
    if ($OUTPUT eq 'md') {
        formatmd (@_);
    }
    # Note: instead of using this script to output to other formats, use pandoc to convert Markdown to other formats
}

sub formatmd {
    my ($text, $type) = @_;
    $type = 'text' unless $type;
    # Check for code block
    if ($text =~ m/```/) {
        $inCodeBlock = not $inCodeBlock;
        # Always put at column 0
        $text =~ s/^\s*#\s*//;
        print "$text\n";
        return;
    }
    if ($inCodeBlock) {
        # Don't trim all leading space, just the first one (if it exists)
        # since it may be part of the code being rendered
        $text =~ s/^\s*#\s?//;
    }
    else {
        $text =~ s/^\s*#\s*//;
    }
    if ($type eq 'package') {
        print "\n# Package $text\n\n";
    }
    elsif ($type eq 'function') {
        $text =~ s/^\s*function:\s*//;
        print "\n## \`$text\`\n\n";
    }
    elsif ($type eq 'alias') {
        $text =~ s/^\s*alias:\s*//;
        print "\n## \`$text\`\n\n";
    }
    else {
        if ($text =~ m/^\s*\@arguments:/) {
           print "\n**Arguments:**\n\n"; 
        }
        elsif (my ($v) = ($text =~ m/^\s*\@returns:\s*(.*)$/)) {
           print "\n**Returns:** $v\n"; 
        }
        elsif (($v) = ($text =~ m/^\s*\@requires:\s*(.*)$/)) {
           print "\n**Requires:** bash $v or later\n";
        }
        elsif ($text =~ m/^\s*\@notes:/) {
           print "\n**Notes:**\n\n";
        }
        elsif ($text =~ m/^\s*\@example:/) {
           print "\n**Example:**\n\n"; 
        }
        elsif ($text =~ m/^\s*- ([A-Z0-9_=]+):/) {
            $text =~ s/- ([A-Z0-9_=]+):/- `$1`:/;
            print "$text\n";
        }
        else {
            print "$text\n";
        }
    }
}

sub parsepkg {
    my $fn = shift @_;
    open (my $fd, '<', $fn) or return;
    my $start = 0;
    while (my $line = <$fd>) {
        chomp $line;
        unless (substr($line, 0, 1) eq '#') {
            return;
        }
        if ($start) {
            formatout $line;
        }
        elsif (my ($pkg) = ($line =~ m/^# \@package: (.*)/)) {
            $start = 1;
            formatout $pkg, 'package';
        }
    }
    close $fd;
}

sub getfcns {
    my $fn = shift @_;
    open (my $fd, '<', $fn) or return ();
    my @fcns = ();
    while (my $line = <$fd>) {
        chomp $line;
        if (my ($f) = ($line =~ m/^\s*function\s+(.*)\s*\(\s*\)/)) {
            push @fcns, $f unless $f =~ /^_/;
        }
        elsif (($f) = ($line =~ m/^\s*alias\s+(.*)=/)) {
            push @fcns, $f unless $f =~ /^_/;
        }
    }
    close $fd;
    return @fcns;
}

sub parsefcns {
    my ($fn, @fcns) = @_;
    return unless @fcns;
    open (my $fd, '<', $fn) or return;
    my $start = 0;
    while (my $line = <$fd>) {
        chomp $line;
        unless (substr($line, 0, 1) eq '#') {
            $start = 0;
            next;
        }
        if ($start) {
            formatout $line;
        }
        elsif (@fcns == 0) {
            last;
        }
        elsif (my ($type, $f) = ($line =~ m/#\s*(function|alias):\s*(\w+)/)) {
            next unless $fcns[0] =~ $f;
            shift @fcns;
            $start = 1;
            formatout $line, $type;
        }
    }
    close $fd;
}

sub maketitle {
    if ($OUTPUT eq 'md') {
        mdtitle (@_);
    }
}

sub mdtitle {
    my ($version) = @_;
    print "---\n";
    print "title: BASH-BOOST(1)\n";
    print "author: github.com/tomocafe\n";
    my $datestr = strftime "%B %-d, %Y", localtime;
    print "date: $datestr\n";
    print "---\n\n";
}

###
### Main
###

if ($ARGV[0] eq "--title") {
    my $version = "$ARGV[1]";
    maketitle $version;
}

foreach my $fn (sort @ARGV) {
    parsepkg $fn;
    parsefcns ($fn, getfcns $fn);
}