#!/bin/sh
# ------------------------------------------------------------------------------
#
# git-qheader.sh: Implement the Git-MQ "git qheader" extension command.
#
# Extracts and displays the log message text, as recorded in the header of
# the topmost applied, or any other nominated patch file.  Although it would
# be technically feasible to retrieve this information from arbitrary patch
# files, only patches which have been registered within the series file are
# currently considered; this restriction is consistent with the behaviour
# of Mercurial's corresponding "hg qheader" command.
#
# $Id$
#
# ------------------------------------------------------------------------------
#
# I'd have liked to call this a "SYNOPSIS", (which is what it is), but git's
# git-sh-setup script requires the much less appropriate name "OPTIONS_SPEC",
# (which describes only a small subset of its actual content).
#
OPTIONS_SPEC="\
git qheader [<patch>]

Display the header text for the current, or a nominated <patch>,
within the currently registered series of patches.
--"
#
# ------------------------------------------------------------------------------
#
# $Id$
#
# Written by Keith Marshall <keith@users.osdn.me>
# Copyright (C) 2018-2020, 2022, Keith Marshall
#
#
# This file is part of the Git-MQ program suite.
#
# The Git-MQ program suite is free software: you can redistribute it
# and/or modify it under the terms of the GNU General Public Licence
# as published by the Free Software Foundation, either version 3 of
# the Licence, or (at your option) any later version.
#
# The Git-MQ program suite 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 Licence for more details.
#
# You should have received a copy of the GNU General Public Licence
# along with this program.  If not, see <https://www.gnu.org/licenses/>.
#
# ------------------------------------------------------------------------------
#
# Although they may not always have any effect, all Git-MQ commands, like
# their hg counterparts, are expected to accept the global verbosity, and
# colour control options; ensure that they are declared:
#
OPTIONS_SPEC="$OPTIONS_SPEC
colour?*     generic output colour control -- may have no effect"
${OPTION_VERBOSE_DEFINED-false} || OPTIONS_SPEC="$OPTIONS_SPEC
v,verbose!*  generic verbosity selector -- may have no effect"

# For Git-MQ options, such as "--colour", we prefer a spelling convention
# which conforms to "World English" standards; however, git itself adopts
# "US English" convention.  Thus, we must also accommodate users who will
# specify "--color" instead of "--colour", without creating any ambiguity
# in the possible abbreviations; to achieve this, we check for "--color",
# among the command-line arguments, replacing it with "--colour", BEFORE
# we allow git to parse them.
#
for mq_argv
do case "$mq_argv" in
     --color*) mq_argv=`echo $mq_argv | sed 's/^--colo/&u/'` ;;
     --no-color) mq_argv="--no-colour" ;;
   esac
   ${mq_argv_init-true} && { set -- "$mq_argv"; mq_argv_init=false
   } || set -- "$@" "$mq_argv"
done

# Now, we may let git parse the command line, and set up its shell script
# processing environment, for use within a git working directory tree.
#
SUBDIRECTORY_OK=true . "`git --exec-path`/git-sh-setup" && require_work_tree

libexecdir=`dirname "$0"`
test `basename "$libexecdir"` = bin && libexecdir=`dirname "$libexecdir"`
libexecdir="$libexecdir/libexec/git-mq/${VERSION=1.0}"

mq_require(){ test -f "$1" || die "fatal: '$1' not found."; . "$1"; }
mq_require "$libexecdir/git-mq-setup.sh"

# Skip over any command line options; (there are none applicable to this
# command, but the global options are accepted, albeit silently ignored).
# Thereafter, ensure that no more than one <patch> argument remains.
#
while git_mq_getopt "$@"; do shift; done
test $# -gt 1 && $fatal "too many arguments
`usage | sed 1q`"

# We now need to scan the series and status files, either to identify the
# topmost applied patch, or to confirm that any nominated patch has been
# registered, (possibly looking up the name corresponding to a nominated
# patch index), before reading, and displaying, the header lines from the
# selected patch file.
#
mq_map_control_file_refs "$mq_patchdir" series status
awk "$mq_series $mq_status"' END { $0 = "'"$1"'";
  if( NF == 0 )
  { if( applied >= 0 ) $0 = series[applied];
    else { print "No patches have been applied."; exit 1; }
  }
  switch( lookup = $1 ) { case /^[0-9][0-9]*$/: $1 = 0 + $1; }
  if( ! ($1 in entry) && ($1 in series) ) $0 = series[$1];
  if( ! ($1 in entry) )
  { switch( lookup )
    { case /^[0-9][0-9]*$/:
	print "There is no patch with index", lookup, "in the series.";
	break;
      default:
	print "There is no \47" lookup "\47 in the patch series.";
    }
    exit 1;
  }
  lookup = "'"$mq_patchdir"'/" $1;
  while( lookup && ((getline < lookup) > 0) )
  { if( NF > 0 ) switch( $1 )
    { case /^#/: break;
      case "diff": close( lookup ); lookup = ""; break;
      default: while( blank_lines-- > 0 ) print ""; print; blank_lines = 0;
    }
    else ++blank_lines;
  }
}' "$mq_series_file" "$mq_status_file"
#
# ------------------------------------------------------------------------------
# $RCSfile$: end of file
