specdown 0.3.0 → 0.4.0.beta.1

data/CHANGELOG.markdown

@@ -1,5 +1,12 @@
 ## CHANGELOG
 
+## 0.4.0.beta.1
+
+First beta release with implicit specs support. See the "Implicit Specs"
+section in the README for details!
+
+Also, output format now defaults to "condensed".
+
 ## 0.3.0
 
 NOTICE: Non-backwards compatible release.

data/README.markdown

@@ -166,10 +166,15 @@ raise "WTF?" unless 1 == 1
 raise "name in scope" if defined? name
 ```
 
-## Non-executing code blocks
+## Non-executable code blocks
 
-It's likely that in the process of writing your documentation tests, you'll want
-to add some code into your markdown that you don't want executed.
+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.
+
+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.
 
@@ -177,7 +182,7 @@ 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:
 
-    # Non-Executing Code Blocks Example
+    # Non-Executable Code Blocks
     
     Here's an example of a non-executing code block:
     
@@ -195,7 +200,7 @@ executed, then just don't specifically flag it as Ruby:
     I'm not flagged as anything, so I won't execute.
     ```
 
-    ## Executing codeblocks
+    ## Executable codeblocks
     
     The only way to make a code block execute is to specifically flag it as Ruby
     
@@ -203,6 +208,73 @@ executed, then just don't specifically flag it as Ruby:
     puts "I execute!"
     ```
 
+## Implicit Specs
+
+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.
+
+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"
+    ```
+
+    We can delete the article by simply using the `delete!` method:
+    
+    ```ruby
+    article.delete!
+    ```
+
+    **The article should now be deleted from the database.**
+
+Notice the emphasis around the last sentence. If we execute this with
+`specdown`, we'll recieve the following result:
+
+    $ specdown
+
+        1 markdown
+        1 test
+        0 passing
+        0 failing
+        1 undefined
+
+
+        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
+
+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):
+
+```markdown
+The article should now be deleted from the database.
+----------------------------------------------------        
+
+    Article.all.should be_empty
+```
+
+The ".specdown" file is simply a markdown file with a different
+extension. It should consist of an unordered list of spec / definition pairs.
+
+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.
+
+
 ## Setting up your test environment
 
 Similar to the cucumber testing framework: if you put a ruby file somewhere inside your "specdown" directory, `specdown` will find it and load it.
@@ -341,15 +413,19 @@ You can also configure this in your env.rb by setting
 `Specdown::Config.format` to either `:short` or `:condensed`:
 
 ```ruby
-Specdown::Config.format = :condensed
+Specdown::Config.format = :short
 ```
 
-The default is `:short`.
+The default is `:condensed`.
 
 ## TODO
 
-This library is still very new, but I am rapidly adding features to it. Here's what is on the immediate horizon:
+This library is quite new, but I am rapidly adding features to it. Here's what is on the immediate horizon:
 
 * allow flagged text in the markdown to execute code, like a cucumber step definition
 * offer the option of outputing the actual markdown while it executes, instead of "..F....FF......"
 * Better stack traces / reporting
