CtplInputStream: CTPL Reference Manual

## CtplInputStream CtplInputStream — CTPL's data input stream |

## Functions

CtplInputStream * | ctpl_input_stream_new ()
CtplInputStream * | ctpl_input_stream_new_for_gfile ()
CtplInputStream * | ctpl_input_stream_new_for_memory ()
CtplInputStream * | ctpl_input_stream_new_for_path ()
CtplInputStream * | ctpl_input_stream_new_for_uri ()
CtplInputStream * | ctpl_input_stream_ref ()
void | ctpl_input_stream_unref ()
GInputStream * | ctpl_input_stream_get_stream ()
const gchar * | ctpl_input_stream_get_name ()
guint | ctpl_input_stream_get_line ()
guint | ctpl_input_stream_get_line_position ()
void | ctpl_input_stream_set_error ()
gssize | ctpl_input_stream_read ()
gchar | ctpl_input_stream_get_c ()
gdouble | ctpl_input_stream_read_float ()
glong | ctpl_input_stream_read_int ()
gboolean | ctpl_input_stream_read_number ()
gchar * | ctpl_input_stream_read_string_literal ()
#define | ctpl_input_stream_read_symbol()
gchar * | ctpl_input_stream_read_symbol_full ()
gchar * | ctpl_input_stream_read_word ()
gssize | ctpl_input_stream_peek ()
gchar | ctpl_input_stream_peek_c ()
#define | ctpl_input_stream_peek_symbol()
gchar * | ctpl_input_stream_peek_symbol_full ()
gchar * | ctpl_input_stream_peek_word ()
gssize | ctpl_input_stream_skip ()
gssize | ctpl_input_stream_skip_blank ()
gssize | ctpl_input_stream_skip_word ()
gboolean | ctpl_input_stream_eof ()
gboolean | ctpl_input_stream_eof_fast ()

## Types and Values

#define | CTPL_EOF
| CtplInputStream

## Includes

    #include <ctpl/ctpl.h>

## Description

The data input stream used by CTPL. This is a buffered input stream on top of GInputStream with current position information (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()`.

The errors that the functions in this module can throw comes from the `G_IO_ERROR` or `CTPL_IO_ERROR` domains unless otherwise mentioned.

## Functions

### 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.

#### Parameters

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()`.

#### Parameters

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()`.

#### Parameters

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.

#### Parameters

path | A local or absolute path to pass to `g_file_new_for_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.

#### Parameters

uri | A URI to pass to `g_file_new_for_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.

#### Parameters

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.

#### Parameters

stream | A CtplInputStream |

Since: 0.2

### ctpl_input_stream_get_stream ()

    GInputStream *
    ctpl_input_stream_get_stream (const CtplInputStream *stream);

Gets the underlying GInputStream associated with a CtplInputStream.

#### Parameters

stream | A CtplInputStream |

#### Returns

The underlying GInputStream of `stream` .

[transfer none]

Since: 0.3

### ctpl_input_stream_get_name ()

    const gchar *
    ctpl_input_stream_get_name (const CtplInputStream *stream);

Gets the name associated with a CtplInputStream.

#### Parameters

stream | A CtplInputStream |

#### Returns

The name associated with `stream` , or `NULL` if none.

[allow-none]

Since: 0.3

### ctpl_input_stream_get_line ()

    guint
    ctpl_input_stream_get_line (const CtplInputStream *stream);

Gets the current line number of a CtplInputStream.

#### Parameters

stream | A CtplInputStream |

#### Returns

The current line number associated with `stream` .

Since: 0.3

### ctpl_input_stream_get_line_position ()

    guint
    ctpl_input_stream_get_line_position (const CtplInputStream *stream);

Gets the current offset position in the current line, in bytes, in a CtplInputStream.

#### Parameters

stream | A CtplInputStream |

#### Returns

The current offset in the current line.

Since: 0.3

### 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.

#### Parameters

stream | A CtplInputStream |
error | A GError to fill, may be `NULL`. | [out callee-allocates][allow-none]
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.

#### Parameters

stream | A CtplInputStream |
buffer | buffer to fill with the read data |
count | number of bytes to read (must be less than or qual to `G_MAXSSIZE`, or a `G_IO_ERROR_INVALID_ARGUMENT` will be thrown) |
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.

#### Parameters

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: 0.2

### ctpl_input_stream_read_float ()

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

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

#### Parameters

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_int ()

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

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

#### Parameters

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 15. 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

#### Parameters

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 `"` (double quote), containing possible escaping sequences escaped by `\` (backslash). A plain escaping character (backslash) need to be escaped too, otherwise it will simply escape the next character.

For instance, a string might look like this:

    1
    -->and \" (double quotes)" ]|

#### Parameters

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()`.

#### Parameters

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()`.

#### Parameters

stream | A CtplInputStream |
max_len | The maximum number of bytes to read, or -1 for no limit. | [default -1]
length | Return location for the read symbol length, or `NULL`. | [out][allow-none]
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);
    }

#### Parameters

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. | [default -1]
length | return location for the length of the read word, or `NULL`. | [out][allow-none]
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.

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.

#### Parameters

stream | A CtplInputStream |
buffer | buffer to fill with the peeked data |
count | number of bytes to peek (must be less than or qual to `G_MAXSSIZE`, or a `G_IO_ERROR_INVALID_ARGUMENT` will be thrown) |
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.

#### Parameters

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()`.

#### Parameters

stream | A CtplInputStream |
max_len | The maximum number of bytes to peek, even if they still matches, or -1 for no limit. | [default -1]
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()`.

#### Parameters

stream | A CtplInputStream |
max_len | The maximum number of bytes to peek, even if they still matches, or -1 for no limit. | [default -1]
length | Return location for the peeked length, or `NULL`. | [out][allow-none]
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()`.

#### Parameters

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. | [default -1]
length | return location for the length of the read word, or `NULL`. | [out][allow-none]
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.

#### Parameters

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: 0.2

### 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()`.

#### Parameters

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.

#### Parameters

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.

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.

#### Parameters

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()`.

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()`.

#### Parameters

stream | A CtplInputStream |

#### Returns

`TRUE` if at end of stream, `FALSE` otherwise.

## Types and Values

### CTPL_EOF

    #define CTPL_EOF  0

End-Of-File constant.

Since: 0.2

### CtplInputStream

    typedef struct _CtplInputStream CtplInputStream;

An opaque object representing an input data stream.