/***************************************************************************
 *   Copyright (C) 2008 by Peter Eschright                                 *
 *   petereschright@gmail.com                                              *
 *                                                                         *
 *   This source code is presented for informational purposes only.        *
 *   Please contact the author for permision for use.                      *
 **************************************************************************/

#ifndef USER_INPUT_H
#define USER_INPUT_H

#include <string.h>

/***************************************************************************
*                                                                          *
*  user_input.h                                                            *
*                                                                          *
*  A library for simple safe command line input from a user.               *
*  Include functions for inputing most data types, with error              *
*  checking and safety.                                                    *
*                                                                          *
*                                                                          *
*  Usage:                                                                  *
*                                                                          *
*  Compile and link with your project, or build seperatly and link.        *
*                                                                          *
*                                                                          *
***************************************************************************/



/**************************************************************
* Maximum read size for all functions is defined by READ_SIZE *
***************************************************************/
#define READ_SIZE 2048




/********************************
*                               *
*  Error codes                  *
*                               *
********************************/
/* user failed to input desired data type */
#define USER_INPUT_ERROR_BAD_INPUT 1
/* user input exceeded allowed size */
#define USER_INPUT_ERROR_TOO_LONG 2
/* std input stream was closed */
#define USER_INPUT_ERROR_CLOSED_STREAM 3
/* input read failed for other reason */
#define USER_INPUT_ERROR_FAILED_READ 4



/**************************************************
*                                                 *
*  Normalize a string:                            *
*  copy normalized str_1 to str_2                 *
*                                                 *
*  String is trimmed of preceding and trailing    *
*  whitespace. string has internal whitespace     *
*  collapsed to single space character.           *
*                                                 *
**************************************************/
void trim_and_normalize(char *str_2, char *str_1);


/*********************************
* read in an unsigned integer    *
* return 0 iff sucessful         *
* return error code if failed    *
*********************************/
int user_input_uint(unsigned int *get_number);

/*********************************
* read in an integer             *
* return 0 iff sucessful         *
* return error code if failed    *
*********************************/
int user_input_int(int *get_number);

/*********************************
* read in an float               *
* return 0 iff sucessful         *
* return error code if failed    *
*********************************/
int user_input_float(float *get_number);

/*************************************************
* read in an double                              *
*                                                *
* Function reads float and casts it to a double. *
* return 0 iff sucessful                         *
* return error code if failed                    *
*************************************************/
int user_input_double(double *get_number);

/*********************************
* read in a single char          *
* return 0 iff sucessful         *
* return error code if failed    *
*********************************/
int user_input_char(char *get_c);

/**************************************************
*  read in a string                               *
*                                                 *
*  String is trimmed of preceding and trailing    *
*  whitespace.                                    *
*                                                 *
*  upto size - 1 characters are read.             *
*  USER_INPUT_ERROR_BAD_INPUT is returned if      *
*  input was too long for get_str and remaining   *
*  input is removed from buffer.                  *
*                                                 *
*  return 0 iff sucessful                         *
*  return error code if failed                    *
**************************************************/
int user_input_str(char *get_str, int size);

/**************************************************
*  read in a word, defined as a continuos         *
*  string of non-whitespace characters.           *
*                                                 *
*  word is trimmed of preceding and trailing      *
*  whitespace.                                    *
*                                                 *
*  upto size - 1 characters are read.             *
*  USER_INPUT_ERROR_BAD_INPUT is returned if      *
*  input was too long for get_str and remaining   *
*  input is removed from buffer.                  *
*                                                 *
*  return 0 iff sucessful                         *
*  return error code if failed                    *
**************************************************/
int user_input_word(char *get_word, int size);


/**************************************************
*  read in a yes or no response,                  *
*  defined as follows                             *
*  string of non-whitespace characters.           *
*                                                 *
*  preceding whitespace and all characters        *
*  first word (see above) are ignored.            *
*                                                 *
*  answer is set to 1 iff yes or 0 iff no         *
*  or -1 iff error)                               *
*                                                 *
*  The input is then interpreted as follows:      *
*  input   interpretation   value of answer       *
*  YES     yes              1                     *
*  Yes     yes              1                     *
*  yes     yes              1                     *
*  Y       yes              1                     *
*  y       yes              1                     *
*  NO      no               0                     *
*  No      no               0                     *
*  no      no               0                     *
*  N       no               0                     *
*  n       no               0                     *
*  other   error            -1                    *
*                                                 *
*                                                 *
*  USER_INPUT_ERROR_BAD_INPUT is returned if      *
*  input was not of form described                *
*  Unused input is removed from buffer.           *
*                                                 *
*  return 0 iff sucessful                         *
*  return error code if failed                    *
**************************************************/
int user_input_yes_no(int *answer);


#endif