allotment 1.0.4 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 260e997e18de045d11302464320c034d157543ea
-  data.tar.gz: d07b300e2acb0bdb7d9441117db692d5e3567cc3
+  metadata.gz: a732dd5ecc0207f646b2bf89f1bbc6adc3183ac9
+  data.tar.gz: 4ee65868e53130c4e6f253cd8db45b4507783717
 SHA512:
-  metadata.gz: 8cbe37969369a29dcc2b000c42842c043c7d97996aba626b03861f96150d1a58f704ec475d125f66f6165348a6cd5e6e4adbf7809c2e87b92d266b623b60130d
-  data.tar.gz: bbb47b9c27e82b8b1696f9b20766751daf8ba545e6b6714b9283a40e1ff7bebc3f193531ca4554461b5bfe94eb5e5af0ba62eba1f91599a67a1d4fbbf2e14541
+  metadata.gz: d7c21e210e1c779334d6c9423c013a525aec0e3c143715c94789690bc66174a74293a39ad9ffd8f4665d5f92d1ac36326c07ca541f866a60086417f7e782579a
+  data.tar.gz: ba69049b2c17d5efec5bd7570cba4a96d0f16e8ed81a4f9dfa3c980d32a80b5568bfc6e543b099473cb65a46ff01a413a5eb61437a31ba7acad68d0fe9303774

data/History.md

@@ -0,0 +1,52 @@
+# History
+## Planned Versions
+### Version 1.1.0
+#### Minor: Simplify, improve, clean
+##### Changed
+ * Rescue within an event to ensure that the timing is stopped in the event of a failure
+ * Remove old hooks and add new block management
+ * Remove and old or unrequired code
+ * Improved method naming
+ * Moved history and license into root
+
+##### Added
+ * Readme completed with hooks, stopwatches and now functionality
+ * 100% coverage rspec tests
+ * Complete commenting of code
+ * Added Rakefile and Tasks
+
+##### Fixed
+ * Updated Stopwatch
+ * Updated Stopwatch Specs
+
+### Version 1.0.4
+#### Patch: Added before and after hooks
+ * Added before and after hooks
+ * Created hooks rspec tests
+ * Had to change allotment into class for hooks
+ * Split instance methods into seprate file
+ * Created release notes
+
+### Version 1.0.3
+#### Patch: Updated and added files
+ * Updated Gemfile
+ * Updated gemspec
+ * Added Version
+ * Added Licence
+
+### Version 1.0.2
+#### Patch: Results returned as Hashie::Mash
+ * results methods now return results as a Hashie::Mash
+
+### Version 1.0.1
+#### Patch: Added instance methods
+ * Added instance methods so that the module can be included into a class and allotment does not need to be called every time.
+ * Cleaned up stopwatch so that it had lap and split
+
+## Released Versions
+### Version 1.0.0
+#### Major: Inital release version.
+ * Allotment has the ablility to record blocks and procs, and to record from two separate points within the code.
+ * Stopwatch has been completed and can start, stop, split, lap and restart.
+ * There is an extention of Array for an average.
+ * There is Cucumber support, a cucumber file has been included that will record scenario and test time.

data/README.md

