/*	gi_keyparm.h         Keyword Parameter Library

Copyright 2004 Eric L. Michelsen. All rights reserved.

All the declarations [needed to use][private to] the ?? module.

Author:        Eric L. Michelsen
Date Created:  9/21/04
============================================================================*/

#ifndef INC_KEYPARM_H
#define INC_KEYPARM_H   // Make sure the include happens only once

// ---------------- Requires                (do not remove) ---------------
// Requires <stdio.h> for FILE, "comtypes.h" for int32, etc.

// ---------------- Constants               (do not remove) ---------------

// ---------------- Structures/Types        (do not remove) ---------------
enum		// datatypes supported for keyword parameters
{ KP_END,	// end of list
  KP_INT,	// signed integer of various sizes
  KP_FLOAT,	// floating point of various sizes
  KP_STRING,	// nul terminated string
};
#define	KP_TYPE_MASK	0xF	// data-type bits
#define	KP_HEX		0x10	// format as hex (for integers)
#define	KP_READONLY	0x20	// don't allow setting w/ keyparm library

typedef	int32	keytype;

typedef struct
{   char *	name;		// keyword
    keytype     typeb;   	// data type & flags
    void *      adrs;   	// variable address
    int		size;		// variable size
    char *	comment;	// comment to display for user help
} keyentry;
// ---------------- Variables               (do not remove) ---------------

// ---------------- Prototypes/Macros       (do not remove) ---------------
#ifdef __cplusplus
extern "C" {
#endif
extern	int32	keyword_parameters(	// # keywords recognized, < 0 on error
  const	keyentry	klist[],	// list of parameters to recognize
  INOUT	int *		argc_ptr,	// updated with post-processing value
  INOUT	char *		argv[]);	// recognized parms removed

extern	keyentry *keyword_find(       	// ptr to klist entry
  const	keyentry	klist[],	// list of parameters to recognize
  const	char		*keyword);	// string to scan for parameters

extern	char * 	keyword_format(		// returns 'str'
  const	keyentry	*kptr,		// keyword entry to format
    OUT	char		*str);		// string for formatted output

extern	char * 	keyname_format_as(		// returns 'str'
  const	keyentry	klist[],	// list of parameters to recognize
  const	char		*kname,		// keyword name to format
    OUT	char		*str);		// string for formatted output

extern	int32	keyword_convert1(	// # of parameters recognized, < 0 on error
  const	keyentry	klist[],	// list of parameters to recognize
  INOUT	char		*ptr,		// string to scan for parameters
OUT const keyentry	**found,	// the matching keyentry
    OUT	char		**sptr,		// start of keyword
    OUT	char		**endptr);	// one past end of keyword value

extern	int32	keyword_scan(       	// # of parameters recognized, < 0 on error
  const	keyentry	klist[],	// list of parameters to recognize
  INOUT	char		*ptr);		// string to scan for parameters

extern	void	keyword_fprint(
	FILE		*fp,		// file pointer to print to
  const	keyentry	klist[],	// list of parameters to print
	bool		comments);	// true to print comments (long form)

#ifdef __cplusplus
}
#endif
#endif // INC_KEYPARM_H