class ROM::HTTP::Dataset

HTTP Dataset

Represents a specific HTTP collection resource. This class can be subclassed in a specialized HTTP adapter to provide its own response/request handlers or any other configuration that should differ from the defaults.

@api public

Constants

PATH_SEPARATOR

Public Instance Methods

absolute_path() click to toggle source

Return the dataset path

@example

Dataset.new(path: '/users').path
# => '/users'

@return [String] the dataset path, with leading slash

@api public

# File lib/rom/http/dataset.rb, line 199
def absolute_path
  PATH_SEPARATOR + path
end
add_body_params(new_body_params) click to toggle source

Return a new dataset with merged request body parameters

@param [Hash] body_params the new request body parameters to add

@example

users = Dataset.new(body_params: { uid: 33 })
users.add_body_params(login: 'jdoe').body_params
# => { uid: 33, :login => 'jdoe' }

@return [Dataset]

@api public

# File lib/rom/http/dataset.rb, line 370
def add_body_params(new_body_params)
  with_options(body_params: ::ROM::HTTP::Transformer[:deep_merge][body_params,
                                                                  new_body_params])
end
add_header(header, value) click to toggle source

Return a new dataset with additional header

@param header [Symbol] the HTTP header to add @param value [String] the header value

@example

users = Dataset.new(headers: { Accept: 'application/json' })
users.add_header(:'X-Api-Key', '1234').headers
# => { :Accept => 'application/json', :'X-Api-Key' => '1234' }

@return [Dataset]

@api public

# File lib/rom/http/dataset.rb, line 235
def add_header(header, value)
  with_headers(headers.merge(header => value))
end
add_query_params(new_query_params) click to toggle source

Return a new dataset with merged request query parameters

@param [Hash] query_params the new request query parameters to add

@example

users = Dataset.new(query_params: { uid: 33 })
users.add_query_params(login: 'jdoe').query_params
# => { uid: 33, :login => 'jdoe' }

@return [Dataset]

@api public

# File lib/rom/http/dataset.rb, line 337
def add_query_params(new_query_params)
  with_options(query_params: ::ROM::HTTP::Transformer[:deep_merge][query_params,
                                                                   new_query_params])
end
append_path(append_path) click to toggle source

Return a new dataset with a modified path

@param path [String] new path fragment

@example

users.append_path('profiles').path
# => users/profiles

@return [Dataset]

@api public

# File lib/rom/http/dataset.rb, line 291
def append_path(append_path)
  with_path(join_path(options[:path], append_path))
end
delete() click to toggle source

Perform an delete over HTTP Delete

@return [Array<Hash>]

@api public

# File lib/rom/http/dataset.rb, line 423
def delete
  with_options(request_method: :delete).response
end
delete?() click to toggle source

Return true if request method is set to :delete

@return [Boolean]

@api public

# File lib/rom/http/dataset.rb, line 173
def delete?
  request_method.equal?(:delete)
end
each(&block) click to toggle source

Iterate over each response value

@yield [Hash] a dataset tuple

@return [Enumerator] if no block is given @return [Array<Hash>]

@api public

# File lib/rom/http/dataset.rb, line 383
def each(&block)
  return to_enum unless block_given?

  response.each(&block)
end
get?() click to toggle source

Return true if request method is set to :get

@return [Boolean]

@api public

# File lib/rom/http/dataset.rb, line 146
def get?
  request_method.equal?(:get)
end
insert(attributes) click to toggle source

Perform an insert over HTTP Post

@param [Hash] attributes the attributes to insert

@return [Array<Hash>]

@api public

# File lib/rom/http/dataset.rb, line 396
def insert(attributes)
  with_options(
    request_method: :post,
    body_params: attributes
  ).response
end
path() click to toggle source

Return the dataset path

@example

Dataset.new(path: '/users').path
# => 'users'

@return [String] the dataset path, without a leading slash

@api public

Calls superclass method
# File lib/rom/http/dataset.rb, line 186
def path
  join_path(base_path, super)
end
post?() click to toggle source

Return true if request method is set to :post

@return [Boolean]

@api public

