mkcmdtable

#!/usr/bin/perl
#
# mkcmdtable: build a table of commands
#       This script was built for Core, and so has boilerplate text
#       to go with the table - one set for builtins, one for regular cmds.
#       Disable the boilerplate with -q.
#
# issues:
#       1. It has only limited knowledge of submodules - it takes a -m
#       option like most of the generator scripts do, but does not
#       understand a list of submodules passed as the argument to that opt
#       (in fact, it deals in SubModule.SMid rather than .SMname)
#       2. the boilerplate is not as appropriate for the non-Core cmds,
#       and there ought to be a way to supress it entirely.
#       3. in common with the other scripts, it has a hardcoded idea
#       of the number of columns, there's not really any reason why
#       that could not be either passed in, or perhaps computed based
#       on the size of elements, or both.
#       4. the xref tags emitted here are not necessarily guaranteed
#       to be unique, so if a module book includes command sections from
#       two different submodules, some care needs to be taken. See
#       Toolkit_Independent/deskenv/makefile for a notation on this.
#       These lines from this script show the problem:
#
#	$tbl = "tbl-cmds";
#	...
#	printf("<table id=\"$tbl\">\n");
#
#       Note that unlike mklibsgmltable, this script emits a full
#       table specification; mklibsgmltable emits only the table /data/,
#       wrapped in starting/ending <tbody> tags. That means files
#       generated by this script are included in a different way than
#       library tables.
#
#
# Originally by:
#	Linux Standard Base, http://www.linuxbase.org/
#       Part of the Linux Foundation, https://www.linuxfoundation.org/
#       Jeff Licquia, licquia@linuxfoundation.org, 2015
#	George Kraft IV, gk4@us.ibm.com, 03/09/2000
#	Nick Stoughton, nick@usenix.org, 2004 - 2005
#
#

# Uncomment to trace SQL statments
#$trace=1;

use DBI;
use Getopt::Long;
use Env qw(LSBUSER LSBDBPASSWD LSBDB LSBDBHOST);

local %references;
local %standards;
my $builtins = 0;

sub usage()
{
        print STDERR "mkcmdtable -v <lsbversion> [-b] [-q] [-m <submodule>]\n Default module is LSB_Base.\n";
        die;
}
################################################################################
#	lsbOpenDB
################################################################################

sub lsbOpenDB {
	$dbh = DBI->connect("DBI:mysql:$LSBDB:$LSBDBHOST", $LSBUSER, $LSBDBPASSWD);
	die unless $dbh;
}

################################################################################
#	lsbCloseDB
################################################################################

sub lsbCloseDB {
	$dbh->disconnect;
}

################################################################################
#	builtinexcepts
################################################################################

sub builtinexcepts {
	print << "END_BIEXCEPT_TEXT";
<orderedlist>
<listitem><para>
The built in commands and utilities shall be provided by the
<command>sh</command> utility itself, and need not 
be implemented in a manner so that they can be accessed via the 
exec family of functions as defined in <xref linkend="std.SUSv4">
and should not be invoked directly by those standard utilities 
that execute other utilities (
<simplelist type=inline>
<member><command>env</command></member>
<member><command>find</command></member>
<member><command>nice</command></member>
<member><command>nohup</command></member>
<member><command>time</command></member>
<member><command>xargs</command></member>
</simplelist>).
<note>
<title>Rationale (Informative)</title>
<para>
Since the built in utilities must affect the environment of the calling
process, they have no effect when executed as a file.
</para></note>
</para></listitem>
</orderedlist>
END_BIEXCEPT_TEXT
}

################################################################################
#	cmdexcepts
################################################################################

