# copyright 2003-2010 LOGILAB S.A. (Paris, FRANCE), all rights reserved.

# contact http://www.logilab.fr/ -- mailto:contact@logilab.fr

#

# This file is part of CubicWeb.

#

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

#

# CubicWeb 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 CubicWeb.  If not, see <http://www.gnu.org/licenses/>.

"""

The :mod:`cubicweb.web.facet` module contains a set of abstract classes to use

as bases to build your own facets

All facet classes inherits from the :class:`AbstractFacet` class, though you'll

usually find some more handy class that do what you want.

Let's see available classes.

Classes you'll want to use

--------------------------

.. autoclass:: cubicweb.web.facet.RelationFacet

.. autoclass:: cubicweb.web.facet.RelationAttributeFacet

.. autoclass:: cubicweb.web.facet.HasRelationFacet

.. autoclass:: cubicweb.web.facet.AttributeFacet

.. autoclass:: cubicweb.web.facet.RangeFacet

.. autoclass:: cubicweb.web.facet.DateRangeFacet

Classes for facets implementor

------------------------------

Unless you didn't find the class that does the job you want above, you may want

to skip those classes...

.. autoclass:: cubicweb.web.facet.AbstractFacet

.. autoclass:: cubicweb.web.facet.VocabularyFacet

.. comment: XXX widgets

"""

__docformat__ = "restructuredtext en"

from copy import deepcopy

from datetime import date, datetime, timedelta

from logilab.mtconverter import xml_escape

from logilab.common.graph import has_path

from logilab.common.decorators import cached

from logilab.common.date import datetime2ticks

from logilab.common.compat import all

from rql import parse, nodes

from cubicweb import Unauthorized, typed_eid

from cubicweb.schema import display_name

from cubicweb.utils import make_uid

from cubicweb.selectors import match_context_prop, partial_relation_possible

from cubicweb.appobject import AppObject

from cubicweb.web.htmlwidgets import HTMLWidget

## rqlst manipulation functions used by facets ################################

def prepare_facets_rqlst(rqlst, args=None):

    """prepare a syntax tree to generate facet filters

    * remove ORDERBY clause

    * cleanup selection (remove everything)

    * undefine unnecessary variables

    * set DISTINCT

    * unset LIMIT/OFFSET

    """

    if len(rqlst.children) > 1:

        raise NotImplementedError('FIXME: union not yet supported')

    select = rqlst.children[0]

    mainvar = filtered_variable(select)

    select.set_limit(None)

    select.set_offset(None)

    baserql = select.as_string(kwargs=args)

    # cleanup sort terms

    select.remove_sort_terms()

    # selection: only vocabulary entity

    for term in select.selection[:]:

        select.remove_selected(term)

    # remove unbound variables which only have some type restriction

    for dvar in select.defined_vars.values():

        if not (dvar is mainvar or dvar.stinfo['relations']):

            select.undefine_variable(dvar)

    # global tree config: DISTINCT, LIMIT, OFFSET

    select.set_distinct(True)

    return mainvar, baserql

def filtered_variable(rqlst):

    vref = rqlst.selection[0].iget_nodes(nodes.VariableRef).next()

    return vref.variable

def get_facet(req, facetid, rqlst, mainvar):

    return req.vreg['facets'].object_by_id(facetid, req, rqlst=rqlst,

                                           filtered_variable=mainvar)

def filter_hiddens(w, **kwargs):

    for key, val in kwargs.items():

        w(u'<input type="hidden" name="%s" value="%s" />' % (

            key, xml_escape(val)))

def _may_be_removed(rel, schema, mainvar):

    """if the given relation may be removed from the tree, return the variable

    on the other side of `mainvar`, else return None

    Conditions:

    * the relation is an attribute selection of the main variable

    * the relation is optional relation linked to the main variable

    * the relation is a mandatory relation linked to the main variable

      without any restriction on the other variable

    """

    lhs, rhs = rel.get_variable_parts()

    rschema = schema.rschema(rel.r_type)

    if lhs.variable is mainvar:

        try:

            ovar = rhs.variable

        except AttributeError:

            # constant restriction

            # XXX: X title LOWER(T) if it makes sense?

            return None

        if rschema.final:

            if len(ovar.stinfo['relations']) == 1:

                # attribute selection

                return ovar

            return None

        opt = 'right'

        cardidx = 0

    elif getattr(rhs, 'variable', None) is mainvar:

        ovar = lhs.variable

        opt = 'left'

        cardidx = 1

    else:

        # not directly linked to the main variable

        return None

    if rel.optional in (opt, 'both'):

        # optional relation

        return ovar

    if all(rdef.cardinality[cardidx] in '1+'

           for rdef in rschema.rdefs.values()):

        # mandatory relation without any restriction on the other variable

        for orel in ovar.stinfo['relations']:

            if rel is orel:

                continue

            if _may_be_removed(orel, schema, ovar) is None:

                return None

        return ovar

    return None

def _add_rtype_relation(rqlst, mainvar, rtype, role):

    """add a relation relying `mainvar` to entities linked by the `rtype`

    relation (where `mainvar` has `role`)

    return the inserted variable for linked entities.

    """

    newvar = rqlst.make_variable()

    if role == 'object':

        rqlst.add_relation(newvar, rtype, mainvar)

    else:

        rqlst.add_relation(mainvar, rtype, newvar)

    return newvar

def _prepare_vocabulary_rqlst(rqlst, mainvar, rtype, role,

                              select_target_entity=True):

    """prepare a syntax tree to generate a filter vocabulary rql using the given

    relation:

    * create a variable to filter on this relation

    * add the relation

    * add the new variable to GROUPBY clause if necessary

    * add the new variable to the selection

    """

    newvar = _add_rtype_relation(rqlst, mainvar, rtype, role)

    if select_target_entity:

        if rqlst.groupby:

            rqlst.add_group_var(newvar)

        rqlst.add_selected(newvar)

    # add is restriction if necessary

    if mainvar.stinfo['typerel'] is None:

        etypes = frozenset(sol[mainvar.name] for sol in rqlst.solutions)

        rqlst.add_type_restriction(mainvar, etypes)

    return newvar

def _remove_relation(rqlst, rel, var):

    """remove a constraint relation from the syntax tree"""

    # remove the relation

    rqlst.remove_node(rel)

    # remove relations where the filtered variable appears on the

    # lhs and rhs is a constant restriction

    extra = []

    for vrel in var.stinfo['relations']:

        if vrel is rel:

            continue

        if vrel.children[0].variable is var:

            if not vrel.children[1].get_nodes(nodes.Constant):

                extra.append(vrel)

            rqlst.remove_node(vrel)

    return extra

def _set_orderby(rqlst, newvar, sortasc, sortfuncname):

    if sortfuncname is None:

        rqlst.add_sort_var(newvar, sortasc)

    else:

        vref = nodes.variable_ref(newvar)

        vref.register_reference()

        sortfunc = nodes.Function(sortfuncname)

        sortfunc.append(vref)

        term = nodes.SortTerm(sortfunc, sortasc)

        rqlst.add_sort_term(term)

def insert_attr_select_relation(rqlst, mainvar, rtype, role, attrname,

                                sortfuncname=None, sortasc=True,

                                select_target_entity=True):

    """modify a syntax tree to :

    * link a new variable to `mainvar` through `rtype` (where mainvar has `role`)

    * retrieve only the newly inserted variable and its `attrname`

    Sorting:

    * on `attrname` ascendant (`sortasc`=True) or descendant (`sortasc`=False)

    * on `sortfuncname`(`attrname`) if `sortfuncname` is specified

    * no sort if `sortasc` is None

    """

    _cleanup_rqlst(rqlst, mainvar)

    var = _prepare_vocabulary_rqlst(rqlst, mainvar, rtype, role,

                                    select_target_entity)

    # not found, create one

    attrvar = rqlst.make_variable()

    rqlst.add_relation(var, attrname, attrvar)

    # if query is grouped, we have to add the attribute variable

    if rqlst.groupby:

        if not attrvar in rqlst.groupby:

            rqlst.add_group_var(attrvar)

    if sortasc is not None:

        _set_orderby(rqlst, attrvar, sortasc, sortfuncname)

    # add attribute variable to selection

    rqlst.add_selected(attrvar)

    return var

