aboutsummaryrefslogtreecommitdiff
path: root/gfsm/gfsm/src/libgfsm/gfsmIO.h
blob: 693169968a38a36220265bf3191b9c6ca602aa2b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
/*=============================================================================*\
 * File: gfsmIO.h
 * Author: Bryan Jurish <moocow@ling.uni-potsdam.de>
 * Description: finite state machine library: I/O
 *
 * Copyright (c) 2006-2008 Bryan Jurish.
 *
 * For information on usage and redistribution, and for a DISCLAIMER
 * OF ALL WARRANTIES, see the file "COPYING" in this distribution.
 *
 * 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
 *=============================================================================*/

/** \file gfsmIO.h
 *  \brief Abstract I/O routines
 */

#ifndef _GFSM_IO_H
#define _GFSM_IO_H

#include <gfsmConfig.h>
#include <gfsmError.h>

#include <stdarg.h>
#include <string.h>
#include <unistd.h>
#include <stdio.h>

#define GFSMIO_EOF ((int)-1)

/*======================================================================
 * I/O: types
 */

/** Builtin I/O types */
typedef enum {
  gfsmIOTCFile,         ///< I/O on a C FILE*
  gfsmIOTZFile,         ///< I/O on a zlib gzFile* (only if GFSM_ZLIB_ENABLED is defined)
  gfsmIOTGString,       ///< I/O on a GString*
  gfsmIOTUser = 255     ///< user I/O
} gfsmIOHandleType;

/*======================================================================
 * I/O: Handles: Function types
 */

/** Generic I/O Handle function type: fflush() and friends */
typedef void (*gfsmIOFlushFunc) (void *handle);

/** Generic I/O Handle function type: fclose() and friends */
typedef void (*gfsmIOCloseFunc) (void *handle);

/** Generic I/O Handle function type: feof() and friends */
typedef gboolean (*gfsmIOEofFunc) (void *handle);


/** Generic I/O Handle function type: fread() and friends */
typedef gboolean (*gfsmIOReadFunc)  (void *handle, void *buf, size_t nbytes);

/** Generic I/O Handle function type: getdelim() and friends */
typedef ssize_t (*gfsmIOGetdelimFunc)  (void *handle, char **lineptr, size_t *n, int delim);


/** Generic I/O Handle function type: fwrite() and friends */
typedef gboolean (*gfsmIOWriteFunc) (void *handle, const void *buf, size_t nbytes);

/** Generic I/O Handle function type: vprintf() and friends */
typedef int (*gfsmIOVprintfFunc) (void *handle, const char *fmt, va_list *app);



/*======================================================================
 * I/O: Handles: structs
 */

/** \brief Generic I/O handle struct */
typedef struct {
  gfsmIOHandleType    iotype;  ///< I/O class of this handle
  void               *handle;  ///< underlying handle data

  gfsmIOReadFunc     read_func;       /** fread() and friends (either read or getc must be defined) */
  gfsmIOGetdelimFunc getdelim_func;   /** getdelim() and friends (optional) */

  gfsmIOWriteFunc    write_func;     /** fwrite() and friends (either write or putc must be defined) */
  gfsmIOVprintfFunc  vprintf_func;   /** vprintf() and friends (optional) */

  gfsmIOFlushFunc    flush_func;     /** fflush() and friends (optional) */
  gfsmIOCloseFunc    close_func;     /** fclose() and friends (optional) */
  gfsmIOEofFunc      eof_func;       /** eof() and friends (optional) */
} gfsmIOHandle;


/** \brief GString with an associated index (read head) */
typedef struct {
  GString *gs;  ///< associated string
  size_t   pos; ///< (read-)position
} gfsmPosGString;

/*======================================================================
 * I/O: Handles: Constructors etc.
 */

