module Nytimes module Articles ## # This class represents a Facet used in the ArticleSearch API. Facets can be used to both search for matching articles (see Article#search) and # are also returned as article and search metadata. Facets are made up of 3 parts: # * facet_type - a string; see Article#search for a list of facet types # * term - a string as well # * count - Facets returned as search metadata (via the :facets parameter to Article#search) also include a non-nil count of matching articles for that facet class Facet ## # The term for the facet attr_reader :term ## # The number of times this facet has appeared in the search results (note: this only applies for facets returned in the facets header on an Article#search) attr_reader :count ## # The facet type attr_reader :facet_type # Facet name constants CLASSIFIERS = 'classifiers_facet' COLUMN = 'column_facet' DATE = 'date' DAY_OF_WEEK = 'day_of_week_facet' DBPEDIA_RESOURCE = 'dbpedia_resource' DBPEDIA_URL = 'dbpedia_resource_url' DESCRIPTION = 'des_facet' DESK = 'desk_facet' FACET_TERM = 'facet_terms' GEO = 'geo_facet' MATERIAL_TYPE = 'material_type_facet' ORGANIZATION = 'org_facet' PAGE = 'page_facet' PERSON = 'per_facet' PUB_DAY = 'publication_day' PUB_MONTH = 'publication_month' PUB_YEAR = 'publication_year' SECTION_PAGE = 'section_page_facet' SOURCE = 'source_facet' WORKS_MENTIONED = 'works_mentioned_facet' # Facets of content formatted for nytimes.com NYTD_BYLINE = 'nytd_byline' NYTD_DESCRIPTION = 'nytd_des_facet' NYTD_GEO = 'nytd_geo_facet' NYTD_ORGANIZATION = 'nytd_org_facet' NYTD_PERSON = 'nytd_per_facet' NYTD_SECTION = 'nytd_section_facet' NYTD_WORKS_MENTIONED = 'nytd_works_mentioned_facet' # The default 5 facets to return DEFAULT_RETURN_FACETS = [DESCRIPTION, GEO, ORGANIZATION, PERSON, DESK] ALL_FACETS = [CLASSIFIERS, COLUMN, DATE, DAY_OF_WEEK, DESCRIPTION, DBPEDIA_RESOURCE, DBPEDIA_URL, DESK, GEO, MATERIAL_TYPE, ORGANIZATION, PAGE, PERSON, PUB_DAY, PUB_MONTH, PUB_YEAR, SECTION_PAGE, SOURCE, WORKS_MENTIONED, NYTD_BYLINE, NYTD_DESCRIPTION, NYTD_GEO, NYTD_ORGANIZATION, NYTD_PERSON, NYTD_SECTION, NYTD_WORKS_MENTIONED] ## # Initializes the facet. There is seldom a reason for you to call this. def initialize(facet_type, term, count) @facet_type = facet_type @term = term @count = count end ## # Takes a symbol name and subs it to a string constant def self.symbol_name(facet) case facet when String return facet when Facet return facet.facet_type when Symbol # fall through else raise ArgumentError, "Unsupported type to Facet#symbol_to_api_name" end case facet when :geography GEO when :org, :orgs ORGANIZATION when :people PERSON when :nytd_geography NYTD_GEO when :nytd_org, :nytd_orgs NYTD_ORGANIZATION when :nytd_people NYTD_PERSON when :dbpedia, :dbpedia_res DBPEDIA_RESOURCE when :dbpedia_url, :dbpedia_resource_url DBPEDIA_URL when :term, :terms, :facet_terms, :facet_term FACET_TERM else name = facet.to_s.upcase if const_defined?(name) const_get(name) elsif name =~ /S$/ && const_defined?(name.gsub(/S$/, '')) const_get(name.gsub(/S$/, '')) else raise ArgumentError, "Unable to find a matching facet key for symbol :#{facet}" end end end ## # Initializes a selection of Facet objects returned from the API. Used for marshaling Facets in articles and metadata from search results # (Note: some facets are returned as scalar values) def self.init_from_api(api_hash) return nil if api_hash.nil? unless api_hash.is_a? Hash raise ArgumentError, "expecting a Hash only" else return nil if api_hash.empty? end out = {} api_hash.each_pair do |k,v| out[k] = v.map {|f| Facet.new(k, f['term'], f['count'])} end out end end end end