bonito 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41888e2e81cc5c6f383b6fe3526984cd0d85bb874853509af626b880c824e669
-  data.tar.gz: ae72f04e929420aaa6698f0b89fb3ffb4dabc3827ab248d84f3b400ec5c72a95
+  metadata.gz: 599d257d6b113cc345ae71a20bb2a00be5bfba1639f647b597a0c98d6cf37df5
+  data.tar.gz: ee359e2a42753140a5b23a864764fe798110f3761a492335d64d2d24b4b8fad5
 SHA512:
-  metadata.gz: 769052dccffcd20cd2fd281217e872c5455c6bc2b26a9dc3b10945a8992767b06dcd91e736dfe723eba49c6d2e007e8fc550197da1e2b8ecb2dc4343338418a4
-  data.tar.gz: 606bfa014aa8ef709f8069a173529f91ef06328dd182242259983c8eaa74ab938be4fc87ffa7e59fc4f461e62e2f9dd3f2dae2167f2d1abd25c033f26c57a886
+  metadata.gz: 9b560ad80a6bc02d69e14a171be711ba6d5599c774b9e85f920d8b9ecc760128f9732227e22ba2c17d01eb69c04e5667a92934a37847777a3605e2675c74e512
+  data.tar.gz: 43ca1a80a0d874de18060eff0ef45dd06c009ded65f6305fa61560ac6715288927f4c8e459ef1717ee561ac3503368fa55a97f7d883da1c8af59872fc15cb50c

data/.travis.yml

@@ -1,6 +1,6 @@
 env:
   global:
-  - CC_TEST_REPORTER_ID=7288d4a38203cc17d30f9fb4e9d46399d6e7b6f017572bc833d8da3f38fea48b
+  - CC_TEST_REPORTER_ID=cd7c4f8ecc524c18ae8a60a1cebf50f64816123ec1040385c367ddff5cdefa0a
 language: ruby
 rvm:
 - 2.5.1

data/README.md

@@ -1,118 +1,90 @@
 # Bonito
 
