CtplInputStream

CtplInputStream — CTPL's data input stream

Synopsis

#include <ctpl/input-stream.h>

#define             CTPL_EOF
#define             CTPL_BLANK_CHARS
#define             ctpl_is_blank                       (c)
#define             CTPL_SYMBOL_CHARS
#define             ctpl_is_symbol                      (c)
#define             CTPL_ESCAPE_CHAR
#define             CTPL_STRING_DELIMITER_CHAR
struct              CtplInputStream;
CtplInputStream *   ctpl_input_stream_new               (GInputStream *stream,
                                                         const gchar *name);
CtplInputStream *   ctpl_input_stream_new_for_gfile     (GFile *file,
                                                         GError **error);
CtplInputStream *   ctpl_input_stream_new_for_memory    (const gchar *data,
                                                         gssize length,
                                                         GDestroyNotify destroy,
                                                         const gchar *name);
CtplInputStream *   ctpl_input_stream_new_for_path      (const gchar *path,
                                                         GError **error);
CtplInputStream *   ctpl_input_stream_new_for_uri       (const gchar *uri,
                                                         GError **error);
CtplInputStream *   ctpl_input_stream_ref               (CtplInputStream *stream);
void                ctpl_input_stream_unref             (CtplInputStream *stream);
void                ctpl_input_stream_set_error         (CtplInputStream *stream,
                                                         GError **error,
                                                         GQuark domain,
                                                         gint code,
                                                         const gchar *format,
                                                         ...);
gssize              ctpl_input_stream_read              (CtplInputStream *stream,
                                                         void *buffer,
                                                         gsize count,
                                                         GError **error);
gchar               ctpl_input_stream_get_c             (CtplInputStream *stream,
                                                         GError **error);
gdouble             ctpl_input_stream_read_double       (CtplInputStream *stream,
                                                         GError **error);
glong               ctpl_input_stream_read_long         (CtplInputStream *stream,
                                                         GError **error);
gboolean            ctpl_input_stream_read_number       (CtplInputStream *stream,
                                                         CtplValue *value,
                                                         GError **error);
gchar *             ctpl_input_stream_read_string_literal
                                                        (CtplInputStream *stream,
                                                         GError **error);
#define             ctpl_input_stream_read_symbol       (stream,
                                                         error)
gchar *             ctpl_input_stream_read_symbol_full  (CtplInputStream *stream,
                                                         gssize max_len,
                                                         gsize *length,
                                                         GError **error);
gchar *             ctpl_input_stream_read_word         (CtplInputStream *stream,
                                                         const gchar *accept,
                                                         gssize accept_len,
                                                         gssize max_len,
                                                         gsize *length,
                                                         GError **error);
gssize              ctpl_input_stream_peek              (CtplInputStream *stream,
                                                         void *buffer,
                                                         gsize count,
                                                         GError **error);
gchar               ctpl_input_stream_peek_c            (CtplInputStream *stream,
                                                         GError **error);
#define             ctpl_input_stream_peek_symbol       (stream,
                                                         max_len,
                                                         error)
gchar *             ctpl_input_stream_peek_symbol_full  (CtplInputStream *stream,
                                                         gssize max_len,
                                                         gsize *length,
                                                         GError **error);
gchar *             ctpl_input_stream_peek_word         (CtplInputStream *stream,
                                                         const gchar *accept,
                                                         gssize accept_len,
                                                         gssize max_len,
                                                         gsize *length,
                                                         GError **error);
gssize              ctpl_input_stream_skip              (CtplInputStream *stream,
                                                         gsize count,
                                                         GError **error);
gssize              ctpl_input_stream_skip_blank        (CtplInputStream *stream,
                                                         GError **error);
gssize              ctpl_input_stream_skip_word         (CtplInputStream *stream,
                                                         const gchar *reject,
                                                         gssize reject_len,
                                                         GError **error);
gboolean            ctpl_input_stream_eof               (CtplInputStream *stream,
                                                         GError **error);
gboolean            ctpl_input_stream_eof_fast          (CtplInputStream *stream);

Description

The data input stream used by CTPL. This is a buffered input stream on top of GInputStream with current position informations (line and position) and some read scheme facilities (words (ctpl_input_stream_read_word()), string literals (ctpl_input_stream_read_string_literal()), ...).

