/*   Cataract - Static web photo gallery generator
 *   Copyright (C) 2009 Tomas Bzatek <tbzatek@users.sourceforge.net>
 *
 *   This program 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 any later version.
 *
 *   This program 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 this program; if not, write to the Free Software
 *   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 */
#ifndef __CGG__BLOCK_PARSER_H__
#define __CGG__BLOCK_PARSER_H__

#include <stdio.h>
#include <glib.h>

G_BEGIN_DECLS


typedef struct BlockParser BlockParser;

/*
 *  conditional function callback, arguments passed as strings. Returning TRUE means not to ignore the block.
 */
typedef gboolean (*BlockParserConditionalFunction) (gchar **args, gpointer user_data);


BlockParser * block_parser_new ();

void block_parser_free (BlockParser *parser);

/*
 *   block_parser_set_conditionals: set a hash table to be used for conditionals lookup
 *
 */
void block_parser_set_conditionals (BlockParser *parser, GHashTable *conditionals);

/*
 *   block_parser_register_key: tell parser to expect the key to catch
 *      key: part of the BEGIN_xxx placeholder, matched BEGIN_xxx and END_xxx as one block
 *      replace_key: placeholder to replace finished block with, for later use in replace_table,
 *                   placeholder will be surrounded by "<!-- $(replace_key) -->"
 *
 */
void block_parser_register_key (BlockParser *parser, const gchar *key, const gchar *replace_key);

/*
 *   block_parser_register_function: function called to determine whether a block should be ignored or not
 *
 */
void block_parser_register_function (BlockParser *parser, const gchar *conditional_name, BlockParserConditionalFunction callback, gpointer user_data);

/*
 *   block_parser_get_data: return retrieved data or NULL if none read yet
 *      returns newly allocated string, caller is responsible for freeing
 *
 */
gchar * block_parser_get_data (BlockParser *parser, const gchar *key);

/*
 *   block_parser_has_unused_data: indicates whether the data have already been read and used (by calling block_parser_get_data)
 *
 */
gboolean block_parser_has_unused_data (BlockParser *parser, const gchar *key);

/*
 *   block_parser_set_as_used: manually set data as used - sometimes blocks can act as containers for other nested blocks and
 *                                                         cannot be used itself
 *
 */
void block_parser_set_as_used (BlockParser *parser, const gchar *key);

/*
 *   block_parser_process: parse input data
 *      - if there's a multiline block, string before the opening placeholder and
 *        string after closing placeholder are returned on one line,
 *        separated by "replace_key" placeholder as specified in registered blocks
 *      - only the outmost "replace_key" placeholder will be used,
 *        no matter how many nested blocks were inside
 *      - returns newly allocated string, caller is responsible for freeing
 *
 */
gchar * block_parser_process (BlockParser *parser, const gchar *buffer);


G_END_DECLS

#endif /* __CGG__BLOCK_PARSER_H__ */