/** create, initialize, and return a new gfsmIOHandle
 *  \param typ type of this handle
 *  \param handle_data value of the \a handle structure datum:
 *    \li for \a typ==gfsmIOTCFile , \a handle_data should be a FILE*
 *    \li for \a typ==gfsmIOTGString , \a handle_data should be a gfsmPosGString*
 *    \li for \a typ==gfsmIOTZFile   , \a handle_data should be a gzFile
 *    \li for \a typ==gfsmIOTUser , \a handle_data is whatever you want
 *
 * \returns new gfsmIOHandle
 */
gfsmIOHandle *gfsmio_handle_new(gfsmIOHandleType typ, void *handle_data);

/** destroy a gfsmIOHandle: does NOT implicitly call \a close or anything else */
void gfsmio_handle_free(gfsmIOHandle *ioh);

/* TODO: utilities ? file_handle_new, zfile_handle_new, gstring_handle_new, user_handle_new ? */

/** Create and return a new gfsmIOHandle to an uncompressed C FILE*
 *  Caller is responsible for closing the handle.
 */
gfsmIOHandle *gfsmio_new_file(FILE *f);

/** Create and return a new gfsmIOHandle to a C FILE* using compression (if available)
 *  Caller is responsible for closing the handle.
 *  The handle returned can always be closed without closing \a f itself.
 */
gfsmIOHandle *gfsmio_new_zfile(FILE *f, const char *mode, int compress_level);

/** Create and return a new gfsmIOHandle to a named file.
 *  Uses gzFile if zlib support was enabled, otherwise C FILE* (uncompressed)
 *  Caller is responsible for closing the handle.
 */
gfsmIOHandle *gfsmio_new_filename(const char *filename, const char *mode, int compress_level, gfsmError **errp);

/** Create and return a new gfsmIOHandle for a PosGString*
 *  Caller is responsible for allocation and de-allocation of the PosGString*.
 */
gfsmIOHandle *gfsmio_new_gstring(gfsmPosGString *pgs);

/*======================================================================
 * I/O: Handles: Methods: Basic
 */

/** close an open I/O handle (calls \a close_func) */
void gfsmio_close(gfsmIOHandle *ioh);

/** flush all data to an output handle (calls \a flush_func) */
void gfsmio_flush(gfsmIOHandle *ioh);

/** returns true if \a h is at EOF, false otherwise (or if no \a eof_func is defined) */
gboolean gfsmio_eof(gfsmIOHandle *ioh);



/*======================================================================
 * I/O: Handles: Methods: Read
 */

/** read a single byte of data from \a h, should return GFSMIO_EOF on EOF */
int gfsmio_getc(gfsmIOHandle *ioh);

/** read \a nbytes of data from \a io into \a buf, as \a fread() */
gboolean gfsmio_read(gfsmIOHandle *ioh, void *buf, size_t nbytes);

/** wrapper for getline(), returns number of bytes read (0 on error) */
ssize_t gfsmio_getline(gfsmIOHandle *ioh, char **lineptr, size_t *n);


/** wrapper for getdelim(), returns number of bytes read (0 on error) */
ssize_t gfsmio_getdelim(gfsmIOHandle *io, char **lineptr, size_t *n, int delim);



/*======================================================================
 * I/O: Handles: Methods: Write
 */

/** write a single byte to handle \a ioh, as \a fputc() */
gboolean gfsmio_putc(gfsmIOHandle *ioh, int c);

/** wrapper for puts() */
gboolean gfsmio_puts(gfsmIOHandle *io, const char *s);

/** write \a nbytes of data from \a buf into \a io, as \a fwrite() */
gboolean gfsmio_write(gfsmIOHandle *io, const void *buf, size_t nbytes);

/** wrapper for printf(): calls \a gfsmio_vprintf() */
int gfsmio_printf(gfsmIOHandle *io, const char *fmt, ...);

/** wrapper for vprintf(): calls \a vprintf_func */
int gfsmio_vprintf(gfsmIOHandle *io, const char *fmt, va_list *app);


#endif /* _GFSM_IO_H */