A CtplInputStream is created with ctpl_input_stream_new(). There is some convenient wrappers to create it from in-memory data (ctpl_input_stream_new_for_memory()), GFiles (ctpl_input_stream_new_for_gfile()), path (ctpl_input_stream_new_for_path()) and URIs (ctpl_input_stream_new_for_uri()). CtplInputStream object uses a GObject-like refcounting, via ctpl_input_stream_ref() and ctpl_input_stream_unref().

Details

CTPL_EOF

#define CTPL_EOF  0

End-Of-File constant.

Since 0.2


CTPL_BLANK_CHARS

#define CTPL_BLANK_CHARS  " \t\v\r\n"

Characters treated as blank, commonly used as separator.


ctpl_is_blank()

#define             ctpl_is_blank(c)

Checks whether a character is one from CTPL_BLANK_CHARS, but can be more optimized than a simple search in the string.

c :

A character

Returns :

TRUE is c is a blank character, FALSE otherwise.

Since 0.2


CTPL_SYMBOL_CHARS

#define             CTPL_SYMBOL_CHARS

Characters that are valid for a symbol.


ctpl_is_symbol()

#define             ctpl_is_symbol(c)

Checks whether a character is one from CTPL_SYMBOL_CHARS, but can be more optimized than a simple search in the string.

c :

A character

Returns :

TRUE is c is a symbol character, FALSE otherwise.

Since 0.2


CTPL_ESCAPE_CHAR

#define CTPL_ESCAPE_CHAR  '\\'

Character used to escape a special character.


CTPL_STRING_DELIMITER_CHAR

#define CTPL_STRING_DELIMITER_CHAR '"'

Character surrounding string literals.


struct CtplInputStream

struct CtplInputStream {
};

An opaque object representing an input data stream.


ctpl_input_stream_new ()

CtplInputStream *   ctpl_input_stream_new               (GInputStream *stream,
                                                         const gchar *name);

Creates a new CtplInputStream for a GInputStream. This function adds a reference to the GInputStream.

stream :

A GInputStream

name :

The name of the stream, or NULL for none. This is used to identify the stream in error messages

Returns :

A new CtplInputStream

Since 0.2


ctpl_input_stream_new_for_gfile ()

CtplInputStream *   ctpl_input_stream_new_for_gfile     (GFile *file,
                                                         GError **error);

Creates a new CtplInputStream for a GFile. This is a wrapper around g_file_read() that also sets the name of the stream to the file's name. The errors this function can throw are those from the G_IO_ERROR domain. See ctpl_input_stream_new().

file :

A GFile to read

error :

Return location for errors, or NULL to ignore them

Returns :

A new CtplInputStream on success, NULL on error.

Since 0.2


ctpl_input_stream_new_for_memory ()

CtplInputStream *   ctpl_input_stream_new_for_memory    (const gchar *data,
                                                         gssize length,
                                                         GDestroyNotify destroy,
                                                         const gchar *name);

Creates a new CtplInputStream for in-memory data. This is a wrapper around GMemoryInputStream; see ctpl_input_stream_new().

data :

Data for which create the stream

length :

length of data

destroy :

GDestroyNotify to call on data when finished, or NULL

name :

The name of the stream to identify it in error messages

Returns :

A new CtplInputStream for the given data

Since 0.2


ctpl_input_stream_new_for_path ()

CtplInputStream *   ctpl_input_stream_new_for_path      (const gchar *path,
                                                         GError **error);

Creates a new CtplInputStream for a path. This is a wrapper for ctpl_input_stream_new_for_gfile() that simply creates a GFile for the given path and call ctpl_input_stream_new_for_gfile() on it.

path :

A path

error :

Return location for errors, or NULL to ignore them

Returns :

A new CtplInputStream on success, NULL on error.

Since 0.2


ctpl_input_stream_new_for_uri ()

CtplInputStream *   ctpl_input_stream_new_for_uri       (const gchar *uri,
                                                         GError **error);

Creates a new CtplInputStream for an URI. This is a wrapper for ctpl_input_stream_new_for_gfile() that simply creates a GFile for the given URI and call ctpl_input_stream_new_for_gfile() on it.

uri :

An URI

error :

Return location for errors, or NULL to ignore them

Returns :

A new CtplInputStream on success, NULL on error.

