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

module RTM::Sugar::Topic::Characteristics
  
  # Returns all Occurrences of this Topic whose datatype is not IRI
  #
  # :call-seq:
  #   internal_occurrences -> Set of Occurrences
  #
  def internal_occurrences
    occurrences.select{|x| x.getDatatype.toExternalForm != RTM::PSI[:IRI]}
  end
  
  # Returns all Occurrences of this Topic whose datatype is IRI
  #
  # :call-seq:
  #   external_occurrences -> Set of Occurrences
  #
  def external_occurrences
    occurrences.select{|y| y.getDatatype.toExternalForm == RTM::PSI[:IRI]}
  end
  
  # Returns the names of this topic which may be filtered for their type,
  # value and/or scope.
  #
  # If scope is set to :ucs, names which exist in the unconstrained scope
  # are selected. If scope is set to :any (default), scope does not constrain
  # the names-Array. Else, only the names which whose scope contains one of the
  # given themes are returned.
  #
  # Returns an empty Array if no names match or if the name type
  # or scope does not exist.
  #
  # :call-seq:
  #   names_by -> Array of Names
  #   names_by(:type => identifier) -> Array of Names
  #   names_by(:value => string) -> Array of Names
  #   names_by(:scope => identifier) -> Array of Names
  #   names_by(:type => identifier, :value => string) -> Array of Names
  #   names_by(:type => identifier, :value => string, :scope => identifier) -> Array of Names
  #   and so on
  #
  def names_by(args = {})
    raise("names_by: arguments must be a Hash") unless args.is_a?(Hash)
    default_hash = {:type => :any, :value => :any, :scope => :any}   
    args = default_hash.merge(args)
    #filter for type
    _names = args[:type] == :any ? names : names(args[:type])
    _names = self.filter_by(_names,args)
    # return Array
    return _names.to_a
  end
  
  # Returns Occurrences of this Topic which may be filtered for their type,
  # value, datatype and/or scope.
  #
  # If scope is set to :ucs, Occurrences which exist in the unconstrained scope
  # are selected. If scope is set to :any (default), scope does not constrain
  # the Occurrence-Array. Else, only the occurrences which whose scope contains
  # one of the given themes are returned.
  #
  # Returns an empty Array if no Occurrences match or if the Occurrence type or
  # scope does not exist.
  #
  # :call-seq:
  #   occurrence_by -> Array of Occurrences
  #   occurrences_by(:type => argument) -> Array of Occurrences
  #   occurrences_by(:value => argument) -> Array of Occurrences
  #   occurrences_by(:scope => argument) -> Array of Occurrences
  #   occurrences_by(:datatype => argument) -> Array of Occurrences
  #   occurrences_by(:type => argument1, :value => argument2) -> Array of Occurrences
  #   occurrences_by(:type => argument1, :value => argument2, :scope => argument3, :datatype => argument4) -> Array of Occurrences
  #   and so on
  #
  def occurrences_by(args = {})
    raise("occurrences_by: arguments must be a Hash") unless args.is_a?(Hash)
    default_hash = {:type => :any, :value => :any, :scope => :any, :datatype => :any}
    args = default_hash.merge(args)
    #filter for type
    _occurrences = args[:type] == :any ? occurrences : occurrences(args[:type])
    _occurrences = self.filter_by(_occurrences,args)
    #filter for datatype
    _occurrences = _occurrences.select{|o| o.datatype == args[:datatype]} unless args[:datatype] == :any
    return _occurrences.to_a
  end
  
 protected
  def filter_by(_characteristics,args)
    #filter for value
    unless args[:value] == :any
      _characteristics = args[:value].is_a?(Array) ? _characteristics.select{|o| args[:value].any?{|v| o.value == v}} : _characteristics.select{|o| o.value == args[:value]}
    end
    #filter for scope
    case args[:scope]
      when :any
      when :ucs, []
        _characteristics = _characteristics.select{|o| o.scope.empty?}
      else
        _scope = topic_map.get(args[:scope])
        _characteristics = _scope.is_a?(Array) ? _characteristics.select{|o| _scope.any?{|theme| o.scope.include?(theme)}} : _characteristics.select{|o| o.scope.include?(_scope)}
    end
    _characteristics
  end
  
  # Returns the Occurrences and Names of this Topic which have the specified type as
  # Occurrence/Name type. Additionally, scope may constrain the the selection.
  #
  # If scope is set to :ucs, Occurrences/Names which exist in the unconstrained scope
  # are selected. If scope is set to :any (default), scope does not constrain
  # the Occurrence/Names-Array. Else, only the Occurrences/Names which exist in the given scope
  # are selected.
  #
  # Returns an empty Array if no Occurrences or Names match or if the Occurrence/Name type or
  # scope does not exist.
  #
  # :call-seq:
  #    characteristics_by -> Array of Occurrences and Names
  #
#  def characteristics_by(args = {})
#    raise("characteristics_by: arguments must be a Hash") unless args.is_a?(Hash)
#    default_hash = {:type => :any, :value => :any, :scope => :any, :datatype => :any}
#    args = default_hash.merge(args)
#    _names = names_by(args) if args[:datatype].include(:any) || args[:datatype] == RTM::PSI[:String] || args[:datatype] == topic_map.create_locator(RTM::PSI[:String])
#    _occurrences = occurrences_by(args)
#    
#  end
  
end