# autoconf -- create `configure' using m4 macros
# Copyright (C) 2001-2003, 2009-2012 Free Software Foundation, Inc.

# This program 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.

# This program 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 this program.  If not, see <http://www.gnu.org/licenses/>.

package Autom4te::Request;

=head1 NAME

Autom4te::Request - a single m4 run request

=head1 SYNOPSIS

  use Autom4te::Request;

=head1 DESCRIPTION

This perl module provides various general purpose support functions
used in several executables of the Autoconf and Automake packages.

=cut

use strict;
use Class::Struct;
use Carp;
use Data::Dumper;

struct
  (
   # The key of the cache files.
   'id' => "\$",
   # True iff %MACRO contains all the macros we want to trace.
   'valid' => "\$",
   # The include path.
   'path' => '@',
   # The set of input files.
   'input' => '@',
   # The set of macros currently traced.
   'macro' => '%',
  );


# Serialize a request or all the current requests.
sub marshall($)
{
  my ($caller) = @_;
  my $res = '';

  # CALLER is an object: instance method.
  my $marshall = Data::Dumper->new ([$caller]);
  $marshall->Indent(2)->Terse(0);
  $res = $marshall->Dump . "\n";

  return $res;
}


# includes_p ($SELF, @MACRO)
# --------------------------
# Does this request covers all the @MACRO.
sub includes_p
{
  my ($self, @macro) = @_;

  foreach (@macro)
    {
      return 0
	if ! exists ${$self->macro}{$_};
    }
  return 1;
}


=head1 SEE ALSO

L<Autom4te::C4che>

=head1 HISTORY

Written by Akim Demaille E<lt>F<akim@freefriends.org>E<gt>.

=cut



1; # for require

### Setup "GNU" style for perl-mode and cperl-mode.
## Local Variables:
## perl-indent-level: 2
## perl-continued-statement-offset: 2
## perl-continued-brace-offset: 0
## perl-brace-offset: 0
## perl-brace-imaginary-offset: 0
## perl-label-offset: -2
## cperl-indent-level: 2
## cperl-brace-offset: 0
## cperl-continued-brace-offset: 0
## cperl-label-offset: -2
## cperl-extra-newline-before-brace: t
## cperl-merge-trailing-else: nil
## cperl-continued-statement-offset: 2
## End:
# Copyright (C) 2003-2012 Free Software Foundation, Inc.

# This program 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 2, or (at your option)
# any later version.

# This program 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 this program.  If not, see <http://www.gnu.org/licenses/>.

###############################################################
# The main copy of this file is in Automake's git repository. #
# Updates should be sent to automake-patches@gnu.org.         #
###############################################################

package Autom4te::FileUtils;

=head1 NAME

Autom4te::FileUtils - handling files

=head1 SYNOPSIS

  use Autom4te::FileUtils

=head1 DESCRIPTION

This perl module provides various general purpose file handling functions.

=cut

use 5.006;
use strict;
use Exporter;
use File::stat;
use IO::File;
use Autom4te::Channels;
use Autom4te::ChannelDefs;

use vars qw (@ISA @EXPORT);

@ISA = qw (Exporter);
@EXPORT = qw (&open_quote &contents
	      &find_file &mtime
	      &update_file &up_to_date_p
	      &xsystem &xsystem_hint &xqx
	      &dir_has_case_matching_file &reset_dir_cache
	      &set_dir_cache_file);


=item C<open_quote ($file_name)>

Quote C<$file_name> for open.

=cut

# $FILE_NAME
# open_quote ($FILE_NAME)
# -----------------------
# If the string $S is a well-behaved file name, simply return it.
# If it starts with white space, prepend './', if it ends with
# white space, add '\0'.  Return the new string.
sub open_quote($)
{
  my ($s) = @_;
  if ($s =~ m/^\s/)
    {
      $s = "./$s";
    }
  if ($s =~ m/\s$/)
    {
      $s = "$s\0";
    }
  return $s;
}

=item C<find_file ($file_name, @include)>

Return the first path for a C<$file_name> in the C<include>s.

We match exactly the behavior of GNU M4: first look in the current
directory (which includes the case of absolute file names), and then,
if the file name is not absolute, look in C<@include>.

If the file is flagged as optional (ends with C<?>), then return undef
if absent, otherwise exit with error.

=cut

