Class: WhosGotDirt::Request

Inherits:
Object
  • Object
show all
Defined in:
lib/whos_got_dirt/request.rb

Overview

Accepts MQL parameters and return URLs to request.

Examples:

Create a new class for transforming parameters to URLs.

class MyAPIRequest < WhosGotDirt::Request
  @base_url = 'https://api.example.com'

  def to_s
    "#{base_url}/endpoint?#{to_query(input)}"
  end
end

Use the class in requesting a URL.

url = MyAPIRequest.new(name: 'John Smith').to_s
response = Faraday.get(url)
#=> "https://api.example.com/endpoint?name=John+Smith"

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(input = {}) ⇒ Request

Sets the MQL parameters.

Parameters:

  • input (Hash) (defaults to: {}) —

    the MQL parameters



45
46
47
48
 
# File 'lib/whos_got_dirt/request.rb', line 45

def initialize(input = {})
  @input = ActiveSupport::HashWithIndifferentAccess.new(input)
  @output = {}
end

Class Attribute Details

.base_url ⇒ Object (readonly)

Returns the value of attribute base_url.



21
22
23
 
# File 'lib/whos_got_dirt/request.rb', line 21

def base_url
  @base_url
end

Instance Attribute Details

#:output(: output) ⇒ Hash

Returns the API-specific parameters.

Returns:

  • (Hash) —

    the API-specific parameters



40
 
# File 'lib/whos_got_dirt/request.rb', line 40

attr_reader :output

#input ⇒ Hash

Returns the MQL parameters.

Returns:

  • (Hash) —

    the MQL parameters



36
37
38
 
# File 'lib/whos_got_dirt/request.rb', line 36

def input
  @input
end

#output ⇒ Object (readonly)

Returns the value of attribute output.



40
41
42
 
# File 'lib/whos_got_dirt/request.rb', line 40

def output
  @output
end

Class Method Details

.to_query(params) ⇒ String

Transforms a query string from a hash to a string.

Parameters:

  • params (Hash) —

    query string parameters

Returns:

  • (String) —

    a query string



27
28
29
30
31
 
# File 'lib/whos_got_dirt/request.rb', line 27

def to_query(params)
  params.map do |key,value|
    "#{CGI.escape(key.to_s)}=#{CGI.escape(value.to_s)}"
  end * '&'
end

Instance Method Details

#all_of(target, source, opts = {}) ⇒ Hash

Helper method to map a parameter that supports MQL AND-like constraints.

Parameters:

  • target (String) —

    the API-specific parameter name

  • source (String) —

    the request parameter name

  • opts (Hash) (defaults to: {}) —

    options

Options Hash (opts):

  • :input (String) —

    substitute MQL parameters

  • :transform (String) —

    a transformation to apply to the value

  • :transform (String) —

    a transformation to apply to the value

Returns:

  • (Hash) —

    the API-specific parameters



134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
 
# File 'lib/whos_got_dirt/request.rb', line 134

def all_of(target, source, opts = {})
  params = parameters(opts)

  if params[source]
    equal(target, source, opts)
  else
    values = []
    params.each do |key,value|
      if key[/:([a-z_]+)$/, 1] == source
        values << value
      end
    end
    if values.empty?
      if opts.key?(:backup)
        send(opts[:backup], target, source, opts)
      end
    else
      output[target] = values.map{|v| transform(v, opts)}.join(and_operator)
    end
  end

  output
end

#and_operator ⇒ Object

This method is abstract.

Subclass and override #and_operator to return the "AND" operator's serialization

Raises:

  • (NotImplementedError) 


186
187
188
 
# File 'lib/whos_got_dirt/request.rb', line 186

def and_operator
  raise NotImplementedError
end

#base_url ⇒ String

Returns the base URL to be used in the request.

Returns:

  • (String) —

    the base URL to be used in the request



53
54
55
 
# File 'lib/whos_got_dirt/request.rb', line 53

def base_url
  self.class.base_url
end

#date_range(target, source, opts = {}) ⇒ Hash

Helper method to map a date parameter that supports comparisons.

