nandoc 0.0.1

data/lib/nandoc/spec-doc/mock-prompt.rb

@@ -0,0 +1,121 @@
+# @todo figure out how to get the symlink hack to work and avoid
+#   this nonsense all the while letting this be a valid requireable file
+require(File.expand_path('../../../nandoc.rb',__FILE__)) unless
+  Object.const_defined?('NanDoc')
+require(File.expand_path('../../spec-doc.rb',__FILE__)) unless
+  NanDoc.const_defined?('SpecDoc')
+require(File.dirname(__FILE__)+'/mini-test.rb') unless
+  NanDoc::SpecDoc.const_defined?('MiniTest')
+
+module NanDoc
+  class MockPrompt
+    #
+    # This is a bit of a misnomer.  it's actually just a wrapper
+    # around the real shell.  It's for testing.  SpecDoc.
+    # @todo - Move this class to under SpecDoc
+    #
+
+    include Treebis::Sopen2
+    include SpecDoc::AgentInstanceMethods
+
+
+    def initialize test_case=nil
+      @last_both = @last_out = @last_err = nil
+      @record = false
+      @test_case = test_case
+    end
+
+    # wrapper around FileUtils cd that takes block form
+    # the tail portion of the path if any that you want to go documented
+    # with SpecDoc is the second arg.  The first arg if any is the part
+    # of the path that will go undocumented.
+    def cd actual_basedir, specdoc_subdir=nil, &block
+      actual_path = File.join( * [actual_basedir, specdoc_subdir].compact)
+      if specdoc_subdir && @record
+        @recordings.add(:cd, specdoc_subdir)
+      end
+      FileUtils.cd(actual_path) do
+        block.call(self)
+      end
+      if specdoc_subdir && @record
+        @recordings.add(:cd_end)
+      end
+    end
+
+    def cosmetic_ellipsis str
+      @record && @recordings.add(:cosmetic_ellipsis, str)
+    end
+
+    def enter2 cmd
+      @last_both = nil
+      @record && @recordings.add(:command, cmd)
+      @last_out, @last_err = sopen2(cmd)
+    end
+
+    def err string, opts={}
+      exp = reindent string
+      assert_equal_strings exp, @last_err, opts
+    end
+
+    def note(*a,&b)
+      @record && @recordings.note(*a, &b)
+    end
+
+    def out string, opts={}
+      exp = reindent(string)
+      @record && @recordings.add(:out, exp)
+      assert_equal_strings exp, @last_out, opts
+    end
+
+    def out_begin exp_begin
+      @exp_begin = reindent(exp_begin)
+      @record && @recordings.add(:out_begin, @exp_begin)
+      # we don't do the assert until we get to (any?) end
+    end
+
+    def out_end exp_end, opts={}
+      @exp_begin or fail("no begin found for end")
+      exp_end2 = reindent(exp_end)
+      @record && @recordings.add(:out_end, exp_end2)
+      act_begin = @last_out[0..@exp_begin.length-1]
+      assert_equal_strings @exp_begin, act_begin, opts
+      act_end = @last_out[(exp_end2.length * -1)..-1]
+      assert_equal_strings exp_end2, act_end, opts
+    end
+
+    def record story_name=nil
+      method = method_name_to_record(caller)
+      @record = true
+      recordings
+      @recordings.add(:method, method)
+      @recordings.add(:story, story_name) if story_name
+    end
+
+    def record_stop
+      @record = false
+      @recordings = nil
+    end
+
+  private
+
+    def assert_equal_strings exp, act, opts
+      # @test_case.assert_equal exp, @last_out
+      @test_case.assert_no_diff exp, act, nil, opts
+    end
+
+    # this is different than the dozens of similar ones
+    def reindent str
+      these = str.scan(/^[\t ]*/).each.with_index.map
+      string, idx = these.min_by{ |x| x[0].length }
+      if string.length == 0 && str.index("\n") # exp
+        s2, _ =
+          these.reject{ |x| x[0].length == 0 }.min_by{ |x| x[0].length }
+        string = s2 if s2
+      end
+      re = /^#{Regexp.escape(string)}/
+      str.gsub(re, '')
+    end
+
+    attr_reader :test_case
+  end
+end

data/lib/nandoc/spec-doc/support-modules.rb

