Class: Stripe::ListObject

Inherits:
StripeObject show all
Includes:
Enumerable, APIOperations::Create, APIOperations::List, APIOperations::Request
Defined in:
lib/stripe/list_object.rb

Constant Summary collapse

OBJECT_NAME = 
"list"

Constants inherited from StripeObject

StripeObject::RESERVED_FIELD_NAMES

Instance Attribute Summary collapse

Attributes inherited from StripeObject

#last_response

Class Method Summary collapse

Instance Method Summary collapse

Methods included from APIOperations::Create

#create

Methods included from APIOperations::Request

included

Methods included from APIOperations::List

#list

Methods inherited from StripeObject

#==, #[]=, #_get_inner_class_type, additive_object_param, additive_object_param?, #as_json, construct_from, #deleted?, #dirty!, #eql?, field_encodings, field_remappings, #hash, inner_class_types, #inspect, #keys, #marshal_dump, #marshal_load, protected_fields, #serialize_params, #to_hash, #to_json, #to_s, #update_attributes, #values

Constructor Details

#initialize(*args) ⇒ ListObject

Returns a new instance of ListObject.



27
28
29
30
 
# File 'lib/stripe/list_object.rb', line 27

def initialize(*args)
  super
  self.filters = {}
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class Stripe::StripeObject

Instance Attribute Details

#filters ⇒ Object

This accessor allows a ListObject to inherit various filters that were given to a predecessor. This allows for things like consistent limits, expansions, and predicates as a user pages through resources.



18
19
20
 
# File 'lib/stripe/list_object.rb', line 18

def filters
  @filters
end

Class Method Details

.empty_list(opts = {}) ⇒ Object

An empty list object. This is returned from next when we know that there isn't a next page in order to replicate the behavior of the API when it attempts to return a page beyond the last.



23
24
25
 
# File 'lib/stripe/list_object.rb', line 23

def self.empty_list(opts = {})
  ListObject.construct_from({ data: [] }, opts, nil, :v1)
end

.object_name ⇒ Object 



11
12
13
 
# File 'lib/stripe/list_object.rb', line 11

def self.object_name
  "list"
end

Instance Method Details

#[](key) ⇒ Object 



32
33
34
35
36
37
38
39
40
41
42
43
 
# File 'lib/stripe/list_object.rb', line 32

def [](key)
  case key
  when String, Symbol
    super
  else
    raise ArgumentError,
          "You tried to access the #{key.inspect} index, but ListObject " \
          "types only support String keys. (HINT: List calls return an " \
          "object with a 'data' (which is the data array). You likely " \
          "want to call #data[#{key.inspect}])"
  end
end

#auto_paging_each(&blk) ⇒ Object

Iterates through each resource in all pages, making additional fetches to the API as necessary.

The default iteration direction is forwards according to Stripe's API "natural" ordering direction -- newer objects first, and moving towards older objects.

However, if the initial list object was fetched using an ending_before cursor (and only ending_before, starting_after cannot also be included), the method assumes that the user is trying to iterate backwards compared to natural ordering and returns results that way -- older objects first, and moving towards newer objects.

Note that this method will make as many API calls as necessary to fetch all resources. For more granular control, please see each and next_page.



70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
 
# File 'lib/stripe/list_object.rb', line 70

def auto_paging_each(&blk)
  return enum_for(:auto_paging_each) unless block_given?

  page = self
  loop do
    # Backward iterating activates if we have an `ending_before` constraint
    # and _just_ an `ending_before` constraint. If `starting_after` was
    # also used, we iterate forwards normally.
    if filters.include?(:ending_before) &&
       !filters.include?(:starting_after)
      page.reverse_each(&blk)
      page = page.previous_page
    else
      page.each(&blk)
      page = page.next_page
    end

    break if page.empty?
  rescue LocalJumpError => e
    raise unless e.reason == :break

    break
  end
end

#each(&blk) ⇒ Object

Iterates through each resource in the page represented by the current ListObject.

Note that this method makes no effort to fetch a new page when it gets to the end of the current page's resources. See also auto_paging_each.



50
51
52
 
# File 'lib/stripe/list_object.rb', line 50

def each(&blk)
  data.each(&blk)
end

#empty? ⇒ Boolean

Returns true if the page object contains no elements.

Returns:

  • (Boolean) 


96
97
98
 
# File 'lib/stripe/list_object.rb', line 96

def empty?
  data.empty?
end

#next_page(params = {}, opts = {}) ⇒ Object

Fetches the next page in the resource list (if there is one).

This method will try to respect the limit of the current page. If none was given, the default limit will be fetched again.



110
111
112
113
114
115
116
117
118
 
# File 'lib/stripe/list_object.rb', line 110

def next_page(params = {}, opts = {})
  return self.class.empty_list(opts) unless has_more

  last_id = data.last.id

  params = filters.merge(starting_after: last_id).merge(params)

  list(params, opts)
end

#previous_page(params = {}, opts = {}) ⇒ Object

Fetches the previous page in the resource list (if there is one).

This method will try to respect the limit of the current page. If none was given, the default limit will be fetched again.



124
125
126
127
128
129
130
131
132
 
# File 'lib/stripe/list_object.rb', line 124

def previous_page(params = {}, opts = {})
  return self.class.empty_list(opts) unless has_more

  first_id = data.first.id

  params = filters.merge(ending_before: first_id).merge(params)

  list(params, opts)
end

#resource_url ⇒ Object 



134
135
136
137
 
# File 'lib/stripe/list_object.rb', line 134

def resource_url
  url ||
    raise(ArgumentError, "List object does not contain a 'url' field.")
end

#retrieve(id, opts = {}) ⇒ Object 



100
101
102
103
104
 
# File 'lib/stripe/list_object.rb', line 100

def retrieve(id, opts = {})
  id, retrieve_params = Util.normalize_id(id)
  url = "#{resource_url}/#{CGI.escape(id)}"
  execute_resource_request(:get, url, :api, retrieve_params, opts)
end

#reverse_each(&blk) ⇒ Object

Iterates through each resource in the page represented by the current ListObject in reverse.



141
142
143
 
# File 'lib/stripe/list_object.rb', line 141

def reverse_each(&blk)
  data.reverse_each(&blk)
end