#
# <one line to give the library's name and an idea of what it does.>
# Copyright (C) 2014    <copyright holder> <email>
# 
# 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 3 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, see <http://www.gnu.org/licenses/>.
# 
#
import edgebuiderinterface
import abc

class NEEdgeBuilderInterface(edgebuiderinterface.EdgeBuiderInterface):
  """!
  The interface for edge builder classes that operate on named entities (NE).
  The names of the channels of NE may vary depending on a model. In order to
  get the name of used NE's set call the method get_ne_set_name. See it's doc
  for further details.

  This is an abstract class. However, all it's methods for checking the used 
  set of NE are static.
  """
  __metaclass__ = abc.ABCMeta

  def __init__(self, str_name, chan_name = None, set_name = None):
    """!
    Pass the input parameters to the super class.

    The class in an abstract class. It's not possible to create an instance
    of this class.

    @param str_name the identifier for this class. It is assigned to edges.
    @type str_name: str
    @param chan_name the name of the channel the class is going to use.
    @type chan_name: str
    @param set_name the name of the set of the channels the class is going to
      use.
    @type set_name: str
    """
    super(NEEdgeBuilderInterface, self).__init__(
      str_name, 
      chan_name, 
      set_name)

  @staticmethod
  def is_nam_channel(channel_name):
    """!
    Check whether the channel's name equals 'nam'.

    @param channel_name the name of the channel to check.
    @type channel_name: str | unicode

    @return True if the condition is met, False otherwise.
    @rtype: bool
    """
    return channel_name.lower() == "nam"

  @staticmethod
  def is_muc_channel(channel_name):
    u"""!
    Check whether the channel's name belongs to muc channel set.

    MUC contains channels: oth, loc, org, per.

    @param channel_name the name of the channel to check.
    @type channel_name: str | unicode

    @return True if the condition is met, False otherwise.
    @rtype: bool
    """
    return channel_name.lower() in ('orh', 'loc', 'per', 'org')

  @staticmethod
  def is_ending_nam_channel(channel_name):
    """!
    Check whether the channel's name ends with '_nam'.

    @param channel_name the name of the channel to check.
    @type channel_name: str | unicode

    @return True if the condition is met, False otherwise.
    @rtype: bool
    """
    return channel_name.lower().endswith('_nam')

  @staticmethod
  def get_ne_set_name(channel_name):
    """!
    Get the name of the named entity set where the channel belongs to.

    The named entity set depends on the configuration file of Liner.
    Available sets (ini files refer to the Liner configuration files):
      - NAM: channels are called 'nam', it is provided by 
          config-nam.ini and config-nam-fast.ini
      - MUC: channels are: 'oth', 'loc', 'per', 'org', it is provided by 
          config-muc.ini and config-muc-fast.ini
      - ENDING_NAM: names of the channels end with '_nam', it is provided by 
          config-5nam.ini and config-56nam.ini

    @param channel_name the channel to check.
    @type channel_name: str | unicode

    @return one of the available sets or None if the channel doesn't 
        belong to any of them.
    @rtype: str | None
    """
    ne_set = None
    if NEEdgeBuilderInterface.is_nam_channel(channel_name):
      ne_set = 'NAM'
    elif NEEdgeBuilderInterface.is_muc_channel(channel_name):
      ne_set = 'MUC'
    elif NEEdgeBuilderInterface.is_ending_nam_channel(channel_name):
      ne_set = 'ENDING_NAM'
    return ne_set