Since 0.2


ctpl_input_stream_ref ()

CtplInputStream *   ctpl_input_stream_ref               (CtplInputStream *stream);

Adds a reference to a CtplInputStream.

stream :

A CtplInputStream

Returns :

The stream

Since 0.2


ctpl_input_stream_unref ()

void                ctpl_input_stream_unref             (CtplInputStream *stream);

Removes a reference from a CtplInputStream. If the reference count drops to 0, frees the stream.

stream :

A CtplInputStream

Since 0.2


ctpl_input_stream_set_error ()

void                ctpl_input_stream_set_error         (CtplInputStream *stream,
                                                         GError **error,
                                                         GQuark domain,
                                                         gint code,
                                                         const gchar *format,
                                                         ...);

This is a wrapper around g_set_error() that adds stream's position information to the reported error.

stream :

A CtplInputStream

error :

A GError to fill, may be NULL

domain :

The domain of the error to report

code :

The code of the error

format :

printf-like format string

... :

printf-like arguments for format

Since 0.2


ctpl_input_stream_read ()

gssize              ctpl_input_stream_read              (CtplInputStream *stream,
                                                         void *buffer,
                                                         gsize count,
                                                         GError **error);

Reads data from a CtplInputStream.

stream :

A CtplInputStream

buffer :

buffer to fill with the read data

count :

number of bytes to read

error :

return location for errors, or NULL to ignore them

Returns :

The number of bytes read, or -1 on error.

Since 0.2


ctpl_input_stream_get_c ()

gchar               ctpl_input_stream_get_c             (CtplInputStream *stream,
                                                         GError **error);

Reads a character from a CtplInputStream.

stream :

A CtplInputStream

error :

Return location for errors, or NULL to ignore them

Returns :

The read character, or CTPL_EOF at stream's end or on error

Since


ctpl_input_stream_read_double ()

gdouble             ctpl_input_stream_read_double       (CtplInputStream *stream,
                                                         GError **error);

Reads a real form a CtplInputStream. See ctpl_input_stream_read_number() for details.

stream :

A CtplInputStream

error :

Return location for errors, or NULL to ignore them

Returns :

The read value, or 0 on error.

Since 0.2


ctpl_input_stream_read_long ()

glong               ctpl_input_stream_read_long         (CtplInputStream *stream,
                                                         GError **error);

Reads an integer from a CtplInputStream. See ctpl_input_stream_read_number() for details.

stream :

A CtplInputStream

error :

Return location for errors, or NULL to ignore them

Returns :

The read integer, or 0 on error.

Since 0.2


ctpl_input_stream_read_number ()

gboolean            ctpl_input_stream_read_number       (CtplInputStream *stream,
                                                         CtplValue *value,
                                                         GError **error);

Reads a number from a CtplInputStream. A number can be a plain decimal integer, a binary integer prefixed with 0b, an octal integer prefixed with 0o, a hexadecimal integer prefixed with 0x, a decimal real with possible decimal exponent separated by a e or a hexadecimal real with possible decimal power separated by a p; each possibly preceded by a plus or minus sign. The decimal point of real numbers is always a period (.).

Example 11. Some numeric constants

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
/* Decimal integers */
42
+512
/* Binary integers */
0b11
/* Octal integers */
0o755
/* Hexadecimal integers */
-0x7FFBE
0x8ff
/* Decimal reals */
+2.1
1.024e3
/* Hexadecimal reals */
0x71F.A0
-0x88fe.2p8


Warning

This function may modify errno.

stream :

A CtplInputStream

value :

A CtplValue to fill with the read number, either CTPL_VTYPE_INT or CTPL_VTYPE_FLOAT

error :

Return location for errors, or NULL to ignore them

Returns :

TRUE on success, FALSE otherwise.

Since 0.2


ctpl_input_stream_read_string_literal ()

gchar *             ctpl_input_stream_read_string_literal
                                                        (CtplInputStream *stream,
                                                         GError **error);

Reads a string quoted with CTPL_STRING_DELIMITER_CHAR, containing possible escaping sequences escaped by CTPL_ESCAPE_CHAR. A plain CTPL_ESCAPE_CHAR need to be escaped too, otherwise it will simply escape the next character.