# $FILE_NAME
# find_file ($FILE_NAME, @INCLUDE)
# --------------------------------
sub find_file ($@)
{
  use File::Spec;

  my ($file_name, @include) = @_;
  my $optional = 0;

  $optional = 1
    if $file_name =~ s/\?$//;

  return File::Spec->canonpath ($file_name)
    if -e $file_name;

  if (!File::Spec->file_name_is_absolute ($file_name))
    {
      foreach my $path (@include)
	{
	  return File::Spec->canonpath (File::Spec->catfile ($path, $file_name))
	    if -e File::Spec->catfile ($path, $file_name)
	}
    }

  fatal "$file_name: no such file or directory"
    unless $optional;
  return undef;
}

=item C<mtime ($file)>

Return the mtime of C<$file>.  Missing files, or C<-> standing for
C<STDIN> or C<STDOUT> are "obsolete", i.e., as old as possible.

=cut

# $MTIME
# MTIME ($FILE)
# -------------
sub mtime ($)
{
  my ($file) = @_;

  return 0
    if $file eq '-' || ! -f $file;

  my $stat = stat ($file)
    or fatal "cannot stat $file: $!";

  return $stat->mtime;
}


=item C<update_file ($from, $to, [$force])>

Rename C<$from> as C<$to>, preserving C<$to> timestamp if it has not
changed, unless C<$force> is true (defaults to false).  Recognize
C<$to> = C<-> standing for C<STDIN>.  C<$from> is always
removed/renamed.

=cut

# &update_file ($FROM, $TO; $FORCE)
# ---------------------------------
sub update_file ($$;$)
{
  my ($from, $to, $force) = @_;
  $force = 0
    unless defined $force;
  my $SIMPLE_BACKUP_SUFFIX = $ENV{'SIMPLE_BACKUP_SUFFIX'} || '~';
  use File::Compare;
  use File::Copy;

  if ($to eq '-')
    {
      my $in = new IO::File ("< " . open_quote ($from));
      my $out = new IO::File (">-");
      while ($_ = $in->getline)
	{
	  print $out $_;
	}
      $in->close;
      unlink ($from) || fatal "cannot remove $from: $!";
      return;
    }

  if (!$force && -f "$to" && compare ("$from", "$to") == 0)
    {
      # File didn't change, so don't update its mod time.
      msg 'note', "'$to' is unchanged";
      unlink ($from)
        or fatal "cannot remove $from: $!";
      return
    }

  if (-f "$to")
    {
      # Back up and install the new one.
      move ("$to",  "$to$SIMPLE_BACKUP_SUFFIX")
	or fatal "cannot backup $to: $!";
      move ("$from", "$to")
	or fatal "cannot rename $from as $to: $!";
      msg 'note', "'$to' is updated";
    }
  else
    {
      move ("$from", "$to")
	or fatal "cannot rename $from as $to: $!";
      msg 'note', "'$to' is created";
    }
}


=item C<up_to_date_p ($file, @dep)>

Is C<$file> more recent than C<@dep>?

=cut

# $BOOLEAN
# &up_to_date_p ($FILE, @DEP)
# ---------------------------
sub up_to_date_p ($@)
{
  my ($file, @dep) = @_;
  my $mtime = mtime ($file);

  foreach my $dep (@dep)
    {
      if ($mtime < mtime ($dep))
	{
	  verb "up_to_date ($file): outdated: $dep";
	  return 0;
	}
    }

  verb "up_to_date ($file): up to date";
  return 1;
}


=item C<handle_exec_errors ($command, [$expected_exit_code = 0], [$hint])>

Display an error message for C<$command>, based on the content of
C<$?> and C<$!>.  Be quiet if the command exited normally
with C<$expected_exit_code>.  If C<$hint> is given, display that as well
if the command failed to run at all.

=cut

sub handle_exec_errors ($;$$)
{
  my ($command, $expected, $hint) = @_;
  $expected = 0 unless defined $expected;
  if (defined $hint)
    {
      $hint = "\n" . $hint;
    }
  else
    {
      $hint = '';
    }

  $command = (split (' ', $command))[0];
  if ($!)
    {
      fatal "failed to run $command: $!" . $hint;
    }
  else
    {
      use POSIX qw (WIFEXITED WEXITSTATUS WIFSIGNALED WTERMSIG);

      if (WIFEXITED ($?))
	{
	  my $status = WEXITSTATUS ($?);
	  # Propagate exit codes.
	  fatal ('',
		 "$command failed with exit status: $status",
		 exit_code => $status)
	    unless $status == $expected;
	}
      elsif (WIFSIGNALED ($?))
	{
	  my $signal = WTERMSIG ($?);
	  fatal "$command terminated by signal: $signal";
	}
      else
	{
	  fatal "$command exited abnormally";
	}
    }
}