def _cleanup_rqlst(rqlst, mainvar):

    """cleanup tree from unnecessary restriction:

    * attribute selection

    * optional relations linked to the main variable

    * mandatory relations linked to the main variable

    """

    if rqlst.where is None:

        return

    schema = rqlst.root.schema

    toremove = set()

    vargraph = deepcopy(rqlst.vargraph) # graph representing links between variable

    for rel in rqlst.where.get_nodes(nodes.Relation):

        ovar = _may_be_removed(rel, schema, mainvar)

        if ovar is not None:

            toremove.add(ovar)

    removed = set()

    while toremove:

        trvar = toremove.pop()

        trvarname = trvar.name

        # remove paths using this variable from the graph

        linkedvars = vargraph.pop(trvarname)

        for ovarname in linkedvars:

            vargraph[ovarname].remove(trvarname)

        # remove relation using this variable

        for rel in trvar.stinfo['relations']:

            if rel in removed:

                # already removed

                continue

            rqlst.remove_node(rel)

            removed.add(rel)

        rel = trvar.stinfo['typerel']

        if rel is not None and not rel in removed:

            rqlst.remove_node(rel)

            removed.add(rel)

        # cleanup groupby clause

        if rqlst.groupby:

            for vref in rqlst.groupby[:]:

                if vref.name == trvarname:

                    rqlst.remove_group_var(vref)

        # we can also remove all variables which are linked to this variable

        # and have no path to the main variable

        for ovarname in linkedvars:

            if ovarname == mainvar.name:

                continue

            if not has_path(vargraph, ovarname, mainvar.name):

                toremove.add(rqlst.defined_vars[ovarname])

## base facet classes ##########################################################

class AbstractFacet(AppObject):

    """Abstract base class for all facets. Facets are stored in their own

    'facets' registry. They are similar to contextual components since the use

    the following configurable properties:

    * `visible`, boolean flag telling if a facet should be displayed or not

    * `order`, integer to control facets display order

    * `context`, telling if a facet should be displayed in the table form filter

      (context = 'tablefilter') or in the facet box (context = 'facetbox') or in

      both (context = '')

    The following methods define the facet API:

    .. automethod:: cubicweb.web.facet.AbstractFacet.get_widget

    .. automethod:: cubicweb.web.facet.AbstractFacet.add_rql_restrictions

    Facets will have the following attributes set (beside the standard

    :class:`~cubicweb.appobject.AppObject` ones):

    * `rqlst`, the rql syntax tree being facetted

    * `filtered_variable`, the variable node in this rql syntax tree that we're

      interested in filtering

    Facets implementors may also be interested in the following properties /

    methods:

    .. automethod:: cubicweb.web.facet.AbstractFacet.operator

    .. automethod:: cubicweb.web.facet.AbstractFacet.rqlexec

    """

    __abstract__ = True

    __registry__ = 'facets'

    cw_property_defs = {

        _('visible'): dict(type='Boolean', default=True,

                           help=_('display the facet or not')),

        _('order'):   dict(type='Int', default=99,

                           help=_('display order of the facet')),

        _('context'): dict(type='String', default='',

                           # None <-> both

                           vocabulary=(_('tablefilter'), _('facetbox'), ''),

                           help=_('context where this facet should be displayed, '

                                  'leave empty for both')),

        }

    visible = True

    context = ''

    needs_update = False

    start_unfolded = True

    cw_rset = None # ensure facets have a cw_rset attribute

    def __init__(self, req, rqlst=None, filtered_variable=None,

                 **kwargs):

        super(AbstractFacet, self).__init__(req, **kwargs)

        assert rqlst is not None

        assert filtered_variable

        # take care: facet may be retreived using `object_by_id` from an ajax call

        # or from `select` using the result set to filter

        self.rqlst = rqlst

        self.filtered_variable = filtered_variable

    @property

    def operator(self):

        """Return the operator (AND or OR) to use for this facet when multiple

        values are selected.

        """

        # OR between selected values by default

        return self._cw.form.get(self.__regid__ + '_andor', 'OR')

    def rqlexec(self, rql, args=None):

        """Utility method to execute some rql queries, and simply returning an

        empty list if :exc:`Unauthorized` is raised.

        """

        try:

            return self._cw.execute(rql, args)

        except Unauthorized:

            return []

    def get_widget(self):

        """Return the widget instance to use to display this facet, or None if

        the facet can't do anything valuable (only one value in the vocabulary

        for instance).

        """

        raise NotImplementedError

    def add_rql_restrictions(self):

        """When some facet criteria has been updated, this method is called to

        add restriction for this facet into the rql syntax tree. It should get

        back its value in form parameters, and modify the syntax tree

        (`self.rqlst`) accordingly.

        """

        raise NotImplementedError

class VocabularyFacet(AbstractFacet):

    """This abstract class extend :class:`AbstractFacet` to use the

    :class:`FacetVocabularyWidget` as widget, suitable for facets that may

    restrict values according to a (usually computed) vocabulary.

    A class which inherits from VocabularyFacet must define at least these methods:

    .. automethod:: cubicweb.web.facet.VocabularyFacet.vocabulary

    .. automethod:: cubicweb.web.facet.VocabularyFacet.possible_values