Class: Apidiesel::Dsl::FilterBuilder

Inherits:
Object
  • Object
show all
Defined in:
lib/apidiesel/dsl.rb

Overview

FilterBuilder defines the methods available within an responds_with block when defining an API action.

Instance Method Summary collapse

Instance Method Details

#array(key, **kargs) ⇒ nil #array(at: , as: , **kargs) ⇒ nil

Returns a array from the API response hash

Examples:


# Given an API response:
#
# {
#   order_id: 5,
#   ordered_at :"2020-01-01",
#   products: [{
#     name: 'Catnip 2lbs',
#     product_id: 2004921
#   }]
# }

expects do
  integer :order_id
  datetime :ordered_at

  array :products do
    string :name
    integer :product_id
  end
end
# Given an API response:
#
# [
#   {
#     name: 'Catnip 2lbs',
#     order_id: 2004921
#   },
#   {
#     name: 'Catnip 5lbs',
#     order_id: 2004922
#   },
# ]

expects do
  array do
    string :name
    integer :order_id
  end
end

Overloads:

  • #array(key, **kargs) ⇒ nil

    Get the array named key from the response hash and name it key in the result hash

    Parameters:

    • key (String, Symbol)

    Options Hash (**kargs):

    • :prefilter (Proc) —

      callback for modifying the value before typecasting

    • :postfilter (Proc) —

      callback for modifying the value after typecasting

    • :filter (Proc) —

      alias for :postfilter

    • :map (Hash) —

      a hash map for replacing the value

  • #array(at: , as: , **kargs) ⇒ nil

    Get the array named at: from the response hash and name it as: in the result hash

    Parameters:

    • at (String, Symbol, Array<Symbol>) (defaults to: ) —

      response hash key name or key path to lookup

    • as (String, Symbol) (defaults to: ) —

      result hash key name to return the value as

    Options Hash (**kargs):

    • :prefilter (Proc) —

      callback for modifying the value before typecasting

    • :postfilter (Proc) —

      callback for modifying the value after typecasting

    • :filter (Proc) —

      alias for :postfilter

    • :map (Hash) —

      a hash map for replacing the value

Returns:

  • (nil) 


446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
 
# File 'lib/apidiesel/dsl.rb', line 446

def array(*args, **kargs, &block)
  unless block.present?
    create_primitive_formatter(:to_a, *args, **kargs)
    return
  end

  args = normalize_arguments(args, kargs)

  response_formatters << lambda do |data, processed_data|
    data = get_value(data, args[:at]) if args[:at]

    return processed_data unless data.present?

    data = [data] if data.is_a?(Hash)

    array_of_hashes = data.map do |hash|
      builder = FilterBuilder.new
      builder.instance_eval(&block)

      result = {}

      hash = apply_filter(args[:prefilter_each], hash)

      next if hash.blank?

      builder.response_formatters.each do |filter|
        result = filter.call(hash, result)
        break if result.blank?
      end

      next if result.blank?

      result = apply_filter(args[:postfilter_each] || args[:filter_each], result)

      result
    end

    if args[:as]
      processed_data[ args[:as] ] = array_of_hashes.compact
      processed_data
    else
      array_of_hashes.compact
    end
  end
end

#boolean(key, **kargs) ⇒ nil #boolean(at: , as: , **kargs) ⇒ nil

Returns a boolean from the API response hash

Please note that response value is typecasted to String for comparison, so that for absent values to be considered false, you have to include an empty string.

Overloads:

  • #boolean(key, **kargs) ⇒ nil

    Get the boolean named key from the response hash and name it key in the result hash

    Parameters:

    • key (String, Symbol)

    Options Hash (**kargs):

    • :prefilter (Proc) —

      callback for modifying the value before typecasting

    • :postfilter (Proc) —

      callback for modifying the value after typecasting

    • :filter (Proc) —

      alias for :postfilter

    • :map (Hash) —

      a hash map for replacing the value

  • #boolean(at: , as: , **kargs) ⇒ nil

    Get the boolean named at: from the response hash and name it as: in the result hash

    Parameters:

    • at (String, Symbol, Array<Symbol>) (defaults to: ) —

      response hash key name or key path to lookup

    • as (String, Symbol) (defaults to: ) —

      result hash key name to return the value as

    Options Hash (**kargs):

    • :prefilter (Proc) —

      callback for modifying the value before typecasting

    • :postfilter (Proc) —

      callback for modifying the value after typecasting

    • :filter (Proc) —

      alias for :postfilter

    • :map (Hash) —

      a hash map for replacing the value

Parameters:

  • kargs (Hash) —

    a customizable set of options

Options Hash (**kargs):

  • :truthy (Array<#to_s>, #to_s) — default: 'true' —

    values to be considered true

  • :falsy (Array<#to_s>, #to_s) — default: 'false' —

    values to be considered false

Returns:

  • (nil) 


279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
 
# File 'lib/apidiesel/dsl.rb', line 279

def boolean(*args, **kargs)
  args = normalize_arguments(args, kargs)

  args.reverse_merge!(truthy: 'true', falsy: 'false')

  args[:truthy] = Array(args[:truthy]).map(&:to_s)
  args[:falsy]  = Array(args[:falsy]).map(&:to_s)

  response_formatters << lambda do |data, processed_data|
    value = get_value(data, args[:at])

    value = apply_filter(args[:prefilter], value)

    value = if args[:truthy].include?(value.to_s)
      true
    elsif args[:falsy].include?(value.to_s)
      false
    else
      nil
    end

    value = apply_filter(args[:postfilter] || args[:filter], value)

    value = args[:map][value] if args[:map]

    processed_data[ args[:as] ] = value

    processed_data
  end
end

#date(key, **kargs) ⇒ nil #date(at: , as: , **kargs) ⇒ nil

Returns a date from the API response hash

Overloads:

  • #date(key, **kargs) ⇒ nil

    Get the date named key from the response hash and name it key in the result hash

    Parameters:

    • key (String, Symbol)

    Options Hash (**kargs):

    • :prefilter (Proc) —

      callback for modifying the value before typecasting

    • :postfilter (Proc) —

      callback for modifying the value after typecasting

    • :filter (Proc) —

      alias for :postfilter

    • :map (Hash) —

      a hash map for replacing the value

  • #date(at: , as: , **kargs) ⇒ nil

    Get the date named at: from the response hash and name it as: in the result hash

    Parameters:

    • at (String, Symbol, Array<Symbol>) (defaults to: ) —

      response hash key name or key path to lookup

    • as (String, Symbol) (defaults to: ) —

      result hash key name to return the value as

    Options Hash (**kargs):

    • :prefilter (Proc) —

      callback for modifying the value before typecasting

    • :postfilter (Proc) —

      callback for modifying the value after typecasting

    • :filter (Proc) —

      alias for :postfilter

    • :map (Hash) —

      a hash map for replacing the value

Returns:

  • (nil) 


355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
 
# File 'lib/apidiesel/dsl.rb', line 355

def date(*args, **kargs)
  args = normalize_arguments(args, kargs)
  args.reverse_merge!(format: '%Y-%m-%d')

  response_formatters << lambda do |data, processed_data|
    value = get_value(data, args[:at])

    value = apply_filter(args[:prefilter], value)

    if args.has_key?(:on_error)
      value = Date.strptime(value, args[:format]) rescue args[:on_error]
    else
      value = Date.strptime(value, args[:format])
    end

    value = apply_filter(args[:postfilter] || args[:filter], value)

    processed_data[ args[:as] ] = value

    processed_data
  end
end

#datetime(key, **kargs) ⇒ nil #datetime(at: , as: , **kargs) ⇒ nil

Returns a datetime from the API response hash

Overloads:

  • #datetime(key, **kargs) ⇒ nil

    Get the datetime named key from the response hash and name it key in the result hash

    Parameters:

    • key (String, Symbol)

    Options Hash (**kargs):

    • :prefilter (Proc) —

      callback for modifying the value before typecasting

    • :postfilter (Proc) —

      callback for modifying the value after typecasting

    • :filter (Proc) —

      alias for :postfilter

    • :map (Hash) —

      a hash map for replacing the value

  • #datetime(at: , as: , **kargs) ⇒ nil

    Get the datetime named at: from the response hash and name it as: in the result hash

    Parameters:

    • at (String, Symbol, Array<Symbol>) (defaults to: ) —

      response hash key name or key path to lookup

    • as (String, Symbol) (defaults to: ) —

      result hash key name to return the value as

    Options Hash (**kargs):

    • :prefilter (Proc) —

      callback for modifying the value before typecasting

    • :postfilter (Proc) —

      callback for modifying the value after typecasting

    • :filter (Proc) —

      alias for :postfilter

    • :map (Hash) —

      a hash map for replacing the value

Returns:

  • (nil) 


331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
 
# File 'lib/apidiesel/dsl.rb', line 331

def datetime(*args, **kargs)
  args = normalize_arguments(args, kargs)
  args.reverse_merge!(format: '%Y-%m-%d')

  response_formatters << lambda do |data, processed_data|
    value = get_value(data, args[:at])

    value = apply_filter(args[:prefilter], value)

    if args.has_key?(:on_error)
      value = DateTime.strptime(value, args[:format]) rescue args[:on_error]
    else
      value = DateTime.strptime(value, args[:format])
    end

    value = apply_filter(args[:postfilter] || args[:filter], value)

    processed_data[ args[:as] ] = value

    processed_data
  end
end

#float(key, **kargs) ⇒ nil #float(at: , as: , **kargs) ⇒ nil

Returns a float from the API response hash

Overloads:

  • #float(key, **kargs) ⇒ nil

    Get the float named key from the response hash and name it key in the result hash

    Parameters:

    • key (String, Symbol)

    Options Hash (**kargs):

    • :prefilter (Proc) —

      callback for modifying the value before typecasting

    • :postfilter (Proc) —

      callback for modifying the value after typecasting

    • :filter (Proc) —

      alias for :postfilter

    • :map (Hash) —

      a hash map for replacing the value

  • #float(at: , as: , **kargs) ⇒ nil

    Get the float named at: from the response hash and name it as: in the result hash

    Parameters:

    • at (String, Symbol, Array<Symbol>) (defaults to: ) —

      response hash key name or key path to lookup

    • as (String, Symbol) (defaults to: ) —

      result hash key name to return the value as

    Options Hash (**kargs):

    • :prefilter (Proc) —

      callback for modifying the value before typecasting

    • :postfilter (Proc) —

      callback for modifying the value after typecasting

    • :filter (Proc) —

      alias for :postfilter

    • :map (Hash) —

      a hash map for replacing the value

Returns:

  • (nil) 


321
322
323
 
# File 'lib/apidiesel/dsl.rb', line 321

def float(*args, **kargs)
  create_primitive_formatter(:to_f, *args, **kargs)
end

#hash(key, **kargs) ⇒ nil #hash(at: , as: , **kargs) ⇒ nil

Returns a hash from the API response hash

Overloads:

  • #hash(key, **kargs) ⇒ nil

    Get the hash named key from the response hash and name it key in the result hash

    Parameters:

    • key (String, Symbol)

    Options Hash (**kargs):

    • :prefilter (Proc) —

      callback for modifying the value before typecasting

    • :postfilter (Proc) —

      callback for modifying the value after typecasting

    • :filter (Proc) —

      alias for :postfilter

    • :map (Hash) —

      a hash map for replacing the value

  • #hash(at: , as: , **kargs) ⇒ nil

    Get the hash named at: from the response hash and name it as: in the result hash

    Parameters:

    • at (String, Symbol, Array<Symbol>) (defaults to: ) —

      response hash key name or key path to lookup

    • as (String, Symbol) (defaults to: ) —

      result hash key name to return the value as

    Options Hash (**kargs):

    • :prefilter (Proc) —

      callback for modifying the value before typecasting

    • :postfilter (Proc) —

      callback for modifying the value after typecasting

    • :filter (Proc) —

      alias for :postfilter

    • :map (Hash) —

      a hash map for replacing the value

Returns:

  • (nil) 


493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
 
# File 'lib/apidiesel/dsl.rb', line 493

def hash(*args, **kargs, &block)
  unless block.present?
    create_primitive_formatter(:to_hash, *args, **kargs)
    return
  end

  args = normalize_arguments(args, kargs)

  response_formatters << lambda do |data, processed_data|
    data = get_value(data, args[:at])

    return processed_data unless data.is_a?(Hash)

    hash = apply_filter(args[:prefilter], data)

    result = {}

    builder = FilterBuilder.new
    builder.instance_eval(&block)

    builder.response_formatters.each do |filter|
      result = filter.call(hash, result)
    end

    result = apply_filter(args[:postfilter_each] || args[:filter_each], result)

    processed_data[ args[:as] ] = result

    processed_data
  end
end

#integer(key, **kargs) ⇒ nil #integer(at: , as: , **kargs) ⇒ nil

Returns a integer from the API response hash

Overloads:

  • #integer(key, **kargs) ⇒ nil

    Get the integer named key from the response hash and name it key in the result hash

    Parameters:

    • key (String, Symbol)

    Options Hash (**kargs):

    • :prefilter (Proc) —

      callback for modifying the value before typecasting

    • :postfilter (Proc) —

      callback for modifying the value after typecasting

    • :filter (Proc) —

      alias for :postfilter

    • :map (Hash) —

      a hash map for replacing the value

  • #integer(at: , as: , **kargs) ⇒ nil

    Get the integer named at: from the response hash and name it as: in the result hash

    Parameters:

    • at (String, Symbol, Array<Symbol>) (defaults to: ) —

      response hash key name or key path to lookup

    • as (String, Symbol) (defaults to: ) —

      result hash key name to return the value as

    Options Hash (**kargs):

    • :prefilter (Proc) —

      callback for modifying the value before typecasting

    • :postfilter (Proc) —

      callback for modifying the value after typecasting

    • :filter (Proc) —

      alias for :postfilter

    • :map (Hash) —

      a hash map for replacing the value

Returns:

  • (nil) 


316
317
318
 
# File 'lib/apidiesel/dsl.rb', line 316

def integer(*args, **kargs)
  create_primitive_formatter(:to_i, *args, **kargs)
end

#objects(key, **kargs) ⇒ nil #objects(at: , as: , **kargs) ⇒ nil

Returns a objects from the API response hash

Examples:

responds_with do
  object :issues,
          processed_with: ->(data) {
            data.delete_if { |k,v| k == 'www_id' }
          }
end

responds_with do
  object :issues,
          wrapped_in: Apidiesel::ResponseObjects::Topic
end

Overloads:

  • #objects(key, **kargs) ⇒ nil

    Get the objects named key from the response hash and name it key in the result hash

    Parameters:

    • key (String, Symbol)

    Options Hash (**kargs):

    • :prefilter (Proc) —

      callback for modifying the value before typecasting

    • :postfilter (Proc) —

      callback for modifying the value after typecasting

    • :filter (Proc) —

      alias for :postfilter

    • :map (Hash) —

      a hash map for replacing the value

  • #objects(at: , as: , **kargs) ⇒ nil

    Get the objects named at: from the response hash and name it as: in the result hash

    Parameters:

    • at (String, Symbol, Array<Symbol>) (defaults to: ) —

      response hash key name or key path to lookup

    • as (String, Symbol) (defaults to: ) —

      result hash key name to return the value as

    Options Hash (**kargs):

    • :prefilter (Proc) —

      callback for modifying the value before typecasting

    • :postfilter (Proc) —

      callback for modifying the value after typecasting

    • :filter (Proc) —

      alias for :postfilter

    • :map (Hash) —

      a hash map for replacing the value

Parameters:

  • kargs (Hash) —

    a customizable set of options

Options Hash (**kargs):

  • :processed_with (Proc) —

    yield the data to this Proc for processing

  • :wrapped_in (Class) —

    wrapper object, will be called as Object.create(data)

Returns:

  • (nil) 


543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
 
# File 'lib/apidiesel/dsl.rb', line 543

def objects(*args, **kargs)
  args = normalize_arguments(args, kargs)

  response_formatters << lambda do |data, processed_data|
    value = get_value(data, args[:at])

    value = apply_filter(args[:prefilter], value)

    value = args[:type].send(:create, value)

    value = apply_filter(args[:postfilter] || args[:filter], value)

    processed_data[ args[:as] ] = value

    processed_data
  end
end

#response_error_if(callable, message:) ⇒ Object

Raises an Apidiesel::ResponseError if the callable returns true

Examples:

responds_with do
  response_error_if ->(data) { data[:code] != 0 },
                    message: ->(data) { data[:message] }

Parameters:

  • callable (Lambda, Proc)
  • message (String, Lambda, Proc)

Raises:



586
587
588
589
590
591
592
 
# File 'lib/apidiesel/dsl.rb', line 586

def response_error_if(callable, message:)
  response_formatters << lambda do |data, processed_data|
    return processed_data unless callable.call(data)

    raise ResponseError.new(error_message(message, data))
  end
end

#set_scope(key) ⇒ Object

Descends into the hash key hierarchy

Useful for cutting out useless top-level keys

Parameters:

  • key (Symbol, Array) 


570
571
572
573
574
 
# File 'lib/apidiesel/dsl.rb', line 570

def set_scope(key)
  response_filters << lambda do |data|
    fetch_path(data, *key)
  end
end

#string(key, **kargs) ⇒ nil #string(at: , as: , **kargs) ⇒ nil

Returns a string from the API response hash

Overloads:

  • #string(key, **kargs) ⇒ nil

    Get the string named key from the response hash and name it key in the result hash

    Parameters:

    • key (String, Symbol)

    Options Hash (**kargs):

    • :prefilter (Proc) —

      callback for modifying the value before typecasting

    • :postfilter (Proc) —

      callback for modifying the value after typecasting

    • :filter (Proc) —

      alias for :postfilter

    • :map (Hash) —

      a hash map for replacing the value

  • #string(at: , as: , **kargs) ⇒ nil

    Get the string named at: from the response hash and name it as: in the result hash

    Parameters:

    • at (String, Symbol, Array<Symbol>) (defaults to: ) —

      response hash key name or key path to lookup

    • as (String, Symbol) (defaults to: ) —

      result hash key name to return the value as

    Options Hash (**kargs):

    • :prefilter (Proc) —

      callback for modifying the value before typecasting

    • :postfilter (Proc) —

      callback for modifying the value after typecasting

    • :filter (Proc) —

      alias for :postfilter

    • :map (Hash) —

      a hash map for replacing the value

Returns:

  • (nil) 


311
312
313
 
# File 'lib/apidiesel/dsl.rb', line 311

def string(*args, **kargs)
  create_primitive_formatter(:to_s, *args, **kargs)
end

#symbol(key, **kargs) ⇒ nil #symbol(at: , as: , **kargs) ⇒ nil

Returns a symbol from the API response hash

Overloads:

  • #symbol(key, **kargs) ⇒ nil

    Get the symbol named key from the response hash and name it key in the result hash

    Parameters:

    • key (String, Symbol)

    Options Hash (**kargs):

    • :prefilter (Proc) —

      callback for modifying the value before typecasting

    • :postfilter (Proc) —

      callback for modifying the value after typecasting

    • :filter (Proc) —

      alias for :postfilter

    • :map (Hash) —

      a hash map for replacing the value

  • #symbol(at: , as: , **kargs) ⇒ nil

    Get the symbol named at: from the response hash and name it as: in the result hash

    Parameters:

    • at (String, Symbol, Array<Symbol>) (defaults to: ) —

      response hash key name or key path to lookup

    • as (String, Symbol) (defaults to: ) —

      result hash key name to return the value as

    Options Hash (**kargs):

    • :prefilter (Proc) —

      callback for modifying the value before typecasting

    • :postfilter (Proc) —

      callback for modifying the value after typecasting

    • :filter (Proc) —

      alias for :postfilter

    • :map (Hash) —

      a hash map for replacing the value

Returns:

  • (nil) 


326
327
328
 
# File 'lib/apidiesel/dsl.rb', line 326

def symbol(*args, **kargs)
  create_primitive_formatter(:to_sym, *args, **kargs)
end

#time(key, **kargs) ⇒ nil #time(at: , as: , **kargs) ⇒ nil

Returns a time from the API response hash

Overloads:

  • #time(key, **kargs) ⇒ nil

    Get the time named key from the response hash and name it key in the result hash

    Parameters:

    • key (String, Symbol)

    Options Hash (**kargs):

    • :prefilter (Proc) —

      callback for modifying the value before typecasting

    • :postfilter (Proc) —

      callback for modifying the value after typecasting

    • :filter (Proc) —

      alias for :postfilter

    • :map (Hash) —

      a hash map for replacing the value

  • #time(at: , as: , **kargs) ⇒ nil

    Get the time named at: from the response hash and name it as: in the result hash

    Parameters:

    • at (String, Symbol, Array<Symbol>) (defaults to: ) —

      response hash key name or key path to lookup

    • as (String, Symbol) (defaults to: ) —

      result hash key name to return the value as

    Options Hash (**kargs):

    • :prefilter (Proc) —

      callback for modifying the value before typecasting

    • :postfilter (Proc) —

      callback for modifying the value after typecasting

    • :filter (Proc) —

      alias for :postfilter

    • :map (Hash) —

      a hash map for replacing the value

Returns:

  • (nil) 


379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
 
# File 'lib/apidiesel/dsl.rb', line 379

def time(*args, **kargs)
  args = normalize_arguments(args, kargs)
  args.reverse_merge!(format: '%Y-%m-%d')

  response_formatters << lambda do |data, processed_data|
    value = get_value(data, args[:at])

    value = apply_filter(args[:prefilter], value)

    if args.has_key?(:on_error)
      value = Time.strptime(value, args[:format]) rescue args[:on_error]
    else
      value = Time.strptime(value, args[:format])
    end

    value = apply_filter(args[:postfilter] || args[:filter], value)

    processed_data[ args[:as] ] = value

    processed_data
  end
end

#value(key, **kargs) ⇒ nil #value(at: , as: , **kargs) ⇒ nil

Returns a value from the API response hash

Overloads:

  • #value(key, **kargs) ⇒ nil

    Get the value named key from the response hash and name it key in the result hash

    Parameters:

    • key (String, Symbol)

    Options Hash (**kargs):

    • :prefilter (Proc) —

      callback for modifying the value before typecasting

    • :postfilter (Proc) —

      callback for modifying the value after typecasting

    • :filter (Proc) —

      alias for :postfilter

    • :map (Hash) —

      a hash map for replacing the value

  • #value(at: , as: , **kargs) ⇒ nil

    Get the value named at: from the response hash and name it as: in the result hash

    Parameters:

    • at (String, Symbol, Array<Symbol>) (defaults to: ) —

      response hash key name or key path to lookup

    • as (String, Symbol) (defaults to: ) —

      result hash key name to return the value as

    Options Hash (**kargs):

    • :prefilter (Proc) —

      callback for modifying the value before typecasting

    • :postfilter (Proc) —

      callback for modifying the value after typecasting

    • :filter (Proc) —

      alias for :postfilter

    • :map (Hash) —

      a hash map for replacing the value

Returns:

  • (nil) 


254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
 
# File 'lib/apidiesel/dsl.rb', line 254

def value(*args, **kargs)
  args = normalize_arguments(args, kargs)

  response_formatters << lambda do |data, processed_data|
    value = get_value(data, args[:at])

    value = apply_filter(args[:prefilter], value)

    value = apply_filter(args[:postfilter] || args[:filter], value)

    value = args[:map][value] if args[:map]

    processed_data[ args[:as] ] = value

    processed_data
  end
end