For instance, a string might look like this, assuming the escape character is \ (backslash) and the quoting character is " (double quote): "a valid string with \"special\" characters such as \\ (backslash)"

stream :

A CtplInputStream

error :

Return location for errors, or NULL to ignore them

Returns :

The read string, or NULL on error

Since 0.2


ctpl_input_stream_read_symbol()

#define             ctpl_input_stream_read_symbol(stream, error)

Reads a symbol (a word composed of the characters from CTPL_SYMBOL_CHARS). See ctpl_input_stream_read_word() and ctpl_input_stream_read_symbol_full().

stream :

A CtplInputStream

error :

return location for errors, or NULL to ignore them

Returns :

A newly allocated string containing the read symbol, or NULL on error.

Since 0.2


ctpl_input_stream_read_symbol_full ()

gchar *             ctpl_input_stream_read_symbol_full  (CtplInputStream *stream,
                                                         gssize max_len,
                                                         gsize *length,
                                                         GError **error);

Reads a symbol from a CtplInputStream. A symbol is a word composed of the characters from CTPL_SYMBOL_CHARS. See ctpl_input_stream_read_word() and ctpl_input_stream_read_symbol().

stream :

A CtplInputStream

max_len :

The maximum number of bytes to read, or -1 for no limit

length :

Return location for the read symbol length, or NULL

error :

return location for errors, or NULL to ignore them

Returns :

A newly allocated string containing the read symbol, or NULL on error.

Since 0.2


ctpl_input_stream_read_word ()

gchar *             ctpl_input_stream_read_word         (CtplInputStream *stream,
                                                         const gchar *accept,
                                                         gssize accept_len,
                                                         gssize max_len,
                                                         gsize *length,
                                                         GError **error);

Reads a word from a CtplInputStream. A word is a sequence of characters referenced by accept. Note that the word might be empty if no characters matching accept are found before one that doesn't match.

For example, reading a word composed of any ASCII lowercase characters may be as the following:

1
2
3
4
5
6
7
8
9
10
11
gchar  *word;
GError *error = NULL;

word = ctpl_input_stream_read_word (stream, "abcdefghijklmnopqrstuvwxyz", -1,
                                    -1, NULL, &error);
if (! word) {
  /* deal with the error */
} else {
  printf ("Read the word \"%s\"\n", word);
  g_free (word);
}

stream :

A CtplInputStream

accept :

string of the character acceptable for the word

accept_len :

length of accept, can be -1 if accept is 0-terminated

max_len :

maximum number of bytes to read, or -1 for no limit

length :

return location for the length of the read word, or NULL

error :

Return location for errors, or NULL to ignore them

Returns :

A newly allocated string containing the read word that should be freed with g_free() when no longer needed; or NULL on error.

Since 0.2


ctpl_input_stream_peek ()

gssize              ctpl_input_stream_peek              (CtplInputStream *stream,
                                                         void *buffer,
                                                         gsize count,
                                                         GError **error);

Peeks data from a CtplInputStream. Peeking data is like reading, but it doesn't removes the data from the stream.

Warning

A peek might resize the internal stream's cache to fit at least count. Therefore, peeking too much data at once should be done with some care.

stream :

A CtplInputStream

buffer :

buffer to fill with the peeked data

count :

number of bytes to peek

error :

return location for errors, or NULL to ignore them

Returns :

the number of bytes peeked, or -1 on error

Since 0.2


ctpl_input_stream_peek_c ()

gchar               ctpl_input_stream_peek_c            (CtplInputStream *stream,
                                                         GError **error);

Peeks a character from a CtplInputStream. This may be implemented as a macro.

stream :

A CtplInputStream

error :

Return location for errors, or NULL to ignore them

Returns :

The peeked character, or CTPL_EOF at end of the stream or on error

Since 0.2


ctpl_input_stream_peek_symbol()

#define             ctpl_input_stream_peek_symbol(stream, max_len, error)

Peeks a symbol from a CtplInputStream. See ctpl_input_stream_peek_word() and ctpl_input_stream_peek_symbol_full().

stream :

A CtplInputStream

max_len :

The maximum number of bytes to peek, even if they still matches, or -1 for no limit

error :

Return location for errors, or NULL to ignore them

Returns :

A newly allocated string containing the peeked symbol, or NULL on error.

Since 0.2


