speculate_about 0.2.3 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a3d2e27062babfecbf03e34c59b76b495cbb1a9f27d3cbd0f4b23501d3be9181
-  data.tar.gz: bdde751f7fa2c532dc95551f06ecc22f44fba32ad0f70103371e1743f62ca347
+  metadata.gz: b7194ffffa00a4292176dafa4120ea24ddf47e8aa6b6ed04d8be2dfaeefcfb8b
+  data.tar.gz: bb6b85091a5c9c59465f7df1f2369f33aa6e3090c249ee4cdc9184a9ef1580e3
 SHA512:
-  metadata.gz: 95b2fd95e73b0b95d8c9237200bdb86c198f8584987d1f0a54968b742b46c1a06ffff29eb6352962a14e54c9d9d7e047a02f98c57b78a8894fc5c14a4f941d8c
-  data.tar.gz: bc56ce52b6e4bc87fbff62c5fb5583ad6fe683b4dd78e18bc8b6d6da28bfbdedf46d3397e297c70878dff8633e3c8c0aa15cb89c871d01ff3c84a8c32c3ccf12
+  metadata.gz: 2e88641b31f6adf08b14730b619fbc31828f4d04b8058946cb1b9b71d7cecf05695d9d1b59849184b31220d88d7fd0d821e0b318f24cc68d803ed303cb792b97
+  data.tar.gz: 7de92ee9f101df89939eea6b8c0b42513d88222bbef60fa51fe2a9413add66e50b5f1da0ca7ff46d7ca02811b31be7ceb925c45509a3ad8c5dabb82fcc28f5e0

data/bin/speculate

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+require_relative '../lib/speculations/cli'
+
+Speculations::CLI.run(ARGV)

data/lib/speculations.rb

@@ -1,2 +1,29 @@
-module Speculations
+require 'fileutils'
+require_relative 'speculations/parser'
+module Speculations extend self
+
+  def compile(infile, outfile=nil)
+    raise ArgumentError, "#{infile} not found" unless File.readable? infile
+    outfile ||= _speculation_path(infile)
+    if _out_of_date?(outfile, infile)
+      ast  = Speculations::Parser.new.parse_from_file(infile)
+      File.write(outfile, ast.to_code.join("\n"))
+    end
+    outfile
+  end
+
+  private
+
+  def _out_of_date?(outf, inf)
+    return true unless File.exists? outf
+    return File.lstat(outf).mtime <= File.lstat(inf).mtime
+  end
+
+  def _speculation_path(file)
+    dir = File.dirname(file)
+    dest_dir = File.join("spec", "speculations", dir)
+    FileUtils.mkdir_p(dest_dir) unless File.directory?(dest_dir)
+    rspec = File.basename(file, ".md")
+    File.join(dest_dir, "#{rspec}_spec.rb")
+  end
 end

data/lib/speculations/cli.rb

@@ -0,0 +1,49 @@
+
+module Speculations
+  module CLI extend self
+    def run args
+      loop do
+      case args.first
+        when "-h", "--help"
+          _usage
+        when "-v", "--version"
+          _version
+        else
+          return _compile_and_maybe_run args
+        end
+      end
+    end
+
+    private
+
+    def _compile_and_maybe_run args
+      require_relative "../speculations"
+      args = Dir.glob(["*.md", "speculations/**/*.md"]) if args.empty?
+        args.each do |input_file|
+          Speculations.compile(input_file)
+        end
+    end
+
+    def _usage
+      puts <<-EOF
+      usage:
+        #{$0} [options] [filenames]
+
+        options:
+          -h | --help display this exit with -1
+          -v | --version display version of the speculate_about gem exit with -2
+
+        filenames (default to all markdown files in the project directory and its speculations subdirectories)
+
+        recreate outdated speculations in `spec/speculations/` 
+      EOF
+      exit -1
+    end
+
+    def _version
+      require_relative 'version'
+      puts VERSION
+      exit -2
+    end
+  end
+end

data/lib/speculations/parser.rb

@@ -1,40 +1,39 @@
-require_relative '../speculations'
-class Speculations::Parser
-  require_relative './parser/context'
-  require_relative './parser/state'
+module Speculations
+  class Parser
+    require_relative './parser/context'
+    require_relative './parser/state'
 
-  attr_reader :filename, :input, :orig_filename, :root, :state
 
-  def self.parsers
-     @__parsers__ ||= {
-       bef: State::Bef,
-       exa: State::Exa,
-       inc: State::Inc,
-       out: State::Out
-     }
-  end
+    def self.parsers
+      @__parsers__ ||= {
+        candidate: State::Candidate,
+        in: State::In,
+        out: State::Out
+      }
+    end
 
-  def parse_from_file file, orig_filename = nil
-    @filename = file
-    @orig_filename = orig_filename || file
-    @input = File
-      .new(file)
-      .each_line(chomp: true)
-      .lazy
-    parse!
-  end
+    def parse_from_file file
+      @filename = file
+      @input = File
+        .new(file)
+        .each_line(chomp: true)
+        .lazy
+      parse!
+    end
 
-  private
+    private
 
-  def initialize
-    @state = :out
-  end
+    def initialize
+      @state = :out
+    end
 
-  def parse!
-    root = node = Context.new(name: "Speculations from #{@filename}", lnb: 0, filename: @filename, orig_filename: orig_filename, parent: nil)
-    input.each_with_index do |line, lnb|
-      @state, node = self.class.parsers.fetch(@state).parse(line, lnb.succ, node)
+    def parse!
+      root = node = Context.new(filename: @filename)
+      ctxt = nil
+      @input.each_with_index do |line, lnb|
+        @state, node, ctxt = self.class.parsers.fetch(@state).parse(line, lnb.succ, node, ctxt)
+      end
+      root
     end
-    root
   end
 end

data/lib/speculations/parser/context.rb

