Added more comprehensive API to list pull requests

This fixes issue #234

src/main/java/org/kohsuke/github/GHDirection.java

@@ -0,0 +1,10 @@
+package org.kohsuke.github;
+
+/**
+ * Sort direction
+ *
+ * @author Kohsuke Kawaguchi
+ */
+public enum GHDirection {
+    ASC, DESC
+}

src/main/java/org/kohsuke/github/GHIssueState.java

@@ -24,7 +24,11 @@
 
 package org.kohsuke.github;
 
+/**
+ * @see GHPullRequestQueryBuilder#state(GHIssueState)
+ */
 public enum GHIssueState {
     OPEN,
-    CLOSED
+    CLOSED,
+    ALL
 }

src/main/java/org/kohsuke/github/GHPullRequestQueryBuilder.java

@@ -0,0 +1,58 @@
+package org.kohsuke.github;
+
+/**
+ * Lists up pull requests with some filtering and sorting.
+ *
+ * @author Kohsuke Kawaguchi
+ * @see GHRepository#queryPullRequests()
+ */
+public class GHPullRequestQueryBuilder extends GHQueryBuilder<GHPullRequest> {
+    private final GHRepository repo;
+
+    /*package*/ GHPullRequestQueryBuilder(GHRepository repo) {
+        super(repo.root);
+        this.repo = repo;
+    }
+
+    public GHPullRequestQueryBuilder state(GHIssueState state) {
+        req.with("state",state);
+        return this;
+    }
+
+    public GHPullRequestQueryBuilder head(String head) {
+        req.with("head",head);
+        return this;
+    }
+
+    public GHPullRequestQueryBuilder base(String base) {
+        req.with("base",base);
+        return this;
+    }
+
+    public GHPullRequestQueryBuilder sort(Sort sort) {
+        req.with("sort",sort);
+        return this;
+    }
+
+    public enum Sort { CREATED, UPDATED, POPULARITY, LONG_RUNNING }
+
+    public GHPullRequestQueryBuilder direction(GHDirection d) {
+        req.with("direction",d);
+        return this;
+    }
+
+    @Override
+    public PagedIterable<GHPullRequest> list() {
+        return new PagedIterable<GHPullRequest>() {
+            public PagedIterator<GHPullRequest> _iterator(int pageSize) {
+                return new PagedIterator<GHPullRequest>(req.asIterator(repo.getApiTailUrl("pulls"), GHPullRequest[].class, pageSize)) {
+                    @Override
+                    protected void wrapUp(GHPullRequest[] page) {
+                        for (GHPullRequest pr : page)
+                            pr.wrapUp(repo);
+                    }
+                };
+            }
+        };
+    }
+}

src/main/java/org/kohsuke/github/GHQueryBuilder.java

@@ -0,0 +1,21 @@
+package org.kohsuke.github;
+
+/**
+ * Used to specify filters, sort order, etc for listing items in a collection.
+ *
+ * @author Kohsuke Kawaguchi
+ */
+public abstract class GHQueryBuilder<T> {
+    protected final GitHub root;
+    protected final Requester req;
+
+    /*package*/ GHQueryBuilder(GitHub root) {
+        this.root = root;
+        this.req = root.retrieve();
+    }
+
+    /**
+     * Start listing items by using the settings built up on this object.
+     */
+    public abstract PagedIterable<T> list();
+}

src/main/java/org/kohsuke/github/GHRepository.java

@@ -617,24 +617,24 @@ public class GHRepository extends GHObject {
      * @see #listPullRequests(GHIssueState)
      */
     public List<GHPullRequest> getPullRequests(GHIssueState state) throws IOException {
-        return listPullRequests(state).asList();
+        return queryPullRequests().state(state).list().asList();
     }
 
     /**
      * Retrieves all the pull requests of a particular state.
+     *
+     * @deprecated
+     *      Use {@link #queryPullRequests()}
      */
-    public PagedIterable<GHPullRequest> listPullRequests(final GHIssueState state) {
-        return new PagedIterable<GHPullRequest>() {
-            public PagedIterator<GHPullRequest> _iterator(int pageSize) {
-                return new PagedIterator<GHPullRequest>(root.retrieve().asIterator(getApiTailUrl("pulls?state="+state.name().toLowerCase(Locale.ENGLISH)), GHPullRequest[].class, pageSize)) {
-                    @Override
-                    protected void wrapUp(GHPullRequest[] page) {
-                        for (GHPullRequest pr : page)
-                            pr.wrapUp(GHRepository.this);
-                    }
-                };
-            }
-        };
+    public PagedIterable<GHPullRequest> listPullRequests(GHIssueState state) {
+        return queryPullRequests().state(state).list();
+    }
+
+    /**
+     * Retrieves pull requests.
+     */
+    public GHPullRequestQueryBuilder queryPullRequests() {
+        return new GHPullRequestQueryBuilder(this);
     }
 
     /**

src/main/java/org/kohsuke/github/GHSearchBuilder.java

@@ -10,9 +10,7 @@ import java.util.List;
  *
  * @author Kohsuke Kawaguchi
  */
-public abstract class GHSearchBuilder<T> {
-    protected final GitHub root;
-    protected final Requester req;
+public abstract class GHSearchBuilder<T> extends GHQueryBuilder<T> {
     protected final List<String> terms = new ArrayList<String>();
 
     /**
@@ -21,15 +19,14 @@ public abstract class GHSearchBuilder<T> {
     private final Class<? extends SearchResult<T>> receiverType;
 
     /*package*/ GHSearchBuilder(GitHub root, Class<? extends SearchResult<T>> receiverType) {
-        this.root = root;
-        this.req = root.retrieve();
+        super(root);
         this.receiverType = receiverType;
     }
 
     /**
      * Search terms.
      */
-    public GHSearchBuilder q(String term) {
+    public GHQueryBuilder<T> q(String term) {
         terms.add(term);
         return this;
     }
@@ -37,6 +34,7 @@ public abstract class GHSearchBuilder<T> {
     /**
      * Performs the search.
      */
+    @Override
     public PagedSearchIterable<T> list() {
         return new PagedSearchIterable<T>(root) {
             public PagedIterator<T> _iterator(int pageSize) {

src/main/java/org/kohsuke/github/Requester.java

@@ -45,6 +45,7 @@ import java.util.HashMap;
 import java.util.Iterator;
 import java.util.LinkedHashMap;
 import java.util.List;
+import java.util.Locale;
 import java.util.Map;
 import java.util.NoSuchElementException;
 import java.util.regex.Matcher;
@@ -130,6 +131,14 @@ class Requester {
         return _with(key, value);
     }
 
+    public Requester with(String key, Enum e) {
+        if (e==null)    return _with(key, null);
+
+        // by convention Java constant names are upper cases, but github uses
+        // lower-case constants. GitHub also uses '-', which in Java we always
+        // replace by '_'
+        return with(key, e.toString().toLowerCase(Locale.ENGLISH).replace('_','-'));
+    }
 
     public Requester with(String key, String value) {
         return _with(key, value);