@@ -0,0 +1,158 @@
+module NanDoc
+  module SpecDoc
+    module AgentInstanceMethods
+      # share things between MockPrompt and TestCaseAgent
+
+      # we used to use first method, now we use first test_ method
+      def method_name_to_record caller
+        line = caller.detect{ |x| x =~ /in `test_/ } or fail('hack fail')
+        method = line =~ /in `(.+)'\Z/ && $1 or fail("hack fail")
+        method
+      end
+
+      def recordings
+        @recordings ||=  NanDoc::SpecDoc::Recordings.get(test_case)
+      end
+
+      def story story_name
+        method = method_name_to_record(caller)
+        rec = recordings
+        rec.add(:method, method)
+        rec.add(:story, story_name)
+        nil
+      end
+
+    end
+
+    class CodeSnippet
+      #
+      # internally this does deferred parsing of the thing
+      # a code snippet holds meta information (or maybe content)
+      # for record_ruby nandoc commands in tests.
+      #
+
+      def initialize matches_hash
+        @start_at = matches_hash
+        @stop_at = nil
+        @lines_proc = nil
+      end
+      attr_reader :start_at
+      %w(method line file).each do |meth|
+        sym = meth.to_sym
+        define_method(meth){ || @start_at[sym] }
+      end
+      def describe
+        last = method ? ":in `#{method}'" : ''
+        "#{file}:#{line}#{tail}"
+      end
+      # just hide all the lines from dumps to make irb debugging prettier
+      def file_lines
+        @lines_proc ||= begin
+          stop_at_assert    # not really appropriate here
+          same_file_assert  # not really appropriate here
+          all_lines = File.open(@start_at[:file],'r').lines.map # sure why not
+          proc{ all_lines }
+        end
+        @lines_proc.call
+      end
+      def line_start
+        @start_at[:line]
+      end
+      def line_stop
+        @stop_at[:line]
+      end
+      # @todo maybe get rid of this.  we interpolate inspects elsewhere
+      def ruby_string_raw
+        @ruby_string_raw ||= begin
+          these = all_lines[line_start..(line_stop-2)]
+          these.join('') # they have newlines already
+        end
+      end
+      def stop_at data=nil
+        data ? (@stop_at = data) : @stop_at
+      end
+    private
+      def same_file_assert
+        @stop_at[:file] == @start_at[:file] or fail("I want life to be"<<
+        " simple. start and stop files must be the same: "<<
+        ([@stop_at, @start_at].map{ |x| File.basename(x)}*' and '))
+      end
+      def stop_at_assert
+        stop_at or fail("no record_ruby_stop() found in method "<<
+        "after #{describe}")
+      end
+    end
+
+    module ParseTrace
+      #
+      # @return [Regexp] enhanced regex that parses a stack trace line
+      #
+      def parse_trace
+        @parse_trace_re ||= begin
+          re = /\A(.*):(\d+)(?::in `([^']+)')?\Z/
+          RegexpEnhance.names(re, :file, :line, :method)
+          re
+        end
+      end
+      def parse_trace_assert line
+        md = parse_trace.match(line) or
+          fail("couldn't parse trace line: #{line}")
+        h = md.to_hash
+        /\A\d+\Z/ =~ h[:line] or fail("not line: #{h[:line]}.inspect")
+        h[:line] = h[:line].to_i
+        h
+      end
+    end
+
+
+    class Recordings < Array
+      #
+      # everything that nandoc does during test runs gets written
+      # to one of these.  It's like a Sexp structure.
+      #
+
+
+      @for_test_case = {}
+
+      class << self
+        attr_accessor :for_test_case
+        def get test_case
+          @for_test_case[test_case.class] ||= new(test_case.class)
+        end
+        def report_test_case_not_found tc
+          msgs = ["no recordings found for #{tc}"]
+          msgs.join('  ')
+        end
+      end
+
+      def add name, *data
+        # this might change if we need to group by method name
+        push [name, *data]
+      end
+
+      def get_first_sexp_for_test_method meth
+        first = index([:method, meth]) or return nil
+        last = (first+1..length-1).detect do |i|
+          self[i].first == :method && self[i][1] != meth
+        end
+        last = last ? (last - 1) : (length - 1)
+        ret = self[first..last]
+        ret
+      end
+
+      def initialize test_case
+        @test_case = test_case
+      end
+
+      def note &block
+        push [:note, block]
+      end
+
+      def report_recording_not_found meth_name
+        "no recordings found for #{meth_name}"
+      end
+
+      attr_reader :test_case
+    end
+  end
+end

data/lib/nandoc/spec-doc/test-case-agent.rb

@@ -0,0 +1,57 @@
+module NanDoc::SpecDoc
+  class TestCaseAgent
+    include ParseTrace, AgentInstanceMethods, ::Treebis::Capture3
+    def initialize test_case
+      @test_case = test_case
+    end
+
+    # @param [block] gets called, and whatever is written to $stdout
+    #   will get asserted against whatever is in
+    # @param [String] exp.
+    # if it passes (or fails?) one of the strings is written to an
+    # :out node in the recording
+    # raises something if $stderr is written to.
+    #
+    # warning - blah blah @todo
+    #
+    #
+    def out exp, &block
+      trace = parse_trace_assert(caller.first)
+      out, err = capture3(&block)
+      fail("no: #{err.inspect}") unless err == ""
+      @test_case.assert_no_diff(exp, out)
+      if out == exp
+        recordings.add(:out, out, trace)
+      end
+      nil
+    end
+    def inspect mixed, exp_str = nil
+      act_str = mixed.inspect
+      line = caller.first
+      trace = parse_trace_assert(line)
+      if exp_str
+        @test_case.assert_no_diff(exp_str, act_str, "at #{line}")
+      end
+      recordings.add(:inspect, act_str, trace)
+    end
+    def record_ruby
+      md = parse_trace_assert(caller.first)
+      snip = CodeSnippet.new(md)
+      recordings.add(:method, snip.method)
+      recordings.add(:record_ruby, snip)
+      @last_snip = snip
+      nil
+    end
+    def record_ruby_stop
+      line = caller.first
+      md = parse_trace_assert(caller.first)
+      @last_snip or fail("no record_start in method before "<<
+      "record_stop at #{line}")
+      @last_snip.stop_at md
+    end
+  private
+    def recordings
+      Recordings.get(@test_case)
+    end
+  end
+end

data/lib/nandoc/spec-doc/test-framework-dispatcher.rb

@@ -0,0 +1,15 @@
+require File.dirname(__FILE__)+'/test-framework-proxy.rb'
+
+module NanDoc
+  module SpecDoc
+    class TestFrameworkDispatcher
+      def initialize gem_root
+        require File.dirname(__FILE__)+'/mini-test.rb'
+        @the_only_proxy = SpecDoc::MiniTest::Proxy.new(gem_root)
+      end
+      def get_sexp *a
+        @the_only_proxy.get_sexp(*a)
+      end
+    end
+  end
+end

data/lib/nandoc/spec-doc/test-framework-proxy.rb

@@ -0,0 +1,78 @@
+module NanDoc::SpecDoc
+  class TestFrameworkProxy
+    # abstract baseclass, an agent that runs tests
+
+    def initialize gem_root
+      @gem_root = gem_root
+    end
+
+    def get_sexp testfile, testname
+      TestFrameworkProxy.sexp_cache[testfile][testname] ||= begin
+        build_sexp testfile, testname
+      end
+    end
+
+    def build_sexp testfile, testname
+      load_file testfile
+      test_case, meth_name = find_test testname
+      run_test_case_method testfile, testname, test_case, meth_name
+      recs = ::NanDoc::SpecDoc::Recordings.for_test_case[test_case] or
+        fail(::NanDoc::SpecDoc::Recordings.
+                               report_test_case_not_found(test_case))
+      sexp = recs.get_first_sexp_for_test_method(meth_name) or
+        fail recs.report_recording_not_found(meth_name)
+      sexp
+    end
+
+    @sexp_cache = Hash.new{ |h,k| h[k] = {} }
+    class << self
+      attr_reader :sexp_cache
+    end
+
+  protected
+
+    #
+    # the stream to write to when things like a specdoc test run fails
+    #
+    def err
+      $stderr
+    end
+
+    def handle_failed_tests runner, testfile, testname
+      err.print "can't SpecDoc. at least one test failed when trying to run"
+      err.puts " #{testfile.inspect} #{testname.inspect} - "
+      runner.report.each do |line|
+        err.puts line
+      end
+      err.puts "Please get your tests green and re-run."
+      exit(1);
+    end
+
+    def load_file testfile
+      path = testdir + '/' + testfile
+      fail("test file not found: #{path.inspect}") unless File.file?(path)
+      # if you need to, do a diff
+      require path
+    end
+
+    #
+    # default way to read what the test run wrote to stdout
+    #
+    def testout_str
+      @testout.rewind
+      @testout.read
+    end
+
+    #
+    # default way to deduce the root directory that holds the tests
+    #
+    def testdir
+      @testdir ||= begin
+        tries = [@gem_root+'/test', @gem_root+'/spec']
+        found = tries.detect{ |path| File.directory?(path) }
+        fail("Couldn't find test dir for gem at (#{tries*', '})") unless found
+        found
+      end
+    end
+  end
+end

data/lib/nandoc/spec-doc.rb

@@ -0,0 +1,46 @@
+# little hack to a) let clients just include this file for test runs
+# and b) allow us to do the symlink hack for developing this.
+unless Object.const_defined?('NanDoc')
+  require File.expand_path('../../nandoc.rb', __FILE__)
+end
+
+me = File.dirname(__FILE__)+'/spec-doc'
+require me + '/support-modules.rb'
+require me + '/test-case-agent.rb'
+require me + '/test-framework-dispatcher.rb'
+
+module NanDoc
+  module SpecDoc
+    class << self
+
+      #
+      # enhance a test framework spec or test case module
+      # for e.g. a minitest spec class.
+      #
+      def include_to mod
+        if Object.const_defined?('MiniTest') &&
+            mod.ancestors.include?(::MiniTest::Spec)
+          require File.dirname(__FILE__)+'/spec-doc/mini-test.rb'
+          ::NanDoc::SpecDoc::MiniTest::SpecInstanceMethods.include_to mod
+        else
+          fail("don't know how to enhance test module: #{mod}")
+        end
+      end
+    end
+
+    def initialize gem_root
+      @sexp_cache = Hash.new{|h,k| h[k] = {}}
+      @test_framework_dispatcher = TestFrameworkDispatcher.new(gem_root)
+    end
+
+    #
+    # only run any test method at most once, just to keep recordings clean
+    #
+    def get_sexp testfile, testname
+      sexp = @sexp_cache[testfile][testname] ||= begin
+        @test_framework_dispatcher.get_sexp testfile, testname
+      end
+      sexp
+    end
+  end
+end

data/lib/nandoc/support/diff-proxy.rb

@@ -0,0 +1,113 @@
+module NanDoc
+  module DiffProxy
+    include Treebis::Sopen2
+    extend self
+    def diff path_a, path_b, opts={}
+      fail('no') unless File.exist?(path_a) && File.exist?(path_b)
+      rel_to = opts.delete(:relative_to)
+      path_a, path_b = relativize(rel_to, path_a, path_b) if rel_to
+      opts = {'--unified=3'=>nil, '--recursive'=>nil}.merge(opts)
+      args = ['diff'] + opts.each.map.flatten.compact + [path_a, path_b]
+      out = err = nil
+      block = proc do
+        out, err = sopen2(*args)
+      end
+      if rel_to
+        FileUtils.cd(rel_to, :verbose=>true, &block)
+      else
+        block.call
+      end
+      diff = Diff.new(out, err, args)
+      if diff.error?
+        return fail(diff.full_error_message){|f| f.diff = diff }
+      end
+      diff
+    end
+  private
+    def fail(*a, &b)
+      raise Fail.new(*a, &b)
+    end
+    def relativize base, path_a, path_b
+      fail("KISS") unless [0,0]==[path_a, path_b].map{|x| x.index(base)}
+      tail_a, tail_b = [path_a, path_b].map{|x| '.'+x[base.length..-1]}
+      [tail_a, tail_b]
+    end
+    class Diff
+      class << self
+        def default_diff_stylesheet
+          @default_diff_stylesheet ||= {
+            :header => [:bold, :yellow],
+            :add    => [:bold, :green],
+            :remove => [:bold, :red],
+            :range  => [:bold, :magenta],
+            :trailing_whitespace => [:background, :red]
+          }
+        end
+        def stream_colorizer_prototype
+          @stream_colorizer_prototype ||= begin
+            require File.dirname(__FILE__)+'/stream-colorizer.rb'
+            NanDoc::StreamColorizer.new do |sc|
+              sc.stylesheet_merge(default_diff_stylesheet)
+              sc.when %r(\Adiff ), :state=>:header
+              sc.when(:header) do |o|
+                o.style :header
+                o.when %r(\A@@), :state=>:range
+              end
+              sc.when(:range) do |o|
+                o.style :range
+                o.when_not %r(\A@@), :state=>:plain
+              end
+              sc.when(:plain) do |o|
+                o.style nil
+                o.when %r(\Adiff ), :state=>:header
+                o.when %r(\A\+), :state=>:add
+                o.when %r(\A\-), :state=>:remove
+              end
+              sc.when(:add) do |o|
+                o.style :add
+                o.trailing_whitespace_style :trailing_whitespace
+                o.when_not %r(\A\+), :state=>:plain
+              end
+              sc.when(:remove) do |o|
+                o.style :remove
+                o.trailing_whitespace_style :trailing_whitespace
+                o.when_not %r(\A\-), :state=>:plain
+              end
+            end
+          end
+        end
+      end
+      def initialize out, err, args
+        @out = out
+        @error = err
+        @args = args
+      end
+      attr_reader :error
+      def command
+        Shellwords.join(@args)
+      end
+      def error?; ! @error.empty? end
+      def full_error_message
+        "diff failed: #{command}\ngot error: #{error}"
+      end
+      def ok?; ! error? end
+      def to_s
+        @out
+      end
+      def colorize out, opts={}
+        colorizer = self.class.stream_colorizer_prototype.spawn do |c|
+          c.stylesheet_merge(opts[:styles] || {})
+        end
+        colorizer.filter(to_s, out)
+        nil
+      end
+    end
+    class Fail < RuntimeError;
+      def initialize(*a,&b)
+        super(*a)
+        yield self if block_given?
+      end
+      attr_accessor :diff
+    end
+  end
+end

data/lib/nandoc/support/orphanage.rb

@@ -0,0 +1,77 @@
+module NanDoc
+  class DataSource # reopen, not really necessary
+    class Orphanage
+      #
+      # @api private implementation for experimental orphan_rescue()
+      #
+      include ItemMethods
+      class << self
+        def rescue_orphans config, items
+          new(config, items).rescue_orphans
+        end
+        private :new
+      end
+
+      def rescue_orphans
+        fail("must have site root to continue hacking") unless site_root
+        items = @items.map # we are going to add to it in loop below
+        items.each do |item|
+          next unless is_orphan? item
+          id = item.identifier
+          parent_id = parent_identifier(id)
+          bare_root = identifier_bare_rootname_assert(id)
+          bare_parent = slash_strip_assert(parent_id)
+          new_id = nil
+          @renamer = nil
+          if @basenames.include?(bare_root)
+            # then we need to hack a rename to the identifier
+            @renamer = /\A\/#{Regexp.escape(bare_root)}\/(.+)\Z/
+            new_id = rename(id)
+          end
+          if (!new_id || bare_parent!=bare_root) && is_orphan?(item, new_id)
+            make_surrogate_parent parent_id
+          end
+          item.identifier = new_id if new_id
+        end
+      end
+    private
+      def initialize config, items
+        @basenames = config[:source_file_basenames] || []
+        @items = items
+      end
+
+      def is_orphan? item, using_identifier=nil
+        item.nandoc_content_leaf? or return false
+        using_identifier ||= item.identifier
+        parent = find_parent using_identifier
+        parent.nil? && using_identifier != '/'
+      end
+
+      def make_surrogate_parent parent_id
+        use_id = @renamer ? rename(parent_id) : parent_id
+        use_path = @renamer ? "../#{parent_id}" : parent_id
+        content = surrogate_content
+        fake_parent = Nanoc3::Item.new(
+          content,
+          {:filename => use_path, :content_filename => use_path },
+          use_id
+        )
+        @items.unshift(fake_parent)
+      end
+
+      # very private
+      def rename str
+        @renamer =~ str or
+          fail("rename fail: #{str.inspect} against #{@renamer}")
+        renamed = "/#{$1}"
+        renamed
+      end
+
+      def surrogate_content
+        @surrogate_content ||= begin
+          File.read(NanDoc::Config.orphan_surrogate_filename)
+        end
+      end
+    end
+  end
+end