## CtplLexer CtplLexer — Syntax analyser |

## Synopsis

    #include <ctpl/ctpl.h>

    #define             CTPL_LEXER_ERROR
    enum                CtplLexerError;
    CtplToken *         ctpl_lexer_lex                      (CtplInputStream *stream,
                                                             GError **error);
    CtplToken *         ctpl_lexer_lex_string               (const gchar *template,
                                                             GError **error);
    CtplToken *         ctpl_lexer_lex_path                 (const gchar *path,
                                                             GError **error);

## Description

Syntax analyser creating a token tree from an input data in the CTPL language.

To analyse some data, use `ctpl_lexer_lex()`, `ctpl_lexer_lex_string()` or `ctpl_lexer_lex_path()`; to destroy the created token tree, use `ctpl_token_free()`.

Example 11. Usage of the lexer and error management

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    CtplToken *tree;
    GError    *error = NULL;

    tree = ctpl_lexer_lex (input, &error);
    if (tree == NULL) {
      fprintf (stderr, "Failed to analyse input data: %s\n", error->message);
      g_clear_error (&error);
    } else {
      /* do what you want with the tree here */

      ctpl_token_free (tree);
    }

## Details

### CTPL_LEXER_ERROR

    #define CTPL_LEXER_ERROR  (ctpl_lexer_error_quark ())

Domain of CtplLexer errors.

### enum CtplLexerError

    typedef enum _CtplLexerError
    {
      CTPL_LEXER_ERROR_SYNTAX_ERROR,
      CTPL_LEXER_ERROR_FAILED
    } CtplLexerError;

Error codes that lexing functions can throw, from the `CTPL_LEXER_ERROR` domain.

`CTPL_LEXER_ERROR_SYNTAX_ERROR` | The input data contains invalid syntax
`CTPL_LEXER_ERROR_FAILED` | An error occurred without any precision on what failed.

### ctpl_lexer_lex ()

    CtplToken *         ctpl_lexer_lex                      (CtplInputStream *stream,
                                                             GError **error);

Analyses some given data and tries to create a tree of tokens representing it.

`stream` : | A CtplInputStream holding the data to analyse
`error` : | A GError return location for error reporting, or `NULL` to ignore errors.
Returns : | A new CtplToken tree holding all read tokens or `NULL` on error. The new tree should be freed with `ctpl_token_free()` when no longer needed.

### ctpl_lexer_lex_string ()

    CtplToken *         ctpl_lexer_lex_string               (const gchar *template,
                                                             GError **error);

Convenient function to lex a template from a string. See `ctpl_lexer_lex()`.

`template` : | A string containing the template data
`error` : | Return location for errors, or `NULL` to ignore them.
Returns : | A new CtplToken tree or `NULL` on error.

### ctpl_lexer_lex_path ()

    CtplToken *         ctpl_lexer_lex_path                 (const gchar *path,
                                                             GError **error);

Convenient function to lex a template from a file. See `ctpl_lexer_lex()`.

Errors can come from the `G_IO_ERROR` domain if the file loading fails, or from the `CTPL_LEXER_ERROR` domain if the lexing fails.

`path` : | The path of the file from which read the template, in the GLib's filename encoding
`error` : | Return location for errors, or `NULL` to ignore them
Returns : | A new CtplToken tree or `NULL` on error.