specdown 0.4.0.beta.3 → 0.4.0

data/README.markdown

@@ -9,11 +9,11 @@ Write your README in markdown, and execute it with specdown.
 When you write a README for a library, a class, a command, etc., you're
 forced to stop and consider your user:
 
-* how are they going to use it?
-* what's the API
-* how am I going to convince them to use my library?
+* How are they going to use it?
+* What kind of API should I provide?
+* How can I convince someone to use my library?
 
-What if you write the README first, before writing your code? This is the
+What if you write the README first, before writing your tests or your code? This is the
 premise of README Driven Development. See Tom Preston-Werner's [blog post](http://tom.preston-werner.com/2010/08/23/readme-driven-development.html)
 on the topic for a quick introduction to all of its benefits.
 
@@ -45,236 +45,217 @@ To install the `specdown` ruby gem, simply:
 
 It comes with a `specdown` command. Try running it. Doesn't matter where.
 
-## Usage
+## Tutorial
 
-Let's write a simple test in ([github-flavored](http://github.github.com/github-flavored-markdown/)) markdown, and execute it with specdown. Create a "specdown" directory, then save the following text into a file inside of it. I'll assume you're calling it "example.markdown":
+The quickest way to learn specdown is to develop a simple ruby library with it. This tutorial should take about 10 minutes. Feel free to skip to the specdown command line reference at the end of this README.
 