=item C<xqx ($command)>

Same as C<qx> (but in scalar context), but fails on errors.

=cut

# xqx ($COMMAND)
# --------------
sub xqx ($)
{
  my ($command) = @_;

  verb "running: $command";

  $! = 0;
  my $res = `$command`;
  handle_exec_errors $command
    if $?;

  return $res;
}


=item C<xsystem (@argv)>

Same as C<system>, but fails on errors, and reports the C<@argv>
in verbose mode.

=cut

sub xsystem (@)
{
  my (@command) = @_;

  verb "running: @command";

  $! = 0;
  handle_exec_errors "@command"
    if system @command;
}


=item C<xsystem_hint ($msg, @argv)>

Same as C<xsystem>, but allows to pass a hint that will be displayed
in case the command failed to run at all.

=cut

sub xsystem_hint (@)
{
  my ($hint, @command) = @_;

  verb "running: @command";

  $! = 0;
  handle_exec_errors "@command", 0, $hint
    if system @command;
}


=item C<contents ($file_name)>

Return the contents of C<$file_name>.

=cut

# contents ($FILE_NAME)
# ---------------------
sub contents ($)
{
  my ($file) = @_;
  verb "reading $file";
  local $/;			# Turn on slurp-mode.
  my $f = new Autom4te::XFile "< " . open_quote ($file);
  my $contents = $f->getline;
  $f->close;
  return $contents;
}


=item C<dir_has_case_matching_file ($DIRNAME, $FILE_NAME)>

Return true iff $DIR contains a file name that matches $FILE_NAME case
insensitively.

