module Feedzirra
  
  # TODO - remove this class, and only use the Feedzirra::Reader class for accessing feed data.
  class Feed
        
    # Fetches and returns the parsed XML for each URL provided.
    #
    # === Parameters
    # [urls<String> or <Array>] A single feed URL, or an array of feed URLs.
    # [options<Hash>] Valid keys for this argument as as followed:
    # * :user_agent - String that overrides the default user agent.
    # * :if_modified_since - Time object representing when the feed was last updated.
    # * :if_none_match - String, an etag for the request that was stored previously.
    # * :on_success - Block that gets executed after a successful request.
    # * :on_failure - Block that gets executed after a failed request.
    # === Returns
    # A Feed object if a single URL is passed.
    #
    # A Hash if multiple URL's are passed. The key will be the URL, and the value the Feed object.
    def self.fetch_and_parse(urls, options = {})
      multi = Feedzirra::HttpMulti.new(urls, options)
      multi.perform
      urls.is_a?(String) ? multi.responses.values.first : multi.responses
    end

    # Updates each feed for each Feed object provided.
    #
    # === Parameters
    # [feeds<Feed> or <Array>] A single feed object, or an array of feed objects.
    # [options<Hash>] Valid keys for this argument as as followed:
    #                 * :user_agent - String that overrides the default user agent.
    #                 * :on_success - Block that gets executed after a successful request.
    #                 * :on_failure - Block that gets executed after a failed request.
    # === Returns
    # A updated Feed object if a single URL is passed.
    #
    # A Hash if multiple Feeds are passed. The key will be the URL, and the value the updated Feed object.
    def self.update(feeds, options = {})
      multi = Feedzirra::HttpMulti.new(urls, options)

      multi.perform
      multi.responses.size == 1 ? multi.responses.values.first : multi.responses.values
    end

    # Fetches and returns the raw XML for each URL provided.
    #
    # === Parameters
    # [urls<String> or <Array>] A single feed URL, or an array of feed URLs.
    # [options<Hash>] Valid keys for this argument as as followed:
    #                 :user_agent - String that overrides the default user agent.
    #                 :if_modified_since - Time object representing when the feed was last updated.
    #                 :if_none_match - String that's normally an etag for the request that was stored previously.
    #                 :on_success - Block that gets executed after a successful request.
    #                 :on_failure - Block that gets executed after a failed request.
    # === Returns
    # A String of XML if a single URL is passed.
    # 
    # A Hash if multiple URL's are passed. The key will be the URL, and the value the XML.
    #
    # FIXME - Raw mode is currently not supported!
    def self.fetch_raw(urls, options = {})
      multi = Feedzirra::HttpMulti.new(urls, options.merge(:raw => true))
      multi.perform
      urls.is_a?(String) ? multi.responses.values.first : multi.responses
    end
     
  end
end