@@ -1,90 +1,129 @@
-class Speculations::Parser::Context
-  require_relative './context/include'
-  require_relative './context/example'
-  require_relative './context/setup'
-
-  attr_reader :filename, :level, :lnb, :name, :orig_filename, :parent, :potential_name, :setup
-
-  def add_child(name:, lnb:)
-    raise "Illegal nesting" if parent
-    children << self.class.new(name: name, lnb: lnb, parent: self)
-    children.last
-  end
-
-  def add_example(lnb:, line:)
-    examples << Example.new(lnb: lnb, parent: self, line: line, name: potential_name)
-    @potential_name = nil
-    examples.last
-  end
-
-  def add_include(lnb:)
-    includes << Include.new(lnb: lnb, parent: self)
-    includes.last
-  end
-
-  def children
-     @__children__ ||= []
-  end
-
-  def examples
-     @__examples__ ||= []
-  end
-
-  def includes
-     @__includes__ ||= []
-  end
-
-  def map_lines(*lines, indent: 0)
-    prefix = "  " * (level + indent)
-    lines.flatten.map{ |line| "#{prefix}#{line.strip}" }.join("\n")
-  end
-
-  def set_name(potential_name)
-    @potential_name = potential_name
-  end
-
-  def set_setup(lnb:)
-    @setup = Setup.new(lnb: lnb, parent: self)
-  end
-
-  def to_code
-    [
-      _header,
-      includes.map(&:to_code),
-      setup&.to_code,
-      examples.map(&:to_code),
-      children.map(&:to_code),
-      _footer
-    ].flatten.compact.join("\n")
-  end
-  
-  private
-
-  def initialize(lnb:, name:, filename: nil, orig_filename: nil, parent: nil)
-    _init_from_parent filename, orig_filename, parent
-    @level         = parent ? parent.level.succ : 1
-    @lnb           = lnb
-    @setup         = nil
-    @name          = name
-    @parent        = parent
-  end
-
-  def _header
-    map_lines(%{context "#{name}" do}, indent: -1)
+module Speculations
+  class Parser
+    class Context
+      require_relative './context/include'
+      require_relative './context/example'
+
+      DISCLAIMER = <<-EOD
+# DO NOT EDIT!!!
+# This file was generated from FILENAME with the speculate_about gem, if you modify this file
+# one of two bad things will happen
+# - your documentation specs are not correct
+# - your modifications will be overwritten by the speculate rake task
+# YOU HAVE BEEN WARNED
+      EOD
+
+      attr_reader :filename, :level, :lnb, :title, :parent, :root, :tree_level
+
+      def new_context(title:, lnb:, level: )
+        new_child = self.class.new(title: title, lnb: lnb, parent: self, level: level)
+        _realign_levels(new_child)
+      end
+
+      def new_example(lnb:, title:)
+        examples << Example.new(lnb: lnb, parent: self, title: title)
+        examples.last
+      end
+
+      def new_include(lnb:)
+        includes << Include.new(lnb: lnb, parent: self)
+        includes.last
+      end
+
+      def parent_of_level needed_min_level
+        # I would love to write
+        # self.enum_by(:parent).find{ |ctxt| ctxt.level <= needed_min_level }
+        current = self
+        while current.level > needed_min_level
+          current = current.parent
+        end
+        current
+      end
+
+      def children
+        @__children__ ||= []
+      end
+
+      def examples
+        @__examples__ ||= []
+      end
+
+      def includes
+        @__includes__ ||= []
+      end
+
+      def map_lines(*lines, indent: 0)
+        prefix = "  " * (tree_level + indent).succ
+        lines.flatten.map{ |line| "#{prefix}#{line.strip}" }
+      end
+
+      def to_code
+        [
+          _header,
+          includes.map(&:to_code),
+          examples.map(&:to_code),
+          children.map(&:to_code),
+          _footer
+        ].flatten.compact
+      end
+
+      def with_new_parent new_parent
+        @parent = new_parent
+        @tree_level += 1
+        self
+      end
+
+
+      private
+
+      def initialize(lnb: 0, title: nil, filename: nil, parent: nil, level: 0)
+        @filename = filename
+        @level    = level
+        @lnb      = lnb
+        @title    = title
+        @parent   = parent
+        if parent
+          _init_from_parent
+        else
+          @root = self
+          @tree_level  = 0
+        end
+      end
+
+      def _header
+        if parent
+          map_lines(%{# #{filename}:#{lnb}}, %{context "#{title}" do}, indent: -1)
+        else
+          _root_header
+        end
+      end
+
+      def _root_header
+        map_lines(DISCLAIMER.gsub("FILENAME", filename.inspect).split("\n"), %{RSpec.describe #{filename.inspect} do}, indent: -1)
+      end
+
+      def _init_from_parent
+        @root = parent.root
+        @filename = parent.filename
+        @tree_level = parent.tree_level.succ
+      end
+
+      def _footer
+        map_lines("end", indent: -1)
+      end
+
+      def _realign_levels new_parent
+        if children.empty? || children.first.level == new_parent.level
+          children << new_parent
+          return new_parent
+        end
+        children.each do |child|
+          new_parent.children << child.with_new_parent(new_parent)
+        end
+        @__children__ = [new_parent]
+        new_parent
+      end
+
+    end
   end
-
-  def _init_from_parent filename, orig_filename, parent
-    _set_filename filename, orig_filename, parent
-    @orig_filename = parent ? parent.orig_filename : orig_filename
-  end
-
-  def _set_filename filename, orig_filename, parent
-    @filename = parent ? parent.filename : filename
-    raise ArgumentError, "no filename given in root context" unless @filename
-  end
-
-  def _footer
-    map_lines("end", indent: -1)
-  end
-
 end

data/lib/speculations/parser/context/example.rb

@@ -1,8 +1,7 @@
 class Speculations::Parser::Context::Example
 
-  attr_reader :lnb, :name, :parent
+  attr_reader :lnb, :title, :parent
 
-  NAMED_EXAMPLE = %r{\A[`~]{3,}ruby\s+:example\s+(.*)}
 
   def add_line line
     lines << line
@@ -15,34 +14,24 @@ class Speculations::Parser::Context::Example
 
   def to_code
     parent.map_lines(_example_head) +
-      "\n" +
       parent.map_lines(lines, indent: 1) +
-      "\n" +
       parent.map_lines("end")
   end
 
 
   private
 
-  def initialize(lnb:, line:, parent:, name: nil)
+  def initialize(lnb:, parent:, title:)
     @lnb    = lnb
     @parent = parent
-    @name   = _compute_name(lnb: lnb, line: line, parent: parent, name: name)
+    @title  = _compute_title(title)
   end
 
-  def _compute_name(lnb:, parent:, line:, name:)
-    _, name1 = NAMED_EXAMPLE.match(line).to_a
-    
-    if name1&.empty? == false # SIC
-      "#{name1} (#{parent.orig_filename}:#{lnb.succ})"
-    elsif name
-      "#{name} (#{parent.orig_filename}:#{lnb.succ})"
-    else
-      "Example from #{parent.orig_filename}:#{lnb.succ}"
-    end
+  def _compute_title(title)
+    "#{title} (#{parent.root.filename}:#{lnb})"
   end
 
   def _example_head
-    %{it "#{name}" do}
+    %{it "#{title}" do}
   end
 end

data/lib/speculations/parser/context/include.rb

@@ -12,7 +12,7 @@ class Speculations::Parser::Context::Include
   end
 
   def to_code
-    parent.map_lines(lines)
+    parent.map_lines("# #{parent.filename}:#{lnb}", lines)
   end
 
   private

data/lib/speculations/parser/state.rb

@@ -1,39 +1,8 @@
 module Speculations::Parser::State extend self
-  require_relative './state/bef'
-  require_relative './state/exa'
-  require_relative './state/inc'
+  require_relative './state/candidate'
+  require_relative './state/in'
   require_relative './state/out'
+  require_relative './state/triggers'
 
-  BEFORE_RGX  = %r[\A\s{0,3}```.*\s:before]
-  CONTEXT_RGX = %r[\A\s{0,3}\#{1,7}\s+Context\s+(.*)]
-  EOBLOCK_RGX = %r[\A\s{0,3}```\s*\z]
-  EXAMPLE_RGX = %r[\A\s{0,3}```.*\s:example]
-  INCLUDE_RGX = %r[\A\s{0,3}```.*\s:include]
-  NAME_RGX    = %r[\A\s{0,3}Example:\s+(.*)]
-
-  def before_match line
-    BEFORE_RGX =~ line
-  end
-
-  def context_match line
-    if match = CONTEXT_RGX.match(line)
-      match.captures.first
-    end
-  end
-
-  def eoblock_match line
-    EOBLOCK_RGX =~ line
-  end
-
-  def example_match line
-    EXAMPLE_RGX =~ line
-  end
-
-  def include_match line
-    INCLUDE_RGX =~ line
-  end
-
-  def potential_name line
-    NAME_RGX.match(line)
-  end
+  extend Triggers
 end

data/lib/speculations/parser/state/candidate.rb

@@ -0,0 +1,32 @@
+module Speculations
+  class Parser
+    module State
+      module Candidate extend self
+        def parse line, lnb, node, ctxt
+          case
+          when State.blank_line(line)
+            [:candidate, node, ctxt]
+          when match = State.context_match(line)
+            level = match[1].size
+            new_parent = node.parent_of_level(level.pred)
+            node = new_parent.new_context(title: match[2], lnb: lnb, level: level)
+            [:out, node]
+          when match = State.maybe_example(line)
+            [:candidate, node, match[:title]]
+          when match = State.maybe_include(line)
+            [:candidate, node, :inc]
+          when match = State.ruby_code_block(line)
+            if ctxt == :inc
+              node = node.new_include(lnb: lnb)
+            else
+              node = node.new_example(title: ctxt, lnb: lnb)
+            end
+            [:in, node]
+          else
+            [:out, node]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/speculations/parser/state/{inc.rb → in.rb}

@@ -1,14 +1,14 @@
 module Speculations
   class Parser
     module State
-      module Inc extend self
+      module In extend self
 
-        def parse line, _lnb, node
+        def parse line, _lnb, node, ctxt
           case
           when State.eoblock_match(line)
             [:out, node.parent]
           else
-            [:inc, node.add_line(line)]
+            [:in, node.add_line(line)]
           end
         end
       end

data/lib/speculations/parser/state/out.rb

@@ -3,29 +3,28 @@ module Speculations
     module State
       module Out extend self
 
-        def parse line, lnb, node
+        def parse line, lnb, node, _ctxt
           case
-          when name = State.context_match(line)
-            node = node.parent if node.parent
-            new_node = node.add_child(name: name, lnb: lnb)
-            [:out, new_node]
-          when State.before_match(line)
-            node = node.set_setup(lnb: lnb)
-            [:bef, node]
-          when State.example_match(line)
-            node = node.add_example(lnb: lnb, line: line)
-            [:exa, node]
-          when State.include_match(line)
-            node = node.add_include(lnb: lnb)
-            [:inc, node]
-          when name = State.potential_name(line)
-            node.set_name(name[1])
-            [:out, node]
+          when match = State.context_match(line)
+            make_new_context(lnb: lnb, node: node, match: match)
+          when match = State.maybe_example(line)
+            [:candidate, node, match[:title]]
+          when match = State.maybe_include(line)
+            [:candidate, node, :inc]
           else
             [:out, node]
           end
         end
 
+        private
+
+        def make_new_context(lnb:, match:, node:)
+          level = match[:level].size
+          new_parent = node.parent_of_level(level.pred)
+          node = new_parent.new_context(title: match[:title], lnb: lnb, level: level)
+          [:out, node]
+        end
+
       end
     end
   end

data/lib/speculations/parser/state/triggers.rb

@@ -0,0 +1,35 @@
+module Speculations::Parser::State::Triggers
+
+  BLANK_RGX   = %r{\A\s*\z}
+  CONTEXT_RGX = %r[\A\s{0,3}(?<level>\#{1,7})\s+Context:?\s+(?<title>.*)]
+  EOBLOCK_RGX = %r[\A\s{0,3}```\s*\z]
+  GIVEN_RGX   = %r[\A\s{0,3}(?:Given|When)\b]
+  EXAMPLE_RGX = %r[\A\s{0,3}Example:?\s+(<?title>.*)]
+  RUBY_RGX    = %r[\A\s{0,3}```ruby]
+  THEN_RGX    = %r[\A\s{0,3}(?:Then|But|And|Also)\b\s*(?<title>.*)]
+
+  def blank_line line
+    BLANK_RGX.match(line)
+  end
+
+  def context_match line
+    CONTEXT_RGX.match(line)
+  end
+
+  def eoblock_match line
+    EOBLOCK_RGX.match(line)
+  end
+
+  def maybe_example line
+    EXAMPLE_RGX.match(line) ||
+      THEN_RGX.match(line)
+  end
+
+  def maybe_include line
+    GIVEN_RGX.match(line)
+  end
+
+  def ruby_code_block line
+    RUBY_RGX.match(line)
+  end
+end

data/lib/speculations/version.rb

@@ -1,3 +1,3 @@
-module SpeculateAbout
-  VERSION = "0.2.3"
+module Speculations
+  VERSION = "0.5.0"
 end

metadata

@@ -1,54 +1,69 @@
 --- !ruby/object:Gem::Specification
 name: speculate_about
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.5.0
 platform: ruby
 authors:
 - Robert Dober
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-11-12 00:00:00.000000000 Z
+date: 2021-01-01 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.9'
+        version: '3.10'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.9'
+        version: '3.10'
 description: Allows Markdown or other text files to be used as literal specs, à la
   Elixr doctest, but from any file.
 email: robert.dober@gmail.com
-executables: []
+executables:
+- speculate
 extensions: []
 extra_rdoc_files: []
 files:
-- lib/speculate_about.rb
+- bin/speculate
 - lib/speculations.rb
+- lib/speculations/cli.rb
 - lib/speculations/parser.rb
 - lib/speculations/parser/context.rb
 - lib/speculations/parser/context/example.rb
 - lib/speculations/parser/context/include.rb
-- lib/speculations/parser/context/setup.rb
 - lib/speculations/parser/state.rb
-- lib/speculations/parser/state/bef.rb
-- lib/speculations/parser/state/exa.rb
-- lib/speculations/parser/state/inc.rb
+- lib/speculations/parser/state/candidate.rb
+- lib/speculations/parser/state/in.rb
 - lib/speculations/parser/state/out.rb
+- lib/speculations/parser/state/triggers.rb
 - lib/speculations/version.rb
 homepage: https://github.com/robertdober/speculate
 licenses:
 - Apache-2.0
 metadata: {}
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -63,8 +78,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
-signing_key:
+rubygems_version: 3.2.3
+signing_key: 
 specification_version: 4
 summary: Extract RSpecs from Markdown
 test_files: []

data/lib/speculate_about.rb

@@ -1,45 +0,0 @@
-require 'rspec'
-
-require 'speculations/parser'
-
-module SpeculateAbout
-  def speculate_about file
-    paths = _find_files(file, File.dirname( caller.first ))
-    raise ArgumentError, "no files found for pattern #{file}" if paths.empty?
-    paths.each do |path|
-      code = _compile path, _readable(path) 
-      ENV["SPECULATE_ABOUT_DEBUG"] ? _show(code, path) : instance_eval(code, path)
-    end
-  end
-
-
-  private
-
-  def _compile path, file
-    ast  = Speculations::Parser.new.parse_from_file(path, file)
-    ast.to_code
-  end
-  def _readable(path)
-    d = File.dirname(path)
-    File.join(File.basename(d), File.basename(path))
-  end
-  def _find_files file, local_path
-    [Dir.pwd, local_path]
-      .flat_map do |dir|
-        Dir.glob(File.join(dir, file))
-    end
-  end
-  def _show(code, path)
-     message = "Generated code for #{path}"
-     _underline(message)
-     puts code
-  end
-  def _underline(message, ul: "=")
-    puts message
-    puts message.gsub(/./, ul)
-  end
-end
-
-RSpec.configure do |conf|
-  conf.extend SpeculateAbout
-end

data/lib/speculations/parser/context/setup.rb

@@ -1,28 +0,0 @@
-class Speculations::Parser::Context::Setup
-
-  attr_reader :lnb, :parent
-
-  def add_line line
-    lines << line
-    self
-  end
-
-  def lines
-     @__lines__ ||= []
-  end
-
-  def to_code
-    parent.map_lines("before do") + 
-      "\n" +
-      parent.map_lines(lines, indent: 1) +
-      "\n" +
-      parent.map_lines("end")
-  end
-
-
-  private
-
-  def initialize(lnb:, parent:)
-    @parent = parent
-  end
-end

data/lib/speculations/parser/state/bef.rb

@@ -1,17 +0,0 @@
-module Speculations
-  class Parser
-    module State
-      module Bef extend self
-
-        def parse line, _lnb, node
-          case
-          when State.eoblock_match(line)
-            [:out, node.parent]
-          else
-            [:bef, node.add_line(line)]
-          end
-        end
-      end
-    end
-  end
-end

data/lib/speculations/parser/state/exa.rb

@@ -1,17 +0,0 @@
-module Speculations
-  class Parser
-    module State
-      module Exa extend self
-
-        def parse line, _lnb, node
-          case
-          when State.eoblock_match(line)
-            [:out, node.parent]
-          else
-            [:exa, node.add_line(line)]
-          end
-        end
-      end
-    end
-  end
-end