#!/usr/bin/perl -w 
# -*-cperl-*-
## Filename: ucs-info
## Modified: Sun Jan 25 14:25:40 2004 (evert)   
##   Author: Stefan Evert
##  Purpose: print information from header of data set file
$| = 1;

use UCS;
use UCS::DS::Stream;

use Getopt::Long;

$Opt_Help = 0;					# --help, -h
$Opt_Size = 0;					# --size, -s
$Opt_List = 0;					# --list-variables, -l
$Opt_Verbose = 0;				# --verbose, -v

$ok = GetOptions(
		 "help|h" => \$Opt_Help,
		 "size|s" => \$Opt_Size,
		 "list-variables|l" => \$Opt_List,
		 "verbose|v" => \$Opt_Verbose,
		);

die "Usage:  ucs-info [-s [-v]] [-l] data.ds.gz\n"
  . "[type 'ucsdoc ucs-info' for more information]\n"
  unless $ok and @ARGV == 1;

$file = shift @ARGV;

print "\nDATA SET FILE:  $file\n\n";

$ds = new UCS::DS::Stream::Read $file;

foreach $line ($ds->comments) {
  print "# $line\n";
}
print "\n";

foreach $var (sort $ds->globals) {
  print "##:: $var = ", $ds->global($var), "\n";
}
print "\n";

if ($Opt_Size) {
  print STDERR "Checking real size ."
    if $Opt_Verbose;
  $N = 0;
  while ($ds->read) {
    $N++;
    die " FORMAT ERROR (row #$N)\n"
      unless $ds->valid;
    print STDERR "." 
      if $Opt_Verbose and ($N & 0xfff) == 0;
  }
  print STDERR " ok\n"
    if $Opt_Verbose;
  print "##:: size = $N\n\n";
}

if ($Opt_List) {
  foreach $var ($ds->vars) {
    $type = $ds->var($var);
    $c = $ds->global($var);
    $comment = (defined $c) ? "# $c" : "";
    printf "%-6s %-20s  %s\n", $type, $var, $comment;
  }
  print "\n";
}


__END__

=head1 NAME

ucs-info - Display information from header of UCS data set file


=head1 SYNOPSIS

  ucs-info [-s [-v]] [-l] data.ds.gz


=head1 DESCRIPTION

This small utility displays information from the header of a data set file
(comment lines and global variables).  

With the C<--size> (or C<-s>) option, the actual size of the data set
(i.e. the number of pair types) is also determined, which may be different
from the size reported in the header.  Note that this operation has to read
the entire data set file and may take some time for larger data sets (use
C<--verbose> or C<-v> to show progress information).

With the C<--list> (or C<-l>) option, the data set variables are listed
together with their data types and optional comments.


=head1 COPYRIGHT

Copyright 2004 Stefan Evert.

This software is provided AS IS and the author makes no warranty as to
its use and performance. You may use the software, redistribute and
modify it under the same terms as Perl itself.

=cut
