nandoc 0.0.3 → 0.0.4

data/lib/nandoc/doc/hack-free-zone-defined.md

@@ -0,0 +1,33 @@
+## hack free zones defined
+
+the intended audience of this document is developers of nanDoc.
+
+out of necessity parts of this project are hack-ful zone. but parts of it are designated hack-free.  Following is a definition of what it means to be hack-free.
+
+these guidelines are to encourage consistency, clarity of intent (self-documenting code), and code that is susceptible to being refactored (agile) with the least hassle.
+
+(in the below as in ruby a `class` is a `module`, so 'module' also refers to class.)
+
+a 'hack free zone' is:
+
+  * no opening up of other people's gem classes.  this also applies to Stdlib and Corelib! (except special cases for testing.)
+  * no being inside of other people's gem modules unless necessitated by their api
+  * module dependencies SHOULD be cited appropriately when not explicit from requires at the top of the file
+  * no policy yet on circular dependencies, but if we can avoid them, MUST not reopen classes, *or reopening of modules*, except to add modules.
+  * each module MUST be defined in a file named after the module with one exception[^1]. a corollary of this is and the above is that at most one module can be defined in a file.  [^1]:The one exception to this is class-private classes or modules.
+  * module hierarchy MUST be reflected in folder hierarchy
+  * however, folder hierarchy CAN be semantic (logical groupings) and doesn't have to follow module hierarchy exactly, but must fall within it:
+    * so, the module tree MUST fit cleanly inside the filesystem tree, while the opposite is not necessarily true
+    * for example, NanDoc::StringMethods could be pulled in by `require 'nandoc/support/string-methods.rb`' but each component of the full constant name must appear in the path.
+  * a module 1) SHOULD first have at least one line of documentation comment, 2) MUST then have any includes or `extend`s 3) MUST then open up the class or module's singleton class if necesssary to define any class or module methods 4) SHOULD list method definitions in alphabetical order (exception intialize with MUST (5) come at the top.)
+  * every file is a leaf file or a branch file.  which it is is not discernible from looking at the filename.
+    * branch files are files whose sole purpose include other files (primarily) that are children of a folder sibling to that file which shares the same name as that file without the '*.rb' extension.
+    * any require statements MUST occur as the first lines in a file, unless the point below
+    * if a module depends on another module:
+      * if the dependee is above and/or outside and around, just include it with rubygems-style "require 'nandoc/foo/bar'".  If you don't and you instead reach up with File.expand_path(..) then a child node in the filestem tree cannot as easily move around because it is coupled with parent, uncle, or cousin node structure.
+      * use the "require File.dirname(__FILE__)"-style of include only for files that require files below them.
+      * modules that require other modules SHOULD require the files for those other modules _in situ_, and not rely on a parent branch-node file having knowledge of the child module's dependencies. exceptions for a branch file that can require module files that many child modules require.
+      * a module can load a dependee conditionally from a method (with the `require` statement occuring in a method and not at the top of the file), but the way in which the file is required MUST follow the above guidelines.
+
+
+the end.

data/lib/nandoc/erb/agent.rb

@@ -6,7 +6,7 @@ module NanDoc::Erb
     #
 
     class << self
-      include NanDoc::OptsNormalizer # unnormalize_opt_keys
+      include NanDoc::Cli::OptionMethods
 
       # put parameter values from the command line into the erb files
       # in the task
@@ -30,7 +30,7 @@ module NanDoc::Erb
       def args_none
         err "Please provide args for the erb templates."
         show_usage
-        my_exit
+        command_abort
       end
 
       def args_parse
@@ -39,7 +39,7 @@ module NanDoc::Erb
           unless /\A--([-_a-z0-9]*)=(.+)\Z/ =~ str
             err "couldn't parse #{str.inspect} -- expecting \"--foo='bar'\""
             show_usage
-            my_exit
+            command_abort
           end
           hash[normalize_opt_key($1)] = $2
         end
@@ -64,7 +64,7 @@ module NanDoc::Erb
         err "missing erb parameter(s): #{miss.join(' ')}" if miss.any?
         if miss.any? or suck.any?
           show_usage;
-          my_exit
+          command_abort
         end
         have
       end
@@ -73,7 +73,7 @@ module NanDoc::Erb
         $stderr.puts(*a)
       end
 
-      def my_exit
+      def command_abort
         exit(1)
       end
 

data/lib/nandoc/{test/minitest-extlib.rb → extlib/minitest.rb}

