# HG changeset patch
# User Maciej Seroka <maciejs@symbian.org>
# Date 1271424328 -3600
# Node ID b7a101a82e4b2bfce5cfaff500deb6508844d619
# Parent  e662a2267ea55979d40332f530511a5a43bad3b7
Added 'help' for ha_filter.pl

diff -r e662a2267ea5 -r b7a101a82e4b bc_tools/ha_filter.pl
--- a/bc_tools/ha_filter.pl	Fri Apr 16 12:56:17 2010 +0100
+++ b/bc_tools/ha_filter.pl	Fri Apr 16 14:25:28 2010 +0100
@@ -15,10 +15,9 @@
 #
 
 use strict;
+use Getopt::Long;
 use XML::Simple;
-use File::Copy;
 use Tie::File;
-use Data::Dumper;
 
 my $report;
 my $header_list;
@@ -27,8 +26,7 @@
 my $del_ok_issues = 1; # This variable determines whether to delete OK issues first.
 my $del_comp_issues = 0; # This variable determines whether to delete Compilation errors.
 my $del_boost_issues = 1; # This variable determines whether to delete issues for Boost API headers.
-my $tsv_file;
-my $sub_reports = 0; # This variable determines whether to generate sub-reports per package.
+my $tsv_file; # If defined then sub-reports per package will be generated.
 my $n;
 my $m;
 my $p;
@@ -39,25 +37,41 @@
 my @pkgs;
 my $nopkg;
 my $pkgs_num;
-my $hdr_to_pkg;
-my $package;
+my ($hdr_to_pkg, $package);
 my $pkg_found;
 my $add_pkg;
 my $temp_report;
 my $current_pkg;
+my $help;
 
-if ($ARGV[1]) {
-	$report = $ARGV[0];
-	$header_list = $ARGV[1];
-	$destfile = "filtered_" . $report;
-} else { 
-	die "Missing parameter(s). For example: ha_filter.pl headers_report.xml public_headers.txt"; 
+sub usage($);
+sub help();
+sub usage_error();
+
+my %optmap = (  'headers-report' => \$report,
+			    'public-api-list' => \$header_list,
+			    'xref-file' => \$tsv_file,
+				'help' => \$help);
+
+GetOptions(\%optmap,
+          'headers-report=s',
+          'public-api-list=s',
+          'xref-file=s',
+		  'help!') 
+          or usage_error();
+
+if ($help) {
+	help();
 }
 
-if ($ARGV[2]) {
-	$tsv_file = $ARGV[2];
-	$sub_reports = 1;
-}
+# --headers-report is mandatory.
+usage_error(), unless (defined($report));
+
+# --public-headers is mandatory.
+usage_error(), unless (defined($header_list));
+
+# Define output file based on the headers report name.
+$destfile = "filtered_" . $report;
 
 # Parse the input XML into hashrefs.
 print "Parsing " . $report . "... ";
@@ -137,7 +151,7 @@
 	$file_name = $current_report->{'bbcresults'}->{'issuelist'}->[0]->{'headerfile'}->[$n]->{'shortname'}->[0];
 	$delete_node = 1;
 	# Load Public API definitions.
-	open FILE, "<$header_list" or print "Failed to read $header_list: $!\n" and return;
+	open FILE, "<$header_list" or die("Failed to read $header_list: $!\n");
 	while ($line = <FILE>) { # Check against header list.
 		chomp $line;
 		if (lc($file_name) eq lc($line)) {	# Mark the node to NOT be deleted.
@@ -173,14 +187,14 @@
 unshift @lines, "<?xml version=\"1.0\" encoding=\"ASCII\" standalone=\"no\" ?>";
 untie @lines;
 
-if ($sub_reports) { # Generate sub-reports per package.
+if (defined($tsv_file)) { # Generate sub-reports per package.
 	# Create the list of packages that link to remaining header files and generate sub-report for Removed header files.
 	$nopkg = 0;
 	$n = 0;
 	while ($n < $header_num) {
 		$file_name = $current_report->{'bbcresults'}->{'issuelist'}->[0]->{'headerfile'}->[$n]->{'shortname'}->[0];
 		$pkg_found = 0;
-		open FILE, "<$tsv_file" or print "Failed to read $tsv_file: $!\n" and return;
+		open FILE, "<$tsv_file" or die("Failed to read $tsv_file: $!\n");
 		while ($line = <FILE>)
 		{
 			chomp $line;
@@ -250,7 +264,7 @@
 		while ($n < $header_num) {
 			$file_name = $temp_report->{'bbcresults'}->{'issuelist'}->[0]->{'headerfile'}->[$n]->{'shortname'}->[0];
 			$pkg_found = 0;
-			open FILE, "<$tsv_file" or print "Failed to read $tsv_file: $!\n" and return;
+			open FILE, "<$tsv_file" or die("Failed to read $tsv_file: $!\n");;
 			while ($line = <FILE>)
 			{
 				chomp $line;
@@ -285,3 +299,32 @@
 		untie @lines;
 	}
 }
+
+exit 0;
+
+sub usage($)
+{
+    my $error = shift;
+    my $fh = $error == 0 ? *STDOUT : *STDERR;
+    print $fh "ha_filter.pl\n" .
+            "Specify the headers report and public API list\n" .
+            "synopsis:\n" .
+            "  ha_filter.pl --help\n" .
+            "  ha_filter.pl [--headers-report=XML_FILE] [--public-api-list=TXT_FILE] [--xref-file=TSV_FILE] \n" .
+            "options:\n" .
+            "  --help                        Display this help and exit.\n" .
+            "  --headers-report=XML_FILE     XML_FILE is the name of the headers report xml file.\n" .
+            "  --public-api-list=TXT_FILE    TXT_FILE is the file containing the list of public header files.\n" .
+            "  --xref-file=TSV_FILE          TSV_FILE is the file containing the index of header files linked to packages generated by summarise_tsv.pl.\n";
+    exit $error;            
+}
+
+sub help()
+{
+    usage(0);
+}
+
+sub usage_error()
+{
+    usage(1);
+}