doc_rspec 0.1.5 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2bd030fdeb4bdb9db6f545adaaeaf107e1d9ee38cceb00d7f194f0068b7ed40b
-  data.tar.gz: d2e2a7ffb00c7f7d871b1de384b61c5c03de5b6e9c23ebdde3263c78273e5335
+  metadata.gz: 2fb556df1f9e8f00edb81eb6fc6db4c0d86d7864dbaedda0a9e559625df7fe98
+  data.tar.gz: 69296b360896f5a2258884bc59dc26b115648b107242f8f877eecca507b3b371
 SHA512:
-  metadata.gz: 9ac8f0128cc6317a4772f9af81255382725250d33aaf2511e89a46de5a64170713106dce69cc730555c0c912ca517ba1fb713eab26edd0252a9f74985fdb2d1d
-  data.tar.gz: 1bdb201bddfee20018855b99f074e683d952f5f67e94f955d32d941f77594cec847baf4f95d630f7f678a64a7526266609c3a9fa27f4f01f68565522a17b8ac6
+  metadata.gz: 641237f09a349ea510b93a562d3548e8398409af64c58f03be21499ce42eee8053f0b2fa4d596befdb6ac035747ba761f3e6e494de5c317966554756c74921cc
+  data.tar.gz: b7100cb9cf8d8b016c4466409fd4a608d569f022e62e20a30bacf90031e65f7047fad2d7d3e758504db4fb64d732a072c4cbb1a8fef853a40e8588a4a17b0230

data/lib/doc_rspec/compiler.rb

@@ -30,15 +30,13 @@ class DocRSpec
     def compile_example(example_spec)
       # See comment above for an explanation why we capture
       # this method as a function into a closure
-      compile_example_line = method(:compile_example_line)
       example_group.it example_spec.it_name(path) do
         example = self
-        code_lines = example_spec
+        code = example_spec
           .lines
-          .map { compile_example_line.(it, example) }
-          .compact
+          .join("\n")
 
-        eval(code_lines.join("\n")) unless code_lines.empty?
+        eval(code) unless code.empty?
       end
     end
 

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

@@ -1,21 +1,23 @@
 # frozen_string_literal: true
 
 class DocRSpec
-  class Ast
+  class Context
     class Example
       attr_reader :lines, :lnb, :name
 
-      def add(op, lhs, rhs)
-        lines << [op, lhs, rhs].compact
+      def add(code)
+        lines << code
       end
 
       def it_name(path)
         "#{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(code)
+      examples.last.add(code)
+    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,21 @@
 # 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