@@ -1,4 +1,4 @@
-# Allotment
+## "Time is what we want most, but what we use worst."
 
 [![Code Climate](https://codeclimate.com/github/benSlaughter/allotment.png)](https://codeclimate.com/github/benSlaughter/allotment)
 [![Build Status](https://travis-ci.org/benSlaughter/allotment.png?branch=master)](https://travis-ci.org/benSlaughter/allotment)
@@ -6,18 +6,31 @@
 [![Coverage Status](https://coveralls.io/repos/benSlaughter/allotment/badge.png?branch=master)](https://coveralls.io/r/benSlaughter/allotment)
 [![Gem Version](https://badge.fury.io/rb/allotment.png)](http://badge.fury.io/rb/allotment)
 
-Allotment is a performance rubygem that records and stores the performance timing of running a block of code,
-or from a from a chosen point, until a task or action is complete.
+Allotment is a performance time recording gem.
+It makes recording performance simple, while still being powerful and flexible.
 
-Each performance recording is stored with a recording name,
-each following recording is added so that multiple recordings can be queried and assesed.
+Allotment gives you the ability to record the performance of code with ease, and all the while it will store all your results as your code runs.
+Results can be acessed at any time from anywhere.
+Recordings are grouped together under their name and an average of the results can be caluculated easily.
+No threads where harmed in the making of this gem, no threads are used, and this makes Allotment lightweight and simple.
 
-Allotment also stores all the results so that they can be easily accessed at any time.
+### Cucumber
+
+Allotment also plays well with cucumber.
+
+A before and after hook records each scenarios completion time.
+
+_See [Cucumber](#using-allotment-with-cucumber)_
+
+### Limitations
+
+* Allotment cannot run two simultaneous recordings of the same name at the same time.
+* Allotment has only one set of results and cannot record to diferent results. (e.g. performance and load)
 
 ## Setup
 
 Allotment has been tested with Ruby 1.9.2 and later.
-To install, type:
+To install:
 
 ```bash
 gem install allotment
@@ -25,7 +38,8 @@ gem install allotment
 
 ## Using Allotment with Cucumber
 
-If you are using Cucumber you can record each scenario, and report the results to the console, add this line into your env.rb file:
+If you are using Cucumber you can record each scenario.
+Add this line into your env.rb file:
 
 ```ruby
 require 'allotment/cucumber'
@@ -33,70 +47,87 @@ require 'allotment/cucumber'
 
 ## Using Allotment
 
-Allotments main features are: the ability to record performance of ruby blocks; and record from point to point.
-
-Require Allotment at the start of your code:
+Require Allotment at the start of your code
 
 ```ruby
 require 'allotment'
 ```
 
 ### Recording a Block
-
-The basic way of recording a block is as follows:
+Recording a block of code could not be simpler.
 
 ```ruby
-Allotment.record_event('my_recording') { # code here }
+Allotment.record('my_recording') { # code here }
 ```
 ```ruby
-Allotment.record_event('my_recording') do
+Allotment.record('my_recording') do
   # code here
 end
 ```
 
-When an event has been completed the performance timing is returned by the method:
+When an event has been completed the performance timing is returned by the method.
 
 ```ruby
-performance = Allotment.record_event { # code here }
+performance = Allotment.record { # code here }
 ```
 ```ruby
-performance = Allotment.record_event do
+performance = Allotment.record do
   # code here
 end
 ```
 
-### Record point to point:
+### Record point to point
 
-The basic way of recording point to point is as follows:
+Sometime you may want to record performance of more than just a block.
+Allotment can do that too.
 
 ```ruby
-require 'allotment'
-
-Allotment.start_recording 'my_recording'
+Allotment.start 'my_recording'
 # code here
-Allotment.stop_recording 'my_recording'
+Allotment.stop 'my_recording'
 ```
 
-When stop recording is called the performance timing is returned by the method:
+When stop is called the performance timing is returned by the method.
 
 ```ruby
-performance = Allotment.stop_recording 'my_recording'
+performance = Allotment.stop 'my_recording'
 ```
 
-When start recording is called the timing stopwatch is returned by the method:
+When start recording is called the timing stopwatch is returned by the method.
 
 ```ruby
-stopwatch = Allotment.start_recording 'my_recording'
+stopwatch = Allotment.start 'my_recording'
 ```
 
 _More on [stopwatches](#allotment-stopwatches)_
 
-If a recording name does not exists, then a NameError shall be raised.
+**Warning!** If a recording name does not exists, then a NameError is raised.
+
+### Hooks
+
+Allotment has two inbuilt hooks, on_start, and on_stop.
+Each hook contains a single proc that is called at points within recordings.
+
+The on_start hook is called before the timer is started.
+The on_stop hook is called after the timer is stopped.
+
+A hook can be redefined at any time.
+To define a hook call the hook and pass in a proc.
+
+```ruby
+Allotment.on_start { # Extra code here }
+```
+```ruby
+Allotment.on_start do
+  # Extra code here
+end
+```
 
 ### Accessing performance results
 
-Performance recordings are stored within a hash. The reperformance results are logged to an array under the recording name.
-They can be access from Allotment at any time:
+Allotment stores all the performance recordings as and when they happen.
+If multiple recording of the same event exist they are stored in an array.
+Allotment also patches Array with an average function.
 
 ```ruby
 hash = Allotment.results
@@ -111,7 +142,64 @@ result = Allotment.results["my_recording"].first
 result = Allotment.results["my_recording"].average
 ```
 
-### Allotment Stopwatches
+## Allotment Stopwatches
+
+Stopwatches are what Allotment uses to keep track of time.
+Strangely enough they act just like a stopwatch.
+
+### Basic usage
+
+Stopwatches live inside the Allotment module.
+When created, a stopwatch is not running, however the start method returns the stopwatch, and so can be called inline.
+
+```ruby
+sw = Allotment::Stopwatch.new
+```
+```ruby
+sw = Allotment::Stopwatch.new.start
+```
+
+When stopping a stopwatch, the time that is currently on the stopwatch is returned
+
+```ruby
+time = sw.stop
+```
+
+Reset will wipe all times clean, and completely reset the time.
+Reset can be called at any time.
+
+```ruby
+sw.reset
+```
+
+### Advanced usage
+
+A stopwatch has the ability to lap, spit, and view the current time.
+Each method behaves in a slightly different way.
+ * Lap is the time elapsed from the last time a lap was called.
+ * Split is the time from the last time the stopwatch was started.
+ * Time is the total time from when the stopwatch was first started.
+
+When the stop watch is run and the methods are called.
+```
+      30 seconds
+      start                    end
+      |--------------------------|
+Lap   |---10---|---10---|---10---|
+Split |---10---|---20---|---30---|
+Time  |---10---|---20---|---30---|
+```
+
+When the stopwatch is stopped and the methods are called.
+```
+      30 seconds with 10 second stop
+      start
+Lap   |---10---|        |---10---|
+Split |---10---|        |---10---|
+Time  |---10---|        |---20---|
+```
 
-TODO
+## Notes
 
+Stopwatches use ruby Time to calculate the time between a start and a stop.
+Allotment rspec tests need to be improved upon.

data/lib/allotment.rb

@@ -1,49 +1,84 @@
+require 'json'
+require 'hashie'
+
 require 'allotment/array'
 require 'allotment/stopwatch'
 
-require 'json'
-require 'hashie'
-require 'hooks'
-
-class Allotment
-  include Hooks
-  define_hooks :before, :after
-
-	class << self
-		def record_event name = 'unnamed', &block
-			start_recording name
-			begin
-				yield
-			ensure
-				time = stop_recording name
-			end
-			return time
-		end
-
-		def start_recording name = 'unnamed'
-      run_hook :before
-			@watches ||= Hashie::Mash.new
-			@watches[name] = Stopwatch.new name
-		end
-
-		def stop_recording name
-			watch = @watches.delete(name) { |n| raise NameError, "No recording:" + n }
-			result = watch.stop
-      run_hook :after
-
-			# Dealing with the results
-			@results ||= Hashie::Mash.new
-			@results[name] ||= Array.new
-			@results[name] << result
-			return result
-		end
-
-		def results
-			@results
-		end
-
-		def results_string
-			JSON.pretty_generate @results
-		end
-	end
+# Allotment
+# "Time is what we want most, but what we use worst."
+#
+# require 'allotment'
+#
+# Allotment.record 'my_event' do
+#   # code here
+# end
+#
+# Allotment.start 'my_event'
+# # code here
+# Allotment.stop 'my_event'
+#
+module Allotment
+  @watches = Hashie::Mash.new
+  @results = Hashie::Mash.new
+
+  # Allotment module methods
+  class << self
+    # Called when a recording is started
+    # @return [Proc] the stored request proc
+    #
+    def on_start &block
+      block_given? ? @on_start = block : @on_start
+    end
+
+    # Called when a recording is stopped
+    # @return [Proc] the stored request proc
+    #
+    def on_stop &block
+      block_given? ? @on_stop = block : @on_stop
+    end
+
+    # Start recording
+    # @param name [String] the name of the event
+    #
+    def start name = 'unnamed_recording'
+      on_start.call if on_start
+      @watches[name] = Stopwatch.new(name).start
+    end
+
+    # Stop recording
+    # @param name [String] the name of the event
+    # @raise [NameError] if the recording does not exist
+    #
+    def stop name
+      result = @watches.delete(name){ |n| raise NameError, "Unknown recording:" + n }.stop
+      on_stop.call if on_stop
+
+      # Dealing with the results
+      @results[name] ||= Array.new
+      @results[name] << result
+      return result
+    end
+
+    # Record event
+    # Expects a block to be passed
+    # @param name [String] the name of the event
+    # @yield [] runs the event
+    #
+    def record name = 'unnamed_event'
+      start name
+      begin
+        yield
+      ensure
+        result = stop name
+      end
+      result
+    end
+
+    # Results at that present moment
+    # @return [Hashie::Mash] the  current results
+    #
+    def results
+      @results
+    end
+  end
 end

data/lib/allotment/array.rb

@@ -1,4 +1,8 @@
+# Ruby Array
 class Array
+  # If an array is all numbers
+  # This displayes the mean average
+  #
   def average
     inject(:+).to_f / size
   end

data/lib/allotment/cucumber.rb

@@ -1,13 +1,9 @@
 require 'allotment'
 
 Before do |scenario|
-	Allotment.start_recording scenario.title
+  Allotment.start scenario.title
 end
 
 After do |scenario|
-	Allotment.stop_recording scenario.title
-end
-
-at_exit do
-	puts Allotment.results_string
+  Allotment.stop scenario.title
 end