# Copyright: Copyright 2009 Topic Maps Lab, University of Leipzig.
# License:   Apache License, Version 2.0

module RTM::Axes

  class Topic < ItemProxy

    # ---- characteristics-axis ----------------------------------------------#
    
    # Returns all Names and Occurrences of this Topic.
    # If an identifier is given, only those Names and Occurrences are returned,
    # whose type or supertypes include the identifier.
    #
    # Identifier may be a Topic or Topic-Reference.
    #
    # The result may be empty.
    #
    # :call-seq:
    #   characteristics -> Array of Names and Occurrences
    #   characteristics(identifier) -> Array of Names and Occurrences
    #
    def characteristics(type=:any)
      _res = @construct.characteristics(type).map{|r| r.axes}
      _res.extend(Characteristics)
    end

    # ---- indicators-axis ---------------------------------------------------#
    
    # Returns all indicators (subject identifiers) of this Topic.
    #
    # The result may be empty.
    #
    # :call-seq:
    #   indicators -> Array of Strings
    #
    def indicators
      @construct.indicators #Array of Strings or empty
    end

    # ---- item-axis ---------------------------------------------------------#
    
    # Returns one item identifier of this Topic or nil
    # if this Topic has no item identifier.
    #
    # :call-seq:
    #   item -> String or nil
    #
    def item
      @construct.item #String or nil
    end

    # ---- locators-axis ------------------------------------------------------#
    
    # Returns all subject locators of this Topic.
    #
    # The result may be empty.
    #
    # :call-seq:
    #   locators -> Array of Strings
    #
    def locators
      @construct.locators #Array of Strings or empty
    end

    # ---- players-axis ------------------------------------------------------#
    
    # Returns all Associations in which this Topic plays a Role.
    #
    # The optional
    # identifier specifies the type of the Roles to be considered.
    # The identifier may be a Topic or Topic-Reference.
    #
    # Multiple instances of the same Association are possible.
    # The result may be empty.
    #
    # :call-seq:
    #   reverse_players -> Array of Associations
    #   reverse_players(identifier) -> Array of Associations
    #
    def reverse_players(type=:any)
      _res = @construct.reverse_players(type).map{|r| r.axes}
      _res.extend(Associations)
    end

    # ---- reifier-axis ------------------------------------------------------#
    
    # Alias for the TMAPI function getReified.
    # Returns the Construct which is reified by this Topic
    # or nil if this Topic does not reify a Construct.
    #
    # So far, only Associations, Names or Occurrences are returned.
    #
    # :call-seq:
    #   reifier -> Association, Name, Occurrence or nil
    #
    def reifier
      #TODO: what if the reified construct is a Topic Map?
      _res = @construct.getReified # Name,Occ,Assoc or nil
      return RTM::Axes::Name.new(_res,@tm) if _res.is_a?(RTM::Name)
      return RTM::Axes::Occurrence.new(_res,@tm) if _res.is_a?(RTM::Occurrence)
      return RTM::Axes::Association.new(_res,@tm) if _res.is_a?(RTM::Association)
      return nil
    end

    # ---- roles-axis --------------------------------------------------------#
    
    # Returns all Associations that have Roles that have
    # this Topic as Role type. Multiple instances of the same
    # Association are possible.
    #
    # The result may be empty.
    #
    # :call-seq:
    #   reverse_roles -> Array of Associations
    #
    def reverse_roles
      _res = @tm.type_instance_index.getRoles(@construct).map {|r| r.getParent }
      _res = _res.map{|r| r.axes}
      _res.extend(Associations)
    end

    # ---- scope-axis --------------------------------------------------------#
    
    # Returns all Associations, Names and Occurrences that include this
    # Topic (theme) in their scope.
    #
    # The result may be empty.
    #
    # :call-seq:
    #   reverse_scope -> Array of Names, Associations and Occurrences
    #
    def reverse_scope
      _index = @tm.scoped_index
      _res = _index.names(@construct).to_a + _index.occurrences(@construct).to_a + _index.associations(@construct).to_a
      _res = _res.map{|r| r.axes}
      _res.extend(AssocsNamesOccs)
    end

    # ---- supertypes-axis ---------------------------------------------------#
    
    # Returns all supertypes of this Topic. The result includes 
    # all direct supertypes
    # and the supertypes of these direct supertypes.
    #
    # The result may be an empty Array.
    #
    # :call-seq:
    #   supertypes -> Array of Topics
    #
    def supertypes
      _res = @construct.transitive_supertypes_with_self.map{|r| r.axes}
      _res.extend(Topics)
    end
    
    # Returns all subtypes of this Topic. The result includes the direct subtypes
    # and the subtypes of these direct subtypes.
    #
    # The result may be an empty Array.
    #
    # :call-seq:
    #   subtypes -> Array of Topics
    #
    def subtypes
      _res = @construct.transitive_subtypes_with_self.map{|r| r.axes}
      _res.extend(Topics)
    end
    
    alias reverse_subtypes supertypes
    alias reverse_supertypes subtypes

    # ---- traverse-axis ---------------------------------------------------#
    
    # First computes all Associations where this Topic playes a Role.
    # There, the optional identifier filters the Associations for their type.
    # 
    # Returns all Players of all Roles in these Associations.
    # The current Topic is deducted ones from the returned Array.
    # The result may be empty.
    #
    # The identifier may be a Topic or Topic-Reference.
    #
    # :call-seq:
    #   traverse(identifier) -> Array of Topics
    #
    def traverse(type=:any)
      _res = @construct.traverse(type).map{|r| r.axes}
      _res.extend(Topics)
    end
    
    # Always returns an empty Array
    #
    # :call-seq:
    #   reverse_traverse -> Array of Topics
    #
    def reverse_traverse
      _res = [] #HARDCODED
      _res.extend(Topics)
    end

    # ---- types-axis ---------------------------------------------------#
    
    # Returns the Topics this Topic is an instance of. Calls
    # the TMAPI getTypes method.
    #
    # The result may be empty.
    #
    # :call-seq:
    #   types -> Array of Topics
    #
    def types
      _res = @construct.types.map{|r| r.axes}
      _res.extend(Topics)
    end
    
    # Returns the Topics which are instances of this Topic.
    # Uses the TMAPI TypeInstanceIndex.
    #
    # The result may be empty.
    #
    # :call-seq:
    #   instances -> Array of Topics
    #
    def instances
      _res = @construct.instances.map{|r| r.axes}
      _res.extend(Topics)
    end
    
    alias reverse_types instances
    alias reverse_instances types

  end #of Class

end