text: # -*- coding: utf-8 -*-
  #
  # Copyright (c) 2009 by Gustavo Narea <http://gustavonarea.net/>.
  #
  # This file is part of Booleano <http://code.gustavonarea.net/booleano/>.
  #
  # Permission is hereby granted, free of charge, to any person obtaining a copy
  # of this software and associated documentation files (the "Software"), to deal
  # in the Software without restriction, including without limitation the rights
  # to use, copy, modify, merge, publish, distribute, distribute with
  # modifications, sublicense, and/or sell copies of the Software, and to permit
  # persons to whom the Software is furnished to do so, subject to the following
  # conditions:
  #
  # The above copyright notice and this permission notice shall be included in
  # all copies or substantial portions of the Software.
  #
  # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  # ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  # WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
  # IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  #
  # Except as contained in this notice, the name(s) of the above copyright
  # holders shall not be used in advertising or otherwise to promote the sale,
  # use or other dealings in this Software without prior written authorization.
  """
  Parser of boolean expressions.
  
  """
  
  from logging import getLogger
  
  from booleano.parser.parsers import EvaluableParser, ConvertibleParser
  from booleano.exc import GrammarError
  
  __all__ = ("EvaluableParseManager", "ConvertibleParseManager", "Grammar",
             "Bind", "SymbolTable")
  
  LOGGER = getLogger(__name__)
  
  
  # TODO: Get a better name for this.
  class ParseManager(object):
  	"""
      Base class for parse managers.
      
      A parse manager controls the parsers to be used in a single kind of
      expression, with one parser per supported grammar.
      
      """
  
  	def __init__(self, generic_grammar, cache_limit=0, **localized_grammars):
  		"""
          
          :param generic_grammar: The default grammar.
          :type generic_grammar: :class:`Grammar`
          :param cache_limit: The maximum amount of expressions to be cached
              internally (use ``None`` for no limit or ``0`` to disable caching).
          :type cache_limit: int
          
          Additional keyword arguments, if any, will be used as custom grammars
          where each key represents the locale of the grammar in the value.
          
          """
  		self._cache = _Cache(cache_limit)
  		self._generic_grammar = generic_grammar
  		self._parsers = {}
  		for (locale, grammar) in localized_grammars.items():
  			self.add_parser(locale, grammar)
  
  	def parse(self, expression, locale=None):
  		"""
          Parse ``expression`` and return its parse tree.
          
          :param expression: The expression to be parsed.
          :type expression: basestring
          :param locale: The locale of the grammar used by ``expression``
              (or ``None`` if it uses the generic grammar).
          :type locale: basestring
          :return: The parse tree for ``expression``.
          :rtype: :class:`booleano.parser.trees.ParseTree`
          :raises booleano.exc.BadExpressionError: If ``expression`` is bad-formed
              according to the grammar ``locale``.
          :raises booleano.exc.InvalidOperationError: If ``expression`` has an 
              invalid operation.
          :raises booleano.exc.ScopeError: If ``expression`` contains unknown 
              identifiers.
          
          If caching is enabled and the ``expression`` was cached previously,
          ``expression`` won't be parsed again and its cached parse tree will
          be returned.
          
          If caching is enabled, but the ``expression`` is not cached, it will
          be parsed and the resulting parse tree will be cached and finally
          returned.
          
          """
  		if self._cache.is_stored(locale, expression):
  			parse_tree = self._cache.get_tree(locale, expression)
  		else:
  			parser = self._get_parser(locale)
  			parse_tree = parser(expression)
  			self._cache.store_tree(locale, expression, parse_tree)
  		return parse_tree
  
  	# { Parser management
  
  	def add_parser(self, locale, grammar):
  		"""
          Create a parser for ``grammar`` and store it.
          
          :param locale: The locale of the ``grammar``.
          :type locale: basestring
          :param grammar: The grammar of the parser to be created.
          :type grammar: :class:`Grammar`
          
          """
  		if locale in self._parsers:
  			raise GrammarError("There is already a parser for grammar %s" %
  			                   locale)
  		parser = self._define_parser(locale, grammar)
  		self._parsers[locale] = parser
  
  	def _get_parser(self, locale):
  		"""
          Return the parser for the grammar identifier by ``locale``.
          
          :param locale: The locale of the grammar whose parser is requested.
          :type locale: basestring
          :return: The requested parser.
          :rtype: Parser
          
          If there's no parser for grammar ``locale``, it will be created based
          on the generic grammar.
          
          """
  		if locale not in self._parsers:
  			self.add_parser(locale, self._generic_grammar)
  			LOGGER.info("Generated parser for unknown grammar %s", repr(locale))
  		return self._parsers[locale]
  
  	def _define_parser(self, locale, grammar):
  		"""
          Build a parser for ``grammar`` and return it.
          
          :param locale: The locale of the ``grammar``.
          :type locale: basestring
          :param grammar: The grammar for the parser to be built.
          :type grammar: Grammar
          :return: The parser built from ``grammar``.
          :rtype: Parser
          
          """
  		raise NotImplementedError("Actual parse managers must define their "
  		                          "parsers")
  
  	# }
  
  
  class EvaluableParseManager(ParseManager):
  	"""
      Parsing manager for evaluable operations.
      
      It manages evaluable parsers.
      
      """
  
  	def __init__(self, symbol_table, generic_grammar, cache_limit=0,
  	             **localized_grammars):
  		"""
          
          :param symbol_table: The symbol table for the supported expressions.
          :type symbol_table: :class:`SymbolTable`
          :param generic_grammar: The default grammar.
          :type generic_grammar: :class:`Grammar`
          :param cache_limit: The maximum amount of expressions to be cached
              internally (use ``None`` for no limit or ``0`` to disable caching).
          :type cache_limit: int
          
          Additional keyword arguments, if any, will be used as custom grammars
          where each key represents the locale of the grammar in the value.
          
          """
  		self._symbol_table = symbol_table
  		super(EvaluableParseManager, self).__init__(generic_grammar,
  		                                            cache_limit,
  		                                            **localized_grammars)
  
  	def evaluate(self, expression, locale, context):
  		"""
          Parse ``expression`` and return its evaluation result with ``context``.
          
          :param expression: The expression to be parsed.
          :type expression: basestring
          :param locale: The locale of the grammar used by ``expression``.
          :type locale: basestring
          :param context: The context under which the parse tree of ``expression``
              has to be evaluated.
          :type context: object
          :return: The result of the evaluation of the parse tree for
              ``expression``.
          :rtype: bool
          :raises BadExpressionError: If ``expression`` is bad-formed
              according to the ``locale`` grammar.
          :raises InvalidOperationError: If ``expression`` has an invalid
              operation.
          :raises ScopeError: If ``expression`` contains unknown identifiers.
          
          """
  		tree = self.parse(expression, locale)
  		return tree(context)
  
  	def _define_parser(self, locale, grammar):
  		"""
          Build an evaluable parser for ``grammar`` and return it.
          
          :param locale: The locale of the ``grammar``.
          :type locale: basestring
          :param grammar: The grammar for the evaluable parser to be built.
          :type grammar: Grammar
          :return: The evaluable parser built from ``grammar``.
          :rtype: EvaluableParser
          
          """
  		namespace = self._symbol_table.get_namespace(locale)
  		parser = EvaluableParser(grammar, namespace)
  		return parser
  
  
  class ConvertibleParseManager(ParseManager):
  	"""
      Parsing manager for convertible operations.
      
      It manages convertible parsers.
      
      """
  
  	def _define_parser(self, locale, grammar):
  		"""
          Build a parser for ``grammar`` and return it.
          
          :param locale: The locale of the ``grammar``.
          :type locale: basestring
          :param grammar: The grammar for the parser to be built.
          :type grammar: Grammar
          :return: The convertible parser built from ``grammar``.
          :rtype: ConvertibleParser
          
          Here the ``locale`` is not used.
          
          """
  		parser = ConvertibleParser(grammar)
  		return parser
  
  
  # { Internal stuff
  
  
  class _Cache(object):
  	"""
      Cache handling for a parse manager.
      
      """
  
  	def __init__(self, limit):
  		"""
          Set up the cache with ``limit``.
          
          :param limit: The maximum amount of expressions that can be cached
              (``None`` for no limit, ``0`` to disable caching).
          :type limit: int
          
          """
  		self.limit = limit
  		self.counter = 0
  		self.cache_by_locale = {}
  		self.latest_expressions = []
  
  	def is_stored(self, locale, expression):
  		"""
          Check if ``expression`` has been cached.
          
          :param locale: The locale of the grammar used by ``expression``.
          :type locale: basestring
          :param expression: The expression in question.
          :type expression: basestring
          :return: Whether ``expression`` is included in the cache or not.
          :rtype: bool
          
          """
  		stored = False
  		try:
  			stored = expression in self.cache_by_locale[locale]
  		except KeyError:
  			pass
  		return stored
  
  	def get_tree(self, locale, expression):
  		"""
          Return the cached parse tree for ``expression`` in ``locale``.
          
          :param locale: The locale of the grammar used by ``expression``.
          :type locale: basestring
          :param expression: The expression whose parse tree is requested.
          :type expression: basestring
          :return: The parse tree for ``expression`` in ``locale``.
          :rtype: ParseTree
          :raises KeyError: If the ``expression`` isn't cached (use
              :meth:`is_stored` first).
          
          """
  		parse_tree = self.cache_by_locale[locale][expression]
  		self.touch_tree(locale, expression)
  		return parse_tree
  
  	def store_tree(self, locale, expression, parse_tree):
  		"""
          Add the ``parse_tree`` of ``expression`` in ``locale`` to the cache.
          
          :param locale: The locale of the grammar used by ``expression``.
          :type locale: basestring
          :param expression: The expression whose parse tree is being stored.
          :type expression: basestring
          :param parse_tree: The parse tree of ``expression`` in ``locale``.
          :type parse_tree: ParseTree
          
          If caching is disabled, it won't do anything.
          
          """
  		if self.limit == 0:
  			# Cache is disabled.
  			return
  		# Cache is enabled, let's store it:
  		self.remove_oldest()
  		if locale not in self.cache_by_locale:
  			self.cache_by_locale[locale] = {}
  		self.cache_by_locale[locale][expression] = parse_tree
  		self.counter += 1
  		self.touch_tree(locale, expression)
  
  	def touch_tree(self, locale, expression):
  		"""
          Mark ``expression`` in ``locale`` as the latest used item in the cache.
          
          :param locale: The locale of the grammar used by ``expression``.
          :type locale: basestring
          :param expression: The expression whose parse tree is being touched.
          :type expression: basestring
          
          """
  		tree_indexes = (locale, expression)
  		if tree_indexes in self.latest_expressions:
  			# Removing the existing occurence:
  			self.latest_expressions.remove(tree_indexes)
  		self.latest_expressions.insert(0, tree_indexes)
  
  	def remove_oldest(self):
  		"""
          Remove the oldest item in the cache.
          
          It won't do anything if there's no caching limit, the limit has not
          been reached or there's nothing cached.
          
          """
  		if self.limit is None or self.counter < self.limit or not self.latest_expressions:
  			return
  		(locale, expression) = self.latest_expressions.pop(-1)
  		del self.cache_by_locale[locale][expression]
  		self.counter -= 1
  
  
  # }
  
  
  # Importing the objects to be available from this namespace:
  from booleano.parser.scope import Bind, SymbolTable
  from booleano.parser.grammar import Grammar
  