Parameters:

  • target (String) —

    the API-specific parameter name

  • source (String) —

    the request parameter name

  • opts (Hash) (defaults to: {}) —

    options

Options Hash (opts):

  • :input (String) —

    substitute MQL parameters

Returns:

  • (Hash) —

    the API-specific parameters



165
166
167
168
169
170
171
172
173
174
175
176
 
# File 'lib/whos_got_dirt/request.rb', line 165

def date_range(target, source, opts = {})
  params = parameters(opts)

  # @note OpenCorporates date range format.
  if params[source]
    output[target] = "#{params[source]}:#{params[source]}"
  elsif params["#{source}>="] || params["#{source}>"] || params["#{source}<="] || params["#{source}<"]
    output[target] = "#{params["#{source}>="] || params["#{source}>"]}:#{params["#{source}<="] || params["#{source}<"]}"
  end

  output
end

#equal(target, source, opts = {}) ⇒ Hash

Helper method to map a parameter that supports the MQL equality operator.

Parameters:

  • target (String) —

    the API-specific parameter name

  • source (String) —

    the request parameter name

  • opts (Hash) (defaults to: {}) —

    options

Options Hash (opts):

  • :input (String) —

    substitute MQL parameters

  • :transform (String) —

    a transformation to apply to the value

  • :default (String) —

    the default value

  • :valid (Set, Array) —

    a list of valid values

Returns:

  • (Hash) —

    the API-specific parameters



67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
 
# File 'lib/whos_got_dirt/request.rb', line 67

def equal(target, source, opts = {})
  params = parameters(opts)

  if opts.key?(:valid)
    if opts[:valid].include?(params[source])
      output[target] = transform(params[source], opts)
    end
  else
    if params[source]
      output[target] = transform(params[source], opts)
    elsif opts[:default]
      output[target] = opts[:default]
    end
  end

  output
end

#match(target, source, opts = {}) ⇒ Hash

Helper method to map a parameter that supports the MQL ~= operator.

Parameters:

  • target (String) —

    the API-specific parameter name

  • source (String) —

    the request parameter name

  • opts (Hash) (defaults to: {}) —

    options

Options Hash (opts):

  • :input (String) —

    substitute MQL parameters

  • :transform (String) —

    a transformation to apply to the value

Returns:

  • (Hash) —

    the API-specific parameters



93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/whos_got_dirt/request.rb', line 93

def match(target, source, opts = {})
  params = parameters(opts)

  if params[source]
    equal(target, source, opts)
  elsif params["#{source}~="]
    output[target] = transform(params["#{source}~="], opts)
  end

  output
end

#one_of(target, source, opts = {}) ⇒ Hash

Helper method to map a parameter that supports the MQL |= operator.

Parameters:

  • target (String) —

    the API-specific parameter name

  • source (String) —

    the request parameter name

  • opts (Hash) (defaults to: {}) —

    options

Options Hash (opts):

  • :input (String) —

    substitute MQL parameters

  • :transform (String) —

    a transformation to apply to the value

Returns:

  • (Hash) —

    the API-specific parameters



113
114
115
116
117
118
119
120
121
122
123
 
# File 'lib/whos_got_dirt/request.rb', line 113

def one_of(target, source, opts = {})
  params = parameters(opts)

  if params[source]
    equal(target, source, opts)
  elsif params["#{source}|="]
    output[target] = params["#{source}|="].map{|v| transform(v, opts)}.join(or_operator)
  end

  output
end

#or_operator ⇒ Object

This method is abstract.

Subclass and override #or_operator to return the "OR" operator's serialization

Raises:

  • (NotImplementedError) 


192
193
194
 
# File 'lib/whos_got_dirt/request.rb', line 192

def or_operator
  raise NotImplementedError
end

#to_s ⇒ Object

This method is abstract.

Subclass and override #to_s to return the URL from which to GET the results

Raises:

  • (NotImplementedError) 


180
181
182
 
# File 'lib/whos_got_dirt/request.rb', line 180

def to_s
  raise NotImplementedError
end