nomdoc

#!/usr/bin/env perl
#
# Copyright (C) 2017  Christian Garbs <mitch@cgarbs.de>
# Licensed under GNU GPL v3 or later.
#
# This file is part of nomd.
#
# nomd is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# nomd is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with nomd.  If not, see <http://www.gnu.org/licenses/>.
#

use strict;
use warnings;
use v5.10;

use List::Util qw(max);
use Getopt::Long;

#################################

sub scanfile($)
{
    my ($file) = @_;
    my @docs;
    
    open SCAN, '<', $file or die "can't open `$file': $!";

    my $current = {};
    
    while (my $line = <SCAN>) {
	if ($line =~ /^([a-z][a-z_]+)\(\)/) {
	    push @docs, $current if exists $current->{DESC};
	    $current = { NAME => $1, PARAMS => [] };
	}
	elsif ($line =~ /^##([A-Z]{8})\s+(.*)$/) {
	    my ($key, $data) = ($1, $2);
	    if ($key eq 'CHECKDSC' or $key eq 'NOTYDESC') {
		if (exists $current->{DESC}) {
		    $current->{DESC} .= "\n";
		} else {
		    $current->{DESC} = '';
		}    
		$current->{DESC} .= $data;
	    }
	    elsif ($key eq 'PARMNAME') {
		push @{$current->{PARAMS}}, { NAME => $data };
	    }
	    elsif ($key eq 'PARMDESC') {
		push @{$current->{PARAMS}->[-1]->{DESC}}, $data;
	    }
	    elsif ($key eq 'PARMDFLT') {
		$current->{PARAMS}->[-1]->{DEFAULT} = $data;
	    }
	}
    }
    push @docs, $current if exists $current->{DESC};
    
    close SCAN or die "can't close `$file': $!";

    return @docs;
}

sub print_short($$)
{
    my ($longest_cmd, $doc) = @_;

    my $cmd = $doc->{NAME};

    my $tagline = $doc->{DESC} // '/no description/';
    chomp $tagline;
    $tagline =~ s/\n.*/[…]/s;

    printf "%-${longest_cmd}s  %s\n", $cmd, $tagline;
}

sub print_long($)
{
    my ($doc) = @_;

    printf "\n==== %s\n\n", $doc->{NAME};

    printf "%s\n", $doc->{DESC} // '/no description/';

    foreach my $param ( @{$doc->{PARAMS}} ) {
	printf "- %s", $param->{NAME};
	printf "  %s", join("\n  ", @{$param->{DESC}}) if (exists $param->{DESC});
	printf "\n";
	printf "  default: %s\n", $param->{DEFAULT} if exists $param->{DEFAULT};
    }
}

#################################

my $help;

GetOptions('help' => \$help);

if ($help) {
    print <<'EOF'
usage:  nomdoc [--help | <regexp>]

Call without parameters to list overview of all available commands.
Call with parameter to list details about all commands matching the regexp.
EOF
	;
    exit 0;
}

my $regexp = $ARGV[0];

my @files = glob "check/*.check notify/*.notify";

my @docs = sort { $a->{NAME} cmp $b->{NAME} } map { scanfile($_) } @files;

if (defined $regexp && $regexp) {
    print_long($_) foreach grep { $_->{NAME} =~ /$regexp/i } @docs;
}
else {
    my $longest_cmd = max map { length $_->{NAME} } @docs;
    print_short($longest_cmd, $_) foreach @docs;
}