# Copyright 2018 The dm_control Authors.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#    http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or  implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# ============================================================================

"""Base class for all MJCF elements in the object model."""

import abc

from dm_control.mjcf import constants


class Element(metaclass=abc.ABCMeta):
  """Abstract base class for an MJCF element.

  This class is provided so that `isinstance(foo, Element)` is `True` for all
  Element-like objects. We do not implement the actual element here because
  the actual object returned from traversing the object hierarchy is a
  weakproxy-like proxy to an actual element. This is because we do not allow
  orphaned non-root elements, so when a particular element is removed from the
  tree, all references held automatically become invalid.
  """
  __slots__ = []

  @abc.abstractmethod
  def get_init_stack(self):
    """Gets the stack trace where this element was first initialized."""

  @abc.abstractmethod
  def get_last_modified_stacks_for_all_attributes(self):
    """Gets a dict of stack traces where each attribute was last modified."""

  @abc.abstractmethod
  def is_same_as(self, other):
    """Checks whether another element is semantically equivalent to this one.

    Two elements are considered equivalent if they have the same
    specification (i.e. same tag appearing in the same context), the same
    attribute values, and all of their children are equivalent. The ordering
    of non-repeated children is not important for this comparison, while
    the ordering of repeated children are important only amongst the same
    type* of children. In other words, for two bodies to be considered
    equivalent, their child sites must appear in the same order, and their
    child geoms must appear in the same order, but permutations between sites
    and geoms are disregarded. (The only exception is in tendon definition,
    where strict ordering of all children is necessary for equivalence.)

    *Note that the notion of "same type" in this function is very loose:
    for example different actuator element subtypes are treated as separate
    types when children ordering is considered. Therefore, two <actuator>
    elements might be considered equivalent even though they result in different
    orderings of `mjData.ctrl` when compiled. As it stands, this function
    is designed primarily as a testing aid and should not be used to guarantee
    that models are actually identical.

    Args:
      other: An `mjcf.Element`

    Returns:
      `True` if `other` element is semantically equivalent to this one.
    """

  @property
  @abc.abstractmethod
  def tag(self):
    pass

  @property
  @abc.abstractmethod
  def spec(self):
    pass

  @property
  @abc.abstractmethod
  def parent(self):
    pass

  @property
  @abc.abstractmethod
  def namescope(self):
    pass

  @property
  @abc.abstractmethod
  def root(self):
    pass

  @abc.abstractmethod
  def prefixed_identifier(self, prefix_root):
    pass

  @property
  @abc.abstractmethod
  def full_identifier(self):
    """Fully-qualified identifier used for this element in the generated XML."""

  @abc.abstractmethod
  def find(self, namespace, identifier):
    """Finds an element with a particular identifier.

    This function allows the direct access to an arbitrarily deeply nested
    child element by name, without the need to manually traverse through the
    object tree. The `namespace` argument specifies the kind of element to
    find. In most cases, this corresponds to the element's XML tag name.
    However, if an element has multiple specialized tags, then the namespace
    corresponds to the tag name of the most general element of that kind.
    For example, `namespace='joint'` would search for `<joint>` and
    `<freejoint>`, while `namespace='actuator'` would search for `<general>`,
    `<motor>`, `<position>`, `<velocity>`, and `<cylinder>`.

    Args:
      namespace: A string specifying the namespace being searched. See the
        docstring above for explanation.
      identifier: The identifier string of the desired element.

    Returns:
      An `mjcf.Element` object, or `None` if an element with the specified
      identifier is not found.

    Raises:
      ValueError: if either `namespace` or `identifier` is not a string, or if
        `namespace` is not a valid namespace.
    """

  @abc.abstractmethod
  def find_all(self, namespace,
               immediate_children_only=False, exclude_attachments=False):
    """Finds all elements of a particular kind.

    The `namespace` argument specifies the kind of element to
    find. In most cases, this corresponds to the element's XML tag name.
    However, if an element has multiple specialized tags, then the namespace
    corresponds to the tag name of the most general element of that kind.
    For example, `namespace='joint'` would search for `<joint>` and
    `<freejoint>`, while `namespace='actuator'` would search for `<general>`,
    `<motor>`, `<position>`, `<velocity>`, and `<cylinder>`.

    Args:
      namespace: A string specifying the namespace being searched. See the
        docstring above for explanation.
      immediate_children_only: (optional) A boolean, if `True` then only
        the immediate children of this element are returned.
      exclude_attachments: (optional) A boolean, if `True` then elements
        belonging to attached models are excluded.

    Returns:
      A list of `mjcf.Element`.

    Raises:
      ValueError: if `namespace` is not a valid namespace.
    """

  @abc.abstractmethod
  def enter_scope(self, scope_identifier):
    """Finds the root element of the given scope and returns it.

    This function allows the access to a nested scope that is a child of this
    element. The `scope_identifier` argument specifies the path to the child
    scope element.

    Args:
      scope_identifier: The path of the desired scope element.

    Returns:
      An `mjcf.Element` object, or `None` if a scope element with the
      specified path is not found.
    """

  @abc.abstractmethod
  def get_attribute_xml_string(self, attribute_name, prefix_root=None):
    pass

  @abc.abstractmethod
  def get_attributes(self):
    pass

  @abc.abstractmethod
  def set_attributes(self, **kwargs):
    pass

  @abc.abstractmethod
  def get_children(self, element_name):
    pass

  @abc.abstractmethod
  def add(self, element_name, **kwargs):
    """Add a new child element to this element.

    Args:
      element_name: The tag of the element to add.
      **kwargs: Attributes of the new element being created.

    Raises:
      ValueError: If the 'element_name' is not a valid child, or if an invalid
        attribute is specified in `kwargs`.

    Returns:
      An `mjcf.Element` corresponding to the newly created child element.
    """

  @abc.abstractmethod
  def remove(self, affect_attachments=False):
    """Removes this element from the model."""

  @property
  @abc.abstractmethod
  def is_removed(self):
    pass

  @abc.abstractmethod
  def all_children(self):
    pass

  @abc.abstractmethod
  def to_xml(self, prefix_root=None, debug_context=None,
             *,
             precision=constants.XML_DEFAULT_PRECISION,
             zero_threshold=0):
    """Generates an etree._Element corresponding to this MJCF element.

    Args:
      prefix_root: (optional) A `NameScope` object to be treated as root
        for the purpose of calculating the prefix.
        If `None` then no prefix is included.
      debug_context: (optional) A `debugging.DebugContext` object to which
        the debugging information associated with the generated XML is written.
        This is intended for internal use within PyMJCF; users should never need
        manually pass this argument.
      precision: (optional) Number of digits to output for floating point
        quantities.
      zero_threshold: (optional) When outputting XML, floating point quantities
        whose absolute value falls below this threshold will be treated as zero.

    Returns:
      An etree._Element object.
    """

  @abc.abstractmethod
  def to_xml_string(self, prefix_root=None,
                    self_only=False, pretty_print=True, debug_context=None,
                    *,
                    precision=constants.XML_DEFAULT_PRECISION,
                    zero_threshold=0):
    """Generates an XML string corresponding to this MJCF element.

    Args:
      prefix_root: (optional) A `NameScope` object to be treated as root
        for the purpose of calculating the prefix.
        If `None` then no prefix is included.
      self_only: (optional) A boolean, whether to generate an XML corresponding
        only to this element without any children.
      pretty_print: (optional) A boolean, whether to the XML string should be
        properly indented.
      debug_context: (optional) A `debugging.DebugContext` object to which
        the debugging information associated with the generated XML is written.
        This is intended for internal use within PyMJCF; users should never need
        manually pass this argument.
      precision: (optional) Number of digits to output for floating point
        quantities.
      zero_threshold: (optional) When outputting XML, floating point quantities
        whose absolute value falls below this threshold will be treated as zero.

    Returns:
      A string.
    """

  @abc.abstractmethod
  def resolve_references(self):
    pass