lab42_literate 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 719c356f00f0141fa7a9c0bfec1b25792f067927
-  data.tar.gz: ab1de21e75855dcf24996a447d08479734a54901
+  metadata.gz: 5dc4434c53fc4b7ae709911bed4ea867eee642b4
+  data.tar.gz: 3a68fe614d6f32e3b5e13d8bb46a02ca28347ffc
 SHA512:
-  metadata.gz: eb38c90f79ff71b04b4d6252fe0f5ce7ba6d4bc9564ce279ee8ea2f198f107568d7e609eccf3952af8680a389c13b0654086cc0edd784d631af86c4db4fbd8f4
-  data.tar.gz: fadeeeee4eb23c14de66a2d1788a7d01aa2ffb620c7a6f65b3c5b82c01c9d5def3e517bb607bdfe3ea7be8e6ce5f643d0dfd12943f6e9c8fae498b58348813d3
+  metadata.gz: d9e5a3cab528ecc1e3c8b4aec44068506e69dfc0445e121ddaef0e6fb350b8c379e6ec1141f48222cb775d7a66925d988d6e65cc23e9b7c21358066a0ddc5184
+  data.tar.gz: 128ced3230f2486533283039ed0ae96d1c278826d4dcc557b5329b52d664ac0f6f4067f75ad3f9dd5e77b547ee64f3982358bb87ecc9c83fbdab4342045ea766

data/README.md

@@ -7,7 +7,17 @@
 [![Issue Count](https://codeclimate.com/github/RobertDober/lab42_literate/badges/issue_count.svg)](https://codeclimate.com/github/RobertDober/lab42_literate)
 [![Test Coverage](https://codeclimate.com/github/RobertDober/lab42_literate/badges/coverage.svg)](https://codeclimate.com/github/RobertDober/lab42_literate)
 
-## Literate Programming à la doctest.
+## Literate Programming à la doctest in Elxir.
+
+[Elixir Doctest](https://elixir-lang.org/getting-started/mix-otp/docs-tests-and-with.html#doctests)  has inspired this gem.
+
+Of course Elixir doctests from the metadata of a compiled elixir source (beam).
+
+As in Ruby we do not have any metadata this works with simple text extraction and evalutaion.
+
+This gives us however the possibility to write our doctests in **any** file and allows you
+to assure that your `README.md` code examples are **all correct**.
+
 
 Just extract code blocks from any file, and run them as specs with a simple `doctest file` in an RSpec example group.
 
@@ -49,14 +59,76 @@ with
 
 ### How does it work?
 
-Each block ` ```ruby literate`  creates an example with title `"literate block in #{file}:#{start_lnb}..#{end_lnb}"`
-and instance_evals the lines from the block in the example's context.
+Each block ` ```ruby literate`  creates an example group with title `"literate block in #{file}:#{start_lnb}..#{end_lnb}"`.
+
+Then an anonymous example `it do ...` 
+and instance_evals the lines from the block in this example's context.
 
 
 ### Setup?
 
-Not yet.
 
-### Explicit Title of the generated example
+#### Inside the spec calling `doctest`
+
+
+Given this literate file
+
+      ```ruby literate
+          foo.reverse #=> 'oof'
+      ```
+
+will perfectly work if you setup your spec as follows
+
+```ruby
+    RSpec.describe 'FOO', type: :literate do
+      let(:foo){ 'foo' }
+      doctest('literate_file.md')
+    end
+```
+
+
+#### Inside the literal file itself
+
+All literate blocks containing a  `Given` block inside the document will be
+executed in the context in which `doctest` has been called, **before** the
+example blocks will be generated, thusly the following literate file will
+succeed
+
+    ```ruby literate
+        Given do
+          let(:a){ 1 }
+        end
+    ```
+    
+    ```ruby literate
+        a + b #=> 42
+    ```
+
+    ```ruby literate
+        Given do
+          let(:b){ 41 }
+        end
+    ```
+
+
+
+### Explicit Title of the generated Example Group
 
 Just add text  after ` ```ruby literate`
+
+E.g.
+
+      ```ruby literate Assure errors are empty
+
+          ...
+          expect(errors).to be_empty
+          
+      ```
+
+### Calling `doctest` inside an Example
+
+Will be deprecated.
+
+Does not support all features.
+
+Use at own risk.

data/lib/lab42/literate.rb

@@ -2,10 +2,18 @@ module Lab42
   module Literate
     require_relative 'literate/example_doctest'
     require_relative 'literate/group_doctest'
+
+    module Given
+      def Given &blk
+        instance_exec(&blk)
+      end
+    end
   end
 end
 
 RSpec.configure do | conf |
   conf.extend Lab42::Literate::GroupDoctest, type: :literate
+  conf.extend Lab42::Literate::Given, type: :literate
+
   conf.include Lab42::Literate::ExampleDoctest, type: :literate
 end

data/lib/lab42/literate/extractor/block.rb

@@ -1,3 +1,7 @@
+require 'parser/current'
+Parser::Builders::Default.emit_lambda = true
+Parser::Builders::Default.emit_procarg0 = true
+
 class Lab42::Literate::Extractor::Block
   attr_reader :lines, :start_lnb, :title
 
@@ -5,14 +9,23 @@ class Lab42::Literate::Extractor::Block
     lines << line
   end
 
+
   def get_title alternative
     title.empty? ?  alternative : title
   end
   
+
+  def given?
+    parsed.children.first.children == [nil, :Given]
+  rescue
+    false
+  end
+
   def range
     start_lnb..(start_lnb.pred + lines.size)
   end
 
+
   private
 
   def initialize start_lnb, title: ''
@@ -21,4 +34,7 @@ class Lab42::Literate::Extractor::Block
     @title     = title
   end
   
+  def parsed
+     @__parsed__ ||= Parser::CurrentRuby.parse(lines.join("\n"))
+  end
 end

data/lib/lab42/literate/group_doctest.rb

@@ -3,20 +3,27 @@ module Lab42::Literate::GroupDoctest
   Ex = Lab42::Literate::Extractor
 
   def doctest filename
-    doc_blocks = Ex.extract(File.readlines(filename))
-    doc_blocks.each{ |block| make_context filename, block }
+   blocks =  Ex
+      .extract(File.readlines(filename))
+
+   setups, examples = blocks.partition(&:given?)
+   setups.each{ |setup| make_setup filename, setup }
+   examples.each{ |example| make_context filename, example }
   end
 
   private
 
-  def make_context filename, block
-    return if block.lines.empty?
-    title = block.get_title "literate block in #{filename}:#{block.range.inspect}"
+  def make_context filename, example
+    return if example.lines.empty?
+    title = example.get_title "literate block in #{filename}:#{example.range.inspect}"
     context title do
       it do
-        eval(block.lines.join("\n"))
+        eval(example.lines.join("\n"))
       end
     end
   end
   
+  def make_setup filename, setup
+    eval(setup.lines.join("\n"))
+  end
 end

data/lib/lab42/literate/version.rb

@@ -1,5 +1,5 @@
 module Lab42
   module Literate
-    VERSION = '0.1.2'
+    VERSION = '0.1.3'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lab42_literate
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Robert Dober
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-12-19 00:00:00.000000000 Z
+date: 2017-12-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.7'
+- !ruby/object:Gem::Dependency
+  name: parser
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
 - !ruby/object:Gem::Dependency
   name: cucumber
   requirement: !ruby/object:Gem::Requirement