#ifndef STIB_UTIL_H
#define STIB_UTIL_H
/* ========================================================================== **
 *                                   util.h
 *
 * Copyright:
 *  Copyright (C) 2007 by Christopher R. Hertel
 *
 * Email: crh@ubiqx.mn.org
 *
 * $Id: util.h 53 2011-04-25 20:39:01Z crh $
 *
 * -------------------------------------------------------------------------- **
 *
 * Description:
 *  Utility functions used with the STiB tool.
 *
 * -------------------------------------------------------------------------- **
 *
 * License:
 *
 *  This library is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU Lesser General Public
 *  License as published by the Free Software Foundation; either
 *  version 2.1 of the License, or (at your option) any later version.
 *
 *  This library 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
 *  Lesser General Public License for more details.
 *
 *  You should have received a copy of the GNU Lesser General Public
 *  License along with this library; if not, write to the Free Software
 *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *
 * -------------------------------------------------------------------------- **
 *
 * Notes:
 *
 * ========================================================================== **
 */

#include <stdlib.h>     /* Standard library.         */
#include <stdint.h>     /* Standard integeter types. */
#include <stdbool.h>    /* Standard boolean type.    */
#include <stdio.h>      /* Standard Input/Output.    */
#include <stdarg.h>     /* Variable argument lists.  */
#include <string.h>     /* For strerror(3).          */
#include <errno.h>      /* For the <errno> external. */


/* -------------------------------------------------------------------------- **
 * Macros:
 *
 *  Err()   - Shorthand for (void)fprintf( stderr, ... )
 *  Say()   - Shorthand for (void)printf( ... )
 *            Yeah, these are kinda weenie but they're much quicker than
 *            typing out the entire function call.
 *  ErrStr  - Shorthand for the error message associated with <errno>.
 */

#define Err( ... ) (void)fprintf( stderr, __VA_ARGS__ )
#define Say( ... ) (void)printf( __VA_ARGS__ )
#define ErrStr     (strerror( errno ))


/* -------------------------------------------------------------------------- **
 * Exported functions:
 */

void Fail( char *fmt, ... );
  /* ------------------------------------------------------------------------ **
   * Format and print a failure message on <stderr>, then exit the process.
   *
   *  Input:  fmt - Format string, as used in printf(), etc.
   *          ... - Variable parameter list.
   *
   *  Output: none
   *
   *  Notes:  Exits the process returning EXIT_FAILURE.
   *
   * ------------------------------------------------------------------------ **
   */


void Usage( const char *msg[], const char *prognam );
  /* ------------------------------------------------------------------------ **
   * Print a usage message to <stdout>.
   *
   *  Input:  msg[]   - An array of strings; the usage message.
   *          prognam - The program name.
   *
   *  Output: <none>
   *
   *  Notes:  The error message is printed to <stdout> so that it can be
   *          easily piped through a program like "more" or "less".
   *
   * ------------------------------------------------------------------------ **
   */


int matchStr( const char *s, const char *m[] );
  /* ------------------------------------------------------------------------ **
   * Find a string that matches <s> in the set of strings <m[]>.
   *
   *  Input:  s   - A string to be matched.
   *          m[] - A set of strings that may match, presented as a
   *                NULL-terminated variable-length array of strings.
   *
   *  Output: The number (starting from 0) of the string in <m[]> that
   *          matched <s>, or -1 if there was no match.
   *
   *  Notes:  The string comparison is case-insensitive using <toupper(3)>.
   *
   * ------------------------------------------------------------------------ **
   */


bool prefixMatch( const char *src, const char *match, const unsigned int min );
  /* ------------------------------------------------------------------------ **
   * Perform a case-insensitive string match, limited to strlen( src ) bytes.
   *
   *  Input:  src   - A pointer to a string that may be a prefix of <match>.
   *          match - A pointer to the string against which to test.
   *          min   - Minimum length of <src> needed in order to declare
   *                  a match.
   *
   *  Output: Boolean <true> if the string in <src> is a prefix of <match>
   *          and <src> is at least <min> bytes in length, otherwise <false>.
   *
   *  Notes:  This function tests to see whether strlen( src ) bytes of
   *          <match> are the same as <src>.  So, for example:
   *            prefixMatch( "foo", "fooberry", 1 )  == true
   *            prefixMatch( "food", "fooberry", 1 ) == false
   *
   *          The <min> parameter is used to determine the minimum number
   *          of characters in <match> which must be matched.  So:
   *            prefixMatch( "foo", "fooberry", 3 ) == true
   *            prefixMatch( "foo", "fooberry", 4 ) == false
   *          since the string "foo" is not long enough to match 4 bytes of
   *          "fooberry".
   *
   *          The function is case insensitive, so:
   *            prefixMatch( "foo", "Fooberry", 3 ) == true
   *
   * ------------------------------------------------------------------------ **
   */


char *vString( char *Rev );
  /* ------------------------------------------------------------------------ **
   * Extract just the version number from a cvs or svn Revision string.
   *
   *  Input:  Rev - Full Revision string (including the dollar signs).
   *
   *  Output: Pointer to static space that contains the extracted version
   *          number string.
   *
   * ------------------------------------------------------------------------ **
   */

/* ========================================================================== */
#endif /* STIB_UTIL_H */