scripts: add an script to parse the ABI files

#!/usr/bin/perl

use strict;

use Pod::Usage;

use Getopt::Long;

use File::Find;

use Fcntl ':mode';

my $help;

my $man;

my $debug;

GetOptions(

	"debug|d+" => \$debug,

	'help|?' => \$help,

	man => \$man

) or pod2usage(2);

pod2usage(1) if $help;

pod2usage(-exitstatus => 0, -verbose => 2) if $man;

pod2usage(2) if (scalar @ARGV != 1);

my ($prefix) = @ARGV;

require Data::Dumper if ($debug);

my %data;

#

# Displays an error message, printing file name and line

#

sub parse_error($$$$) {

	my ($file, $ln, $msg, $data) = @_;

	print STDERR "file $file#$ln: $msg at\n\t$data";

}

#

# Parse an ABI file, storing its contents at %data

#

sub parse_abi {

	my $file = $File::Find::name;

	my $mode = (stat($file))[2];

	return if ($mode & S_IFDIR);

	return if ($file =~ m,/README,);

	my $name = $file;

	$name =~ s,.*/,,;

	my $type = $file;

	$type =~ s,.*/(.*)/.*,$1,;

	my $what;

	my $new_what;

	my $tag;

	my $ln;

	print STDERR "Opening $file\n" if ($debug > 1);

	open IN, $file;

	while(<IN>) {

		$ln++;

		if (m/^(\S+):\s*(.*)/i) {

			my $new_tag = lc($1);

			my $content = $2;

			if (!($new_tag =~ m/(what|date|kernelversion|contact|description|users)/)) {

				if ($tag eq "description") {

					$data{$what}->{$tag} .= "\n$content";;

					$data{$what}->{$tag} =~ s/\n+$//;

					next;

				} else {

					parse_error($file, $ln, "tag '$tag' is invalid", $_);

				}

			}

			if ($new_tag =~ m/what/) {

				if ($tag =~ m/what/) {

					$what .= ", " . $content;

				} else {

					$what = $content;

					$new_what = 1;

				}

				$tag = $new_tag;

				next;

			}

			$tag = $new_tag;

			if ($new_what) {

				$new_what = 0;

				$data{$what}->{type} = $type;

				$data{$what}->{file} = $name;

				print STDERR "\twhat: $what\n" if ($debug > 1);

			}

			if (!$what) {

				parse_error($file, $ln, "'What:' should come first:", $_);

				next;

			}

			$data{$what}->{$tag} = $content;

			next;

		}

		# Silently ignore any headers before the database

		next if (!$tag);

		if (m/^\s*(.*)/) {

			$data{$what}->{$tag} .= "\n$1";

			$data{$what}->{$tag} =~ s/\n+$//;

			next;

		}

		# Everything else is error

		parse_error($file, $ln, "Unexpected line:", $_);

	}

	close IN;

}

# Outputs the output on ReST format

sub output_rest {

	foreach my $what (sort keys %data) {

		my $type = $data{$what}->{type};

		my $file = $data{$what}->{file};

		my $w = $what;

		$w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g;

		print "$w\n\n";

		print "- defined on file $file (type: $type)\n\n::\n\n";

		my $desc = $data{$what}->{description};

		$desc =~ s/^\s+//;

		# Remove title markups from the description, as they won't work

		$desc =~ s/\n[\-\*\=\^\~]+\n/\n/g;

		# put everything inside a code block

		$desc =~ s/\n/\n /g;

		if (!($desc =~ /^\s*$/)) {

			print " $desc\n\n";

		} else {

			print " DESCRIPTION MISSING\n\n";

		}

	}

}

#

# Parses all ABI files located at $prefix dir

#

find({wanted =>\&parse_abi, no_chdir => 1}, $prefix);

print STDERR Data::Dumper->Dump([\%data], [qw(*data)]) if ($debug);

#

# Outputs an ReST file with the ABI contents

#

output_rest

__END__

=head1 NAME

abi_book.pl - parse the Linux ABI files and produce a ReST book.

=head1 SYNOPSIS

B<abi_book.pl> [--debug] <ABI_DIR>]

=head1 OPTIONS

=over 8

=item B<--debug>

Put the script in verbose mode, useful for debugging. Can be called multiple

times, to increase verbosity.

=item B<--help>

Prints a brief help message and exits.

=item B<--man>

Prints the manual page and exits.

=back

=head1 DESCRIPTION

Parse the Linux ABI files from ABI DIR (usually located at Documentation/ABI)

and produce a ReST book containing the Linux ABI.

=head1 BUGS

Report bugs to Mauro Carvalho Chehab <mchehab@s-opensource.com>

=head1 COPYRIGHT

Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab@s-opensource.com>.

License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>.

This is free software: you are free to change and redistribute it.

There is NO WARRANTY, to the extent permitted by law.

=cut