ctpl_input_stream_peek_symbol_full ()

gchar *             ctpl_input_stream_peek_symbol_full  (CtplInputStream *stream,
                                                         gssize max_len,
                                                         gsize *length,
                                                         GError **error);

Peeks a symbol from a CtplInputStream. See ctpl_input_stream_peek_word() and ctpl_input_stream_peek_symbol().

stream :

A CtplInputStream

max_len :

The maximum number of bytes to peek, even if they still matches, or -1 for no limit

length :

Return location for the peeked length, or NULL

error :

Return location for errors, or NULL to ignore them

Returns :

A newly allocated string containing the peeked symbol, or NULL on error.

Since 0.2


ctpl_input_stream_peek_word ()

gchar *             ctpl_input_stream_peek_word         (CtplInputStream *stream,
                                                         const gchar *accept,
                                                         gssize accept_len,
                                                         gssize max_len,
                                                         gsize *length,
                                                         GError **error);

Peeks a word from a CtplInputStream. See ctpl_input_stream_peek() and ctpl_input_stream_read_word().

stream :

A CtplInputStream

accept :

string of the character acceptable for the word

accept_len :

length of accept, can be -1 if accept is 0-terminated

max_len :

maximum number of bytes to peek, or -1 for no limit

length :

return location for the length of the read word, or NULL

error :

return location for errors, or NULL to ignore them

Returns :

A newly allocated string containing the peeked word that should be freed with g_free() when no longer needed; or NULL on error.

Since 0.2


ctpl_input_stream_skip ()

gssize              ctpl_input_stream_skip              (CtplInputStream *stream,
                                                         gsize count,
                                                         GError **error);

Skips count bytes from a CtplInputStream.

stream :

A CtplInputStream

count :

Number of bytes to skip

error :

Return location for errors, or NULL to ignore them

Returns :

The number of skipped bytes, or -1 on error.

Since


ctpl_input_stream_skip_blank ()

gssize              ctpl_input_stream_skip_blank        (CtplInputStream *stream,
                                                         GError **error);

Skips blank characters (as reported by ctpl_is_blank()). See ctpl_input_stream_skip().

stream :

A CtplInputStream

error :

Return location for errors, or NULL to ignore them

Returns :

The number of skipped characters.

Since 0.2


ctpl_input_stream_skip_word ()

gssize              ctpl_input_stream_skip_word         (CtplInputStream *stream,
                                                         const gchar *reject,
                                                         gssize reject_len,
                                                         GError **error);

Skips all the characters matching reject from a CtplInputStream until the first that doesn't match.

stream :

A CtplInputStream

reject :

A string of the characters to skip

reject_len :

Length of reject, can be -1 if 0-terminated

error :

Return location for errors, or NULL to ignore them

Returns :

The number of skipped bytes, or -1 on error.

Since 0.2


ctpl_input_stream_eof ()

gboolean            ctpl_input_stream_eof               (CtplInputStream *stream,
                                                         GError **error);

Reliably checks if the stream reached its end. The error this function can throw are from the G_IO_ERROR domain.

Warning

The return value of this function is quite uncommon: it returns TRUE if at stream's end, but also on error. This is to be more convenient since this function is mainly used to ensure the stream does NOT have reached its end. To differentiate an error from EOF, check if the error was set.

stream :

A CtplInputStream

error :

return location for errors, or NULL to ignore them

Returns :

FALSE if not at EOF, TRUE otherwise (note that this includes I/O error).

Since 0.2


ctpl_input_stream_eof_fast ()

gboolean            ctpl_input_stream_eof_fast          (CtplInputStream *stream);

Checks if a CtplInputStream reached its end. See also ctpl_input_stream_eof().

Warning

This function is reliable only to know if the stream already reached EOF, not if next read will do so. To reliably check whether the stream have data to be read, first call a function that will do a read if necessary, and then reach the end of the stream. For example, use ctpl_input_stream_peek_c():

1
2
3
4
5
ctpl_input_stream_peek_c (stream, &error);
/* deal with the possible error */
if (ctpl_input_stream_eof_fast (stream)) {
  /* here EOF is reliable */
}

There is also a reliable version, but that can fail: ctpl_input_stream_eof().

stream :

A CtplInputStream

Returns :

TRUE if at end of stream, FALSE otherwise.