-    EQUALS_OP = %r{\s+ => \s+}x
-    EXAMPLE_LINE = %r{\A \s* \#+ \s+ (.*)}x
+    CONTEXT_DEFINITION = %r{\A \s* \# \s ={1,7} \s (.*)}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
+    EXAMPLE_LINE = %r{\A \s* \# \s{4,} (.*)}x
+
+    SHORT_EQUALS = %r{\s eq\! \s}x
+    SHORT_MATCHES = %r{\s \= \~ \s}x
+    SHORT_PREDICATE = %r{\s is\! \s}x
+    START_EXAMPLE = %r{\A \s* \# \s{4,} \# \s example: \s (.*)}x
 
     attr_reader :ast, :lines, :state
 
@@ -24,26 +23,51 @@ 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]
+      return if code.empty?
 
-      case code.split(EQUALS_OP)
+      case code.split(SHORT_EQUALS)
       in [lhs, rhs]
-        ast.last.add_example_line(:eq, lhs, rhs)
+        ast.last.add_example_line("expect(#{lhs}).to eq(#{rhs})")
       else
-        ast.last.add_example_line(:verb, line.gsub(COMMENT, ''))
+        case code.split(SHORT_MATCHES)
+        in [lhs, rhs]
+          ast.last.add_example_line("expect(#{lhs}).to match(#{rhs})")
+        else
+          case code.split(SHORT_PREDICATE)
+          in [lhs, rhs]
+            ast.last.add_example_line("expect(#{lhs}).to be_#{rhs}")
+          else
+            ast.last.add_example_line(code)
+          end
+        end
       end
-
     end
 
     def parse_line(line, lnb)
@@ -51,45 +75,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.5'
+    VERSION = '0.2.1'
   end
 end
 # SPDX-License-Identifier: AGPL-3.0-or-later

data/lib/doc_rspec.rb

@@ -2,87 +2,88 @@
 
 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
+# = Code
 #
-# Install the gem `gem install doc_rspec` or put `doc_rspec` in your Gemfile
+# can be found [at Codeberg](https://codeberg.org/lab419/doc_rspec)
+#
+# = Usage
+#
+# 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
+#
+#   docspec '<path_to_file>'
+#
+# Where +path_to_file+ is relative to the +lib+ directory
+#
+# = Abstract
+#
+# Ruby Codeblocks that start with a comment line as follows
+#       # example: example_name
+#
+# are considered an +RSpec+ example of the +RSpec+ example group +doctest+ has been called.
+#
+# = RSpec Examples
+#
+# == Just plain old Ruby Code
+#
+#    # example: just an RSpec example
+#    expect(2*21).to eq(42)
+#
+# = Implementation Notice
+#
+#    # example: We have access to the wrapping context
 #
-# 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.
+#    this_is_available(22) eq! 44
 #
-# For each `rdoc` block an `ExampleGroup` is created and the lines
-# between  ` ```spec ` and ` ``` ` will be executed in the context
-# of one example.
+# This implies two thing
 #
-# ## Simplified exceptions in examples
+# - 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.
 #
-# ```spec
-#   41 + 1 => 42
-# ```
+# The context is taken from the last headline
+# == First Examples
 #
-# but can also fail (and therefore this example is not marked with `spec`)
+#     # example: equality
+#     expect(41 + 1).to eq(42)
 #
-# ```not-spec
-#  41 => 42
-# ```
+# == Shortcuts
 #
-# We have acces to the environment of the RSpec example
-# group we call `docspec` in.
+# In addition to _standard_ +RSpec+ code, one can use 3 shorthand forms that are compiled as follows
 #
-# ```spec
-#   this_is_available(21) => 42
-# ```
+# === +eq!+
 #
-# Morever we will adapt the `to eq` matcher to the `to match` matcher
-# if the expression right to `=>` evaluates to a `Regexp`.
+#     # example: eq! shorthand for eq
 #
-# ```spec
-#   DocRSpec::Version::VERSION => %r{\d+\.\d+\.\d+} 
-# ```
+#     answer = 42
 #
-# ## Just plain old RSpec...
+#     answer eq! 42
 #
-# is available for all lines that do not contain a `=>` string.
+# this was compiled to <tt>expect(answer).to eq(42)</tt>
 #
-# ```spec
-#   expect(42).to be > 41
-# ```
-# ## Naming Examples
+# === +=~+ for match
 #
-# Without naming examples the output when running a doctest with
-# `formatter=:doc` looks like this:
+#     # example: =~ shorthand for match
 #
-#     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)
+#     "alpha" =~ /\Aa.+a\z/
 #
-# We can improve on this by giving an example a name with the ` ```spec # <name>` syntax
+# === +is!+ for be_
 #
-# ```spec # fourtytwo is the answer
-#     the_answer = 42
-#     expect(42).to eq(the_answer)
-# ```
-# 
-# Now the output looks like:
+#     # example: =~ shorthand for be 
 #
-#     DocRSpec
-#       example from rdoc (doc_rspec.rb:21)
-#       ...
-#       fourtytwo is the answer (doc_rspec.rb:65)
+#     require 'ostruct'
+#     OpenStruct.new(ok?: true) is! ok
 #
 class DocRSpec
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: doc_rspec
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.2.1
 platform: ruby
 authors:
 - Robert Dober
@@ -37,25 +37,22 @@ 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: []
 extra_rdoc_files: []
 files:
-- ".rdoc_options"
 - 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: {}
@@ -73,7 +70,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.6.8
 specification_version: 4
-summary: '["Doc rspecs for Ruby"]'
+summary: '["Extract RSpec Examples from RDocs formatted with RDoc::Markup (the default)"]'
 test_files: []

data/.rdoc_options

@@ -1,27 +0,0 @@
----
-encoding: UTF-8
-static_path: []
-rdoc_include: []
-page_dir:
-apply_default_exclude: true
-autolink_excluded_words: []
-charset: UTF-8
-class_module_path_prefix:
-embed_mixins: false
-exclude: []
-file_path_prefix:
-hyperlink_all: false
-line_numbers: false
-locale_dir: locale
-locale_name:
-main_page:
-markup: markdown
-output_decoration: true
-show_hash: false
-skip_tests: true
-tab_width: 8
-template_stylesheets: []
-title:
-visibility: :protected
-warn_missing_rdoc_ref: true
-webcvs:

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