-![build](https://travis-ci.org/TomFinill/bonito.svg?branch=master) [![Maintainability](https://api.codeclimate.com/v1/badges/42198ebf17bf127e0da6/maintainability)](https://codeclimate.com/github/TomFinill/bonito/maintainability) [![Test Coverage](https://api.codeclimate.com/v1/badges/42198ebf17bf127e0da6/test_coverage)](https://codeclimate.com/github/TomFinill/bonito/test_coverage)
+_Data, in a can_
 
-## TL;DR
-
-**Bonito** is a ruby DSL for generating canned data.  It can simulate, by 
- _freezing time_, sequences of events happening in series and parallel in 
- order to approximate any kind of live data.
+![build](https://travis-ci.org/TomFinill/bonito.svg?branch=master) [![Maintainability](https://api.codeclimate.com/v1/badges/15ad4524ca0d4c0cdff4/maintainability)](https://codeclimate.com/github/tmfnll/bonito/maintainability) [![Test Coverage](https://api.codeclimate.com/v1/badges/15ad4524ca0d4c0cdff4/test_coverage)](https://codeclimate.com/github/tmfnll/bonito/test_coverage)
 
-`Bonito` uses [Timecop](https://github.com/travisjeffery/timecop) in order to
- perform this _freezing_. 
+## TL;DR
 
-![bonito](https://live.staticflickr.com/3363/3278938654_a9991fa129_z.jpg)
+_`Bonito` is a ruby DSL for generating canned data where timing is important._  
 
-### An example is worth a thousand theorems
+`Bonito` uses [Timecop](https://github.com/travisjeffery/timecop) to simulate
+the flow of time as it generates data.
 
-#### Timeline Definition
+## Introduction
 
-Suppose you work for a small media startup and you wish to create a set of data
-that can be loaded into a demo environment in order to then be used by the sales 
-department when presenting to potential customers.
+At the core of `Bonito` is the concept of a _timeline_.  A timeline is a sort
+of schema that defines in what time period each of a sequence of actions can
+occur.
 
-This data could consist of models representing `Author`s and the `Article`s they 
-write, as well as readers (or `User`s) and `Comment`s they leave on the 
-aforementioned `Article`s.
+An action in `Bonito` is called a `Moment` and is considered to have a duration
+of `0` itself.
 
-Obviously, each `Article` should be created by an `Author` and the simulated
- creation time of each `Comment` should be _after_ that of its associated 
- `Article`.  In fact, we can consider the data to consist of a collection of 
- _timelines_ where each timeline includes the creation of an `Article` by an 
- `Author` with this being followed afterwards by a series of `Comment`s on the
- `Article` being created by `User`s.
- 
-`Bonito` offers a `Window` object to model such timelines. 
+#### `Bonito` can generate data in series:
 
-Each `Window` has a duration in which events occur.  These events are referred 
-to in `Bonito` as `Moment`s.  
+Suppose we wish to simulate an online content creator's data, where _author_s
+write _articles_ and _users_ _comment_ on these articles.
 
-For example, a `Window` representing the timeline described above could be 
-created as follows:
+We could use `Bonito` to define a `serial timeline`:
 
 ```ruby
-example_window = Bonito.over 1.week do
-  please do
-    author = authors.sample
+# First we create data structures to store out data and keep track of them in
+# a `Scope` object: 
+scope = Bonito::Scope.new.tap do |scope|
+  scope.authors = []
+  scope.articles = []
+  scope.users = []
+  scope.comments = []
+  scope.users_and_authors = []
+end
+
+# Next we define out serial timeline:
+serial = Bonito.over 1.week do
+  please do |scope|  # The `please` method denotes the definition of an action
+    author = scope.authors.sample
     title = Faker::Company.bs
-    self.article = Article.new(title, author)
-    articles << article
+    scope.article = Article.new(title, author)
+    scope.articles << article
   end
 
   repeat times: rand(10), over: 5.days do
-    please do
-      user = users.sample
+    please do |scope|
+      user = scope.users.sample
       content = Faker::Lorem.sentence
-      comments << Comment.new(content, article, user)
+      scope.comments << Comment.new(content, scope.article, user)
     end
   end
 end
 ```
 
-Here, via the `over` method on the `Bonito` module, a `Window` is defined.  Within
-this window a series of `Moment`s are defined. Firstly, the `Window#please` method 
-is invoked to define the event.  In this case the event consists of creating an
-`Article`.
-
-After this, we wish to define `Moment`s in which many `Comment`s are created for
-the `Article`.
+This _timeline_ specifies the creation of an instance of `Article` _followed by_
+the creation of _up to_ 10 `Comment` belonging to that `Article`. 
+The `created_at` time on the `Article` will be before that of each of the
+`Comment`s. The total elapsed time between the creation of the `Article` and
+the creation of the final `Comment` will not be more than `1.week`.
 
-To do this we use the `Window#repeat` method. This method accepts a block along 
-with a `times` parameter and an `over` parameter and inserts a new, child `Window`
-into the current, parent window.  The contents of the child window will be
-that defined by the block repeated `times` times.
 
-This means that the child `Window` defines up to 9 (`rand(10)`) `Moment`s
-where each such `Moment` creates a `Comment` belonging to the previously 
-created `Article`.
+#### `Bonito` can generate data in parallel:
 
-_Now_, suppose we intend to simulate the creation of multiple `Article`s and 
-their associated `Comment`s.  One way to achieve this would be to repeat the 
-previously defined `Window` via the `repeat` command:
+Consider the timeline `serial` we defined above.  We might realistically want
+to generate data that represents many authors working _simultaneously_ on
+articles with users then commenting on these once they have been published.
 
-```ruby
-serial_window = Bonito.over 10.weeks do
-  repeat times: 5 do
-    use example_window
-  end
-end
-``` 
-
-However this approach has a serious drawback: all events will occur _in series_.
-The second `Article` will not be created until all the `Comment`s on the first 
-`Article` have been created and similarly the third `Article` will be preceded by
-all `Comment`s on the second.
-
-Ideally what we want is for `Articles` and `Comment`s to be _interleaved_.
-
-We can achieve this using the `Window#simultaneously`
-method to create a `Container` object, used to define parallel timelines. We 
-then fill that container with the same, `Window` five times, using the 
-`Container#use` method.
+This can be done as follows:
 
 ```ruby
-parallel_window = Bonito.over 2.weeks do
+parallel = Bonito.over 2.weeks do
   simultaneously do
     repeat times: 5 do
-      use example_window 
+      use serial
     end
   end
 end
 ```
 
-The above will create 5 `Article`s, each having up to 9 `Comment`s where the 
-moment at which `Article` is created is independent of any other `Article` or 
-`Comment`.  The times at which the `Comment`s are created, meanwhile, are 
+The above will create 5 `Article`s, each having up to 9 `Comment`s where the
+moment at which `Article` is created is independent of any other `Article` or
+`Comment`.  The times at which the `Comment`s are created, meanwhile, are
 dependent _only_ on the `Article` to which they belong.
 
 #### Execution
@@ -120,40 +92,168 @@ dependent _only_ on the `Article` to which they belong.
 Now we have defined the _shape_ of the data we wish to create, it remains 
 to actually create it.  
 
-This is achieved via a `Runner` object that takes a `Window` and uses it to 
-evaluate `Moment`s.
+This is achieved via a `Runner` object that takes a timeline and uses it to 
+evaluate the individual actions. It distributes these actions randomly yet
+within the confines of the schedule defined by the timeline.
 
 ```ruby
-  Bonito.run parallel_window, starting: 8.weeks_ago
+  Bonito.run parallel_window, scope: scope, starting: 8.weeks_ago
 ```
 
 This will take the `Window` object `parallel_window` and distribute the `Moment`s
-it contains according to its configuration, mapping each `Moment` to a point 
+it contains according to its configuration, mapping each `Moment` to a point
 in time relative to the start time given by the `starting` parameter.
 
-_However_, a typical use case may require different data set sizes for 
+## Scaling
+
+A typical use case may require different data set sizes for
 different applications: For example, a large dataset to live in a staging 
 environment in order to sanity check releases and a small, easy to load dataset 
 that can be used locally while developing.
 
-Suppose we have certain events that we wish to occur only once, 
-(using the above example, this may be the creation of some `Organisation` object
-representing the news company for which articles are being written) as well
+Suppose we have certain events that we wish to occur only once,
+(using the above example, this may be the creation of some `Publication` object
+representing the newspaper for which articles are being written) as well
 as events that we wish to be able to scale, such as the creation of `Article`
 objects and their associated `Comment`s.
 
-Using `Bonito`, we could define two windows: a `singleton_window` that is run once per
-dataset and generates our `Organisation` model, as well as a `scalable_window`
+Using `Bonito`, we could define two timelines: a `singleton_timeline` 
+that is run once per dataset and generates our 
+`Organisation` model, as well as a `scalable_timeline`
 that results in different sizes of data according to some size parameter.
 
-These windows can then be combined as follows, where the size paramter `factor`
+These timelines can then be combined as follows, where the size parameter `n`
 can be provided dynamically as, say, an argument provided to a `Rake` task.
  
 ```ruby
-scaled_window = singleton_window + (scalable_window * factor)
+scaled = singleton_timeline + (scalable_timeline ** n)
 ```
 
-The `scaled_window`, when run, will run the `scalable_window` `factor` times
+The `scaled_timeline`, when run, will run the `scalable_timeline` `n` times
 in parallel.
 
+## Scoping
+
+Data can be shared amongst `Moments` via a `Scope` object.
+Attributes on a `Scope` object are available within the **current** serial 
+timeline and in all **child** serial timelines.
+
+Consider the following example:
+
+```ruby
+Bonito.over 1.week do
+  please do |scope|
+    scope.foo = 'bar'
+  end
+
+  over 2.days do
+    please do |scope|
+      puts scope.foo # prints 'bar'
+    end
+
+    please do |scope|
+      scope.foo = 'baz'
+    end
+
+    please do |scope|
+      puts scope.foo # now prints 'baz'
+    end
+  end
+  
+  please do |scope|
+    puts scope.foo # still prints 'bar'
+  end
+end
+```
+
+## An Example
+
+Consider the following:
+
+```ruby
+# Initialise the data store, in practice a database would probably be used for 
+# this. Defined this way, these variables are available globally.
+ 
+scope = Bonito::Scope.new.tap do |scope|
+  scope.publications = []
+  scope.authors = []
+  scope.articles = []
+  scope.users = []
+  scope.comments = []
+  scope.users_and_authors = []
+end
+
+# We only ever want to create publication, regardless of how we scale, so we 
+# create a setup timeline to handle this
+singleton_timeline = Bonito.over 1.day do
+  please do |scope|
+    scope.publications << Publication.new
+  end
+end
+
+
+scalable_timeline = Bonito.over 1.week do
+  # Make the publication available to the current timeline.
+  please do |scope|
+    scope.publication = scope.publications.first
+  end
+  # Simultaneously create authors and users, interweaving the two.
+  simultaneously do
+    over 1.day do
+      # Create 5 authors over the course of a day 
+      repeat times: 5, over: 1.day do
+        please do |scope|
+          name = Faker::Name.name
+          author = Author.new(name)
+          scope.authors << author
+          scope.users_and_authors << author
+        end
+      end
+    end
+
+    # Create 10 users, also over one day, waiting at least 2 hours before 
+    # creating the first. 
+    also over: 1.day, after: 2.hours do
+      repeat times: 10, over: 1.day do
+        please do |scope|
+          name = Faker::Name.name
+          email = Faker::Internet.safe_email(name)
+          user = User.new(name, email)
+          scope.users << user
+          scope.users_and_authors << user
+        end
+      end
+    end
+  end
+  
+  # Repeat the following sequence of events 5 times over 5 days
+  repeat times: 5, over: 5.days do
+    # Choose one of the existing authors and create an article belonging to that
+    # author. 
+    please do |scope|
+      author = scope.authors.sample
+      title = Faker::Company.bs
+      scope.article = Article.new(title, author, scope.publication)
+      scope.articles << scope.article
+    end
+    
+    # Choose one of the existing users and have them leave a comment on the 
+    # article that was just created. 
+    repeat times: rand(10), over: 5.hours do
+      please do |scope|
+        user = scope.users.sample
+        content = Faker::Lorem.sentence
+        scope.comments << Comment.new(content, scope.article, user)
+      end
+    end
+  end
+end
+
+# Finally, we run the timeline to generate our data 
+scale = 5
+scaled_timeline = singleton_timeline + (scalable_timeline ** scale)
+
+Bonito.run scaled_timeline, scope: scope, starting: 8.weeks_ago
+```
+
 

data/bonito.gemspec

@@ -12,7 +12,7 @@ Gem::Specification.new do |spec|
 
   spec.summary       = 'A simple tool to create demo data'
   spec.description   = 'Create realistic demo data by simulating events occurring over some time period'
-  spec.homepage      = 'https://github.com/TomFinill/bonito'
+  spec.homepage      = 'https://github.com/tmfnll/bonito'
   spec.license       = 'MIT'
 
   # Specify which files should be added to the gem when it is released.
@@ -34,8 +34,8 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'activesupport'
   spec.add_development_dependency 'bundler', '~> 2.0'
   spec.add_development_dependency 'factory_bot'
-  spec.add_development_dependency 'faker', '~> 1.9.1'
-  spec.add_development_dependency 'rake', '~> 12.3'
+  spec.add_development_dependency 'faker', '~> 2.10.1'
+  spec.add_development_dependency 'rake', '~> 13'
   spec.add_development_dependency 'rdoc'
   spec.add_development_dependency 'reek'
   spec.add_development_dependency 'rspec', '~> 3.0'

data/lib/bonito/progress.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
+require 'logger'
 require 'ruby-progressbar'
+
 module Bonito
   module ProgressCounter # :nodoc:
     attr_reader :total

data/lib/bonito/timeline.rb

@@ -67,7 +67,7 @@ module Bonito
     end
 
     def evaluate
-      freeze { @scope.instance_eval(&self) }
+      freeze { to_proc.call(@scope) }
     end
 
     private

data/lib/bonito/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Bonito
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bonito
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Tom Finill
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-07-08 00:00:00.000000000 Z
+date: 2020-03-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: algorithms
@@ -100,28 +100,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.9.1
+        version: 2.10.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.9.1
+        version: 2.10.1
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '12.3'
+        version: '13'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '12.3'
+        version: '13'
 - !ruby/object:Gem::Dependency
   name: rdoc
   requirement: !ruby/object:Gem::Requirement
@@ -225,7 +225,7 @@ files:
 - lib/bonito/serial_timeline.rb
 - lib/bonito/timeline.rb
 - lib/bonito/version.rb
-homepage: https://github.com/TomFinill/bonito
+homepage: https://github.com/tmfnll/bonito
 licenses:
 - MIT
 metadata: {}
@@ -244,7 +244,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.4
+rubygems_version: 3.0.6
 signing_key: 
 specification_version: 4
 summary: A simple tool to create demo data