jiraby 0.0.1 → 0.0.2

data/README.md

@@ -1,11 +1,29 @@
 Jiraby
 ======
+[![Build Status](https://secure.travis-ci.org/a-e/jiraby.png?branch=dev)](http://travis-ci.org/a-e/jiraby)
 
 Jiraby is a Ruby wrapper for the [JIRA](http://www.atlassian.com/JIRA)
 [REST API](https://docs.atlassian.com/jira/REST/latest/), supporting Jira
-versions 6.2 and up.
+versions 6.x onward.
 
-[Full documentation is on rdoc.info](http://rubydoc.info/github/a-e/jiraby/master/frames).
+- [Source](https://github.com/a-e/jiraby)
+- [Documentation](http://rubydoc.info/github/a-e/jiraby/master/frames)
+- [Gem](http://rubygems.org/gems/jiraby)
+- [Status](https://travis-ci.org/a-e/jiraby)
+
+
+Install
+-------
+
+Just do:
+
+    $ gem install jiraby
+
+Or add:
+
+    gem 'cherby'
+
+to your project's Gemfile or gemspec.
 
 
 Connect to Jira
@@ -49,8 +67,8 @@ All REST methods return a `Jiraby::Entity` (a hash-like object built directly fr
 the JSON response), or an `Array` of them (for those REST methods that return arrays).
 
 
-Wrappers
---------
+Issue wrapper
+-------------
 
 You can look up a Jira issue using the `#issue` method:
 
@@ -104,6 +122,78 @@ Then save the updates back to Jira:
     # => true
 
 
+Enumerator wrapper
+------------------
+
+Several of Jira's REST API methods return their data in batches, based on the
+value of `startAt` and `maxResults` parameters, effectively breaking larger
+result sets into pages. Since it's likely you'll want to eventually fetch all
+pages of results, the `Jiraby::Jira` class can wrap such methods in an
+`Enumerator`, via the `#enumerator` method.
+
+For example, using the issue `search` method to look up all issues in project
+"FOO", then using `.each` to iterate over them:
+
+    query = 'project=FOO order by key'
+    jira.enumerator(
+      :post, 'search', {:jql => query}, 'issues'
+    ).each do |issue|
+      puts "#{issue.key}: #{issue.fields.summary}"
+    end
+
+The output might be:
+
+    FOO-1: First issue in Foo project
+    FOO-2: Another issue
+    (...)
+    FOO-149: Penultimate issue
+    FOO-150: Last issue
+
+Because the `search` method is so useful, it includes a wrapper of its own; all
+you need to provide is a JQL query:
+
+    issues = jira.search('project=FOO order by key')
+    # => #<Enumerator: ...>
+
+This `Enumerator` spits out `Issue` instances. Simply iterate over the issues
+using `.each`, `.map`, `.select` or their ilk, and each page will be fetched
+as it's needed, transparently:
+
+    issues.each do |issue|
+      puts "#{issue.key}: #{issue['summary']}"
+    end
+
+    issue_keys = issues.map { |issue| issue.key }
+
+    unassigned_subtasks = issues.select do |issue|
+      !issue.is_assigned? && issue.is_subtask?
+    end
+
+Using the `Enumerator` prevents having to load the entire list of issues into
+memory at once, but can mean doing a lot of requests to Jira. If you plan to
+iterate through the issues more than once and would like to avoid repeated
+requests to the REST API, you could convert the `Enumerator` to an `Array`:
+
+    issues_array = issues.to_a
+
+Below is a complete list of Jira REST API methods that accept `startAt`
+and `maxResults`.
+
+Returning `Jiraby::Entity`:
+
+    GET /dashboard => { 'dashboards' => [...], 'total' => N } (dashboards)
+    GET /search => { 'issues' => [...], 'total' => N } (issues)
+    POST /search => { 'issues' => [...], 'total' => N } (issues)
+
+Returning `Array` of `Jiraby::Entity`:
+
+    GET /user/assignable/multiProjectSearch => [...] (users)
+    GET /user/assignable/search => [...] (users)
+    GET /user/permission/search => [...] (users)
+    GET /user/search => [...] (users)
+    GET /user/viewissue/search => [...] (users)
+
+
 Copyright
 ---------
 

data/jiraby.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = "jiraby"
-  s.version = "0.0.1"
+  s.version = "0.0.2"
   s.summary = "Jira-Ruby bridge"
   s.description = <<-EOS
     Jiraby is a Ruby wrapper for the JIRA REST API,

data/lib/jiraby/jira.rb

@@ -136,40 +136,19 @@ module Jiraby
 
     # Return an Enumerator yielding items returned by a REST method that
     # accepts `startAt` and `maxResults` parameters. This allows you to
-    # iterate through large data sets
-    #
-    # For example, using the issue `search` method to look up all issues
-    # in project "FOO", then using `each` to iterate over them:
-    #
-    #     query = 'project=FOO order by key'
-    #     jira.enumerator(
-    #       :post, 'search', {:jql => query}, 'issues'
-    #     ).each do |issue|
-    #       puts "#{issue.key}: #{issue.fields.summary}"
-    #     end
-    #
-    # The output might be:
-    #
-    #   FOO-1: First issue in Foo project
-    #   FOO-2: Another issue
-    #   (...)
-    #   FOO-149: Penultimate issue
-    #   FOO-150: Last issue
-    #
-    # Below is a complete list of Jira REST API methods that accept `startAt`
-    # and `maxResults`.
-    #
-    # Returning Entity:
-    #   GET /dashboard => { 'dashboards' => [...], 'total' => N } (dashboards)
-    #   GET /search => { 'issues' => [...], 'total' => N } (issues)
-    #   POST /search => { 'issues' => [...], 'total' => N } (issues)
-    #
-    # Returning Array of Entity:
-    #   GET /user/assignable/multiProjectSearch => [...] (users)
-    #   GET /user/assignable/search => [...] (users)
-    #   GET /user/permission/search => [...] (users)
-    #   GET /user/search => [...] (users)
-    #   GET /user/viewissue/search => [...] (users)
+    # iterate through large data sets.
+    #
+    # @param [String,Symbol] method
+    #   HTTP request method to use (`:get` or `:post`)
+    # @param [String] path
+    #   Relative path to the REST method (such as `user/search`)
+    # @param [Hash] params
+    #   GET or POST parameters to submit (depending on which method
+    #   and path you're requesting)
+    # @param [String] list_key
+    #   For REST methods returning an array embedded in an object
+    #   (like `search` and `dashboard`), the attribute name where
+    #   the array of things is stored.
     #
     def enumerator(method, path, params={}, list_key=nil)
       max_results = @@max_results

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jiraby
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-03-17 00:00:00.000000000 Z
+date: 2014-03-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client