We need to be cautious on case-insensitive case-preserving file
systems (e.g. Mac OS X's HFS+).  On such systems C<-f 'Foo'> and C<-f
'foO'> answer the same thing.  Hence if a package distributes its own
F<CHANGELOG> file, but has no F<ChangeLog> file, automake would still
try to distribute F<ChangeLog> (because it thinks it exists) in
addition to F<CHANGELOG>, although it is impossible for these two
files to be in the same directory (the two file names designate the
same file).

=cut

use vars '%_directory_cache';
sub dir_has_case_matching_file ($$)
{
  # Note that print File::Spec->case_tolerant returns 0 even on MacOS
  # X (with Perl v5.8.1-RC3 at least), so do not try to shortcut this
  # function using that.

  my ($dirname, $file_name) = @_;
  return 0 unless -f "$dirname/$file_name";

  # The file appears to exist, however it might be a mirage if the
  # system is case insensitive.  Let's browse the directory and check
  # whether the file is really in.  We maintain a cache of directories
  # so Automake doesn't spend all its time reading the same directory
  # again and again.
  if (!exists $_directory_cache{$dirname})
    {
      error "failed to open directory '$dirname'"
	unless opendir (DIR, $dirname);
      $_directory_cache{$dirname} = { map { $_ => 1 } readdir (DIR) };
      closedir (DIR);
    }
  return exists $_directory_cache{$dirname}{$file_name};
}

=item C<reset_dir_cache ($dirname)>

Clear C<dir_has_case_matching_file>'s cache for C<$dirname>.

=cut

sub reset_dir_cache ($)
{
  delete $_directory_cache{$_[0]};
}

=item C<set_dir_cache_file ($dirname, $file_name)>

State that C<$dirname> contains C<$file_name> now.

=cut

sub set_dir_cache_file ($$)
{
  my ($dirname, $file_name) = @_;
  $_directory_cache{$dirname}{$file_name} = 1
    if exists $_directory_cache{$dirname};
}

1; # for require

### Setup "GNU" style for perl-mode and cperl-mode.
## Local Variables:
## perl-indent-level: 2
## perl-continued-statement-offset: 2
## perl-continued-brace-offset: 0
## perl-brace-offset: 0
## perl-brace-imaginary-offset: 0
## perl-label-offset: -2
## cperl-indent-level: 2
## cperl-brace-offset: 0
## cperl-continued-brace-offset: 0
## cperl-label-offset: -2
## cperl-extra-newline-before-brace: t
## cperl-merge-trailing-else: nil
## cperl-continued-statement-offset: 2
## End:
# Copyright (C) 2012 Free Software Foundation, Inc.

# This program 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.

# This program 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 this program.  If not, see <http://www.gnu.org/licenses/>.

package Autom4te::Getopt;

=head1 NAME

Autom4te::Getopt - GCS conforming parser for command line options

=head1 SYNOPSIS

  use Autom4te::Getopt;

=head1 DESCRIPTION

Export a function C<parse_options>, performing parsing of command
line options in conformance to the GNU Coding standards.

=cut

use 5.006;
use strict;
use warnings FATAL => 'all';
use Exporter ();
use Getopt::Long ();
use Autom4te::ChannelDefs qw/fatal/;
use Carp qw/croak confess/;

use vars qw (@ISA @EXPORT);
@ISA = qw (Exporter);
@EXPORT= qw/getopt/;

=item C<parse_options (%option)>

Wrapper around C<Getopt::Long>, trying to conform to the GNU
Coding Standards for error messages.

=cut

sub parse_options (%)
{
  my %option = @_;

  Getopt::Long::Configure ("bundling", "pass_through");
  # Unrecognized options are passed through, so GetOption can only fail
  # due to internal errors or misuse of options specification.
  Getopt::Long::GetOptions (%option)
    or confess "error in options specification (likely)";

  if (@ARGV && $ARGV[0] =~ /^-./)
    {
      my %argopts;
      for my $k (keys %option)
	{
	  if ($k =~ /(.*)=s$/)
	    {
	      map { $argopts{(length ($_) == 1)
			     ? "-$_" : "--$_" } = 1; } (split (/\|/, $1));
	    }
	}
      if ($ARGV[0] eq '--')
	{
	  shift @ARGV;
	}
      elsif (exists $argopts{$ARGV[0]})
	{
	  fatal ("option '$ARGV[0]' requires an argument\n"
		 . "Try '$0 --help' for more information.");
	}
      else
	{
	  fatal ("unrecognized option '$ARGV[0]'.\n"
		 . "Try '$0 --help' for more information.");
	}
    }
}

=back

=head1 SEE ALSO

L<Getopt::Long>

=cut

1; # for require

### Setup "GNU" style for perl-mode and cperl-mode.
## Local Variables:
## perl-indent-level: 2
## perl-continued-statement-offset: 2
## perl-continued-brace-offset: 0
## perl-brace-offset: 0
## perl-brace-imaginary-offset: 0
## perl-label-offset: -2
## cperl-indent-level: 2
## cperl-brace-offset: 0
## cperl-continued-brace-offset: 0
## cperl-label-offset: -2
## cperl-extra-newline-before-brace: t
## cperl-merge-trailing-else: nil
## cperl-continued-statement-offset: 2
## End:
# autoconf -- create `configure' using m4 macros
# Copyright (C) 2003, 2006, 2009-2012 Free Software Foundation, Inc.

# This program 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.
#
# This program 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 this program.  If not, see <http://www.gnu.org/licenses/>.

package Autom4te::C4che;

=head1 NAME

Autom4te::C4che - a single m4 run request

=head1 SYNOPSIS

  use Autom4te::C4che;

=head1 DESCRIPTION

This Perl module handles the cache of M4 runs used by autom4te.

=cut

use Data::Dumper;
use Autom4te::Request;
use Carp;
use strict;

=over 4

=item @request

List of requests.

We cannot declare it "my" as the loading, performed via "do", would
refer to another scope, and @request would not be updated.  It used to
work with "my" vars, and I do not know whether the current behavior
(5.6) is wanted or not.

=cut

use vars qw(@request);

=item C<$req = Autom4te::C4che-E<gt>retrieve (%attr)>

Find a request with the same path and input.

=cut

sub retrieve($%)
{
  my ($self, %attr) = @_;

  foreach (@request)
    {
      # Same path.
      next
	if join ("\n", @{$_->path}) ne join ("\n", @{$attr{path}});

      # Same inputs.
      next
	if join ("\n", @{$_->input}) ne join ("\n", @{$attr{input}});

      # Found it.
      return $_;
    }

  return undef;
}

=item C<$req = Autom4te::C4che-E<gt>register (%attr)>

Create and register a request for these path and input.

=cut

# $REQUEST-OBJ
# register ($SELF, %ATTR)
# -----------------------
# NEW should not be called directly.
# Private.
sub register ($%)
{
  my ($self, %attr) = @_;

  # path and input are the only ID for a request object.
  my $obj = new Autom4te::Request ('path'  => $attr{path},
				   'input' => $attr{input});
  push @request, $obj;

  # Assign an id for cache file.
  $obj->id ("$#request");

  return $obj;
}


=item C<$req = Autom4te::C4che-E<gt>request (%request)>

Get (retrieve or create) a request for the path C<$request{path}> and
the input C<$request{input}>.

=cut

# $REQUEST-OBJ
# request($SELF, %REQUEST)
# ------------------------
sub request ($%)
{
  my ($self, %request) = @_;

  my $req =
    Autom4te::C4che->retrieve (%request)
    || Autom4te::C4che->register (%request);

  # If there are new traces to produce, then we are not valid.
  foreach (@{$request{'macro'}})
    {
      if (! exists ${$req->macro}{$_})
	{
	  ${$req->macro}{$_} = 1;
	  $req->valid (0);
	}
    }

  # It would be great to have $REQ check that it is up to date wrt
  # its dependencies, but that requires getting traces (to fetch the
  # included files), which is out of the scope of Request (currently?).

  return $req;
}


=item C<$string = Autom4te::C4che-E<gt>marshall ()>

Serialize all the current requests.

=cut


# marshall($SELF)
# ---------------
sub marshall ($)
{
  my ($caller) = @_;
  my $res = '';

  my $marshall = Data::Dumper->new ([\@request], [qw (*request)]);
  $marshall->Indent(2)->Terse(0);
  $res = $marshall->Dump . "\n";

  return $res;
}


=item C<Autom4te::C4che-E<gt>save ($file)>

Save the cache in the C<$file> file object.

=cut

# SAVE ($FILE)
# ------------
sub save ($$)
{
  my ($self, $file) = @_;

  confess "cannot save a single request\n"
    if ref ($self);

  $file->seek (0, 0);
  $file->truncate (0);
  print $file
    "# This file was generated.\n",
    "# It contains the lists of macros which have been traced.\n",
    "# It can be safely removed.\n",
    "\n",
    $self->marshall;
}


=item C<Autom4te::C4che-E<gt>load ($file)>

Load the cache from the C<$file> file object.

=cut

# LOAD ($FILE)
# ------------
sub load ($$)
{
  my ($self, $file) = @_;
  my $fname = $file->name;

  confess "cannot load a single request\n"
    if ref ($self);

  my $contents = join "", $file->getlines;

  eval $contents;

  confess "cannot eval $fname: $@\n" if $@;
}


=head1 SEE ALSO

L<Autom4te::Request>

=head1 HISTORY

Written by Akim Demaille E<lt>F<akim@freefriends.org>E<gt>.

=cut

1; # for require

### Setup "GNU" style for perl-mode and cperl-mode.
## Local Variables:
## perl-indent-level: 2
## perl-continued-statement-offset: 2
## perl-continued-brace-offset: 0
## perl-brace-offset: 0
## perl-brace-imaginary-offset: 0
## perl-label-offset: -2
## cperl-indent-level: 2
## cperl-brace-offset: 0
## cperl-continued-brace-offset: 0
## cperl-label-offset: -2
## cperl-extra-newline-before-brace: t
## cperl-merge-trailing-else: nil
## cperl-continued-statement-offset: 2
## End:
# autoconf -- create `configure' using m4 macros
# Copyright (C) 2001-2004, 2006-2007, 2009-2012 Free Software
# Foundation, Inc.

# This program 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.

# This program 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 this program.  If not, see <http://www.gnu.org/licenses/>.

package Autom4te::General;

=head1 NAME

Autom4te::General - general support functions for Autoconf

=head1 SYNOPSIS

  use Autom4te::General

=head1 DESCRIPTION

This perl module provides various general purpose support functions
used in several executables of the Autoconf package.

=cut

use 5.006;
use Exporter;
use Autom4te::ChannelDefs;
use Autom4te::Channels;
use Autom4te::Getopt ();
use File::Basename;
use File::Path ();
use File::stat;
use IO::File;
use Carp;
use strict;

use vars qw (@ISA @EXPORT);

@ISA = qw (Exporter);

# Variables we define and export.
my @export_vars =
  qw ($debug $force $help $me $tmp $verbose $version);

# Functions we define and export.
my @export_subs =
  qw (&debug
      &getopt &shell_quote &mktmpdir
      &uniq);

# Functions we forward (coming from modules we use).
my @export_forward_subs =
  qw (&basename &dirname &fileparse);

@EXPORT = (@export_vars, @export_subs, @export_forward_subs);


# Variable we share with the main package.  Be sure to have a single
# copy of them: using `my' together with multiple inclusion of this
# package would introduce several copies.

=head2 Global Variables

=over 4

=item C<$debug>

Set this variable to 1 if debug messages should be enabled.  Debug
messages are meant for developers only, or when tracking down an
incorrect execution.

=cut

use vars qw ($debug);
$debug = 0;

=item C<$force>

Set this variable to 1 to recreate all the files, or to consider all
the output files are obsolete.

=cut

use vars qw ($force);
$force = undef;

=item C<$help>

Set to the help message associated with the option C<--help>.

=cut

use vars qw ($help);
$help = undef;

=item C<$me>

The name of this application, for diagnostic messages.

=cut

use vars qw ($me);
$me = basename ($0);

=item C<$tmp>

The name of the temporary directory created by C<mktmpdir>.  Left
C<undef> otherwise.

=cut

# Our tmp dir.
use vars qw ($tmp);
$tmp = undef;

=item C<$verbose>

Enable verbosity messages.  These messages are meant for ordinary
users, and typically make explicit the steps being performed.

=cut

use vars qw ($verbose);
$verbose = 0;

=item C<$version>

Set to the version message associated to the option C<--version>.

=cut

use vars qw ($version);
$version = undef;

=back

=cut



## ----- ##
## END.  ##
## ----- ##

=head2 Functions

=over 4

=item C<END>

Filter Perl's exit codes, delete any temporary directory (unless
C<$debug>), and exit nonzero whenever closing C<STDOUT> fails.