sub cmdexcepts {
	print << "END_EXCEPT_TEXT";
<orderedlist>
<listitem><para>
If any operand (except one which follows <option>--</option>) starts with a
hyphen, the behavior is unspecified.
<note><title>Rationale (Informative)</title>
<para>Applications should place options before operands, or use
<option>--</option>, as needed.  This text is needed because,
by default, GNU option parsing
differs from POSIX, unless the environment variable 
<envar>POSIXLY_CORRECT</envar>
is set.  For example, <command>ls . -a</command> in GNU
<command>ls</command> means to list the current directory, showing all
files (that is, <option>"."</option> is an operand and <option>-a</option> is an
option).  In POSIX, <option>"."</option> and <option>-a</option> are both operands,
and the command means to list the current directory, and also the file
named <filename>-a</filename>.  Suggesting that applications rely on the
setting of the <envar>POSIXLY_CORRECT</envar> environment variable,
or try to set it, seems worse than just asking the applications to invoke
commands in ways which work with either the POSIX or GNU behaviors.</para>

</note>
</para></listitem>
</orderedlist>
END_EXCEPT_TEXT
}
################################################################################
#	lsbCommands
################################################################################

sub lsbCommands {

	my $status, $title, $tbl, $MainTitle, $builtinCheck;
	if ($builtins) {
		$status = 'Included';
		$builtinCheck = 'Command.Cbuiltin = \'Yes\'';
		$title = 'shell built in utilities';
		$tbl = "tbl-builtins";
		$MainTitle = "Built In Utilities";
	} else {
		$status = 'Included';
		$builtinCheck = 'Command.Cbuiltin <> \'Yes\''; # let's include 'Unknown' builtins here
		$title = 'commands and utilities';
		$tbl = "tbl-cmds";
		$MainTitle = "Commands And Utilities";
	}
	$sth = $dbh->prepare("SELECT DISTINCT Sfull, Sid, Sname FROM Standard,Command
                          LEFT JOIN SModCmd ON Command.Cid=SModCmd.SMCcid
                          LEFT JOIN CmdStd ON CScid=Cid
                          WHERE SModCmd.SMCsmid IN ($SMid)
                          AND Standard.Sid=CSsid
                          AND SMCappearedin > '' AND SMCappearedin<='$lsbversion'
                          AND (SMCwithdrawnin IS NULL OR SMCwithdrawnin>'$lsbversion')
                          AND Sappearedin > '' AND Sappearedin<='$lsbversion'
                          AND (Swithdrawnin IS NULL OR Swithdrawnin>'$lsbversion')
                          AND CSappearedin > '' AND CSappearedin<='$lsbversion'
                          AND (CSwithdrawnin IS NULL OR CSwithdrawnin>'$lsbversion')
                          AND $builtinCheck
                          ORDER BY Sname");
	$sth->execute;

	if ($sth->rows > 0) {

	$sth->finish;
	printf("<!-- Start of text generated from database -->\n");
	if (!$noboiler) {
		printf("<para>\n");
		printf("An LSB conforming implementation shall provide the\n");
		printf("%s as described in <xref linkend=\"%s\">, with at least the behavior\n",
			$title, $tbl);
		printf("described as mandatory in the referenced underlying\n");
		printf("specification, with the following exceptions:\n");
		$builtins ? builtinexcepts : cmdexcepts;

		printf("</para>\n");
	}

	$sth = $dbh->prepare("SELECT Cname, CSsid, Sfull, Sid, Sname, Stag FROM Command
                            LEFT JOIN SModCmd ON Command.Cid=SModCmd.SMCcid
                            LEFT JOIN CmdStd ON CScid=Cid
                            LEFT JOIN Standard ON CSsid=Standard.Sid
                            WHERE SMCappearedin > '' AND SMCappearedin<='$lsbversion'
                            AND (SMCwithdrawnin IS NULL OR SMCwithdrawnin>'$lsbversion')
                            AND Sappearedin > '' AND Sappearedin<='$lsbversion'
                            AND (Swithdrawnin IS NULL OR Swithdrawnin>'$lsbversion')
			    AND CSappearedin > '' AND CSappearedin<='$lsbversion'
			    AND (CSwithdrawnin IS NULL OR CSwithdrawnin>'$lsbversion')
                            AND $builtinCheck
                            AND SModCmd.SMCsmid IN ($SMid)
                            ORDER BY Command.Cname");
	$sth->execute;

	if ($sth->rows < 1) {
		printf("<para>No Commands or Utilities found!</para>\n");
		$sth->finish;
		return;
	} 

	if (!$noboiler) {
		printf("<table id=\"$tbl\">\n");
		printf("<title>$MainTitle</title>\n");
		printf("<tgroup cols=5>\n");
	}
	printf("<tbody>\n");
	printf("<row>\n");

	my $col = 0; #column count
	my $row = 0;
	my $totalrows = int(($sth->rows+4) / 5);

	my $cmds = $sth->fetchall_arrayref({});

	while ($row < $totalrows) {

		#
		# fixed width table ... 5 columns
		#
		if ($col == 5) {
			last if(++$row >= $totalrows);
			printf("</row><row>\n");
			$col = 0;
		}
		my $idx = ($row + ($col++ * $totalrows));
		$field = $cmds->[($idx)];

		#
		# Shouldn't need this, but we've seen this script 
		# go into an infinite loop before, so this is a safeguard.
		#
		die "OVERFLOW!!! $idx > " . $totalrows * 5 unless ($idx <= $totalrows*5);

		$ref = $permutation{$field->{'CSsid'}};

		#$ftid = sprintf("std-fn-%s-%s",  
		#	$field[1], $permutation{$field[1]});

		printf("<entry>%s\n", $field->{'Cname'});
		# figure out a reference
		# each table is followed by a list of references
		#
		# this is a little complex:
		# %references is a hash, using keys of the form "std-%d-%d"
		#   with values being the names of the standards
		# @ref is an array; each element is a key in %ref
		# $refno is the current index into that array
		if( !$noboiler && $field->{'Sid'} ) {

			my $refstr = sprintf "std-cmd%s-%d",
				$builtins ? "bi":"" ,$field->{'Sid'};
			$references{$refstr} = $field->{'Stag'};
			$refno = 0;
			for $r (0..$#ref) {
				$refno = $r;
				last if ($ref[$r] eq $refstr);
			}
			if ($ref[$refno] ne $refstr) {
				push(@ref, $refstr);
				$refno = $#ref;
			}
			
			printf("<link linkend=\"%s\"> [%d]</link>\n", 
				$refstr, $refno+1 );
		}
		printf("</entry>\n");

	}

	printf("</row>\n");
	printf("</tbody>\n");
	if (!$noboiler) {
		printf("</tgroup>\n");
		printf("</table>\n");
		#
		# now print out the referenced standards list
		#
		if ($#ref >= 0) {
			print "<para><emphasis>Referenced Specification(s)</emphasis></para>\n";
			for $r (0..$#ref) {
				$refstr = $ref[$r];
				printf "<formalpara><title id=\"%s\">[%d]</title><para><xref linkend=\"std.%s\"></para></formalpara>\n",
					$refstr, $r+1, $references{$refstr};
				}
			}
		}
	}
	$sth->finish;

	printf("<!-- End of text generated from database -->\n");
}

################################################################################
#	main
################################################################################

# We can get module id from Module Table. Commands list will be generated as per modules.
GetOptions("b" => \$builtins,
           "q" => \$noboiler,
           "m=s" => \$submodule,
	   "v=s" => \$lsbversion);

lsbOpenDB;

if(!$submodule) { 
    $submodule='LSB_Base';
}
$SMid = "";
foreach $mod (split /,/, $submodule) {
	($modid) = $dbh->selectrow_array("SELECT SMid FROM SubModule WHERE SMname='$mod'");
	die("Incorrect SubModule name: " . $mod) if not $modid;
	if ($SMid == "") {
		$SMid = $modid;
	} else {
		$SMid = $SMid . "," . $modid;
	}
}

if(!$lsbversion) { usage(); }

lsbCommands;
lsbCloseDB;

exit;

# EOF