# File lib/rom/http/dataset.rb, line 155
def post?
  request_method.equal?(:post)
end
put?() click to toggle source

Return true if request method is set to :put

@return [Boolean]

@api public

# File lib/rom/http/dataset.rb, line 164
def put?
  request_method.equal?(:put)
end
response() click to toggle source

Execute the current dataset

@return [Array<hash>]

@api public

# File lib/rom/http/dataset.rb, line 432
def response
  response_handler.call(request_handler.call(self), self)
end
update(attributes) click to toggle source

Perform an update over HTTP Put

@param [Hash] attributes the attributes to update

@return [Array<Hash>]

@api public

# File lib/rom/http/dataset.rb, line 410
def update(attributes)
  with_options(
    request_method: :put,
    body_params: attributes
  ).response
end
uri() click to toggle source

Return the dataset’s URI

@return [URI::HTTP]

@api public

Calls superclass method
# File lib/rom/http/dataset.rb, line 131
def uri
  uri = URI(join_path(super, path))

  if query_params.any?
    uri.query = query_param_encoder.call(query_params)
  end

  uri
end
with_base_path(base_path) click to toggle source

Return a new dataset with a different base path

@param base_path [String] the new base request path

@example

users.with_base_path('/profiles').base_path
# => 'profiles'

@return [Dataset]

@api public

# File lib/rom/http/dataset.rb, line 261
def with_base_path(base_path)
  with_options(base_path: base_path)
end
with_body_params(body_params) click to toggle source

Return a new dataset with replaced request body parameters

@param [Hash] body_params the new request body parameters

@example

users = Dataset.new(body_params: { uid: 33 })
users.with_body_params(login: 'jdoe').body_params
# => { :login => 'jdoe' }

@return [Dataset]

@api public

# File lib/rom/http/dataset.rb, line 354
def with_body_params(body_params)
  with_options(body_params: body_params)
end
with_headers(headers) click to toggle source

Return a new dataset with given headers

@param headers [Hash] The new headers

@note this replaces the dataset’s currently configured headers.

To non-destructively add a new header, use `#add_header`

@example

users = Dataset.new(headers: { Accept: 'application/json' })
users.with_headers(:'X-Api-Key' => '1234').headers
# => { :'X-Api-Key' => '1234' }

@return [Dataset]

@api public

# File lib/rom/http/dataset.rb, line 218
def with_headers(headers)
  with_options(headers: headers)
end
with_options(opts) click to toggle source

Return a new dataset with additional options

@param opts [Hash] the new options to add

@return [Dataset]

@api public

# File lib/rom/http/dataset.rb, line 246
def with_options(opts)
  __new__(**options.merge(opts))
end
with_path(path) click to toggle source

Return a new dataset with a different path

@param path [String] the new request path

@example

users.with_path('/profiles').path
# => 'profiles'

@return [Dataset]

@api public

# File lib/rom/http/dataset.rb, line 276
def with_path(path)
  with_options(path: path)
end
with_query_params(query_params) click to toggle source

Return a new dataset with replaced request query parameters

@param [Hash] query_params the new request query parameters

@example

users = Dataset.new(query_params: { uid: 33 })
users.with_query_params(login: 'jdoe').query_params
# => { :login => 'jdoe' }

@return [Dataset]

@api public

# File lib/rom/http/dataset.rb, line 321
def with_query_params(query_params)
  with_options(query_params: query_params)
end
with_request_method(request_method) click to toggle source

Return a new dataset with a different request method

@param [Symbol] request_method the new HTTP verb

@example

users.request_method(:put)

@return [Dataset]

@api public

# File lib/rom/http/dataset.rb, line 305
def with_request_method(request_method)
  with_options(request_method: request_method)
end

Private Instance Methods

__new__(*args, **kwargs, &block) click to toggle source

@api private

# File lib/rom/http/dataset.rb, line 441
def __new__(*args, **kwargs, &block)
  self.class.new(*args, **kwargs, &block)
end
join_path(*paths) click to toggle source

@api private

# File lib/rom/http/dataset.rb, line 446
def join_path(*paths)
  paths.reject(&:empty?).join(PATH_SEPARATOR)
end