mountain_berry_fields 1.0.0

data/.gitignore

@@ -0,0 +1,19 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+features/proving_grounds
+.DS_Store

data/.simplecov

@@ -0,0 +1,12 @@
+SimpleCov.start do
+  add_filter '/spec/'
+  add_filter '/features/'
+
+  # this gets acceptance tested, not unit tested
+  add_filter 'formatter.rb'
+
+  # don't look at coverage of plugins, let them test themselves
+  add_filter do |source_file|
+    !source_file.filename[File.dirname(__FILE__)+'/']
+  end
+end

data/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Josh Cheek
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,30 @@
+#!/usr/bin/env rake
+require 'bundler/gem_tasks'
+
+task :rspec do
+  require 'rspec'
+  Dir.glob("spec/**/*_spec.rb").each { |filename| require File.expand_path filename }
+  RSpec::Core::Runner.run []
+end
+
+require 'cucumber/rake/task'
+default_cucumber_opts = "features --format pretty --tags ~@not-implemented"
+Cucumber::Rake::Task.new(:cucumber)      { |t| t.cucumber_opts = default_cucumber_opts + " --tags ~@wip" }
+Cucumber::Rake::Task.new('cucumber:wip') { |t| t.cucumber_opts = default_cucumber_opts + " --tags @wip" }
+
+
+task rspec_must_be_100_percent: :rspec do
+  percent = SimpleCov.result.covered_percent
+  unless percent == 100
+    SimpleCov.result.format!
+    fail "\e[31mYo, dawg some of your shit isn't getting tested, only %0.2f%%\e[0m" % percent
+  end
+end
+
+
+require 'mountain_berry_fields/rake_task'
+MountainBerryFields::RakeTask.new(:generate_readme, 'Readme.md.mountain_berry_fields')
+
+task default: [:rspec_must_be_100_percent, :cucumber, :generate_readme]
+
+

data/Readme.md

