#########################################################################
# This file is part of Lyntin.
#
# Lyntin 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 3 of the License, or
# (at your option) any later version.
#
# Lyntin 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, see <http://www.gnu.org/licenses/>.
#
# copyright (c) Free Software Foundation 2001-2007
#
# $Id: helpmanager.py,v 1.7 2007/07/24 00:39:03 willhelm Exp $
#########################################################################
"""
Lyntin has a comprehensive X{help} system that can be accessed in-game
through the "#help" command.  The help material is all organized
and manipulated by the "HelpManager".  Help is organized as
topics which exist in a hierarchy of categories and it comes from 
a couple of sources:

  1. dynamically loaded at Lyntin startup from files located in 
     the help subdirectory and ending with .tpc extension

  2. when commands are registered via the exported.add_command
     function

  3. by any module using the exported.add_help function


It's interesting to note that the README and COMMANDS files
are generated entirely of in-game help topics using a template
script file and my personal home-brew #exporthelp command.

The help manager holds a hierarchy of help files indexed by category.
It also houses a series of methods for adding new help text, parsing
help file text, and also exporting help content into some format
which then can be converted to a variety of other formats: HTML,
XML, JoesMagicTextMarkup, ...
"""
import types
from lyntin import utils, config, manager

class HelpManager(manager.Manager):
  """
  The HelpManager exists on the engine scoping--there is only one
  per Lyntin instance.  It holds a hierarchy of help texts which
  can be retrieved and perused through via the #help user command.
  In general, it's best to access the HelpManager instance through
  the exported module.

  Help texts are indexed by an 'fqn' which is a fully-qualified-name.
  For example, the #alias command would be under 'commands.alias'
  where 'commands' is the category in the help hierarchy that it goes
  under and 'alias' is the help text topic name.

  Help text can also handle options set in the text in itself.  Currently
  the only option we support is "category".  This will be used if
  the fqn you supply to the addHelp call is lacking a category--for
  example 'alias'.
  """
  def __init__(self, e):
    self._help_tree = {}
    self._engine = e

  def addHelp(self, fqn, helptext):
    """
    Adds a help text to the hierarchy.  Use the 'exported.add_help'
    and not this directly.

    @param fqn: the fully qualified name
    @type  fqn: string

    @param helptext: the help text
    @type  helptext: string

    @return: the fqn of the help topic we just added (this can change
        depending on whether there's a category directive)
    @rtype: string

    @raises ValueError: if the help name or help text are not valid
    """
    categorylist, helpname = self._split_name(fqn)

    if not helptext or not helpname:
      raise ValueError("Help name and text are required.")

    directives, helptext = _parse_directives(helptext)

    if "category" in directives:
      categorylist = directives["category"].split(".") + categorylist

    place = self._help_tree
    for mem in categorylist:
      if mem in place:
        if isinstance(place[mem], dict):
          place = place[mem]
        else:
          tmp = place[mem]
          place[mem] = {}
          place[mem]["__doc__"] = tmp
          place = place[mem]
      else:
        place[mem] = {}
        place = place[mem]

    if helpname in place:
      if isinstance(place[helpname], dict):
        place[helpname]["__doc__"] = helptext
      else:
        place[helpname] = helptext
    else:
      place[helpname] = helptext

    if categorylist:
      fqn = "%s.%s" % (".".join(categorylist), helpname)
    else:
      fqn = "root.%s" % helpname
    return fqn

  def removeHelp(self, fqn):
    """
    Takes in a fully-qualified name and attempts to remove it from
    the structure.

    @param fqn: the fully qualified name of the help topic to remove
    @type  fqn: string

    @raises ValueError: if no topic by that fqn exists
    """
    categories, name = self._split_name(fqn)

    place = self._help_tree
    breadcrumbs = []

    for mem in categories:
      if mem in place:
        breadcrumbs.append(place)
        place = place[mem]
      else:
        raise ValueError("Topic '%s' does not exist." % fqn)

    if name in place:
      del place[name]
      self._trimTree(self._help_tree)

    else:
      raise ValueError("Topic '%s' does not exist." % fqn)


  def _trimTree(self, tree):
    """
    Takes a tree and trims off the branches that don't hold any 
    elements.  This method is recursive and will call itself at
    the various branches.  It modifies the tree in place.

    @param tree: the map of topics to trim
    @type  tree: dict
    """
    for mem in list(tree.keys()):
      if isinstance(tree[mem], dict):
        self._trimTree(tree[mem])

        if len(list(tree[mem].keys())) == 0:
          del tree[mem]

  def getNode(self, fqn):
    """
    Retrieves the help topic requested.

    The difference between this and getHelp is that getHelp will
    do searching and try to find the best topic for what you asked
    for.  This will return the topic at the prescribed place or
    throw an exception if it doesn't exist.  This is better for
    exporting help topics to a manual of some kind.

    @param fqn: the fully qualified name of the topic being requested
    @type  fqn: string

    @return: a tuple consisting of the topic data string, and then a list
        of nodes under this fqn (if it's a category)
    @rtype: (string, list of strings)

    @raises ValueError: if the fqn doesn't exist
    """
    categorylist, name = self._split_name(fqn)
    categorylist.append(name)

    tree = self._help_tree

    for mem in categorylist:
      if isinstance(tree, dict):
        if mem in tree:
          tree = tree[mem]
        else:
          raise ValueError("FQN '%s' doesn't exist." % fqn)
      else:
        raise ValueError("FQN '%s' doesn't exist." % fqn)

    if isinstance(tree, dict):
      list = []
      for key, value in list(tree.items()):
        list.append("%s.%s" % (".".join(categorylist), key))

      list.sort()
      if "__doc__" in tree:
        list.remove(".".join(categorylist) + ".__doc__")
        return (tree["__doc__"], list)

      return ('', list)

    return (tree, [])

    
  def getHelp(self, fqn):
    """
    Retrieves the help topic requested.  This is the hard-core
    attempt at finding help text.  It will look for it outright,
    then try searching, then try black magic.

    @param fqn: the fully qualified name or topic name
    @type  fqn: string

    @return: A tuple composed of three strings.  The first string is
        error text (if any or empty string if none).  The second
        string is the breadcrumbs trail.  The third string is the
        help text found or a columnized text of what tree elements
        exist at that level.
    @rtype: tuple of (string, string, string)
    """
    categorylist, name = self._split_name(fqn)

    categorylist.append(name)

    tree = self._help_tree
    breadcrumbs = "root"
    found = 1

    for mem in categorylist:
      if isinstance(tree, dict):
        if mem in tree:
          tree = tree[mem]
          breadcrumbs += "." + mem
        else:
          found = 0
          break
      else:
        found = 0
        break
    
    if found == 0 and fqn != "": 
      # first find all instances of categorylist[0] in the help tree.
      potentialroots = []
      start = categorylist[0]

      tosearch = [ ("root",self._help_tree) ]
      while tosearch:
        nextbreadcrumbs, nextnode = tosearch[0]
        tosearch = tosearch[1:]
        for key in nextnode.keys():
          currentbreadcrumbs = "%s.%s" % (nextbreadcrumbs, key)
          if key == categorylist[0]:
            potentialroots.append( (currentbreadcrumbs,nextnode[key]) )
          if isinstance(nextnode[key], dict):
            tosearch.append( (currentbreadcrumbs,nextnode[key]) )

      foundnodes = []

      # Now walk through all of the nodes named categorylist[0] and see if
      # they have they have categorylist[1:] under them.
      for bc,node in potentialroots:
        for key in categorylist[1:]:
          if not isinstance(node, dict) or key not in node:
            bc=None
            node=None
          else:
            bc = "%s.%s" % (bc, key)
            node = node[key]
        if node:
          foundnodes.append( (bc,node) )


      # If we only found one thing then run the rest of the function
      # as though that was what was entered.  Otherwise build the
      # The error text to state the nodes that were found.
      if len(foundnodes) == 1:
        breadcrumbs,tree = foundnodes[0]
        error = ""
      elif len(foundnodes) == 0:
        error = "Cannot find '%s'.  We did find this:" % fqn
      else:
        error = "Could not find exact match for '%s'.  We did find these matches:" % fqn
        list = [x[0] for x in foundnodes]
        return (error, "", utils.columnize(textlist=list,indent=3))
    else:
      error = ""

    if isinstance(tree, dict):
      toplist = []
      catlist = []
      for key, value in tree.items():
        if isinstance(value, dict):
          catlist.append("%s(%d) " % (key, len(value)))
        else:
          toplist.append(key)
      toplist.sort()
      catlist.sort()
      if "__doc__" in tree:
        if "__doc__" in toplist: toplist.remove("__doc__")
        if "__doc__" in catlist: catlist.remove("__doc__")
        helphead = tree["__doc__"] + "\n\nOther things in this category:\n\n"
      else:
        helphead = ""
      data = helphead
      if catlist:
        data += "Categories:\n" + utils.columnize(catlist, indent=3) + "\n"
      if toplist:
        data += "Topics:\n" + utils.columnize(toplist, indent=3) + "\n"

      return (error, breadcrumbs, data)
    return (error, breadcrumbs, tree)
    
  def _printTree(self, tree=None, tab=""):
    """
    Prints out the hierarchy--for debugging purposes.
    """
    if tree is None:
      tree = self._help_tree
      print(f"{tab}Root:")

    for key, value in list(tree.items()):
      if isinstance(value, dict):
        print(f"{tab} {key}:")
        self._printTree(value, tab + "  ")
      else:
        print(f"{tab}  node: {key}")


  def _split_name(self, fqn):
    """
    Takes an fqn and splits it into a series of categories and a help
    topic name.  fqn's are delimited by a '.' (period).

    It tries to fix up the fqn as well--doing things like removing
    lyntin command characters from the name (some users type "#help #alias"
    to view the help on the alias command) and also removing instances
    of "root" from the beginning of the fqn because it's not needed.

    @param fqn: the fully qualified name to split
    @type  fqn: string

    @return: the category list and the help topic name
    @rtype: tuple of (list of strings, string)
    """
    if not fqn:
      fqn = ""

    keys = fqn.split(".")
    if len(keys) > 1 and keys[0] == "root":
      keys = keys[1:]

    if len(keys) > 0:
      categories = keys[:-1]
      name = keys[-1]
      if len(name) > 0 and name[0] == self._engine.getConfigManager().get("commandchar"):
        name = name[1:]
      return (categories, name)
    else:
      return ([], "")


_directives = ["category"]

def _parse_directives(helptext):
  """
  Parses out the directives in the last lines of a given help text 
  and returns these directives in a dict.  Also strips the helptext
  (removing whitespace at the beginning and the end), removes
  directives found at the end, and returns this adjusted help text.

  To add new directives to extract, add them to the '_directives' 
  variable.

  If no directives were found, we return an empty string.

  @param helptext: the help text topic
  @type  helptext: string

  @return: the dictionary of directives and adjusted helptext
  @rtype: tuple of (dict, string)
  """
  ret = {}

  helptext = helptext.strip()
  lines = helptext.splitlines()

  i = len(lines) - 1
  while (i >= 0):
    mem = lines[i]
    founditem = 0
    for mem2 in _directives:
      if mem.find(mem2 + ": ") == 0:
        ret[mem2] = mem[len(mem2 + ": "):]
        founditem = 1
        break

    if founditem == 0:
      break

    i = i - 1

  return (ret, "\n".join(lines[:i+1]).strip())

# Local variables:
# mode:python
# py-indent-offset:2
# tab-width:2
# End:
