Class: DocRSpec

Inherits:
Object
  • Object
show all
Defined in:
lib/doc_rspec.rb,
lib/doc_rspec/ast.rb,
lib/doc_rspec/parser.rb,
lib/doc_rspec/version.rb,
lib/doc_rspec/compiler.rb,
lib/doc_rspec/ast/example.rb,
lib/doc_rspec/example_group.rb

Overview

# Usage

Install the gem ‘gem install doc_rspec` or put doc_rspec in your Gemfile or gemspec file.

Then ‘require doc_rspec` in the file you want to use the docspec macro or put it into your spec_helper.rb or use any advanced require strategy you are used to.

# Abstract

DocRSpec allows us to call ‘doctest <sourcefile>` and the specs between ` “`spec ` and ` “` ` will be executed in the context of the RSpec example group doctest has been called.

For each rdoc block an ExampleGroup is created and the lines between ‘ “`spec ` and ` “` ` will be executed in the context of one example.

## Simplified exceptions in examples

“‘spec

41 + 1 => 42

“‘

but can also fail (and therefore this example is not marked with spec)

“‘not-spec

41 => 42

“‘

We have acces to the environment of the RSpec example group we call docspec in.

“‘spec

this_is_available(21) => 42

“‘

Morever we will adapt the ‘to eq` matcher to the `to match` matcher if the expression right to `=>` evaluates to a Regexp.

“‘spec

DocRSpec::Version::VERSION => %r{\d+\.\d+\.\d+}

“‘

## Just plain old RSpec…

is available for all lines that do not contain a ‘=>` string.

“‘spec

expect(42).to be > 41

“‘ ## Naming Examples

Without naming examples the output when running a doctest with ‘formatter=:doc` looks like this:

DocRSpec
  example from rdoc (doc_rspec.rb:21)
  example from rdoc (doc_rspec.rb:34)
  example from rdoc (doc_rspec.rb:41)
  example from rdoc (doc_rspec.rb:49)

We can improve on this by giving an example a name with the ‘ “`spec # <name>` syntax

“‘spec # fourtytwo is the answer

the_answer = 42
expect(42).to eq(the_answer)

“‘

Now the output looks like:

DocRSpec
  example from rdoc (doc_rspec.rb:21)
  ...
  fourtytwo is the answer (doc_rspec.rb:65)

Defined Under Namespace

Modules: ExampleGroup, Version Classes: Ast, Compiler, Parser

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#example_group ⇒ Object (readonly)

Returns the value of attribute example_group.



89
90
91
 
# File 'lib/doc_rspec.rb', line 89

def example_group
  @example_group
end

#lines ⇒ Object (readonly)

Returns the value of attribute lines.



89
90
91
 
# File 'lib/doc_rspec.rb', line 89

def lines
  @lines
end

#path ⇒ Object (readonly)

Returns the value of attribute path.



89
90
91
 
# File 'lib/doc_rspec.rb', line 89

def path
  @path
end

Instance Method Details

#generate_specs ⇒ Object 



91
92
93
94
 
# File 'lib/doc_rspec.rb', line 91

def generate_specs
  spec_definitions = DocRSpec::Parser.new(lines).parse
  DocRSpec::Compiler.new(spec_definitions:, example_group:, path:).compile
end