@@ -1,5 +1,5 @@
 require 'diff/lcs'
-require(File.dirname(__FILE__)+'/diff-to-string.rb')
+require 'nandoc/support/diff-to-string'
 
 module MiniTest
   module Assertions

data/lib/nandoc/filters/builtin-tags/fence/terminal.rb

@@ -0,0 +1,24 @@
+require 'nandoc/spec-doc/playback'
+require 'nandoc/spec-doc/ruby2ruby-standin'
+
+module NanDoc::Filters::Fence
+  class Terminal
+    include NanDoc::SpecDoc::Ruby2RubyStandin
+    include NanDoc::SpecDoc::Playback::Terminal::ColorToHtml
+
+    class << self
+      def =~ str
+        str =~ /\Afrom the command line\Z/
+      end
+    end
+
+    def run out, indent, label, content
+      content_ind = reindent_content content, indent
+      # if color codes colorize color codes, else prompts
+      html = terminal_color_to_html(content_ind)
+      html ||= prompt_highlight(content_ind)
+      out.push_tag_now 'pre', 'terminal', html
+      nil
+    end
+  end
+end

data/lib/nandoc/filters/builtin-tags/fence-dispatcher.rb

@@ -0,0 +1,43 @@
+require 'nandoc/html'
+
+module NanDoc::Filters
+  class FenceDispatcher
+    Re = %r<
+      (.*?)
+      ^((?:[ ]|\t)*)((?:[a-z]|[ ])+):(?:[ ]|\t)*\n
+      \2~~~(?:[ ]|\t)*\n
+      (.*?)\n
+      \2~~~(?:[ ]|\t)*\n
+    >mx
+    @fences = []
+    class << self
+      def =~ item_content
+        Re =~ item_content
+      end
+      def register fent
+        @fences.push fent
+      end
+      attr_reader :fences
+    end
+    def run item_content
+      scn = StringScanner.new(item_content)
+      out = NanDoc::Html::Tags.new
+      while (match = scn.scan_until(Re))
+        Re =~ match or fail("internal parse fail :(")
+        noparse, indent, label, content = $~.captures
+        fence_cls = self.class.fences.detect{ |fent| fent =~ label }
+        if ! fence_cls
+          # silently fail on unidentified blocks for now, pass them thru
+          out.push_raw $~[0]
+        else
+          out.push_raw noparse
+          fence_tag = fence_cls.new
+          fence_tag.run(out, indent, label, content)
+        end
+      end
+      out.push_raw scn.rest
+      html = out.to_html
+      html
+    end
+  end
+end

data/lib/nandoc/filters/builtin-tags/fences.rb

@@ -0,0 +1,4 @@
+me = File.dirname(__FILE__)
+require me + '/fence-dispatcher.rb'
+require me +'/fence/terminal.rb'
+NanDoc::Filters::FenceDispatcher.register NanDoc::Filters::Fence::Terminal

data/lib/nandoc/filters/builtin-tags/see-test.rb