@@ -0,0 +1,184 @@
+# MountainBerryFields
+
+Tests code in readme files, generates the readme if they are successful.
+
+## Usage
+
+When you have a file with embedded code samples, rename it to include a .mountain_berry_fields suffix.
+Then wrap test statements around the code samples. I've written two testing strategies: rspec and magic_comments.
+You can create your own without much effort.
+
+
+### Code samples with magic comments
+
+You will need to
+`$ gem install mountain_berry_fields-magic_comments`
+for this to work.
+
+The file `Readme.mountain_berry_fields.md`
+
+    # MyLibName
+
+        <% test 'an example', with: :magic_comments do %>
+        MyLibName.new('some data').result # => "some cool result"
+        <% end %>
+
+Run `$ mountain_berry_fields Readme.mountain_berry_fields.md` and it will generate `Readme.md`
+
+    # MyLibName
+
+        MyLibName.new('some data').result # => "some cool result"
+
+If at some point, you change your lib to not do that cool thing, then it will not generate the file.  Instead it will give you an error message:
+
+    FAILURE: an example
+    Expected: MyLibName.new('some data').result # => "some cool result"
+    Actual:   MyLibName.new('some data').result # => "some unexpected result"
+
+Now you can be confident that your code is still legit.
+
+Realworld [example](https://github.com/JoshCheek/deject/blob/8eb0d92949318cf4ef87c2b1a2070328024b0196/Readme.md.mountain_berry_fields#L40-48).
+
+### Code samples with RSpec
+
+You will need to
+`$ gem install mountain_berry_fields-rspec`
+for this to work.
+
+The file `Readme.mountain_berry_fields.md`
+
+    # MyLibName
+
+        <% test 'an example', with: :rspec do %>
+        describe MyLibName do
+          it 'does what I made it do' do
+            described_class.new('some data').result.should == 'some cool result'
+          end
+        end
+        <% end %>
+
+Run `$ mountain_berry_fields Readme.mountain_berry_fields.md` to generate `Readme.md`
+
+    # MyLibName
+
+        describe MyLibName do
+          it 'does what I made it do' do
+            described_class.new('some data').result.should == 'some cool result'
+          end
+        end
+
+And an rspec error:
+
+    FAILURE: an example
+    MyLibName does what I made it do:
+      expected: "some cool result"
+         got: "some unexpected result" (using ==)
+
+    backtrace:
+      /spec.rb:8:in `block (2 levels) in <top (required)>'
+
+Realworld [example](https://github.com/JoshCheek/surrogate/blob/b7ad4d3cd5ce2e3b8bf44c3743436e4d614b1991/Readme.md.mountain_berry_fields#L254-258).
+
+### Setup blocks
+
+You may need to do something to setup the environment for the tests (e.g. load the lib your examples are using)
+Do that with a setup block:
+
+    <% setup do %>
+    $LOAD_PATH.unshift File.expand_path '../lib', __FILE__
+    require 'my_lib_name'
+    <% end %>
+
+This will not show up anywhere in the generated file. It will be prepended before each code sample when running tests.
+
+Realworld [example](https://github.com/JoshCheek/deject/blob/8eb0d92949318cf4ef87c2b1a2070328024b0196/Readme.md.mountain_berry_fields#L22-25).
+
+### Context blocks
+
+Some examples may need to be executed within a context. Use a context block for that.
+Use the `__CODE__` macro to indicate where the code should go relative to this context.
+
+    <% context 'a user named Carlita' do %>
+    user = Struct.new(:name).new 'Carlita'
+    __CODE__
+    <% end %>
+
+    <% test 'users have a name', context: 'a user named Carlita', with: :magic_comments do %>
+    user.name # => "Carlita"
+    <% end %>
+
+Context blocks can, themselves, be rendered into a context `<% context 'current', context: "my context's context" do %>`
+
+Realworld [example](https://github.com/JoshCheek/surrogate/blob/b7ad4d3cd5ce2e3b8bf44c3743436e4d614b1991/Readme.md.mountain_berry_fields#L237-258).
+
+### Rake Task
+
+If you want to add this as part of your build, there is a rake task:
+
+```ruby
+require 'mountain_berry_fields/rake_task'
+MountainBerryFields::RakeTask.new(:mbf, 'Readme.mountain_berry_fields.md')
+```
+
+which will allow you to say `$ rake mbf`. You could then add it to your default task with
+`task default: :mbf`, or have whatever task runs your tests just execute it at the end.
+
+Realworld [example](https://github.com/JoshCheek/surrogate/blob/b7ad4d3cd5ce2e3b8bf44c3743436e4d614b1991/Rakefile#L13-17).
+
+### Creating your own test strategy
+
+I've written the magic_comments and rspec strategies. You can write your own that do
+whatever interesting thing you've thought of.
+
+If you want it to be a gem, then the strategy needs to be in the file
+`mountain_berry_fields/test/your_strategy.rb`. Mountain Berry Fields
+will automatically load files at these paths. If your strategy is not a gem,
+then it is up to you to ensure the code defining the strategy is loaded.
+
+Any strategy can be made accessible to the .mountain_berry_fields file like this:
+`MountainBerryFields::Test::Strategy.register :your_strategy, YourStrategy`
+And then accessed by `<% test 'testname', with: :your_strategy do %>`
+
+Strategies will be initialized with the code to test, and are expected to
+implement `#pass?` which returns a boolean of whether the code passes according
+to that strategy, and `#failure_message` which will used to describe why the spec
+failed to users.
+
+Realworld gem [example](https://github.com/JoshCheek/mountain_berry_fields-rspec/blob/cc6364ad106a7c65822542709bc5676bfb0b2c07/lib/mountain_berry_fields/test/rspec.rb).
+Realworld non-gem [example](https://github.com/JoshCheek/mountain_berry_fields/blob/be751536c8b0f94c84b09167fa83616b94b13b12/readme_helper.rb).
+
+### About the name
+
+I am often asked why I picked this name. I make things like this for me, because I have decided that they have value.
+I felt the need to remind myself of that so I chose a name that no one would realisitcally choose,
+to remind myself of the fact that no one could tell me I couldn't choose it.
+
+The phrase "Mountain berry fields" is a lyric in a [song](http://www.myspace.com/joyelectric/music/songs/birds-will-sing-forever-christian-songs-album-version-34576758) that makes me happy.
+
+If it bothers you: `$ alias mbf=mountain_berry_fields`
+
+## TODO
+* set it up on Travis
+
+## Features to add for v2
+
+Note that my use cases are to be able to test Deject and Surrogate,
+which this currently does quite nicely. As a result, I have no imminent
+need for any of these features, and so they are not a priority for me.
+If you have a need for them (or for other features), let me know and that
+will cause it to be a much higher priority for me. Alternatively,
+pull requests that add them, fix bugs, or generally make it better,
+are more than welcome.
+
+* contexts should be lazy (can define context after a block that uses it)
+* should be able to pass options to the initializer
+* enable the test strategy to decide what should be returned
+* support for multiple input files
+* FLAGS:
+* * -o set up input files so they don't need a .mountain_berry_fields in their name (output filename is provided, so input filename needs no naming conventions)
+* * -s list all known test strategies
+* * -v version
+* * -c check syntax (no output, thus also no input filename restrictions)
+* * -e flag for outputting erb (e.g. when it gives weird ass _buf error)
+* * -h to display this menu
+* * ?? to display the code that was passed to the test, along with the failure

data/Readme.md.mountain_berry_fields

@@ -0,0 +1,197 @@
+<% load "readme_helper.rb" %>
+# MountainBerryFields
+
+Tests code in readme files, generates the readme if they are successful.
+
+## Usage
+
+When you have a file with embedded code samples, rename it to include a .mountain_berry_fields suffix.
+Then wrap test statements around the code samples. I've written two testing strategies: rspec and magic_comments.
+You can create your own without much effort.
+
+
+### Code samples with magic comments
+
+You will need to
+`<% test('dep magic_comments', with: :install_dep) { %>$ gem install mountain_berry_fields-magic_comments<% } %>`
+for this to work.
+
+<% test 'show magic comments', with: :mbf_example do %>
+The file `Readme.mountain_berry_fields.md`
+
+    # MyLibName
+
+        <%% test 'an example', with: :magic_comments do %>
+        MyLibName.new('some data').result # => "some cool result"
+        <%% end %>
+
+Run `$ mountain_berry_fields Readme.mountain_berry_fields.md` and it will generate `Readme.md`
+
+    # MyLibName
+
+        MyLibName.new('some data').result # => "some cool result"
+
+If at some point, you change your lib to not do that cool thing, then it will not generate the file.  Instead it will give you an error message:
+
+    FAILURE: an example
+    Expected: MyLibName.new('some data').result # => "some cool result"
+    Actual:   MyLibName.new('some data').result # => "some unexpected result"
+<% end %>
+
+Now you can be confident that your code is still legit.
+
+Realworld [example](https://github.com/JoshCheek/deject/blob/8eb0d92949318cf4ef87c2b1a2070328024b0196/Readme.md.mountain_berry_fields#L40-49).
+
+### Code samples with RSpec
+
+You will need to
+`<% test('dep rspec', with: :install_dep) { %>$ gem install mountain_berry_fields-rspec<% } %>`
+for this to work.
+
+<% test 'show rspec', with: :mbf_example do %>
+The file `Readme.mountain_berry_fields.md`
+
+    # MyLibName
+
+        <%% test 'an example', with: :rspec do %>
+        describe MyLibName do
+          it 'does what I made it do' do
+            described_class.new('some data').result.should == 'some cool result'
+          end
+        end
+        <%% end %>
+
+Run `$ mountain_berry_fields Readme.mountain_berry_fields.md` to generate `Readme.md`
+
+    # MyLibName
+
+        describe MyLibName do
+          it 'does what I made it do' do
+            described_class.new('some data').result.should == 'some cool result'
+          end
+        end
+
+And an rspec error:
+
+    FAILURE: an example
+    MyLibName does what I made it do:
+      expected: "some cool result"
+         got: "some unexpected result" (using ==)
+
+    backtrace:
+      /spec.rb:8:in `block (2 levels) in <top (required)>'
+<% end %>
+
+Realworld [example](https://github.com/JoshCheek/surrogate/blob/b7ad4d3cd5ce2e3b8bf44c3743436e4d614b1991/Readme.md.mountain_berry_fields#L254-258).
+
+### Setup blocks
+
+You may need to do something to setup the environment for the tests (e.g. load the lib your examples are using)
+Do that with a setup block:
+
+<% test 'setup blocks', with: :requires_lib do %>
+    <%% setup do %>
+    $LOAD_PATH.unshift File.expand_path '../lib', __FILE__
+    require 'my_lib_name'
+    <%% end %>
+<% end %>
+
+This will not show up anywhere in the generated file. It will be prepended before each code sample when running tests.
+
+Realworld [example](https://github.com/JoshCheek/deject/blob/8eb0d92949318cf4ef87c2b1a2070328024b0196/Readme.md.mountain_berry_fields#L22-25).
+
+### Context blocks
+
+Some examples may need to be executed within a context. Use a context block for that.
+Use the `__CODE__` macro to indicate where the code should go relative to this context.
+
+<% test 'context block', with: :generic_mbf do %>
+    <%% context 'a user named Carlita' do %>
+    user = Struct.new(:name).new 'Carlita'
+    __CODE__
+    <%% end %>
+
+    <%% test 'users have a name', context: 'a user named Carlita', with: :magic_comments do %>
+    user.name # => "Carlita"
+    <%% end %>
+<% end %>
+
+Context blocks can, themselves, be rendered into a context `<%% context 'current', context: "my context's context" do %>`
+
+Realworld [example](https://github.com/JoshCheek/surrogate/blob/b7ad4d3cd5ce2e3b8bf44c3743436e4d614b1991/Readme.md.mountain_berry_fields#L237-258).
+
+### Rake Task
+
+If you want to add this as part of your build, there is a rake task:
+
+```ruby
+<%# this is the only one I'm going to test here. Maybe in the future, a gem for strategies specifically targeting rake %>
+<% test 'rake task', with: :task_named_mbf do %>
+require 'mountain_berry_fields/rake_task'
+MountainBerryFields::RakeTask.new(:mbf, 'Readme.mountain_berry_fields.md')
+<% end %>
+```
+
+which will allow you to say `$ rake mbf`. You could then add it to your default task with
+`task default: :mbf`, or have whatever task runs your tests just execute it at the end.
+
+Realworld [example](https://github.com/JoshCheek/surrogate/blob/b7ad4d3cd5ce2e3b8bf44c3743436e4d614b1991/Rakefile#L13-17).
+
+### Creating your own test strategy
+
+I've written the magic_comments and rspec strategies. You can write your own that do
+whatever interesting thing you've thought of.
+
+If you want it to be a gem, then the strategy needs to be in the file
+`mountain_berry_fields/test/your_strategy.rb`. Mountain Berry Fields
+will automatically load files at these paths. If your strategy is not a gem,
+then it is up to you to ensure the code defining the strategy is loaded.
+
+Any strategy can be made accessible to the .mountain_berry_fields file like this:
+`<% test('registering', with: :register_your_strategy){ %>MountainBerryFields::Test::Strategy.register :your_strategy, YourStrategy<%}%>`
+And then accessed by `<%% test 'testname', with: :your_strategy do %>`
+
+Strategies will be initialized with the code to test, and are expected to
+implement `#pass?` which returns a boolean of whether the code passes according
+to that strategy, and `#failure_message` which will used to describe why the spec
+failed to users.
+
+Realworld gem [example](https://github.com/JoshCheek/mountain_berry_fields-rspec/blob/cc6364ad106a7c65822542709bc5676bfb0b2c07/lib/mountain_berry_fields/test/rspec.rb).
+Realworld non-gem [example](https://github.com/JoshCheek/mountain_berry_fields/blob/be751536c8b0f94c84b09167fa83616b94b13b12/readme_helper.rb),
+and the code that [loads](https://github.com/JoshCheek/mountain_berry_fields/blob/754c3fb9d26779e38c01e15999ea6b86137372a2/Readme.md.mountain_berry_fields#L1) it.
+
+### About the name
+
+I am often asked why I picked this name. I make things like this for me, because I have decided that they have value.
+I felt the need to remind myself of that so I chose a name that no one would realisitcally choose,
+to remind myself of the fact that no one could tell me I couldn't choose it.
+
+The phrase "Mountain berry fields" is a lyric in a [song](http://www.myspace.com/joyelectric/music/songs/birds-will-sing-forever-christian-songs-album-version-34576758) that makes me happy.
+
+If it bothers you: `$ alias mbf=mountain_berry_fields`
+
+## TODO
+* set it up on Travis
+
+## Features to add for v2
+
+Note that my use cases are to be able to test Deject and Surrogate,
+which this currently does quite nicely. As a result, I have no imminent
+need for any of these features, and so they are not a priority for me.
+If you have a need for them (or for other features), let me know and that
+will cause it to be a much higher priority for me. Alternatively,
+pull requests that add them, fix bugs, or generally make it better,
+are more than welcome.
+
+* contexts should be lazy (can define context after a block that uses it)
+* should be able to pass options to the initializer
+* enable the test strategy to decide what should be returned
+* support for multiple input files
+* FLAGS:
+* * -o set up input files so they don't need a .mountain_berry_fields in their name (output filename is provided, so input filename needs no naming conventions)
+* * -s list all known test strategies
+* * -v version
+* * -c check syntax (no output, thus also no input filename restrictions)
+* * -e flag for outputting erb (e.g. when it gives weird ass _buf error)
+* * -h to display this menu
+* * ?? to display the code that was passed to the test, along with the failure