doc_rspec 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ea386bcbd5e9be13a6eb83e7476d536fc4b15a565312c422dda406a1fe93d96
-  data.tar.gz: b05c0db28f9d81c95dddb6f782c18ba8cce4bd6e6bdf6a208b2987b7378a856f
+  metadata.gz: 88e3a986df1d2228b1455a425584ffa80e6ca725961a5e86e2cf14eb7d600b0c
+  data.tar.gz: ccbe8af928c2762e281e776b451d7a14a981d8f28fef39ac2ceb72f447b297de
 SHA512:
-  metadata.gz: 6faa80959f62b2a1a3a9e4147bc5506ec274fc64189b622d6efd3df0d5c817807636db842d7a116f2738ebeed4ac494ac98a4f52fcd6b179dffa4f9be337b322
-  data.tar.gz: 37c7b059562e6cc58ba4ad5aa759a752c5cf94472e55260d80178a77b789082dfa23da37d4ecb5fb7e172a492b2b198e3106217e0b817f221588d8345e48d70c
+  metadata.gz: 9a1a4f71792902e0454f2e857471f0122f06c2cea648401cdee47e7c6e743fbcd52ea689771edd675d3d69a529c77b2a602b130bbb2246dce045a3e51a020df2
+  data.tar.gz: 0f51c159a2cdde070fc6339c4bf7c2fab713047d391b649f887337c24544ee039f5493df0e66d8172d228b49d630767e61d4a9bf470aed31da3518458970d346

data/lib/doc_rspec/{ast → context}/example.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 class DocRSpec
-  class Ast
+  class Context
     class Example
       attr_reader :lines, :lnb, :name
 
@@ -13,9 +13,11 @@ class DocRSpec
         "#{name || "example from rdoc"} (#{path}:#{lnb})"
       end
 
+      def empty? = lines.empty?
+
       private
-      def initialize(lnb,match)
-        @name = match[2] unless match[2].empty?
+      def initialize(lnb, name:)
+        @name = name
         @lnb = lnb
         @lines = []
       end

data/lib/doc_rspec/context.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative 'context/example'
+class DocRSpec
+  class Context
+    attr_reader :examples, :lnb, :name
+
+    def add_example(lnb, name:)
+      examples.pop if examples.last&.empty?
+      examples << Example.new(lnb, name:)
+    end
+
+    def add_example_line(op, lhs, rhs=nil)
+      examples.last.add(op, lhs, rhs)
+    end
+
+    def context_name(path)
+      "#{name || "docspec"} (#{path}:#{lnb})"
+    end
+
+    def empty? = examples.empty?
+
+    private
+    def initialize(lnb, name: nil)
+      @lnb = lnb
+      @examples = []
+      @name = name
+    end
+
+  end
+end
+# SPDX-License-Identifier: AGPL-3.0-or-later

data/lib/doc_rspec/parser.rb

@@ -1,22 +1,19 @@
 # frozen_string_literal: true
 
-require_relative 'ast'
+require_relative 'context'
 
 class DocRSpec
   class Parser
     class InternalError < RuntimeError; end
     class SyntaxError < RuntimeError; end
 
-    COMMENT = %r{\A \s* \# \s*}x
 
-    EMPTY_LINE = %r{\A \s* \#+ \s* \z}x
+    CONTEXT_DEFINITION = %r{\A \s* \# \s ={1,7} \s (.*)}x
+
     EQUALS_OP = %r{\s+ => \s+}x
-    EXAMPLE_LINE = %r{\A \s* \#+ \s+ (.*)}x
+    EXAMPLE_LINE = %r{\A \s* \# \s{4,} (.*)}x
 
-    START_EXAMPLE = %r{\A \s* \#+ \s+ ```spec \s* (\# \s+)?(.*)?}x
-    START_RDOC_COMMENT = %r{\A \s* \#\#}x
-    STOP_EXAMPLE = %r{\A \s* \#+ \s+ ```}x
-    STOP_RDOC_COMMENT = %r{\A \s* [^#]* \z}x
+    START_EXAMPLE = %r{\A \s* \# \s{4,} \# \s example: \s (.*)}x
 
     attr_reader :ast, :lines, :state
 
@@ -24,26 +21,40 @@ class DocRSpec
       lines.each_with_index do |line, lnb|
         parse_line(line, lnb.succ)
       end
-      ast
+      ast.reject(&:empty?)
     end
 
     private
     def initialize(lines)
-      @ast   = []
+      @ast   = [Context.new(0)]
       @state = :outside
       @lines = lines
     end
 
-    def parse_example_line(line, lnb)
-      EXAMPLE_LINE.match(line) => [code]
+    def add_example(lnb, match)
+      name = match[1]
+      current_context.add_example(lnb, name:)
+      @state = :inside
+    end
+
+    def current_context = ast.last
+
+    def maybe_new_context(lnb, match)
+      name = match[1]
+      ast.pop if current_context.empty?
+      ast << Context.new(lnb, name:)
+      @state = :outside
+    end
+
+    def parse_example_line(match)
+      code = match[1]
 
       case code.split(EQUALS_OP)
       in [lhs, rhs]
         ast.last.add_example_line(:eq, lhs, rhs)
       else
-        ast.last.add_example_line(:verb, line.gsub(COMMENT, ''))
+        ast.last.add_example_line(:verb, code) unless code.empty?
       end
-
     end
 
     def parse_line(line, lnb)
@@ -51,45 +62,32 @@ class DocRSpec
       case state
       when :outside
         parse_line_outside(line, lnb)
-      when :inside_rdoc
-        parse_line_inside_rdoc(line, lnb)
-      when :inside_example
-        parse_line_inside_example(line, lnb)
+      when :inside
+        parse_line_inside(line, lnb)
       else
         raise InternalError, "unexpected state :#{state} (in line: #{line} at #{lnb}"
       end
     end
 
-    def parse_line_inside_example(line, lnb)
-      case line
-      when EMPTY_LINE
-        nil
-      when STOP_EXAMPLE
-        ast.last.close_example { raise SyntaxError, "Empty docspec example in line #{ast.last.examples.last.lnb}" }
-        @state = :inside_rdoc
-      when STOP_RDOC_COMMENT
-        raise SyntaxError, "Missing end of ```spec (starting at #{ast.last.examples.last.lnb}) at end of rdoc comment at #{lnb}"
-      else
-        parse_example_line(line, lnb)
-      end
-    end
-
-    def parse_line_inside_rdoc(line, lnb)
+    def parse_line_inside(line, lnb)
       case line
+      when CONTEXT_DEFINITION
+        maybe_new_context(lnb, Regexp.last_match)
       when START_EXAMPLE
-        ast.last.add_example(lnb, Regexp.last_match)
-        @state = :inside_example
+        add_example(lnb, Regexp.last_match)
+      when EXAMPLE_LINE
+        parse_example_line(Regexp.last_match)
       end
     end
 
     def parse_line_outside(line, lnb)
       case line
-      when START_RDOC_COMMENT
-        ast << Ast.new(lnb)
-        @state = :inside_rdoc
+      when CONTEXT_DEFINITION
+        maybe_new_context(lnb, Regexp.last_match)
+      when START_EXAMPLE
+        add_example(lnb, Regexp.last_match)
       end
     end
-
   end
 end
 # SPDX-License-Identifier: AGPL-3.0-or-later

data/lib/doc_rspec/{example_group.rb → rspec_example_group.rb}

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 class DocRSpec
-  module ExampleGroup
+  module RSpecExampleGroup
     def docspec(path)
       DocRSpec.new(path, self).generate_specs
     end

data/lib/doc_rspec/version.rb

@@ -2,7 +2,7 @@
 
 class DocRSpec
   module Version
-    VERSION = '0.1.2'
+    VERSION = '0.2.0'
   end
 end
 # SPDX-License-Identifier: AGPL-3.0-or-later

data/lib/doc_rspec.rb

@@ -2,87 +2,66 @@
 
 require 'rspec'
 require_relative 'doc_rspec/compiler'
-require_relative 'doc_rspec/example_group'
+require_relative 'doc_rspec/rspec_example_group'
 require_relative 'doc_rspec/parser'
-RSpec.configure { it.extend DocRSpec::ExampleGroup }
+RSpec.configure { it.extend DocRSpec::RSpecExampleGroup }
 
 ##
-# # Usage
+# = Usage
 #
-# Install the gem `gem install doc_rspec` or put `doc_rspec` in your Gemfile
+# Install the gem <tt>gem install doc_rspec</tt> 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
+# Then <tt>require doc_rspec</tt> 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
+# Inside your +RSpec+ file, at the example group level then call
 #
-# 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.
+#   # Usage example
+#   docspec '<path_to_file>'
 #
-# For each `rdoc` block an `ExampleGroup` is created and the lines
-# between  ` ```spec ` and ` ``` ` will be executed in the context
-# of one example.
+# Where +path_to_file+ is relative to the +lib+ directory
 #
-# ## Simplified exceptions in examples
+# = Abstract
 #
-# ```spec
-#   41 + 1 => 42
-# ```
+# Ruby Codeblocks that start with a comment line as follows
+#       # example: example_name
 #
-# but can also fail (and therefore this example is not marked with `spec`)
+# are considered an +RSpec+ example of the +RSpec+ example group +doctest+ has been called.
 #
-# ```not-spec
-#  41 => 42
-# ```
+# = RSpec Examples
 #
-# We have acces to the environment of the RSpec example
-# group we call `docspec` in.
+# == Just plain old Ruby Code
 #
-# ```spec
-#   this_is_available(21) => 42
-# ```
+#    # example: just an RSpec example
+#    expect(2*21).to eq(42)
 #
-# Morever we will adapt the `to eq` matcher to the `to match` matcher
-# if the expression right to `=>` evaluates to a `Regexp`.
+# = Implementation Notice
 #
-# ```spec
-#   DocRSpec::Version::VERSION => %r{\d+\.\d+\.\d+} 
-# ```
+#    # example: We have access to the wrapping context
 #
-# ## Just plain old RSpec...
+#     this_is_available(22) => 44
 #
-# is available for all lines that do not contain a `=>` string.
+# Although this gem is named +doc_rspec+ and its goal is certainly to document behavior
+# of Ruby code inside the +RDoc+ documentation of that code, and _most_ _importantly_
+# backing the claims made in this documentation up with *actual* +RSpec+ examples,
+# in this _MVP_ the parser will simply generate code for all lines matching 
+# <tt>/\A \s* \# \s{3,}/x</tt> after a triggering line macthing
+# <tt>/\A \s* \# \s{3,} \# \s example: \s (.+)/x</tt>
+# and potentially ended with the aforementioned <tt>/\A \s* \# \s{3,} \# \s end \s of \s example/x</tt>
 #
-# ```spec
-#   expect(42).to be > 41
-# ```
-# ## Naming Examples
+# This implies two thing
 #
-# Without naming examples the output when running a doctest with
-# `formatter=:doc` looks like this:
+# - you can also write +RSpec+ examples inside your code (inside comments) which are not part of rdoc
+# - you can use (although that would be missleading) an example like syntax in your +RDoc+ comments
+#   by spacing the ruby code block with only two spaces.
 #
-#     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)
+# The context is taken from the last headline
+# == First Examples
 #
-# 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)
+#     # example: equality
+#     expect(41 + 1).to eq(42)
 #
 class DocRSpec
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: doc_rspec
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Robert Dober
@@ -37,9 +37,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 3.13.0
-description: 'Implementing docspecs à la Elixir''s doctests
-
-  '
+description: Extract RSpec Examples from RDocs formatted with RDoc::Markup (the default)
 email: robert.dober@gmail.com
 executables: []
 extensions: []
@@ -48,13 +46,13 @@ files:
 - LICENSE
 - README.md
 - lib/doc_rspec.rb
-- lib/doc_rspec/ast.rb
-- lib/doc_rspec/ast/example.rb
 - lib/doc_rspec/compiler.rb
-- lib/doc_rspec/example_group.rb
+- lib/doc_rspec/context.rb
+- lib/doc_rspec/context/example.rb
 - lib/doc_rspec/parser.rb
+- lib/doc_rspec/rspec_example_group.rb
 - lib/doc_rspec/version.rb
-homepage: https://codeberg.org/lab419/doc_spec
+homepage: https://codeberg.org/lab419/doc_rspec
 licenses:
 - AGPL-3.0-or-later
 metadata: {}
@@ -74,5 +72,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.7
 specification_version: 4
-summary: '["Doc rspecs for Ruby"]'
+summary: '["Extract RSpec Examples from RDocs formatted with RDoc::Markup (the default)"]'
 test_files: []

data/lib/doc_rspec/ast.rb

@@ -1,34 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'ast/example'
-class DocRSpec
-  class Ast
-    attr_reader :examples, :lnb
-
-    def add_example(lnb, match)
-      examples << Example.new(lnb, match)
-    end
-
-    def add_example_line(op, lhs, rhs=nil)
-      examples.last.add(op, lhs, rhs)
-    end
-
-    def close_example(&error_handler)
-      return unless examples.last.lines.empty?
-
-      error_handler.()
-    end
-
-    def context_name(path)
-      "docspec #{path}:#{lnb}"
-    end
-
-    private
-    def initialize(lnb)
-      @lnb = lnb
-      @examples = []
-    end
-    
-  end
-end
-# SPDX-License-Identifier: AGPL-3.0-or-later