-    # Our first test!
+Let's develop a simple todo list library. We'll be using [github-flavored](http://github.github.com/github-flavored-markdown/) markdown for all of our specdown. 
 
-    This is our very first test. It's going to blow your mind.
+We'll start by describing our library:
 
-    ```ruby
-    raise "WTF?" unless 1 == 1
-    ```
+    Todo
+    ====================
 
-Ok, if you've been following along, then `ls -R` should return the following directory structure:
+    The `todo` gem provides a simple ruby DSL for managing your TO DO list via IRB. 
 
-```sh
-$ ls -R
-  
-  specdown/
-    example.markdown
-```
 
-Great. Now run the `specdown` command:
+    Why?
+    --------------------------
+    
+    Most people would prefer to manage their TODO list through a website, mobile app, or desktop app.
+    But some geeks prefer doing everything in the terminal. If you're that kind of geek, read on.
 
-```sh
-    $ specdown
 
-        .
+    Installation
+    --------------------------
 
-        1 markdown
-        1 test
-        1 success
-        0 failures
-```
+    To get started, first install the "todo" gem:
 
-Booya!
+        $ gem install todo
+    
+    Next, fire up IRB and load your gem:
 
-### How does it work?
+        $ irb
+        > require 'rubygems'
+        > require 'todo'
+    
+    You're now ready to start interacting with your TODO list via the IRB prompt. 
 
-`specdown` loads any "markdown" files it can find inside the "specdown" directory, parses them into trees, then performs exhaustive depth-first searches on the trees to execute the code.
 
-Let's update our README to help illustrate this:
+Our readme tells you what the library is, why you might want to use it, and how to get started.  
 
-    # Our first test!
+We haven't written any real code yet, but let's go ahead and let specdown take a crack at executing it. Save your readme in your current working directory (I'm going to assume you call it "readme.markdown"), then run `specdown readme.markdown` at the command line.
 
-    This is our very first test. It's going to blow your mind.
-    
-    ```ruby
-    raise "WTF?" unless 1 == 1
-    ```
+    $ specdown readme.markdown
+      
+      readme.markdown: ..
 
-    ## A Subsection
+      1 markdown
+      2 tests
+      2 passing
+      0 failures
 
-    In this section, we're going to create a variable.
+Interesting. Specdown found two tests inside our README, then executed them and found that they were passing. But what were those tests?
 
-    ```ruby
-    name = "moonmaster9000"
-    ```
+Specdown works by parsing a README into a tree, letting the header structure form the nodes of the tree. Here's what our tree looks like so far:
 
-    ### A sub subsection
+                    #Todo
+                    /    \
+                   /      \
+                  /        \
+                 /          \
+                /            \
+               /              \
+              /                \
+          ##Why?             ##Installation
 
-    In this subsection, we have access to anything created or within scope in parent sections:
+Specdown performs an exhaustive depth-first search on the tree from the root to each leaf, collecting `ruby` codeblocks along the way. Our two tests are thus:
 
-    ```ruby
-    raise "name not in scope" if !defined? name
-    ```
+* #Todo -> ##Why?
+* #Todo -> ##Installation
 
-    ## Another Subsection
+However, at this point we have not yet written any `ruby` code blocks inside our markdown, so the tests are empty (and therefore passing by default). Let's change that. Add the following section to the end of your README:
+
+    Usage
+    -------------------
+
+    You'll use the `todo` method to interact with your list. For example, to see what's inside your list, simply call the `todo` method:
 
-    In this subsection, we don't have access to the "name" variable. Think of your markdown as a tree.
-    
     ```ruby
-    raise "name in scope" if defined? name
+    todo #==> []
     ```
 
-Read through that. I'm giving you some important scoping hints in it. 
 
-Save it, run it.
+We've just created our first executable test. When we surrounded the `todo` code with a `ruby` backtick fence, we told specdown to execute that code. The "#==> []" is of course not executable - it's just a comment. 
 
-```sh
-$ specdown
+Now if you run the specdown command, you'll get an exception report telling you that the "todo" constant is undefined:
 
-    ..
-    
-    1 markdown
-    2 tests
-    0 failures
-```
+    $ specdown readme.markdown
+      
+      readme.markdown: ..F
 
-Notice how the headers in your markdown form a tree?
+      ----------------------------
+      1 markdown
+      2 tests
+      1 passing
+      1 failing
+      ----------------------------
+
+      In readme.markdown: #<NameError>: (eval):2:in `execute_code': undefined local variable or method `todo'
 
-```sh
-                #Our first test!
-                    /    \
-                   /      \
-                  /        \
-                 /          \
-                /            \
-               /              \
-              /                \
-      ##A Subection       ##Another Subsection
-            /
-           /
-          /
-    ###A sub subsection
-```
 
-Specdown turned that tree into two tests. The first test (#Our first test! --> ##A Subsection --> ###A sub subsection):
+How can we rectify that?
+
+Create a "todo.rb" file inside your current working directory, and add the following code to it:
 
 ```ruby
-raise "WTF?" unless 1 == 1
-name = "moonmaster9000"
-raise "name not in scope" if !defined? name
+def todo
+end
 ```
 
-Here's what the second test looked like (#Our first test! --> ##Another Subsection)
+Then, create a "specdown" directory inside your current working directory and add another ruby file "specdown/env.rb" with the following code:
 
 ```ruby
-raise "WTF?" unless 1 == 1
-raise "name in scope" if defined? name
+$LOAD_PATH.unshift "." # ruby 1.9+
+require "todo"
 ```
 
-## Non-executable code blocks
-
-As of version `0.3.0`, you must surround any codeblocks you
-want specdown to execute with a github-flavored backtick fence. This
-change is not backwards-compatible with previous versions; you'll need
-to update your tests if you want to upgrade to this version.
+Run the specdown command again, and all tests should pass.
 
-I made this change because it's likely that in the process of writing your 
-specdown, you'll want to add some code into your markdown that you don't want executed.
-Perhaps it's code in a different language, or perhaps you're showing off
-some command line functionality.
+Next, let's show people how to add items to our `todo` list:
 
-Specdown only executes fenced codeblocks specifically flagged as `ruby`.
-Thus, if you want to add some code to your markdown that shouldn't be
-executed, then just don't specifically flag it as Ruby:
+      
+    To add an item to your `todo` list, simply pass a string to the `todo!` method:
 
-    # Non-Executable Code Blocks
-    
-    Here's an example of a non-executing code block:
-    
-        $ cd /
-    
-    Here's another example of a non-executing code block:
-        
-    ```javascript
-    console.log("I'm javascript, so I won't execute.");
+    ```ruby
+    todo! 'buy groceries'
     ```
-
-    A third example:
     
-    ```
-    I'm not flagged as anything, so I won't execute.
-    ```
+    **"buy groceries" is now in your todo list.** Call the `todo` method again to confirm.
+
+    Lastly, to remove an item from your list, pass it to the `done!` method:
 
-    ## Executable codeblocks
-    
-    The only way to make a code block execute is to specifically flag it as Ruby
-    
     ```ruby
-    puts "I execute!"
+    done! 'buy groceries'
     ```
+    
+    **Your list should now be empty again**.
 
-## Implicit Specs
+Notice that we surrounded some assertions with double stars. Run the `specdown` command and it will report an undefined "implicit" assertion:
 
-**Note: This feature requires version 0.4.0.beta.1 or greater.** 
+    $ specdown readme.markdown
+      
+      readme.markdown: ..U
 
-In all of the examples so far, we've made all code that we want executed
-explicit within the markdown. Sometimes, however, it's advantageous to
-simply state a specification, and then map that to code
-behind-the-scenes. They're conceptually equivalent to cucumber step
-definitions.
+      ----------------------------
+      1 markdown
+      2 tests
+      1 passing
+      1 undefined
+      0 failures
+      ----------------------------
 
-Imagine we've written the following markdown for an imaginary `Article`
-model:
 
-    # Deleting an article from the database
-    
-    Imagine we create the following article:
-        
-    ```ruby
-    article = Article.create :title => "Specdown"
-    ```
+      Now add the following implicit spec definition to a file suffixed with ".specdown":
 
-    We can delete the article by simply using the `delete!` method:
-    
-    ```ruby
-    article.delete!
-    ```
+      "buy groceries" is now in your todo list
+      ----------------------------------------
 
-    **The article should now be deleted from the database.**
+          pending # replace this with the code you wish you had
 
-Notice the emphasis around the last sentence. If we execute this with
-`specdown`, we'll recieve the following result:
 
-    $ specdown
+      Your list should now be empty again
+      -----------------------------------
 
-        1 markdown
-        1 test
-        0 passing
-        0 failing
-        1 undefined
+          pending # replace this with the code you wish you had
 
 
-        Now add the following implicit spec definition to a file suffixed with ".specdown":
 
-        The article should now be deleted from the database.
-        ----------------------------------------------------        
-            
-            pending # replace this with the code you want
+Create a "specdown" directory inside your current working directory, then add markdown to it. (Note: "specdown" files simply contain markdown, but are interpreted by specdown as containing implicit specifications. If you've used cucumber before, you can think of these as something similar to a cucumber step definition.)
 
-If we do as it says and rerun the `specdown` command, we'll receive a
-notice that we now have a pending implicit spec. Thus, we could
-implement the pending spec like so (assuming we were using RSpec
-expectations):
+If you rerun the `specdown` command, you'll get notified that your test is pending now. We can fill in the implicit specifications thusly. I'd like to use RSpec `should` expectations to fill out my tests; luckily, if specdown detects that the "rspec" gem is installed, it will make RSpec expectations available to your tests. Otherwise, it will default to `test/unit` assertions. We can ensure that "rspec" expectations are available in our tests by creating a Gemfile inside our current working directory with the following content:
 
-```markdown
-The article should now be deleted from the database.
-----------------------------------------------------        
+    source "http://rubygems.org"
 
-    Article.all.should be_empty
-```
+    gem "rspec"
+    gem "specdown"
+
+Now run `bundle` at the command line. Next, update your "readme.specdown" file and fill out the tests:
+
+    "buy groceries" is now in your todo list
+    ----------------------------------------
+
+        todo.should include("buy groceries")
+
+
+    Your list should now be empty again
+    -----------------------------------
+
+        todo.should be_empty
+
+Great! Now run `bundle exec specdown readme.markdown` and watch your tests fail! Keep it up, implementing just enough code to get your all of your tests passing.  
+
+### Implicit v. Explicit Assertions
 
-The ".specdown" file is simply a markdown file with a different
-extension. It should consist simply of headings (of any level) and code blocks. Any other elements within the file will simply be ignore by `specdown`. This allows you to organize the file and add extra comments into it in any way you desire.  
+Note that nothing requires us to create implicit assertions. We could have just as easily embedded these assertions in our main readme:
+
+    To add an item to your `todo` list, simply pass a string to the `todo` method:
+
+    ```ruby
+    todo! 'buy groceries'
+    todo.should include('buy groceries')
+    ```
+    
+    Call the `todo` method yourself to confirm.
+
+    Lastly, to remove an item from your list, pass it to the `done!` method:
+
+    ```ruby
+    done! 'buy groceries'
+    todo.should be_empty
+    ```
 
-Also, Note that we didn't surround our code with a github-flavored backtick
-fence. Since ".specdown" files are solely used for defining implicit
-specifications, it's assumed that all code blocks (unless they're
-spefically marked as something other than ruby) will be executed.
+However, we've sacrificied the readability (and utility) of our README by doing so.
 
 
 ## Setting up your test environment
@@ -397,7 +378,7 @@ The reporter defaults to `Specdown::ColorTerminalReporter`.
 
 ### Report format: short or condensed
 
-Currently, we offer two report formats: short, or condensed. Short
+Currently, we offer two report formats: short and condensed. Short
 offers only the most basic information, whereas `condensed` will provide
 you with summary details per file.
 

data/VERSION

@@ -1 +1 @@
-0.4.0.beta.3
+0.4.0

data/lib/specdown/command.rb

@@ -16,7 +16,7 @@ module Specdown
         run
       end
 
-      exit(@readmes.count == @readmes.select {|readme| readme.exceptions.empty? && readme.undefined_implicits.empty?}.count)
+      exit exit_status
     end
     
     private
@@ -36,5 +36,9 @@ module Specdown
         @readmes.last.execute
       end
     end
+
+    def exit_status
+      @readmes.all? &:passing?
+    end
   end
 end

data/lib/specdown/readme.rb

@@ -12,6 +12,10 @@ module Specdown
       build_tests
     end
 
+    def passing?
+      exceptions.empty? && pending_exceptions.empty? && undefined_implicits.empty?
+    end
+
     def exceptions
       @tests.collect(&:exception).compact
     end

metadata

@@ -1,110 +1,80 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: specdown
-version: !ruby/object:Gem::Version 
-  hash: 3084443435
-  prerelease: 6
-  segments: 
-  - 0
-  - 4
-  - 0
-  - beta
-  - 3
-  version: 0.4.0.beta.3
+version: !ruby/object:Gem::Version
+  version: 0.4.0
+  prerelease: 
 platform: ruby
-authors: 
+authors:
 - Matt Parker
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2012-01-30 00:00:00 Z
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2012-05-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: gitdown
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: &70337292991060 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 27
-        segments: 
-        - 0
-        - 0
-        - 2
+      - !ruby/object:Gem::Version
         version: 0.0.2
   type: :runtime
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: term-ansicolor
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  version_requirements: *70337292991060
+- !ruby/object:Gem::Dependency
+  name: term-ansicolor
+  requirement: &70337292990580 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 25
-        segments: 
-        - 1
-        - 0
-        - 7
+      - !ruby/object:Gem::Version
         version: 1.0.7
   type: :runtime
-  version_requirements: *id002
-- !ruby/object:Gem::Dependency 
-  name: hook
   prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  version_requirements: *70337292990580
+- !ruby/object:Gem::Dependency
+  name: hook
+  requirement: &70337292990120 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 27
-        segments: 
-        - 0
-        - 0
-        - 2
+      - !ruby/object:Gem::Version
         version: 0.0.2
   type: :runtime
-  version_requirements: *id003
-- !ruby/object:Gem::Dependency 
-  name: cucumber
   prerelease: false
-  requirement: &id004 !ruby/object:Gem::Requirement 
+  version_requirements: *70337292990120
+- !ruby/object:Gem::Dependency
+  name: cucumber
+  requirement: &70337292989740 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id004
-- !ruby/object:Gem::Dependency 
-  name: rspec
   prerelease: false
-  requirement: &id005 !ruby/object:Gem::Requirement 
+  version_requirements: *70337292989740
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70337287099060 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id005
+  prerelease: false
+  version_requirements: *70337287099060
 description: 
 email: moonmaster9000@gmail.com
-executables: 
+executables:
 - specdown
 extensions: []
-
-extra_rdoc_files: 
+extra_rdoc_files:
 - CHANGELOG.markdown
 - README.markdown
-files: 
+files:
 - VERSION
 - lib/specdown/command/option_parser.rb
 - lib/specdown/command.rb
@@ -209,40 +179,29 @@ files:
 - features/test.feature
 homepage: http://github.com/moonmaster9000/specdown
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">"
-    - !ruby/object:Gem::Version 
-      hash: 25
-      segments: 
-      - 1
-      - 3
-      - 1
-      version: 1.3.1
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.8.10
+rubygems_version: 1.8.17
 signing_key: 
 specification_version: 3
 summary: Write your specs as if they were a README, then EXECUTE them.
-test_files: 
+test_files:
 - features/command.feature
 - features/config.feature
 - features/event_server.feature