Class: Stripe::ListObject
- Inherits:
-
StripeObject
- Object
- StripeObject
- Stripe::ListObject
- 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
-
#filters ⇒ Object
This accessor allows a ‘ListObject` to inherit various filters that were given to a predecessor.
Class Method Summary collapse
-
.empty_list(opts = {}) ⇒ Object
An empty list object.
Instance Method Summary collapse
- #[](key) ⇒ Object
-
#auto_paging_each(&blk) ⇒ Object
Iterates through each resource in all pages, making additional fetches to the API as necessary.
-
#each(&blk) ⇒ Object
Iterates through each resource in the page represented by the current ‘ListObject`.
-
#empty? ⇒ Boolean
Returns true if the page object contains no elements.
-
#initialize(*args) ⇒ ListObject
constructor
A new instance of ListObject.
-
#next_page(params = {}, opts = {}) ⇒ Object
Fetches the next page in the resource list (if there is one).
-
#previous_page(params = {}, opts = {}) ⇒ Object
Fetches the previous page in the resource list (if there is one).
- #resource_url ⇒ Object
- #retrieve(id, opts = {}) ⇒ Object
-
#reverse_each(&blk) ⇒ Object
Iterates through each resource in the page represented by the current ‘ListObject` in reverse.
Methods included from APIOperations::Create
Methods included from APIOperations::Request
Methods included from APIOperations::List
Methods inherited from StripeObject
#==, #[]=, additive_object_param, additive_object_param?, #as_json, construct_from, #deleted?, #dirty!, #eql?, #hash, #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.
24 25 26 27 |
# File 'lib/stripe/list_object.rb', line 24 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.
15 16 17 |
# File 'lib/stripe/list_object.rb', line 15 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.
20 21 22 |
# File 'lib/stripe/list_object.rb', line 20 def self.empty_list(opts = {}) ListObject.construct_from({ data: [] }, opts) end |
Instance Method Details
#[](key) ⇒ Object
29 30 31 32 33 34 35 36 37 38 39 40 |
# File 'lib/stripe/list_object.rb', line 29 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
.
67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 |
# File 'lib/stripe/list_object.rb', line 67 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? 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
.
47 48 49 |
# File 'lib/stripe/list_object.rb', line 47 def each(&blk) data.each(&blk) end |
#empty? ⇒ Boolean
Returns true if the page object contains no elements.
89 90 91 |
# File 'lib/stripe/list_object.rb', line 89 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.
104 105 106 107 108 109 110 111 112 |
# File 'lib/stripe/list_object.rb', line 104 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.
118 119 120 121 122 123 124 125 126 |
# File 'lib/stripe/list_object.rb', line 118 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
128 129 130 131 |
# File 'lib/stripe/list_object.rb', line 128 def resource_url url || raise(ArgumentError, "List object does not contain a 'url' field.") end |
#retrieve(id, opts = {}) ⇒ Object
93 94 95 96 97 98 |
# File 'lib/stripe/list_object.rb', line 93 def retrieve(id, opts = {}) id, retrieve_params = Util.normalize_id(id) url = "#{resource_url}/#{CGI.escape(id)}" resp, opts = execute_resource_request(:get, url, retrieve_params, opts) Util.convert_to_stripe_object(resp.data, opts) end |
#reverse_each(&blk) ⇒ Object
Iterates through each resource in the page represented by the current ‘ListObject` in reverse.
135 136 137 |
# File 'lib/stripe/list_object.rb', line 135 def reverse_each(&blk) data.reverse_each(&blk) end |