Document lots of new features and syntax.

[fwd] / scan.h

/* -*-c-*-
 *
 * $Id: scan.h,v 1.2 1999/07/26 23:24:33 mdw Exp $
 *
 * Character scanners
 *
 * (c) 1999 Straylight/Edgeware
 */

/*----- Licensing notice --------------------------------------------------* 
 *
 * This file is part of the `fw' port forwarder.
 *
 * `fw' is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 * 
 * `fw' 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 License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with `fw'; if not, write to the Free Software Foundation,
 * Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 */

/*----- Revision history --------------------------------------------------* 
 *
 * $Log: scan.h,v $
 * Revision 1.2  1999/07/26 23:24:33  mdw
 * Complete rewrite.  Allow a list of character sources to enable changes
 * during parsing of syntactic constructs.
 *
 * Revision 1.1.1.1  1999/07/01 08:56:23  mdw
 * Initial revision.
 *
 */

#ifndef SCAN_H
#define SCAN_H

#ifdef __cplusplus
  extern "C" {
#endif

/*----- Header files ------------------------------------------------------*/

#include <stdio.h>

#include <mLib/dstr.h>

/*----- Data structures ---------------------------------------------------*/

/* --- A low-level scanner source --- */

typedef struct scansrc {
  struct scansrc *next;			/* Next one in the list */
  struct scansrc_ops *ops;		/* Pointer to operations table */
  char *src;				/* Name of this source */
  int line;				/* Current line number */
  int pushback;				/* Pushback character */
  char *tok;				/* Token pushback */
  unsigned t;				/* Token type pushback */
} scansrc;

/* --- Scanner source operations --- */

typedef struct scansrc_ops {
  int (*scan)(scansrc */*ss*/);		/* Read another character */
  void (*destroy)(scansrc */*ss*/);	/* Destroy an unwanted source */
} scansrc_ops;

/* --- A character scanner --- */

typedef struct scanner {
  scansrc *head, **tail;		/* Scanner list head and tail */
  int t;				/* Token type */
  dstr d;				/* Current token value */
} scanner;

/*----- Particular scanner types ------------------------------------------*/

/* --- @scan_file@ --- *
 *
 * Arguments:	@FILE *fp@ = pointer to file descriptor
 *		@char *name@ = pointer to source file name
 *		@unsigned f@ = flags
 *
 * Returns:	A scanner source.
 *
 * Use:		Creates a new scanner source for reading from a file.
 */

extern scansrc *scan_file(FILE */*fp*/, char */*name*/, unsigned /*f*/);

#define SCF_NOCLOSE 1u
#define SCF_FREENAME 2u

/* --- @scan_argv@ --- *
 *
 * Arguments:	@char **av@ = pointer to argument array (null terminated)
 *
 * Returns:	A scanner source.
 *
 * Use:		Creates a new scanner source for reading from an @argv@
 *		array.
 */

extern scansrc *scan_argv(char **/*av*/);

/*----- General scanner handling ------------------------------------------*/

/* --- @scan@ --- *
 *
 * Arguments:	@scanner *sc@ = pointer to main scanner context
 *
 * Returns:	Character read, or end-of-file.
 *
 * Use:		Scans a character from a source of characters.
 */

extern int scan(scanner */*sc*/);    

/* --- @unscan@ --- *
 *
 * Arguments:	@scanner *sc@ = pointer to main scanner context
 *		@int ch@ = character to unscan
 *
 * Returns:	---
 *
 * Use:		Scans a character from a source of characters.
 */

extern void unscan(scanner */*sc*/, int /*ch*/);

/* --- @scan_push@ --- *
 *
 * Arguments:	@scanner *sc@ = pointer to main scanner context
 *		@scansrc *ss@ = souorce to push
 *
 * Returns:	---
 *
 * Use:		Pushes a scanner source onto the front of the queue.
 */

extern void scan_push(scanner */*sc*/, scansrc */*ss*/);

/* --- @scan_add@ --- *
 *
 * Arguments:	@scanner *sc@ = pointer to main scanner context
 *		@scansrc *ss@ = souorce to push
 *
 * Returns:	---
 *
 * Use:		Adds a scanner source onto the end of the queue.
 */

extern void scan_add(scanner */*sc*/, scansrc */*ss*/);

/* --- @scan_create@ --- *
 *
 * Arguments:	@scanner *sc@ = scanner context to initialize
 *
 * Returns:	---
 *
 * Use:		Initializes a scanner block ready for use.
 */

extern void scan_create(scanner */*sc*/);

/* --- @scan_destroy@ --- *
 *
 * Arguments:	@scanner *sc@ = pointer to scanner context
 *
 * Returns:	---
 *
 * Use:		Destroys a scanner and all the sources attached to it.
 */

extern void scan_destroy(scanner */*sc*/);

/*----- That's all, folks -------------------------------------------------*/

#ifdef __cplusplus
  }
#endif

#endif