=cut

# END
# ---
sub END
{
  # $? contains the exit status we will return.
  # It was set using one of the following ways:
  #
  #  1) normal termination
  #     this sets $? = 0
  #  2) calling `exit (n)'
  #     this sets $? = n
  #  3) calling die or friends (croak, confess...):
  #     a) when $! is non-0
  #        this set $? = $!
  #     b) when $! is 0 but $? is not
  #        this sets $? = ($? >> 8)   (i.e., the exit code of the
  #        last program executed)
  #     c) when both $! and $? are 0
  #        this sets $? = 255
  #
  # Cases 1), 2), and 3b) are fine, but we prefer $? = 1 for 3a) and 3c).
  my $status = $?;
  $status = 1 if ($! && $! == $?) || $? == 255;
  # (Note that we cannot safely distinguish calls to `exit (n)'
  # from calls to die when `$! = n'.  It's not big deal because
  # we only call `exit (0)' or `exit (1)'.)

  if (!$debug && defined $tmp && -d $tmp)
    {
      local $SIG{__WARN__} = sub { $status = 1; warn $_[0] };
      File::Path::rmtree $tmp;
    }

  # This is required if the code might send any output to stdout
  # E.g., even --version or --help.  So it's best to do it unconditionally.
  if (! close STDOUT)
    {
      print STDERR "$me: closing standard output: $!\n";
      $? = 1;
      return;
    }

  $? = $status;
}


