First cut at pagination.
diff --git a/collections.go b/collections.go
new file mode 100644
index 0000000..6e48228
--- /dev/null
+++ b/collections.go
@@ -0,0 +1,150 @@
+package gophercloud
+
+import (
+ "errors"
+
+ "github.com/racker/perigee"
+)
+
+var (
+ // ErrPageNotAvailable is returned from a Pager when a next or previous page is requested, but does not exist.
+ ErrPageNotAvailable = errors.New("The requested Collection page does not exist.")
+)
+
+// Collection describes the minimum functionality that any collection resource must implement to be able to use
+// the global paging and iteration functions.
+// Every resource that returns a list of multiple results must implement this functionality, whether or not it is paged.
+// In addition to the methods provided here, each collection should also provide an AsItem(Page) method that
+// casts the Page to its more specific type and returns the Page's contents as a slice.
+type Collection interface {
+
+ // Pager returns one of the concrete Pager implementations from this package, or a custom one.
+ // The style of Pager returned determines how the collection is paged.
+ Pager() Pager
+}
+
+// EachPage iterates through a Collection one page at a time.
+// The handler function will be invoked with a Collection containing each page.
+// If the handler returns true, iteration will continue. If it returns false, no more pages will be fetched.
+func EachPage(first Collection, handler func(Collection) bool) error {
+ p := first.Pager()
+ var err error
+ current := first
+
+ for {
+ if !handler(current) {
+ return nil
+ }
+
+ if !p.HasNextPage() {
+ return nil
+ }
+
+ current, err = p.NextPage()
+ if err != nil {
+ return err
+ }
+ }
+}
+
+// AllPages consolidates all pages reachable from a provided starting point into a single mega-Page.
+// Use this only when you know that the full set will always fit within memory.
+func AllPages(first Collection) (Collection, error) {
+ return first, nil
+}
+
+// Pager describes a specific paging idiom for a Page resource.
+// Generally, to use a Pager, the Page must also implement a more specialized interface than Page.
+// Clients should not generally interact with Pagers directly.
+// Instead, use the more convenient collection traversal methods: All and EachPage.
+type Pager interface {
+
+ // HasNextPage returns true if a call to NextPage will return an additional Page of results.
+ HasNextPage() bool
+
+ // NextPage returns the next Page in the sequence.
+ // Panics if no page is available, so always check HasNextPage first.
+ NextPage() (Collection, error)
+}
+
+// SinglePager is used by collections that are not actually paged.
+// It has no additional interface requirements for its host Page.
+type SinglePager struct{}
+
+// HasNextPage always reports false.
+func (p SinglePager) HasNextPage() bool {
+ return false
+}
+
+// NextPage always returns an ErrPageNotAvailable.
+func (p SinglePager) NextPage() (Collection, error) {
+ return nil, ErrPageNotAvailable
+}
+
+// PaginationLinks stores the `next` and `previous` links that are provided by some (but not all) paginated resources.
+type PaginationLinks struct {
+
+ // Next is the full URL to the next page of results, or nil if this is the last page.
+ Next *string `json:"next,omitempty"`
+
+ // Previous is the full URL to the previous page of results, or nil if this is the first page.
+ Previous *string `json:"previous,omitempty"`
+}
+
+// LinkCollection must be satisfied by a Page that uses a LinkPager.
+type LinkCollection interface {
+
+ // Pager is specified here so every LinkCollection will also be a valid Page.
+ Pager() Pager
+
+ // Service returns the client used to make further requests.
+ Service() *ServiceClient
+
+ // Links returns the pagination links from a single page.
+ Links() PaginationLinks
+
+ // Interpret an arbitrary JSON result as a new LinkCollection.
+ Interpret(interface{}) (LinkCollection, error)
+}
+
+// LinkPager implements paging for collections that provide a link structure in their response JSON.
+// It follows explicit `next` links and stops when the `next` link is "null".
+type LinkPager struct {
+ current LinkCollection
+}
+
+// NewLinkPager creates and initializes a pager for a LinkCollection.
+func NewLinkPager(first LinkCollection) *LinkPager {
+ return &LinkPager{current: first}
+}
+
+// HasNextPage checks the `next` link in the pagination data.
+func (p *LinkPager) HasNextPage() bool {
+ return p.current.Links().Next != nil
+}
+
+// NextPage follows the `next` link to construct the next page of data.
+func (p *LinkPager) NextPage() (Collection, error) {
+ url := p.current.Links().Next
+ if url == nil {
+ return nil, ErrPageNotAvailable
+ }
+
+ var response interface{}
+ _, err := perigee.Request("GET", *url, perigee.Options{
+ MoreHeaders: p.current.Service().Provider.AuthenticatedHeaders(),
+ Results: &response,
+ OkCodes: []int{200},
+ })
+ if err != nil {
+ return nil, err
+ }
+
+ interpreted, err := p.current.Interpret(response)
+ if err != nil {
+ return nil, err
+ }
+
+ p.current = interpreted
+ return interpreted, nil
+}
diff --git a/collections_test.go b/collections_test.go
new file mode 100644
index 0000000..4c8674d
--- /dev/null
+++ b/collections_test.go
@@ -0,0 +1,198 @@
+package gophercloud
+
+import (
+ "errors"
+ "fmt"
+ "net/http"
+ "reflect"
+ "testing"
+
+ "github.com/rackspace/gophercloud/testhelper"
+)
+
+// SinglePage sample and test cases.
+
+type SinglePageCollection struct {
+ results []int
+}
+
+func (c SinglePageCollection) Pager() Pager {
+ return SinglePager{}
+}
+
+func AsSingleInts(c Collection) []int {
+ return c.(SinglePageCollection).results
+}
+
+var single = SinglePageCollection{
+ results: []int{1, 2, 3},
+}
+
+func TestEnumerateSinglePaged(t *testing.T) {
+ callCount := 0
+ EachPage(single, func(page Collection) bool {
+ callCount++
+
+ expected := []int{1, 2, 3}
+ actual := AsSingleInts(page)
+ if !reflect.DeepEqual(expected, actual) {
+ t.Errorf("Expected %v, but was %v", expected, actual)
+ }
+ return true
+ })
+
+ if callCount != 1 {
+ t.Errorf("Callback was invoked %d times", callCount)
+ }
+}
+
+func TestAllSinglePaged(t *testing.T) {
+ r, err := AllPages(single)
+ if err != nil {
+ t.Fatalf("Unexpected error when iterating pages: %v", err)
+ }
+
+ expected := []int{1, 2, 3}
+ actual := AsSingleInts(r)
+ if !reflect.DeepEqual(expected, actual) {
+ t.Errorf("Expected %v, but was %v", expected, actual)
+ }
+}
+
+// LinkedPager sample and test cases.
+
+type LinkedCollection struct {
+ PaginationLinks
+
+ service *ServiceClient
+ results []int
+}
+
+func (c LinkedCollection) Links() PaginationLinks {
+ return c.PaginationLinks
+}
+
+func (c LinkedCollection) Service() *ServiceClient {
+ return c.service
+}
+
+func (c LinkedCollection) Interpret(response interface{}) (LinkCollection, error) {
+ fmt.Printf("Interpreting result: %#v\n", response)
+ casted, ok := response.([]interface{})
+ if ok {
+ asInts := make([]int, len(casted))
+ for index, item := range casted {
+ f := item.(float64)
+ asInts[index] = int(f)
+ }
+
+ var nextURL *string
+ switch asInts[0] {
+ case 4:
+ u := testhelper.Server.URL + "/foo?page=3&perPage=3"
+ nextURL = &u
+ case 7:
+ // Leave nextURL as nil.
+ default:
+ return nil, fmt.Errorf("Unexpected resultset: %#v", asInts)
+ }
+
+ result := LinkedCollection{
+ PaginationLinks: PaginationLinks{Next: nextURL},
+ service: c.service,
+ results: asInts,
+ }
+ if nextURL != nil {
+ fmt.Printf("Returning result: %s\n", *nextURL)
+ } else {
+ fmt.Printf("No next link")
+ }
+ return result, nil
+ }
+ return nil, errors.New("Wat")
+}
+
+func (c LinkedCollection) Pager() Pager {
+ return NewLinkPager(c)
+}
+
+func AsLinkedInts(results Collection) []int {
+ return results.(LinkedCollection).results
+}
+
+func createLinked() LinkedCollection {
+ nextURL := testhelper.Server.URL + "/foo?page=2&perPage=3"
+ return LinkedCollection{
+ PaginationLinks: PaginationLinks{Next: &nextURL},
+ service: &ServiceClient{
+ Provider: &ProviderClient{TokenID: "1234"},
+ Endpoint: testhelper.Endpoint(),
+ },
+ results: []int{1, 2, 3},
+ }
+}
+
+func setupLinkedResponses(t *testing.T) {
+ testhelper.Mux.HandleFunc("/foo", func(w http.ResponseWriter, r *http.Request) {
+ testhelper.TestMethod(t, r, "GET")
+ testhelper.TestHeader(t, r, "X-Auth-Token", "1234")
+ w.Header().Add("Content-Type", "application/json")
+
+ r.ParseForm()
+
+ pages := r.Form["page"]
+ if len(pages) != 1 {
+ t.Errorf("Endpoint called with unexpected page: %#v", r.Form)
+ }
+
+ switch pages[0] {
+ case "2":
+ fmt.Fprintf(w, `[4, 5, 6]`)
+ case "3":
+ fmt.Fprintf(w, `[7, 8, 9]`)
+ default:
+ t.Errorf("Endpoint called with unexpected page: %s", pages[0])
+ }
+ })
+}
+
+func TestEnumerateLinked(t *testing.T) {
+ testhelper.SetupHTTP()
+ defer testhelper.TeardownHTTP()
+
+ setupLinkedResponses(t)
+ lc := createLinked()
+
+ callCount := 0
+ err := EachPage(lc, func(page Collection) bool {
+ actual := AsLinkedInts(page)
+ t.Logf("Handler invoked with %v", actual)
+
+ var expected []int
+ switch callCount {
+ case 0:
+ expected = []int{1, 2, 3}
+ case 1:
+ expected = []int{4, 5, 6}
+ case 2:
+ expected = []int{7, 8, 9}
+ default:
+ t.Fatalf("Unexpected call count: %d", callCount)
+ return false
+ }
+
+ if !reflect.DeepEqual(expected, actual) {
+ t.Errorf("Call %d: Expected %#v, but was %#v", callCount, expected, actual)
+ }
+
+ callCount++
+ return true
+ })
+ if err != nil {
+ t.Errorf("Unexpected error for page iteration: %v", err)
+ }
+
+ if callCount != 3 {
+ t.Errorf("Expected 3 calls, but was %d", callCount)
+ }
+}
diff --git a/pagination.go b/pagination.go
deleted file mode 100644
index f100651..0000000
--- a/pagination.go
+++ /dev/null
@@ -1,11 +0,0 @@
-package gophercloud
-
-// Pagination stores information that's necessary to enumerate through pages of results.
-type Pagination struct {
-
- // Next is the full URL to the next page of results, or nil if this is the last page.
- Next *string `json:"next,omitempty"`
-
- // Previous is the full URL to the previous page of results, or nil if this is the first page.s
- Previous *string `json:"previous,omitempty"`
-}