##############################################################################
#
# Copyright (c) 2002-2009 Nexedi SA and Contributors. All Rights Reserved.
#                    Jean-Paul Smets-Solanes <jp@nexedi.com>
#                    Vincent Pelletier <vincent@nexedi.com>
#
# WARNING: This program as such is intended to be used by professional
# programmers who take the whole responsability of assessing all potential
# consequences resulting from its eventual inadequacies and bugs
# End users who are looking for a ready-to-use solution with commercial
# garantees and support are strongly adviced to contract a Free Software
# Service Company
#
# 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 (at your option) 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., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
#
##############################################################################

from zope.interface import Interface

class ISQLExpression(Interface):
  """
    This is a container for chunks of SQL generated by a Query.
    Each Query instance generates its own SQLExpression instance.
    SQLExpressions can be nested (an SQLExpression can contain 0, 1 or more
    SQLExpressions).

    Chunks are:
    - table_alias_dict
    - order_by_list
    - group_by_list
    - select_dict
    - limit
    Mutualy exclusive chunks are:
    - where expression
    - sql_expression_list
    Deprecated chunks are:
    - from_expression

    Providing sql_expression_list with more than one entry makes
    where_expression_operator mandatory.
  """

  def __init__(query,
               table_alias_dict=None,
               order_by_list=None,
               order_by_dict=None,
               group_by_list=None,
               where_expression=None,
               where_expression_operator=None,
               sql_expression_list=None,
               select_dict=None,
               limit=None,
               from_expression=None):
    """
      Instantiate an SQLExpression object.

      This method does consistency checks on received parameters, so that
      failures are detected as early as possible.

      Also, it casts most optional parameters into empty lists and empty dicts
      to make code using those values simpler.

      query (Query)
        The Query instance which called this constructor.
      table_alias_dict (dict, key: string, value: string)
        Table alias dict as returned by ColumnMap.getTableAliasDict() .
      order_by_list (list of strings)
        List of result ordering, pre-rendered.
      order_by_dict (dict, key: string, value: string)
        Column rendering replacement specific to order_by.
      group_by_list (list of strings)
        List of column names on which result line list will be grouped.
      where_expression (string)
        Text representing a "where" expression of an SQL query.
      where_expression_operator ("and", "or", "not", None)
        Operator to apply on immediately contained SQLExpressions.
        It must be "and" or "or" when there are multiple contained
        SQLExpressions, it can be "not" if there is exactly one contained
        SQLExpression, and must not be provided if there is no contained
        SQLExpression.
      sql_expression_list (list of SQLExpression)
        List of immediately contained SQLExpressions.
      select_dict (dict, key:string, value:string or Null)
        Lists all columns to be part of select expression.
        Key is column alias.
        Value is column name, or Null. If it is Null, the alias will also be
        used as column name.
      limit (1-tuple, 2-tuple, other)
        First item is the number of lines expected, second one if given is the
        offset of limited result list within the unlimited result list.
        If it is not a tuple it is treated as the value of a 1-tuple
        parameter.
      from_expression (string)
        This parameter is deprecated.
    """

  def asSQLExpressionDict():
    """
      Returns a dictionnary usable as a **kw for a catalog sql method.

      It renders aliases (see getTableAliasDict) as a list of strings and
      "from" expression (see getFromExpression) as a list of strings.

      See getWhereExpression, getOrderByExpression, getLimitExpression,
      getSelectExpression, getGroupByExpression.
    """