## ----------- ##
## Functions.  ##
## ----------- ##


=item C<debug (@message)>

If the debug mode is enabled (C<$debug> and C<$verbose>), report the
C<@message> on C<STDERR>, signed with the name of the program.

=cut

# &debug(@MESSAGE)
# ----------------
# Messages displayed only if $DEBUG and $VERBOSE.
sub debug (@)
{
  print STDERR "$me: ", @_, "\n"
    if $verbose && $debug;
}


=item C<getopt (%option)>

Wrapper around C<Autom4te::Getopt::parse_options>.  In addition to
the user C<option>s, support C<-h>/C<--help>, C<-V>/C<--version>,
C<-v>/C<--verbose>, C<-d>/C<--debug>, C<-f>/C<--force>.  Conform to
the GNU Coding Standards for error messages.

=cut

# getopt (%OPTION)
# ----------------
# Handle the %OPTION, plus all the common options.
sub getopt (%)
{
  my (%option) = @_;
  %option = ("h|help"     => sub { print $help; exit 0 },
	     "V|version"  => sub { print $version; exit 0 },

	     "v|verbose"  => sub { ++$verbose },
	     "d|debug"    => sub { ++$debug },
	     'f|force'    => \$force,

	     # User options last, so that they have precedence.
	     %option);
  Autom4te::Getopt::parse_options (%option);

  setup_channel 'note', silent => !$verbose;
  setup_channel 'verb', silent => !$verbose;
}


