Lab42::Literate

Elixir Doctest 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.

  gem install lab42_literate

or in Gemfile

  gem 'lab42_literate'

Then in your spec_helper

  require 'lab42/literate'

which makes the doctest method available in all example groupes of type literate.

You can write RSpec example code inside a ```ruby literate block.

    ```ruby literate
      expect(%w{a b c}).not_to be_empty
    ```

There is an easy way to express expect(...).to eq(...) with the following special form...

    ```ruby literate
      1 + 41 #=> 42
    ```

Then, assuming the above text being inside a file some_literate.md one can execute the two examples above with

    RSpec.describe 'example', type: :literate do
      doctest 'some_literate.md'
    end

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.

Given this literate file

  ```ruby literate
      foo.reverse #=> 'oof'
  ```

will perfectly work if you setup your spec as follows

    RSpec.describe 'FOO', type: :literate do
      let(:foo){ 'foo' }
      doctest('literate_file.md')
    end

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
```

N.B. It follows from this behaviour that one cannot put a Given do ... end and code to be exceuted inside the generated examples into the same ```ruby literate block.

Just add text after ```ruby literate

E.g.

  ```ruby literate Assure errors are empty

      ...
      expect(errors).to be_empty
      
  ```

Will be deprecated.

Does not support all features.

Use at own risk.