Lab42::Literate

Literate Programming à la doctest in Elxir.

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.

Installation

  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.

Very Quick Start

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

How does it work?

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?

Inside the spec calling doctest

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

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

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.

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.