@@ -0,0 +1,67 @@
+require 'strscan'
+require 'nandoc/spec-doc'
+require 'nandoc/spec-doc/playback'
+require 'nandoc/html'
+
+module NanDoc::Filters
+  class SeeTest
+    include TagParseInstanceMethods
+  private
+    Re = %r{\(see:[ ]*(?:spec|test)[^\s]+
+      (?:
+        [ ]*
+        (?:--?|/)
+        [ ]*
+        (?:
+          '[^']*' |
+          "[^"]*" |
+          [^\s'"]+
+        )
+      )+ \)[ ]*\n
+    }x
+    Re2 =  /(.*)(#{Re.source})/mx
+    class << self
+      def =~ item_content
+        Re =~ item_content
+      end
+    end
+  public
+    def run item_content
+      scn = MyStringScanner.new(item_content)
+      doc = NanDoc::Html::Tags.new
+      while (match = scn.scan_until(Re))
+        noparse, parse = Re2 =~ match && $1, $2
+        doc.push_raw noparse
+        scn2 = MyStringScanner.new(parse)
+        scn2.skip(/\(see: */)
+        path = scn2.scan_assert(/[-\w]+\.\w+/i, 'path')
+        things = []
+        loop do
+          scn2.skip(%r<\s*(?:--?|/)\s*>)
+          this = scn2.scan(/ '[^']*' | "[^"]*" | [^\s'"]+ /x) or
+            fail("internal parse fail near #{scn2.rest.inspect}")
+          things.push unquote(this)
+          scn2.skip(/\)\s*/)
+          scn2.eos? and break
+        end
+        playback = NanDoc::SpecDoc::Playback::Method.new(path, things)
+        playback.make_html doc
+      end
+      doc.push_raw scn.rest
+      html = doc.to_html
+      html
+    end
+    # push it up if desired
+    class MyStringScanner < StringScanner
+      def scan_assert foo, name=nil
+        ret = scan(foo)
+        unless ret
+          use_name = name ? "#{name} (/#{foo.source}/)" :
+            "/#{foo.source}/"
+          fail("Unable to find #{use_name} in #{rest.inspect}")
+        end
+        ret
+      end
+    end
+  end
+end

data/lib/nandoc/filters/builtin-tags.rb

@@ -0,0 +1,11 @@
+module NanDoc::Filters
+
+  me = File.dirname(__FILE__) + '/builtin-tags'
+
+  require me + '/see-test'
+  CustomTags.register_class SeeTest
+
+  require me + '/fences'
+  CustomTags.register_class FenceDispatcher
+
+end

data/lib/nandoc/filters/custom-tag.rb

@@ -0,0 +1,43 @@
+require 'strscan'
+require File.dirname(__FILE__)+'/tag-parser.rb'
+require 'nandoc/spec-doc'
+
+module NanDoc::Filters
+  class CustomTag
+    include TagParsingInstanceMethods
+    def initialize
+    end
+    def name
+      @name || 'anonymous custom filter'
+    end
+    def tag_parser
+      nil
+    end
+    private :tag_parser
+    def wants? md
+      tp = tag_parser
+      ret = nil
+      if ! tp
+        ret = false
+        @last_failure_lines = ["#{name} doesn't want #{md[:content].inspect}"]
+      else
+        if tree = tp.parse(md[:content])
+          ret = true
+          @last_tree = tree
+        else
+          ret = false
+          these = tp.failure_lines(md[:content])
+          these.unshift("#{name} couldn't parse tag:")
+          @last_failure_lines = these
+        end
+      end
+      ret
+    end
+    def get_failure_lines md
+      @last_failure_lines
+    end
+    def render_block filter, md
+      fail("this is the one you want to implement. look at @last_tree maybe.")
+    end
+  end
+end

data/lib/nandoc/filters/custom-tags.rb

@@ -0,0 +1,19 @@
+module NanDoc::Filters
+  class CustomTagsClass < Array
+    def register_class cls
+      unshift cls
+    end
+    def change_item_content content
+      each do |cls|
+        if cls =~ content
+          tag_filter = cls.new
+          new_content = tag_filter.run(content)
+          content.replace(new_content)
+        end
+      end
+      content
+    end
+  end
+
+  CustomTags = CustomTagsClass.new
+end

data/lib/nandoc/filters/tag-parse-instance-methods.rb

@@ -0,0 +1,11 @@
+module NanDoc::Filters
+  module TagParseInstanceMethods
+    def unquote str
+      case str
+        when /\A'(.*)'\Z/ ; $1
+        when /\A"(.*)"\Z/ ; $1
+        else str
+      end
+    end
+  end
+end

data/lib/nandoc/filters/tag-parser.rb

@@ -0,0 +1,206 @@
+module NanDoc::Filters
+  class CustomTag # we are just (re) opening this class
+
+    class TagParser
+      # treetop?
+      #
+      def initialize
+        @last_failure_lines = nil
+      end
+      def failure_lines *ignored
+        @last_failure_lines
+      end
+      def get_symbol mixed
+        if mixed.kind_of?(ParserSymbol)
+          mixed
+        elsif :start == mixed
+          name = symbols[:start]
+          sym = get_symbol_with_name(name)
+        elsif :end == mixed
+          sym = EndSymbol
+        elsif mixed.kind_of?(Array)
+          sym = Seq.new(self, mixed)
+        else
+          sym = get_symbol_with_name(mixed)
+        end
+        sym
+      end
+      def get_symbol_with_name name
+        thing = symbols[name] or fail("Symbol not found: #{name.inspect}")
+        sym = case thing
+          when Hash
+            RegexpSymbol.new(self, thing, name)
+          else
+            fail("no: #{thing.inspect}")
+        end
+        sym
+      end
+      def get_start_symbol
+        get_symbol(:start)
+      end
+      # return tree or (nil and set failure lines)
+      def parse str
+        sym = get_start_symbol
+        scn = StringScanner.new(str)
+        sex = []
+        fails = []
+        ok = true
+        while sym
+          ch_ret = sym.parse(scn, sex, fails)
+          case ch_ret
+          when ParserSymbol
+            sym = ch_ret
+          when false;
+            ok = false
+            break
+          when true;
+            ok = true
+            break
+          else
+            debugger; 'x'
+          end
+        end
+        if ok
+          sex
+        else
+          @last_failure_lines = fails
+          nil
+        end
+      end
+      def symbols
+        @symbols ||= begin
+          self.class.const_get(:Symbols) or
+            fail("Symbols constant not found in #{self.class}")
+        end
+      end
+      module ParserSymbol
+        def secret_grammar grammar
+          sing = class << self; self end
+          kelsey = grammar
+          sing.send(:define_method, :grammar){ kelsey }
+        end
+      end
+      class EndSymbolClass
+        include ParserSymbol
+        def parse scn, sex, fails
+          puts "END is parsing #{scn.rest.inspect}"
+          ret = nil
+          if scn.rest == ""
+            ret = true
+            sex.push [:end]
+          else
+            fails.push "expecting end of input near #{scn.rest.inspect}"
+            ret = false
+          end
+          ret
+        end
+      end
+      EndSymbol = EndSymbolClass.new
+      class RegexpSymbol
+        include ParserSymbol
+        def initialize(grammar, hash, name)
+          secret_grammar grammar
+          @desc = hash[:desc] or fail("no")
+          @re   = hash[:re]   or fail("no")
+          @next = hash[:next]
+          @no_sexp = hash[:no_sexp]
+          self.name = name
+        end
+        attr_reader :desc
+        attr_accessor :name
+        attr_reader :re
+        attr_reader :next
+        def next_symbol_or_nil
+          self.next and grammar.get_symbol(self.next)
+        end
+        # @return nil iff you succeed and have no next
+        # @return next parser if you succeed and have a next parser
+        # @return false if you fail
+        def parse scn, sex, fails
+          print "[#{name.inspect}] is parsing #{scn.rest.inspect}"
+          my_ret = nil
+          if matched = scn.scan(re)
+            sex.push([name, matched]) unless @no_sexp
+            my_ret = next_symbol_or_nil
+            my_ret ||= true # assume no next and we parsed it ok
+            puts " matched: #{matched}"
+          else
+            fails.push "expecting #{desc} near #{scn.rest.inspect}."
+            my_ret = false
+            puts " not found"
+          end
+          my_ret
+        end
+      end
+      # union production
+      class Or < Array
+        include ParserSymbol
+        class << self
+          def [](*arr)
+            new(arr)
+          end
+        end
+        # def parse scn, sex, fails
+        #   debugger; 'x'
+        #   my_fails = []
+        #   my_ret = nil
+        #   found = false
+        #   self.each do |child|
+        #     ch_fails = []
+        #     ch_ret = child.parse(scn, sex, ch_fails)
+        #   end
+        # end
+      end
+      # concatentation production
+      class Seq
+        include ParserSymbol
+        def initialize grammar, arr
+          secret_grammar grammar
+          @arr = arr
+          @parsers = Array.new(arr.size)
+          @done = false
+        end
+        def get_parser_at offset
+          @parsers[offset] ||= begin
+            def_thing = @arr[offset]
+            sym = nil
+            if def_thing
+              sym = grammar.get_symbol(def_thing)
+            end
+            sym
+          end
+        end
+        def parse scn, sex, fails
+          my_ret = nil
+          current = 0
+          last = @arr.size - 1
+          sym = get_parser_at(current)
+          while sym
+            puts "sequence at #{current} about to parse #{scn.rest.inspect}"
+            ch_ret = sym.parse(scn, sex, fails)
+            if ch_ret.kind_of?(ParserSymbol)
+              sym = ch_ret
+            elsif ch_ret == false
+              sym = false
+              my_ret = false
+              break
+            elsif ch_ret == true
+              current += 1
+              sym = get_parser_at(current)
+            else
+              fail("don't know what to do with this: #{ch_ret.inspect}")
+            end
+          end
+          if my_ret.nil?
+            if current <= last
+              fail("what happened?")
+            else
+              my_ret = true
+            end
+          end
+          my_ret
+        end
+      end
+    end
+  end
+end