/* vooly.h -- A pure C, fast Vooly parser
   Copyright (C) 2005  Christian Neukirchen <chneukirchen@gmail.com>  */

#ifndef _VOOLY_H_
#define _VOOLY_H_

/* The maximum nesting depth of Vooly tags.  */
#define VOOLY_MAXDEPTH  256

/* The default size of the allocated all-purpose buffer.  */
#define VOOLY_DEFAULT_SIZE  128

/* VoolyState holds the current state of the parser.  There are five
   states, each has a char associated to ease debugging.  */ 
enum VoolyState {
  VOOLY_TEXT  = '*',		/* Parsing text/tag contents.  */
  VOOLY_OPEN  = '<',		/* Parsing the tag name.       */
  VOOLY_CLOSE = '>',		/* The tag just ended.         */
  VOOLY_ERROR = '!',		/* A (fatal) error happened.   */
  VOOLY_EOF   = '.'		/* EOF was found.              */
};

/* VoolyStrip is the way to deal with whitespace.
     VOOLY_STRIP_PURE:  If vp->text is only whitespace (as by isspace(3)),
                        clear it, else keep the whole text.
     VOOLY_STRIP_ALL:   Strip all leading and trailing whitespace.
     VOOLY_STRIP_NONE:  Strip nothing.  */
enum VoolyStrip {
  VOOLY_STRIP_ALL = 1,
  VOOLY_STRIP_NEVER,
  VOOLY_STRIP_PURE
};

/* VoolyParser encapsulates the state of a Vooly pull parser.  All
   functions in vooly.c deal with pointers to VoolyParser.  */
typedef struct VoolyParser {
  enum {
    VOOLY_IO_PARSER = 1,
    VOOLY_STR_PARSER
  } style;
  union {
    FILE *io;			/* The stream to be parsed.  */
    struct {
      char *string;		/* The string to be parsed.  */
      char *last;		/* Its last char.  */
    } str;
  } source;
  enum VoolyStrip strip;	/* The way of whitespace handling.  */

  enum VoolyState state;	/* Public: The current state of the parser.  */
  enum VoolyState next_state;	/* The state that will follow at the
				   next state change. */
  
  /* The number of braces of the open tags. */
  unsigned long depths[VOOLY_MAXDEPTH];
  unsigned long *depth;		/* Head of DEPTHS.  */

  /* The current position in the stream IO.  (Why doesn't ftell(3)
     work with non-seekable streams?)  */
  unsigned long filepos;

 /* The offsets in the stream where tags were opened (for error
    reporting).  */
  unsigned long offsets[VOOLY_MAXDEPTH];
  unsigned long *offset;	/* Head of OFFSETS.  */

  /* The current text of the parser.  Depends on the STATE:
     VOOLY_TEXT   The read text.
     VOOLY_OPEN   The name of the tag just opened, or NULL for unnamed tags.
     VOOLY_CLOSE  Always NULL.
     VOOLY_ERROR  The error message.
     VOOLY_EOF    Always NULL.

     The data to be read by the parsing function ranges from text to
     text+size.  */
  char *text;			/* Public. */
  unsigned long size;		/* Public. */
  
  /* All-purpose buffer, contains TEXT, but possibly more.  */
  char *buffer;

  /* Size of bytes allocated for BUFFER.  */
  unsigned long alloc;
} VoolyParser;

/* These are a few accessor macros, please use them and do not access
   VoolyParser fields directly.  */

/* Return the current state of the parser.  */
#define vooly_state(vp)  ((vp)->state)

/* Return a pointer to the start of the text buffer.  */
#define vooly_text(vp)   ((vp)->text)

/* Return the size of the text buffer.  */
#define vooly_size(vp)   ((vp)->size)

/* Prototypes for Vooly functions.  */

/* Return a new VoolyParser that will parse from the FILE* IO and
   perform whitespace stripping according to enum VoolyStrip STRIP
   (see vooly.h for the modes available).  Returns NULL if there is
   not enough memory available.  */
VoolyParser* vooly_new_io_parser(FILE *io, enum VoolyStrip strip);

/* Return a new VoolyParser that will parse from the char* STRING
   sized SIZE and perform whitespace stripping according to enum
   VoolyStrip STRIP (see vooly.h for the modes available).  Returns
   NULL if there is not enough memory available.  */
VoolyParser *vooly_new_str_parser(char *string, size_t length, enum VoolyStrip strip);

/* Free a VoolyParser VP created by vooly_new_parser.  */
void vooly_free_parser (VoolyParser *vp);

/* Parse one token using the VoolyParser VP.  Will set text, size and
   state of the parser VP.  Returns 1 if it wants to be called again,
   and 0 if there is nothing more to parse, either because of errors
   or EOF.  */
int vooly_next(VoolyParser *vp);

#endif  /* _VOOLY_H_ */