// -*- C++ -*- //

/* set.h
 *
 * Copyright 2006 libgdamm Development Team
 *
 * 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., 675 Mass Ave, Cambridge, MA 02139, USA.
 */

#include <libgdamm/batch.h>
#include <libgdamm/statement.h>

_DEFS(libgdamm,libgda)
_PINCLUDE(glibmm/private/object_p.h)

namespace Gnome
{

namespace Gda
{

_WRAP_ENUM(SqlParserMode, GdaSqlParserMode)
_WRAP_GERROR(SqlParserError, GdaSqlParserError, GDA_SQL_PARSER_ERROR)
		
//TODO: Find out how to escape /* so we can actually show the full syntax at the end of this text.
/** SQL parser.
 *
 * The Gda::SqlParser is an object dedicated to creating Gda::Statement and 
 * Gda::Batch objects from SQL strings. The actual contents of the parsed 
 * statements is represented as Gda::SqlStatement structures (which can be 
 * obtained from any Gda::Statement through the "structure" property).
 *
 * Gda::SqlParser parsers can be created by calling Gda::ServerProvider::create_parser() 
 * for a provider adapted SQL parser, or using create() for a general purpose SQL parser.
 * 
 * The Gda::SqlParser can either work in "parse" mode where it will try to parse
 * the SQL string, or in "delimiter" mode where it will only attempt at delimiting 
 * SQL statements in a string which may contain several SQL statements (usually 
 * separated by a semi column). If operating in "parser" mode, and the parser 
 * can't correctly parse the string, then it will switch to the "delimiter" mode 
 * for the next statement in the string to parse (and create a STATEMENT_UNKNOWN statement).
 * 
 * The Gda::SqlParser object parses and analyses SQL statements and reports the 
 * following statement types:
 *
 * - SELECT (and COMPOUND select), INSERT, UPDATE and DELETE SQL statements should be completely parsed.
 *
 * - Transaction related statements (corresponding to the BEGIN, COMMIT, 
 *   ROLLBACK, SAVEPOINT, ROLLBACK SAVEPOINT and DELETE SAVEPOINT) are parsed and a 
 *   minimalist structure is created to extract some information (that structure is not enough per-se to re-create the complete SQL statement).
 *
 * Any other type of SQL statement (CREATE TABLE, ...) creates a GdaStatement of 
 * type STATEMENT_UNKNOWN, and it only able to locate place holders (variables)
 * and end of statement marks.
 *
 * NOTE: Any SQL of a type which should be parsed which but which creates a Gda::Statement
 * of type GDA_SQL_STATEMENT_UNKNOWN (check with Gda::Statement::get_statement_type()) 
 * should be reported as a bug.
 *
 * The Gda::SqlParser object recognizes place holders (variables), which can later
 * be queried and valued using Gda::Statement::get_parameters(). 
 * See the syntax description for the underlying <a href="http://library.gnome.org/devel/libgda/stable/GdaSqlParser.html#GdaSqlParser.description">GdaSqlParser</a>.
 *
 * @ingroup Connection
 */
class SqlParser : public Glib::Object
{
  _CLASS_GOBJECT(SqlParser, GdaSqlParser, GDA_SQL_PARSER, Glib::Object, GObject)
protected:
  _CTOR_DEFAULT()
public:
  _WRAP_CREATE()
  
  //TODO: Should these be const?
  _WRAP_METHOD_DOCS_ONLY(gda_sql_parser_parse_string)
  Glib::RefPtr<Statement> parse_string(const Glib::ustring& sql, Glib::ustring& remain);

  Glib::RefPtr<Statement> parse_string(const Glib::ustring& sql);
    
  _WRAP_METHOD_DOCS_ONLY(gda_sql_parser_parse_string_as_batch)
  Glib::RefPtr<Batch> parse_string_as_batch(const Glib::ustring& sql, Glib::ustring& remain);

  Glib::RefPtr<Batch> parse_string_as_batch(const Glib::ustring& sql);
  
  _WRAP_METHOD(Glib::RefPtr<Batch> parse_file_as_batch(const std::string& filename), gda_sql_parser_parse_file_as_batch, errthrow)

  _IGNORE(gda_sql_parser_set_overflow_error, gda_sql_parser_set_syntax_error)
 
  _WRAP_PROPERTY("column-error", int)
  _WRAP_PROPERTY("line-error", int)
  _WRAP_PROPERTY("mode", int)
  _WRAP_PROPERTY("tokenizer-flavour", int)

};

} // namespace Gda
} // namespace Gnome