+
+## LICENSE
+
+This software is [public domain](http://en.wikipedia.org/wiki/Public_domain). GO WILD

data/VERSION

@@ -1 +1 @@
-0.3.0
+0.4.0.beta.1

data/features/command.feature

@@ -113,7 +113,9 @@ Feature: `specdown` command
     When I run `specdown specdown/tests`
     Then I should see the following output:
       """
-        ...
+        1.markdown: .
+        2.markdown: .
+        3.markdown: .
 
         3 markdowns
         3 tests

data/features/config.feature

@@ -50,7 +50,7 @@ Feature: Specdown::Config
     * Specdown::Config.expectations #==> nil
     * Specdown::Config.reporter     #==> Specdown::ColorTerminalReporter
     * Specdown::Config.root         #==> "specdown"
-    * Specdown::Config.format       #==> :short
+    * Specdown::Config.format       #==> :condensed
 
   Scenario: Reset the Specdown::Config
     Given I have configured Specdown:
@@ -58,7 +58,7 @@ Feature: Specdown::Config
         Specdown::Config.expectations = :rspec
         Specdown::Config.reporter     = Specdown::TerminalReporter
         Specdown::Config.root         = "dir/"
-        Specdown::Config.format       = :condensed
+        Specdown::Config.format       = :short
       """
 
     When I reset Specdown:
@@ -70,7 +70,7 @@ Feature: Specdown::Config
       * Specdown::Config.expectations #==> nil
       * Specdown::Config.reporter     #==> Specdown::ColorTerminalReporter
       * Specdown::Config.root         #==> "specdown"
-      * Specdown::Config.format       #==> :short
+      * Specdown::Config.format       #==> :condensed
 
 
 

data/features/fixtures/codeblocks_and_implicits.markdown

@@ -0,0 +1,7 @@
+# Specdown Example
+
+**This is an implicit spec.**
+
+```ruby
+hi = "explicit spec"
+```

data/features/implicit_parser.feature

@@ -0,0 +1,113 @@
+Feature: Specdown::ImplicitParser
+
+  The Specdown::ImplicitParser will parse ".specdown" files.
+
+  Imagine the following file "implicits.specdown":
+
+
+      some text
+      ==================
+      
+          some code
+
+
+
+      some more text
+      ==================
+
+          some more code
+
+
+  We can pass it off to the Specdown::ImplicitParser as a string:
+
+      result = Specdown::ImplicitParser File.read("implicits.specdown")
+
+  The result will be a hash lookup for the definitions:
+
+      result.should == {
+        "some text" => "some code",
+        "some more text" => "some more code"
+      }
+
+
+  Note that, unlike a regular markdown file that you ask specdown to execute, specdown does not care about the header levels inside your ".specdown" files.
+ 
+
+  Scenario: Multiple Implicits
+
+    Given the following implicit specification:
+      """
+        @implicits = <<-SPECDOWN.undent
+          a
+          -----------------
+
+              a code
+
+
+          b
+          ===================
+
+              b code
+          
+
+          c
+          ------------------
+
+          here's the c code:
+              
+              c code
+          
+          plus some more c code:
+
+              more c code
+
+        SPECDOWN
+      """
+    
+    When I parse it with the implicit parser: 
+      """
+        @result = Specdown::ImplicitParser.parse @implicits
+      """
+
+    Then I should receive a hash lookup of implicit definitions:
+      """
+        @result.should == {
+          "a" => "a code",
+          "b" => "b code",
+          "c" => "c code\nmore c code"
+        }
+      """
+
+  Scenario: Several implicit specification strings
+
+    Given two implicit specification strings:
+      """
+        @implicits_1 = <<-SPECDOWN.undent
+          a
+          ---------------
+
+              a code
+        SPECDOWN
+
+        @implicits_2 = <<-SPECDOWN.undent
+          b
+          --------------
+
+          ```ruby
+          b code
+          ```
+        SPECDOWN
+      """
+    
+    When I pass both off to the Specdown::ImplicitParser:
+      """
+        @results = Specdown::ImplicitParser.parse @implicits_1, @implicits_2
+      """
+
+    Then I should receive a hash lookup of implicit definitions:
+      """
+        @results.should == {
+          "a" => "a code",
+          "b" => "b code"
+        }
+      """

data/features/implicit_specs.feature

@@ -0,0 +1,135 @@
+Feature: Implicit Specs
+
+  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.
+
+  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"
+      ```
+
+      We can delete the article by simply using the `delete!` method:
+      
+      ```ruby
+      article.delete!
+      ```
+
+      **The article should now be deleted from the database.**
+
+  Notice the emphasis around the last sentence. If we execute this with
+  `specdown`, we'll recieve the following result:
+
+  ```sh
+  $ specdown
+
+      1 markdown
+      1 test
+      0 passing
+      0 failing
+      1 undefined
+
+      
+      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
+  ```
+
+  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):
+
+  ```markdown
+  The article should now be deleted from the database.
+  --------------------------------------------------------
+
+      Article.all.should be_empty
+  ```
+
+  The ".specdown" file is simply a markdown file with a different
+  extension. It should consist of an unordered list of spec / definition pairs.
+
+  Note that, according to the [markdown specification](http://daringfireball.net/projects/markdown/syntax#list), codeblocks within list items must be indented twice (two tabs or 8 spaces).
+
+
+  Scenario: No implicit specification
+
+    Given a markdown file with an implicit spec:
+      """
+        # Heading
+
+        **An implicit spec.**
+      """
+    But no implicit specification
+    When I run the `specdown` command
+    Then I should see the following output:
+      """
+        1 undefined
+
+        Now add the following implicit spec definition to a file suffixed with ".specdown":
+
+        An implicit spec.
+        ------------------------------------------------------
+            
+            pending # replace this with the code you wish you had
+      """
+  
+  Scenario: Pending implicit specification
+    Given a markdown file with an implicit spec:
+      """
+        # Heading
+
+        **An implicit spec.**
+      """
+
+    And a specdown file with a pending specification:
+      """
+      An implicit spec.
+      ---------------------
+
+          pending
+      """
+
+    When I run the `specdown` command
+    Then I should see the following output:
+      """
+        1 pending
+      """
+ 
+  Scenario: Complete implicit specification
+    Given a markdown file with an implicit spec:
+      """
+        # Heading
+
+        **An implicit spec.**
+      """
+    
+    And a specdown file with a complete specification:
+      """
+        An implicit spec.
+        ----------------------
+
+            raise "oops!" unless 1 == 1
+      """
+
+    When I run the `specdown` command
+
+    Then I should see the following output:
+      """
+        1 success
+        0 failures
+      """
+
+