Class: NPR::API::QueryBuilder

Inherits:
Object
  • Object
show all
Defined in:
lib/npr/api/query_builder.rb

Constant Summary collapse

CLASS_BUILDER_METHODS = 
[
  :where,
  :order,
  :limit,
  :offset,
  :set
]

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(klass) ⇒ QueryBuilder 



19
20
21
22
 
# File 'lib/npr/api/query_builder.rb', line 19

def initialize(klass)
  @_klass  = klass
  @builder = {}
end

Instance Attribute Details

#_klass ⇒ Object (readonly)

Returns the value of attribute _klass.



15
16
17
 
# File 'lib/npr/api/query_builder.rb', line 15

def _klass
  @_klass
end

#builder ⇒ Object (readonly)

Returns the value of attribute builder.



15
16
17
 
# File 'lib/npr/api/query_builder.rb', line 15

def builder
  @builder
end

Instance Method Details

#limit(limit) ⇒ Object

Set the limit.

Accepts an Integer.

Example:

query.limit(10)

Note that NPR limits the maximum results to 20, and will return only 20 results if more than the maximum is requested.



167
168
169
170
 
# File 'lib/npr/api/query_builder.rb', line 167

def limit(limit)
  @builder[:limit] = limit
  self
end

#offset(offset) ⇒ Object

Offset the number of results Useful for pagination

Accepts an Integer.

Example:

query.offset(100)



182
183
184
185
 
# File 'lib/npr/api/query_builder.rb', line 182

def offset(offset)
  @builder[:offset] = offset
  self
end

#order(order) ⇒ Object

Set the order.

Accepts a String.

Example:

query.order("date descending")



150
151
152
153
 
# File 'lib/npr/api/query_builder.rb', line 150

def order(order)
  @builder[:order] = order
  self
end

#query ⇒ Object

Fire the query and return the full Response object

Example:

query = NPR::API::QueryBuilder.new(NPR::Story)
query.where(:id => [100, 150]).query
#=> NPR::API::Response

See NPR::API::Response for what methods are available to you.

Note that for this method, NPR.config.apiKey must be set.



92
93
94
 
# File 'lib/npr/api/query_builder.rb', line 92

def query
  client.query(self.to_params)
end

#set(params) ⇒ Object

Add in arbitrary parameters.

These take precedence over anything set via any of the other builder methods.

Accepts a hash of key/values that the API can receive and handle.

Example:

query.set(apiKey: "YOUR_API_KEY")



109
110
111
112
 
# File 'lib/npr/api/query_builder.rb', line 109

def set(params)
  @builder[:extra] = (@builder[:extra] || {}).merge(params)
  self
end

#to_a ⇒ Object

Fire the query and return an Array of stories (or empty [])

Returns an Array. If the query returned any stories, then it will be an array of those stories. If no stories were returned, then it will be an empty array.

There is no way to access the List or Messages returned from the response. This method is meant to be a way to get to the Stories as quickly and easily as possible. If you want access to the full Response object, use #query.

Example:

query = NPR::API::QueryBuilder.new(NPR::Story)
query.where(:id => [100, 150]).to_a
#=> [NPR::Story, NPR::Story]

# Assuming there is no story with an ID of 1
query.where(:id => 1).to_a
#=> []

Note that for this method, NPR.config.apiKey must be set.



68
69
70
71
72
73
74
75
76
77
 
# File 'lib/npr/api/query_builder.rb', line 68

def to_a
  response = self.query
  stories  = []

  if response.list
    stories = Array.wrap(response.list.stories)
  end

  stories
end

#to_params ⇒ Object

Build the params hash. This is automatically called by #to_a, so it probably doesn’t need to be used manually.



28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
 
# File 'lib/npr/api/query_builder.rb', line 28

def to_params
  if @_klass == NPR::Entity::Story && @builder[:conditions]
    conditions = parse_conditions(@builder[:conditions])
  else
    conditions = @builder[:conditions]
  end

  params = conditions || {}
  params[:sort]       = @builder[:order]  if @builder[:order]
  params[:numResults] = @builder[:limit]  if @builder[:limit]
  params[:startNum]   = @builder[:offset] if @builder[:offset]
  params.merge!(@builder[:extra])         if @builder[:extra]

  params
end

#where(conditions) ⇒ Object

Merge in the passed-in conditions to what already exists.

Accepts a Hash.

Example:

query.where(id: 999, requiredAssets: "text")

Extra convenience:

  • You may pass an array to :id

    query.where(id: [70, 180])

  • You may pass a date range to :date

    last_week = Time.new(2012, 10, 21)
yesterday = Time.new(2012, 10, 25)
query.where(date: (last_week..yesterday))



136
137
138
139
 
# File 'lib/npr/api/query_builder.rb', line 136

def where(conditions)
  @builder[:conditions] = (@builder[:conditions] || {}).merge(conditions)
  self
end