=item C<shell_quote ($file_name)>

Quote C<$file_name> for the shell.

=cut

# $FILE_NAME
# shell_quote ($FILE_NAME)
# ------------------------
# If the string $S is a well-behaved file name, simply return it.
# If it contains white space, quotes, etc., quote it, and return
# the new string.
sub shell_quote($)
{
  my ($s) = @_;
  if ($s =~ m![^\w+/.,-]!)
    {
      # Convert each single quote to '\''
      $s =~ s/\'/\'\\\'\'/g;
      # Then single quote the string.
      $s = "'$s'";
    }
  return $s;
}

=item C<mktmpdir ($signature)>

Create a temporary directory which name is based on C<$signature>.
Store its name in C<$tmp>.  C<END> is in charge of removing it, unless
C<$debug>.

=cut

# mktmpdir ($SIGNATURE)
# ---------------------
sub mktmpdir ($)
{
  my ($signature) = @_;
  my $TMPDIR = $ENV{'TMPDIR'} || '/tmp';
  my $quoted_tmpdir = shell_quote ($TMPDIR);

  # If mktemp supports dirs, use it.
  $tmp = `(umask 077 &&
	   mktemp -d $quoted_tmpdir/"${signature}XXXXXX") 2>/dev/null`;
  chomp $tmp;

  if (!$tmp || ! -d $tmp)
    {
      $tmp = "$TMPDIR/$signature" . int (rand 10000) . ".$$";
      mkdir $tmp, 0700
	or croak "$me: cannot create $tmp: $!\n";
    }

  print STDERR "$me:$$: working in $tmp\n"
    if $debug;
}


=item C<uniq (@list)>

Return C<@list> with no duplicates, keeping only the first
occurrences.

=cut

# @RES
# uniq (@LIST)
# ------------
sub uniq (@)
{
  my @res = ();
  my %seen = ();
  foreach my $item (@_)
    {
      if (! exists $seen{$item})
	{
	  $seen{$item} = 1;
	  push (@res, $item);
	}
    }
  return wantarray ? @res : "@res";
}


=item C<handle_exec_errors ($command)>

Display an error message for C<$command>, based on the content of
C<$?> and C<$!>.

=cut


# handle_exec_errors ($COMMAND)
# -----------------------------
sub handle_exec_errors ($)
{
  my ($command) = @_;

  $command = (split (' ', $command))[0];
  if ($!)
    {
      error "failed to run $command: $!";
    }
  else
    {
      use POSIX qw (WIFEXITED WEXITSTATUS WIFSIGNALED WTERMSIG);

      if (WIFEXITED ($?))
	{
	  my $status = WEXITSTATUS ($?);
	  # WIFEXITED and WEXITSTATUS can alter $!, reset it so that
	  # error() actually propagates the command's exit status, not $!.
	  $! = 0;
	  error "$command failed with exit status: $status";
	}
      elsif (WIFSIGNALED ($?))
	{
	  my $signal = WTERMSIG ($?);
	  # In this case we prefer to exit with status 1.
	  $! = 1;
	  error "$command terminated by signal: $signal";
	}
      else
	{
	  error "$command exited abnormally";
	}
    }
}

=back

=head1 SEE ALSO

L<Autom4te::XFile>

=head1 HISTORY

Written by Alexandre Duret-Lutz E<lt>F<adl@gnu.org>E<gt> and Akim
Demaille E<lt>F<akim@freefriends.org>E<gt>.

=cut



1; # for require

### Setup "GNU" style for perl-mode and cperl-mode.
## Local Variables:
## perl-indent-level: 2
## perl-continued-statement-offset: 2
## perl-continued-brace-offset: 0
## perl-brace-offset: 0
## perl-brace-imaginary-offset: 0
## perl-label-offset: -2
## cperl-indent-level: 2
## cperl-brace-offset: 0
## cperl-continued-brace-offset: 0
## cperl-label-offset: -2
## cperl-extra-newline-before-brace: t
## cperl-merge-trailing-else: nil
## cperl-continued-statement-offset: 2
## End: