ke 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4fbfaca5a83423f479bc2a76e0b7903397b5fdd0
-  data.tar.gz: eff7b260a09a7ae6c2c5e4d7c8d58ac37843c1be
+  metadata.gz: a454abebf9c74fc4899e037d679ffc93ff2c3c5f
+  data.tar.gz: ddb889ef03b9d3ebfcd45aec0cc492825d0db945
 SHA512:
-  metadata.gz: 9bb0ebe5335d9f3b31c2a21aa71bfb7c4e67c65f102a76d5be0818e84fd25b904902f6a32b4e035adefb7f9060dc02b04214daad3356713ad857c1b383da3d9b
-  data.tar.gz: c5718d042ff068d8dd43520ab670d6b5478ed91aab5934c47cd44dc7696cd882c4573d1374c6c804d0450a1e6cefd50bff77707d1142ee713b5a1edda5cd768d
+  metadata.gz: e9c14271dbff7f588832f90d102a006ad808a6c6a6c9e606f50bc950e2e587aa601fc53e94aa750d8332905a92cef6dd9e7d5de5bf237f9d0813c06fdbb870b4
+  data.tar.gz: c1dfe86497dab79e7957510475b461a46a5a32719056b4d420efdabed6247c9ce08d088a5327d24b9bf0f982fbb6d0788b6f970015a6df97ae4561766fd9c939

data/README.md

@@ -4,45 +4,88 @@ Measure progress of Ruby code with the ability to provide estimates for time unt
 
 Supports tasks with a known (determinate) and unknown (indeterminate) number of iterations. For indeterminate tasks it's only possible to provide a rate. For determinate tasks it's possible to provide both a rate and an estimated remaining time.
 
+## Installation
+
+Install them gem with `gem install ke`.
+
+If you're using Bundler then add it to your Gemfile with `gem ke` and run `bundle install`.
+
 ## Usage
 
-Install them gem with `gem install ke`. If you're using Bundler then add it to your Gemfile with `gem ke` and run `bundle install`. Usage examples below:
+Assume this is your code before, performing some work each iteration:
 
-### Example 1: An indeterminate task with a multi line reporting output
+```ruby
+5.times do
+  sleep 0.1 # do work
+end
+```
+
+To report on the progress as the code runs, you need to wrap with in `Ke.job {}` block, and wrap the "work" code in the iteration part in a `job.tick {}` block:
 
 ```ruby
-require 'ke'
-
-task = Ke::IndeterminateTask.new
-reporter = Ke::MultiLineReporter.new(task, "indeterminate task")
-task.start
-reporter.print_start
-loop do
-  break if rand(200) == 50
-  sleep 0.1
-  task.tick
-  reporter.print_tick if task.tick_count % 10 == 0
+Ke.job do |job|
+  5.times do
+    job.tick do
+      sleep 1
+    end
+  end
 end
-task.complete
-reporter.print_complete
 ```
 
-### Example 2: A determinate task with a single line reporting output
+Now when we run this, we'll see a progress report printed to `STDOUT` as the iteration proceeds:
+
+```
+Starting task
+Running task, 0.0 minutes elapsed, 27027.03 ticks/second
+Running task, 0.02 minutes elapsed, 2.0 ticks/second
+Running task, 0.03 minutes elapsed, 1.5 ticks/second
+Running task, 0.05 minutes elapsed, 1.33 ticks/second
+Running task, 0.07 minutes elapsed, 1.25 ticks/second
+Completed task, 5.005121 total duration
+```
+
+### More examples
 
 ```ruby
-require 'ke'
-
-task = Ke::DeterminateTask.new(total_ticks: 50)
-reporter = Ke::SingleLineReporter.new(task, "determinate task")
-task.start
-reporter.print_start
-50.times do
-  sleep 0.1
-  task.tick
-  reporter.print_tick if task.tick_count % 10 == 0
+# Set a specific reporter.
+Ke.job(reporter: Ke::MultiLineReporter) do |job|
+  50.times do
+    job.tick do
+      sleep 0.1
+    end
+  end
+end
+
+# Set the total number of ticks, so we use DeterminateTask and get a time remaining estimates.
+Ke.job(50) do |job|
+  50.times do
+    job.tick do
+      sleep 0.1
+    end
+  end
+end
+
+# Report progress every 10 ticks.
+Ke.job(report_every: 10) do |job|
+  50.times do
+    job.tick do
+      sleep 0.1
+    end
+  end
+end
+
+# Report to a file.
+File.open("log.txt", "w") do |f|
+  f.sync = true
+
+  Ke.job(io: f) do |job|
+    50.times do
+      job.tick do
+        sleep 0.1
+      end
+    end
+  end
 end
-task.complete
-reporter.print_complete
 ```
 
 ## Custom reporters
@@ -51,7 +94,6 @@ You can add your own reporters as needed. Scope the existing reporters to learn
 
 ## TODO
 
-- Provide some syntactic sugar for the API, it's a bit rough at present
 - Provide some pleasant looking default reporters (the current 2 work, but are ugly)
 - Add some real tests
 - Add more Ruby versions to Travis CI (anything 1.9+ compat should work)

data/examples.rb

@@ -0,0 +1,50 @@
+require 'ke'
+
+# Simplest usage, no arguments.
+Ke.job do |job|
+  50.times do
+    job.tick do
+      sleep 0.1
+    end
+  end
+end
+
+# Set a specific reporter.
+Ke.job(reporter: Ke::MultiLineReporter) do |job|
+  50.times do
+    job.tick do
+      sleep 0.1
+    end
+  end
+end
+
+# Set the total number of ticks, so we use DeterminateTask and get a time remaining estimates.
+Ke.job(50) do |job|
+  50.times do
+    job.tick do
+      sleep 0.1
+    end
+  end
+end
+
+# Report progress every 10 ticks.
+Ke.job(report_every: 10) do |job|
+  50.times do
+    job.tick do
+      sleep 0.1
+    end
+  end
+end
+
+# Report to a file.
+File.open("log.txt", "w") do |f|
+  f.sync = true
+
+  Ke.job(io: f) do |job|
+    50.times do
+      job.tick do
+        sleep 0.1
+      end
+    end
+  end
+end

data/lib/ke.rb

@@ -4,3 +4,29 @@ require 'ke/indeterminate_task'
 require 'ke/determinate_task'
 require 'ke/reporters/single_line_reporter'
 require 'ke/reporters/multi_line_reporter'
+require 'ke/job'
+
+module Ke
+  def self.job(*args, &blk)
+    total_ticks = args[0] if Integer === args[0]
+    label = args[1] if String === args[1]
+    opts = args.detect { |arg| Hash === arg } || {}
+
+    task_class = total_ticks ? DeterminateTask : IndeterminateTask
+    task_opts = opts[:task_opts] || {}
+    task_opts = task_opts.merge(total_ticks: total_ticks) if total_ticks
+
+    reporter_class = opts[:reporter] || MultiLineReporter
+    reporter_label = label || "task"
+    reporter_io = opts[:io] || STDOUT
+
+    job_class = Job
+    job_opts = opts || {}
+
+    task = task_class.new(task_opts)
+    reporter = reporter_class.new(task, reporter_label, reporter_io)
+    job = job_class.new(task, reporter, job_opts)
+
+    job.run(&blk)
+  end
+end

data/lib/ke/determinate_task.rb

@@ -1,5 +1,7 @@
 module Ke
   class DeterminateTask < IndeterminateTask
+    attr_reader :total_ticks
+
     def initialize(opts = {})
       super
       @total_ticks = opts[:total_ticks]

data/lib/ke/job.rb

@@ -0,0 +1,32 @@
+module Ke
+  class Job
+    attr_reader :task, :reporter, :opts
+
+    def initialize(task, reporter, opts = {})
+      @task = task
+      @reporter = reporter
+      @opts = opts
+
+      @opts[:report_every] ||= if @task.respond_to?(:total_ticks)
+        [1, [@task.total_ticks / 10, 100].min].max
+      else
+        1
+      end
+    end
+
+    def tick
+      task.tick
+      reporter.print_tick if task.tick_count % opts[:report_every] == 0
+      yield
+    end
+
+    def run
+      task.start
+      reporter.print_start
+      return_val = yield(self)
+      task.complete
+      reporter.print_complete
+      return_val
+    end
+  end
+end

data/lib/ke/version.rb

@@ -1,3 +1,3 @@
 module Ke
-  VERSION = "0.0.1"
+  VERSION = "0.1.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ke
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Mark Dodwell
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-07-28 00:00:00.000000000 Z
+date: 2014-10-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -51,11 +51,13 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- examples.rb
 - ke.gemspec
 - lib/ke.rb
 - lib/ke/capped_sample.rb
 - lib/ke/determinate_task.rb
 - lib/ke/indeterminate_task.rb
+- lib/ke/job.rb
 - lib/ke/reporters/multi_line_reporter.rb
 - lib/ke/reporters/single_line_reporter.rb
 - lib/ke/version.rb
@@ -88,3 +90,4 @@ summary: Measure progress of Ruby code.
 test_files:
 - test/ke_test.rb
 - test/test_helper.rb
+has_rdoc: