rundoc 4.0.0 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ab49039bd205d3d147c1de91935b0deb1ffa095311eead39c750b426db1d7c87
-  data.tar.gz: f6a45b2b7a7b858ce09c8464ab891f9b3e7afe272de9d00768e5760a36f4533d
+  metadata.gz: 8ca738c51da79babb0fba6093b9d2055e6efd6d435d56b3397aed926d002701d
+  data.tar.gz: be7e9bd2c06a3a0e92dd078a3cd66d67f77b7cf1f4490190281fb7e573f8696e
 SHA512:
-  metadata.gz: 3d946cf5081696a80ef34867e6559cb51f2191682e74ec21d44d524c41c11bdc05f73fe0f832afe9a89e5c85e6d6f588dfb85f857dbe141f2da278fc60df2527
-  data.tar.gz: 2c0fd644519f2cde9ca67ef6d56c9f1fa17727883149ebb0a437a9e163b70c41b478f1be39f50560fd7c7bf59ba77dab305d4654c2737fdfdc350098f094a549
+  metadata.gz: 7db578e4f26a9b347ca93d8ae5b4013ae9605feaff56ba937d1b22c1a78316764af8f96274d9f449c5640282df277a3ac06e0530e8f760e8153c029aa2f05a27
+  data.tar.gz: 4b71fb1cfd4851d58759ca443e9d17a365d485621d7c1763b570171557a89c79a52e67080f53c25f1d7c4057a2a4decd43e46df7aa34909dc627b2717668a77b

data/.gitignore

@@ -11,6 +11,7 @@ coverage/
 .DS_Store
 Gemfile.lock
 .env
+.ruby-version
 
 # IDEs
 .idea/

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## HEAD
 
+## 4.1.0
+
+- Add: Rundoc command `pre.erb` command used for dynamically templating any command using ERB syntax. (https://github.com/zombocom/rundoc/pull/90)
+
 ## 4.0.0
 
 - Add: Rundoc command `background.stdin_write` to send a string to a backtround process' STDIN. This allows driving REPL interfaces (https://github.com/zombocom/rundoc/pull/79)

data/README.md

@@ -73,6 +73,8 @@ This will generate a project folder with your project in it, and a markdown `REA
 - Execute Bash Commands
   - [$](#shell-commands)
   - [fail.$](#shell-commands)
+- Dynamic command templating
+  - [pre.erb](#pre.erb)
 - Printing
   - [print.text](#print)
   - [print.erb](#print)
@@ -257,6 +259,66 @@ These custom commands are kept to a minimum, and for the most part behave as you
 
 Running shell commands like this can be very powerful, you'll likely want more control of how you manipulate files in your project. To do this you can use the `file.` namespace:
 
+## Dynamic command templating
+
+Meta commands that produce no output but instead allow for generating commands via dynamic templates.
+
+Current Commands:
+
+- `pre.erb`
+
+### pre.erb
+
+Placing `pre.erb` in-front of another command will allow dynmaic templating via Ruby's [ERB](https://rubyapi.org/3.3/o/erb) syntax.
+
+For example:
+
+  ```
+  :::>> pre.erb $ echo "The answer to everything is <%= 6*7 %>"
+  ```
+
+When this runs, it will first replace the template with the result of the ERB. It would be the same as this:
+
+    ```
+    :::>> $ echo "The answer to everything is 42"
+    ```
+
+The binding (variable and method scope) for `pre.erb` is shared across all executions and the default `print.erb` command. That means you can use it to persist data or logic and re-use it:
+
+    ```ruby
+    :::-- print.erb <%
+      # Won't be rendered because it's using `--` visibility
+      def lol
+        "haha"
+      end
+
+      user = "Schneems"
+    %>
+    ```
+
+    ```
+    :::>> pre.erb $ echo <%= user %> said <%= lol() %> | tr '[:lower:]' '[:upper:]'
+    ```
+
+When run, this would produce:
+
+    ```
+    $ echo Schneems said haha | tr '[:lower:]' '[:upper:]'
+    SCHNEEMS SAID HAHA
+    ```
+
+Multi-line commands are also supported
+
+    ```
+    :::>> pre.erb file.write "lol.txt"
+    Super secret key:
+      <%= "#{key}" %>
+    ```
+
+The only thing to watch out for is if the resulting template contains a `:::>>` (or similar) rundoc marker at the beginning of the line; Rundoc will think it is a new command rather than a part of `pre.erb` template.
+
+The visibility of the `pre.erb` is forwarded to whatever command is run.
+
 ## Print
 
 Current commands:

data/lib/rundoc/cli.rb

@@ -157,7 +157,7 @@ module Rundoc
 
       io.puts "## Working dir is #{execution_context.output_dir}"
       Dir.chdir(execution_context.output_dir) do
-        parser = Rundoc::Parser.new(
+        parser = Rundoc::Document.new(
           source_contents,
           context: execution_context
         )
@@ -203,7 +203,7 @@ module Rundoc
         to: on_failure_dir
       )
 
-      on_failure_dir.join("RUNDOC_FAILED.md").write(Rundoc::Parser.partial_result_to_doc)
+      on_failure_dir.join("RUNDOC_FAILED.md").write(Rundoc::Document.partial_result_to_doc)
     end
 
     private def on_success(output)

data/lib/rundoc/code_command/file_command/append.rb

@@ -12,7 +12,9 @@ class Rundoc::CodeCommand::FileCommand
     def to_md(env)
       return unless render_command?
 
-      raise "must call write in its own code section" unless env[:commands].empty?
+      if env[:commands].any? { |c| c[:object].not_hidden? }
+        raise "Must call append in its own code section"
+      end
 
       env[:before] << if @line_number
         "In file `#{filename}`, on line #{@line_number} add:"

data/lib/rundoc/code_command/file_command/remove.rb

@@ -7,7 +7,10 @@ class Rundoc::CodeCommand::FileCommand
     end
 
     def to_md(env)
-      raise "must call write in its own code section" unless env[:commands].empty?
+      if env[:commands].any? { |c| c[:object].not_hidden? }
+        raise "Must call remove in its own code section"
+      end
+
       env[:before] << "In file `#{filename}` remove:"
       env[:before] << NEWLINE
       nil

data/lib/rundoc/code_command/pre/erb.rb

@@ -0,0 +1,63 @@
+require_relative "../print/erb"
+
+class Rundoc::CodeCommand
+  class PreErb < Rundoc::CodeCommand
+    def initialize(line)
+      @line = line
+      @binding = RUNDOC_ERB_BINDINGS[RUNDOC_DEFAULT_ERB_BINDING]
+      @code = nil
+      @command = nil
+      @template = nil
+      @render_delegate_result = nil
+      @render_delegate_command = nil
+      # Hide self, pass visibility onto delegate
+      @render_result = false
+      @render_command = false
+    end
+
+    # Visibility is injected by the parser, capture it and pass it to the delegate
+    def render_result=(value)
+      @render_delegate_result = value
+    end
+
+    def render_command=(value)
+      @render_delegate_command = value
+    end
+
+    def code
+      @code ||= begin
+        vis = +""
+        vis += @render_delegate_result ? ">" : "-"
+        vis += @render_delegate_command ? ">" : "-"
+        code = [@line, @contents]
+          .compact
+          .reject(&:empty?)
+          .join("\n")
+        @template = ":::#{vis} #{code}"
+
+        puts "pre.erb: Applying ERB, template:\n#{@template}"
+        result = ERB.new(@template).result(@binding)
+        puts "pre.erb: ERB result:\n#{result}"
+        puts "pre.erb: done, ready to delegate"
+        result
+      end
+    end
+
+    def command
+      @command ||= Rundoc::FencedCodeBlock.parse_code_commands(code).first
+    end
+
+    def to_md(env = {})
+      ""
+    end
+
+    def call(env = {})
+      # Defer running ERB until as late as possible
+      delegate = command
+      # Delegate will be executed by the caller working through the stack
+      env[:stack].push(delegate)
+      ""
+    end
+  end
+end
+Rundoc.register_code_command(:"pre.erb", Rundoc::CodeCommand::PreErb)

data/lib/rundoc/code_command/print/erb.rb

@@ -10,11 +10,12 @@ class EmptyBinding
   end
 end
 
-RUNDOC_ERB_BINDINGS = Hash.new { |h, k| h[k] = EmptyBinding.create }
-
 class Rundoc::CodeCommand
+  RUNDOC_ERB_BINDINGS = Hash.new { |h, k| h[k] = EmptyBinding.create }
+  RUNDOC_DEFAULT_ERB_BINDING = "default"
+
   class PrintERB < Rundoc::CodeCommand
-    def initialize(line = nil, binding: "default")
+    def initialize(line = nil, binding: RUNDOC_DEFAULT_ERB_BINDING)
       @line = line
       @binding = RUNDOC_ERB_BINDINGS[binding]
     end
@@ -31,7 +32,7 @@ class Rundoc::CodeCommand
       @render ||= ERB.new([@line, contents].compact.join("\n")).result(@binding)
     end
 
-    def call(erb = {})
+    def call(env = {})
       if render_before?
         ""
       else
@@ -44,5 +45,4 @@ class Rundoc::CodeCommand
     end
   end
 end
-
 Rundoc.register_code_command(:"print.erb", Rundoc::CodeCommand::PrintERB)

data/lib/rundoc/code_command/rundoc/require.rb

@@ -17,7 +17,7 @@ class ::Rundoc::CodeCommand
         execution_context = env[:context]
         document_path = @path.expand_path(execution_context.source_dir)
 
-        output = Rundoc::Parser.new(
+        output = Rundoc::Document.new(
           document_path.read,
           context: Rundoc::Context::Execution.new(
             source_path: document_path,

data/lib/rundoc/code_command/write.rb

@@ -24,7 +24,9 @@ module Rundoc
 
       def to_md(env)
         if render_command?
-          raise "must call write in its own code section" unless env[:commands].empty?
+          if env[:commands].any? { |c| c[:object].not_hidden? }
+            raise "must call write in its own code section"
+          end
           env[:before] << "In file `#{filename}` write:"
           env[:before] << NEWLINE
         end

data/lib/rundoc/code_command.rb

@@ -60,3 +60,4 @@ require "rundoc/code_command/background"
 require "rundoc/code_command/website"
 require "rundoc/code_command/print/text"
 require "rundoc/code_command/print/erb"
+require "rundoc/code_command/pre/erb"

data/lib/rundoc/{parser.rb → document.rb}

@@ -1,25 +1,20 @@
 module Rundoc
-  # This poorly named class is responsible for taking in the raw markdown and running it
+  # Represents a single rundoc file on disk,
   #
-  # It works by pulling out the code blocks (CodeSection), and putting them onto a stack.
-  # It then executes each in turn and records the results.
-  class Parser
-    DEFAULT_KEYWORD = ":::"
-    INDENT_BLOCK = '(?<before_indent>(^\s*$\n|\A)(^(?:[ ]{4}|\t))(?<indent_contents>.*)(?<after_indent>[^\s].*$\n?(?:(?:^\s*$\n?)*^(?:[ ]{4}|\t).*[^\s].*$\n?)*))'
+  # Each document contains one or more fenced code blocks.
+  # Those are parsed as `FencedCodeBlock` instances and then
+  # executed.
+  class Document
     GITHUB_BLOCK = '^(?<fence>(?<fence_char>~|`){3,})\s*?(?<lang>\w+)?\s*?\n(?<contents>.*?)^\g<fence>\g<fence_char>*\s*?\n?'
     CODEBLOCK_REGEX = /(#{GITHUB_BLOCK})/m
-    COMMAND_REGEX = ->(keyword) {
-      /^#{keyword}(?<tag>(\s|=|-|>)?(=|-|>)?)\s*(?<command>(\S)+)\s+(?<statement>.*)$/
-    }
     PARTIAL_RESULT = []
 
-    attr_reader :contents, :keyword, :stack, :context
+    attr_reader :contents, :stack, :context
 
-    def initialize(contents, context:, keyword: DEFAULT_KEYWORD)
+    def initialize(contents, context:)
       @context = context
       @contents = contents
       @original = contents.dup
-      @keyword = keyword
       @stack = []
       partition
       PARTIAL_RESULT.clear
@@ -44,7 +39,7 @@ module Rundoc
 
     def self.partial_result_to_doc
       out = to_doc(result: PARTIAL_RESULT)
-      unfinished = CodeSection.partial_result_to_doc
+      unfinished = FencedCodeBlock.partial_result_to_doc
       out << unfinished if unfinished
       out
     end
@@ -60,9 +55,10 @@ module Rundoc
         @stack << head unless head.empty?
         unless code.empty?
           match = code.match(CODEBLOCK_REGEX)
-          @stack << CodeSection.new(
-            match,
-            keyword: keyword,
+          @stack << FencedCodeBlock.new(
+            fence: match[:fence],
+            lang: match[:lang],
+            code: match[:contents],
             context: context
           )
         end
@@ -71,5 +67,3 @@ module Rundoc
     end
   end
 end
-
-# convert string of markdown to array of strings and code_command

data/lib/rundoc/fenced_code_block.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Rundoc
+  # A code secttion respesents a block of fenced code
+  #
+  # A document can have multiple code sections
+  class FencedCodeBlock
+    AUTOGEN_WARNING = "\n<!-- STOP. This document is autogenerated. Do not manually modify. See the top of the doc for more details. -->"
+    attr_accessor :fence, :lang, :code
+
+    PARTIAL_RESULT = []
+    PARTIAL_ENV = {}
+
+    # Used for tests to inspect the command that was executed
+    def executed_commands
+      raise "Nothing executed" unless @env[:commands].any?
+
+      @env[:commands].map { |c| c[:object] }
+    end
+
+    # @param fence [String] the fence used to start the code block like "```".
+    # @param lang [String] any extra string after the fence like for example
+    #        a fence of "```ruby" the lang would be "ruby".
+    # @param code [String] the code block contents inside the fence.
+    # @param context [Context::Execution] The details about where
+    #        the code block came from.
+    def initialize(fence:, lang:, code:, context:)
+      @fence = fence
+      @lang = lang
+      @code = code
+      @executed = false
+      @env = {}
+      @stack = []
+      @context = context
+      @rendered = ""
+      self.class.parse_code_commands(@code).each do |code_command|
+        @stack.unshift(code_command)
+      end
+
+      PARTIAL_RESULT.clear
+      PARTIAL_ENV.clear
+    end
+
+    def call
+      return self if @executed
+      @executed = true
+
+      result = []
+      env = @env
+      env[:commands] = []
+      env[:fence_start] = "#{fence}#{lang}"
+      env[:fence_end] = "#{fence}#{AUTOGEN_WARNING}"
+      env[:before] = []
+      env[:after] = []
+      env[:context] = @context
+      env[:stack] = @stack
+
+      while (code_command = @stack.pop)
+        code_output = code_command.call(env) || ""
+        code_line = code_command.to_md(env) || ""
+        result << code_line if code_command.render_command?
+        result << code_output if code_command.render_result?
+
+        PARTIAL_RESULT.replace(result)
+        PARTIAL_ENV.replace(env)
+
+        env[:commands] << {
+          object: code_command,
+          output: code_output,
+          command: code_line
+        }
+      end
+
+      if env[:commands].any? { |c| c[:object].not_hidden? }
+        @rendered = self.class.to_doc(result: result, env: env)
+      end
+      self
+    end
+
+    def render
+      call
+      @rendered
+    end
+
+    def self.partial_result_to_doc
+      to_doc(result: PARTIAL_RESULT, env: PARTIAL_ENV)
+    end
+
+    def self.to_doc(result:, env:)
+      array = [env[:before]]
+
+      result.flatten!
+      result.compact!
+      result.map! { |s| s.respond_to?(:rstrip) ? s.rstrip : s }
+      result.reject!(&:empty?)
+      result.map!(&:to_s)
+
+      if !result.empty?
+        array << env[:fence_start]
+        array << result
+        array << env[:fence_end]
+      end
+      array << env[:after]
+
+      array.flatten!
+      array.compact!
+      array.map! { |s| s.respond_to?(:rstrip) ? s.rstrip : s }
+      array.reject!(&:empty?)
+      array.map!(&:to_s)
+
+      array.join("\n") << "\n"
+    end
+
+    def self.parse_code_commands(code)
+      parser = Rundoc::PegParser.new.code_block
+      tree = parser.parse(code)
+      commands = Rundoc::PegTransformer.new.apply(tree)
+      commands = [commands] unless commands.is_a?(Array)
+      commands
+    rescue ::Parslet::ParseFailed => e
+      raise "Could not compile code:\n#{code}\nReason: #{e.message}"
+    end
+  end
+end

data/lib/rundoc/version.rb

@@ -1,3 +1,3 @@
 module Rundoc
-  VERSION = "4.0.0"
+  VERSION = "4.1.0"
 end

data/lib/rundoc.rb

@@ -87,8 +87,8 @@ module Rundoc
   end
 end
 
-require "rundoc/parser"
-require "rundoc/code_section"
+require "rundoc/document"
+require "rundoc/fenced_code_block"
 require "rundoc/code_command"
 require "rundoc/peg_parser"
 require "rundoc/cli_argument_parser"

data/test/integration/pre_erb_test.rb

@@ -0,0 +1,56 @@
+require "test_helper"
+
+class IntegrationPreErb < Minitest::Test
+  def test_file_write
+    key = SecureRandom.hex
+    contents = <<~RUBY
+      ```
+      :::>> pre.erb file.write "lol.txt"
+      Multi line
+      <%= "#{key}" %>
+      ```
+    RUBY
+
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        expected = <<~EOF
+          In file `lol.txt` write:
+
+          ```
+          Multi line
+          #{key}
+          ```
+        EOF
+
+        parsed = parse_contents(contents)
+        actual = parsed.to_md.gsub(Rundoc::FencedCodeBlock::AUTOGEN_WARNING, "").strip
+        assert_equal expected.strip, actual.strip
+      end
+    end
+  end
+
+  def test_erb_shared_binding_persists_values
+    key = SecureRandom.hex
+    contents = <<~RUBY
+      ```
+      :::-- print.erb <% secret = "#{key}" %>
+      :::>> pre.erb $ echo <%= secret %>
+      ```
+    RUBY
+
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        expected = <<~EOF
+          ```
+          $ echo #{key}
+          #{key}
+          ```
+        EOF
+
+        parsed = parse_contents(contents)
+        actual = parsed.to_md.gsub(Rundoc::FencedCodeBlock::AUTOGEN_WARNING, "").strip
+        assert_equal expected.strip, actual.strip
+      end
+    end
+  end
+end

data/test/integration/print_test.rb

@@ -21,7 +21,7 @@ class IntegrationPrintTest < Minitest::Test
           #{key}
         EOF
         parsed = parse_contents(contents)
-        actual = parsed.to_md.gsub(Rundoc::CodeSection::AUTOGEN_WARNING, "")
+        actual = parsed.to_md.gsub(Rundoc::FencedCodeBlock::AUTOGEN_WARNING, "")
         assert_equal expected, actual
       end
     end
@@ -44,7 +44,7 @@ class IntegrationPrintTest < Minitest::Test
           one
         EOF
         parsed = parse_contents(contents)
-        actual = parsed.to_md.gsub(Rundoc::CodeSection::AUTOGEN_WARNING, "")
+        actual = parsed.to_md.gsub(Rundoc::FencedCodeBlock::AUTOGEN_WARNING, "")
         assert_equal expected, actual
       end
     end
@@ -70,7 +70,7 @@ class IntegrationPrintTest < Minitest::Test
           ```
         EOF
         parsed = parse_contents(contents)
-        actual = parsed.to_md.gsub(Rundoc::CodeSection::AUTOGEN_WARNING, "")
+        actual = parsed.to_md.gsub(Rundoc::FencedCodeBlock::AUTOGEN_WARNING, "")
         assert_equal expected, actual
       end
     end
@@ -94,7 +94,7 @@ class IntegrationPrintTest < Minitest::Test
           there
         EOF
         parsed = parse_contents(contents)
-        actual = parsed.to_md.gsub(Rundoc::CodeSection::AUTOGEN_WARNING, "")
+        actual = parsed.to_md.gsub(Rundoc::FencedCodeBlock::AUTOGEN_WARNING, "")
         assert_equal expected, actual
       end
     end
@@ -118,7 +118,7 @@ class IntegrationPrintTest < Minitest::Test
           there
         EOF
         parsed = parse_contents(contents)
-        actual = parsed.to_md.gsub(Rundoc::CodeSection::AUTOGEN_WARNING, "")
+        actual = parsed.to_md.gsub(Rundoc::FencedCodeBlock::AUTOGEN_WARNING, "")
         assert_equal expected, actual
       end
     end
@@ -142,7 +142,7 @@ class IntegrationPrintTest < Minitest::Test
           there
         EOF
         parsed = parse_contents(contents)
-        actual = parsed.to_md.gsub(Rundoc::CodeSection::AUTOGEN_WARNING, "")
+        actual = parsed.to_md.gsub(Rundoc::FencedCodeBlock::AUTOGEN_WARNING, "")
         assert_equal expected, actual
       end
     end
@@ -163,7 +163,7 @@ class IntegrationPrintTest < Minitest::Test
           Hello there
         EOF
         parsed = parse_contents(contents)
-        actual = parsed.to_md.gsub(Rundoc::CodeSection::AUTOGEN_WARNING, "")
+        actual = parsed.to_md.gsub(Rundoc::FencedCodeBlock::AUTOGEN_WARNING, "")
         assert_equal expected, actual
       end
     end
@@ -186,7 +186,7 @@ class IntegrationPrintTest < Minitest::Test
           ```
         EOF
         parsed = parse_contents(contents)
-        actual = parsed.to_md.gsub(Rundoc::CodeSection::AUTOGEN_WARNING, "")
+        actual = parsed.to_md.gsub(Rundoc::FencedCodeBlock::AUTOGEN_WARNING, "")
         assert_equal expected, actual
       end
     end

data/test/integration/require_test.rb

@@ -22,7 +22,7 @@ class IntegrationRequireTest < Minitest::Test
           source_path.read,
           source_path: source_path
         )
-        actual = parsed.to_md.gsub(Rundoc::CodeSection::AUTOGEN_WARNING, "")
+        actual = parsed.to_md.gsub(Rundoc::FencedCodeBlock::AUTOGEN_WARNING, "")
         assert_equal "Hello World!", actual.strip
       end
     end
@@ -50,7 +50,7 @@ class IntegrationRequireTest < Minitest::Test
           source_path.read,
           source_path: source_path
         )
-        actual = parsed.to_md.gsub(Rundoc::CodeSection::AUTOGEN_WARNING, "")
+        actual = parsed.to_md.gsub(Rundoc::FencedCodeBlock::AUTOGEN_WARNING, "")
         # Command was run
         assert dir.join("foo.txt").exist?
         assert "echo hello world", dir.join("foo.txt").read.strip
@@ -89,7 +89,7 @@ class IntegrationRequireTest < Minitest::Test
           source_path.read,
           source_path: source_path
         )
-        actual = parsed.to_md.gsub(Rundoc::CodeSection::AUTOGEN_WARNING, "")
+        actual = parsed.to_md.gsub(Rundoc::FencedCodeBlock::AUTOGEN_WARNING, "")
         assert_equal "Hello World!", actual.strip
       end
     end

data/test/integration/website_test.rb

@@ -23,7 +23,7 @@ class IntegrationWebsiteTest < Minitest::Test
           output_dir: screenshots_dir.parent,
           screenshots_dirname: screenshots_dirname
         )
-        actual = parsed.to_md.gsub(Rundoc::CodeSection::AUTOGEN_WARNING, "")
+        actual = parsed.to_md.gsub(Rundoc::FencedCodeBlock::AUTOGEN_WARNING, "")
 
         expected = "![Screenshot of https://example.com/](screenshots/screenshot_1.png)"
         assert_equal expected, actual.strip

data/test/rundoc/code_section_test.rb

@@ -14,10 +14,11 @@ class CodeSectionTest < Minitest::Test
 
     Dir.mktmpdir do |dir|
       Dir.chdir(dir) do
-        match = contents.match(Rundoc::Parser::CODEBLOCK_REGEX)
-        result = Rundoc::CodeSection.new(
-          match,
-          keyword: ":::",
+        match = contents.match(Rundoc::Document::CODEBLOCK_REGEX)
+        result = Rundoc::FencedCodeBlock.new(
+          fence: match[:fence],
+          lang: match[:lang],
+          code: match[:contents],
           context: default_context
         ).render
         assert_equal "", result
@@ -33,13 +34,14 @@ class CodeSectionTest < Minitest::Test
 
     RUBY
 
-    match = contents.match(Rundoc::Parser::CODEBLOCK_REGEX)
-    result = Rundoc::CodeSection.new(
-      match,
-      keyword: ":::",
+    match = contents.match(Rundoc::Document::CODEBLOCK_REGEX)
+    result = Rundoc::FencedCodeBlock.new(
+      fence: match[:fence],
+      lang: match[:lang],
+      code: match[:contents],
       context: default_context
     ).render
-    assert_equal contents, result.gsub(Rundoc::CodeSection::AUTOGEN_WARNING, "\n")
+    assert_equal contents, result.gsub(Rundoc::FencedCodeBlock::AUTOGEN_WARNING, "\n")
   end
 
   def test_show_command_hide_render
@@ -49,15 +51,16 @@ class CodeSectionTest < Minitest::Test
       ```
     RUBY
 
-    match = contents.match(Rundoc::Parser::CODEBLOCK_REGEX)
-    code_section = Rundoc::CodeSection.new(
-      match,
-      keyword: ":::",
+    match = contents.match(Rundoc::Document::CODEBLOCK_REGEX)
+    code_section = Rundoc::FencedCodeBlock.new(
+      fence: match[:fence],
+      lang: match[:lang],
+      code: match[:contents],
       context: default_context
     )
     code_section.render
 
-    code_command = code_section.commands.first
+    code_command = code_section.executed_commands.first
     assert_equal true, code_command.render_command
     assert_equal false, code_command.render_result
 
@@ -67,15 +70,16 @@ class CodeSectionTest < Minitest::Test
       ```
     RUBY
 
-    match = contents.match(Rundoc::Parser::CODEBLOCK_REGEX)
-    code_section = Rundoc::CodeSection.new(
-      match,
-      keyword: ":::",
+    match = contents.match(Rundoc::Document::CODEBLOCK_REGEX)
+    code_section = Rundoc::FencedCodeBlock.new(
+      fence: match[:fence],
+      lang: match[:lang],
+      code: match[:contents],
       context: default_context
     )
     code_section.render
 
-    code_command = code_section.commands.first
+    code_command = code_section.executed_commands.first
     assert_equal true, code_command.render_command
     assert_equal false, code_command.render_result
   end
@@ -87,16 +91,17 @@ class CodeSectionTest < Minitest::Test
       ```
     RUBY
 
-    match = contents.match(Rundoc::Parser::CODEBLOCK_REGEX)
-    code_section = Rundoc::CodeSection.new(
-      match,
-      keyword: ":::",
+    match = contents.match(Rundoc::Document::CODEBLOCK_REGEX)
+    code_section = Rundoc::FencedCodeBlock.new(
+      fence: match[:fence],
+      lang: match[:lang],
+      code: match[:contents],
       context: default_context
     )
     code_section.render
 
-    puts code_section.commands.inspect
-    code_command = code_section.commands.first
+    puts code_section.executed_commands.inspect
+    code_command = code_section.executed_commands.first
     assert_equal true, code_command.render_command
     assert_equal true, code_command.render_result
   end
@@ -108,15 +113,16 @@ class CodeSectionTest < Minitest::Test
       ```
     RUBY
 
-    match = contents.match(Rundoc::Parser::CODEBLOCK_REGEX)
-    code_section = Rundoc::CodeSection.new(
-      match,
-      keyword: ":::",
+    match = contents.match(Rundoc::Document::CODEBLOCK_REGEX)
+    code_section = Rundoc::FencedCodeBlock.new(
+      fence: match[:fence],
+      lang: match[:lang],
+      code: match[:contents],
       context: default_context
     )
     code_section.render
 
-    code_command = code_section.commands.first
+    code_command = code_section.executed_commands.first
     assert_equal false, code_command.render_command
     assert_equal false, code_command.render_result
 
@@ -126,15 +132,16 @@ class CodeSectionTest < Minitest::Test
       ```
     RUBY
 
-    match = contents.match(Rundoc::Parser::CODEBLOCK_REGEX)
-    code_section = Rundoc::CodeSection.new(
-      match,
-      keyword: ":::",
+    match = contents.match(Rundoc::Document::CODEBLOCK_REGEX)
+    code_section = Rundoc::FencedCodeBlock.new(
+      fence: match[:fence],
+      lang: match[:lang],
+      code: match[:contents],
       context: default_context
     )
     code_section.render
 
-    code_command = code_section.commands.first
+    code_command = code_section.executed_commands.first
     assert_equal false, code_command.render_command
     assert_equal false, code_command.render_result
   end
@@ -146,15 +153,16 @@ class CodeSectionTest < Minitest::Test
       ```
     RUBY
 
-    match = contents.match(Rundoc::Parser::CODEBLOCK_REGEX)
-    code_section = Rundoc::CodeSection.new(
-      match,
-      keyword: ":::",
+    match = contents.match(Rundoc::Document::CODEBLOCK_REGEX)
+    code_section = Rundoc::FencedCodeBlock.new(
+      fence: match[:fence],
+      lang: match[:lang],
+      code: match[:contents],
       context: default_context
     )
     code_section.render
 
-    code_command = code_section.commands.first
+    code_command = code_section.executed_commands.first
     assert_equal false, code_command.render_command
     assert_equal true, code_command.render_result
   end

data/test/rundoc/parser_test.rb

@@ -17,7 +17,7 @@ class ParserTest < Minitest::Test
       Dir.chdir(dir) do
         expected = "sup\n\n```\n$ mkdir foo\n$ ls\nfoo\n```\n\nyo\n"
         parsed = parse_contents(contents)
-        actual = parsed.to_md.gsub(Rundoc::CodeSection::AUTOGEN_WARNING, "")
+        actual = parsed.to_md.gsub(Rundoc::FencedCodeBlock::AUTOGEN_WARNING, "")
         assert_equal expected, actual
       end
     end
@@ -39,7 +39,7 @@ class ParserTest < Minitest::Test
       Dir.chdir(dir) do
         expected = "sup\n\nIn file `foo/code.rb` write:\n\n```\na = 1 + 1\nb = a * 2\n```\nyo\n"
         parsed = parse_contents(contents)
-        actual = parsed.to_md.gsub(Rundoc::CodeSection::AUTOGEN_WARNING, "")
+        actual = parsed.to_md.gsub(Rundoc::FencedCodeBlock::AUTOGEN_WARNING, "")
         assert_equal expected, actual
       end
     end
@@ -57,7 +57,7 @@ class ParserTest < Minitest::Test
       Dir.chdir(dir) do
         expected = "\nIn file `foo/newb.rb` write:\n\n```\nputs 'hello world'\n$ cat foo/newb.rb\nputs 'hello world'\n```\n"
         parsed = parse_contents(contents)
-        actual = parsed.to_md.gsub(Rundoc::CodeSection::AUTOGEN_WARNING, "")
+        actual = parsed.to_md.gsub(Rundoc::FencedCodeBlock::AUTOGEN_WARNING, "")
         assert_equal expected, actual
       end
     end

data/test/rundoc/peg_parser_test.rb

@@ -240,22 +240,6 @@ class PegParserTest < Minitest::Test
   end
 
   def test_no_args
-    # input = String.new
-    # input << %Q{rundoc}
-    # parser = Rundoc::PegParser.new.no_args_method
-    # tree = parser.parse_with_debug(input)
-    # actual = @transformer.apply(tree)
-    # assert_equal("rundoc", actual.to_s)
-
-    # input = String.new
-    # input << %Q{:::-- rundoc\n}
-    # parser = Rundoc::PegParser.new.command
-    # tree = parser.parse_with_debug(input)
-
-    # actual = @transformer.apply(tree)
-    # assert_equal :rundoc, actual.keyword
-    # assert_nil(actual.original_args)
-
     input = +""
     input << %(:::-- rundoc\n)
     input << %(email = ENV['HEROKU_EMAIL'] || `heroku auth:whoami`\n)
@@ -333,19 +317,7 @@ class PegParserTest < Minitest::Test
     actual = @transformer.apply(tree)
     assert_equal ["rails server", {name: "server"}], actual.original_args
 
-    # input = +""
-    # input << %Q{background.start("rails server", name: "server")}
-    # parser = Rundoc::PegParser.new.method_call
-
-    # tree = parser.parse_with_debug(input)
-
-    # puts tree.inspect
-
-    # actual = @transformer.apply(tree)
-    # assert_equal :"background.start", actual.keyword
-
     # ================
-
     input = +""
     input << %{call("foo", "bar")}
 
@@ -358,7 +330,6 @@ class PegParserTest < Minitest::Test
     assert_equal ["foo", "bar"], actual.original_args
 
     # ======================
-
     input = +""
     input << %{call("foo", "bar", biz: "baz")}
 
@@ -372,14 +343,10 @@ class PegParserTest < Minitest::Test
   def test_positional_args_code_block
     input = +""
     input << %{:::>> background.start("rails server", name: "server")\n}
-    # input << %Q{:::-- background.stop(name: "server")\n}
 
     parser = Rundoc::PegParser.new.command
 
     tree = parser.parse_with_debug(input)
-
-    # puts tree.inspect
-
     actual = @transformer.apply(tree)
     assert_equal :"background.start", actual.keyword
     assert_equal ["rails server", {name: "server"}], actual.original_args

data/test/rundoc/regex_test.rb

@@ -4,36 +4,20 @@ class RegexTest < Minitest::Test
   def setup
   end
 
-  def test_indent_regex
-    contents = <<~RUBY
-      foo
-      
-          $ cd
-          yo
-          sup
-      
-      bar
-    RUBY
-
-    regex = Rundoc::Parser::INDENT_BLOCK
-    parsed = contents.match(/#{regex}/).to_s
-    assert_equal "\n    $ cd\n    yo\n    sup\n", parsed
-  end
-
   def test_github_regex
     contents = <<~RUBY
       foo
-      
+
       ```
       $ cd
       yo
       sup
       ```
-      
+
       bar
     RUBY
 
-    regex = Rundoc::Parser::GITHUB_BLOCK
+    regex = Rundoc::Document::GITHUB_BLOCK
     parsed = contents.match(/#{regex}/m).to_s
     assert_equal "```\n$ cd\nyo\nsup\n```\n", parsed
   end
@@ -41,74 +25,40 @@ class RegexTest < Minitest::Test
   def test_github_tagged_regex
     contents = <<~RUBY
       foo
-      
+
       ```ruby
       $ cd
       yo
       sup
       ```
-      
+
       bar
     RUBY
 
-    regex = Rundoc::Parser::GITHUB_BLOCK
+    regex = Rundoc::Document::GITHUB_BLOCK
     parsed = contents.match(/#{regex}/m).to_s
     assert_equal "```ruby\n$ cd\nyo\nsup\n```\n", parsed
   end
 
-  def test_command_regex
-    regex = Rundoc::Parser::COMMAND_REGEX.call(":::")
-
-    contents = ":::$ mkdir schneems"
-    match = contents.match(regex)
-    assert_equal "", match[:tag]
-    assert_equal "$", match[:command]
-    assert_equal "mkdir schneems", match[:statement]
-
-    contents = ":::=$ mkdir schneems"
-    match = contents.match(regex)
-    assert_equal "=", match[:tag]
-    assert_equal "$", match[:command]
-    assert_equal "mkdir schneems", match[:statement]
-
-    contents = ":::=       $ mkdir schneems"
-    match = contents.match(regex)
-    assert_equal "=", match[:tag]
-    assert_equal "$", match[:command]
-    assert_equal "mkdir schneems", match[:statement]
-
-    contents = ":::-$ mkdir schneems"
-    match = contents.match(regex)
-    assert_equal "-", match[:tag]
-    assert_equal "$", match[:command]
-    assert_equal "mkdir schneems", match[:statement]
-
-    contents = ":::- $ mkdir schneems"
-    match = contents.match(regex)
-    assert_equal "-", match[:tag]
-    assert_equal "$", match[:command]
-    assert_equal "mkdir schneems", match[:statement]
-  end
-
   def test_codeblock_regex
     contents = <<~RUBY
       foo
-      
+
       ```
       :::>$ mkdir
       ```
-      
+
       zoo
-      
+
       ```
       :::>$ cd ..
       something
       ```
-      
+
       bar
     RUBY
 
-    regex = Rundoc::Parser::CODEBLOCK_REGEX
+    regex = Rundoc::Document::CODEBLOCK_REGEX
 
     actual = contents.partition(regex)
     expected = ["foo\n\n",
@@ -133,7 +83,7 @@ class RegexTest < Minitest::Test
       ```java
       :::>> write app/controllers/Application.java
       package controllers;
-      
+
       import static java.util.concurrent.TimeUnit.SECONDS;
       import models.Pinger;
       import play.libs.Akka;
@@ -146,7 +96,7 @@ class RegexTest < Minitest::Test
       import akka.actor.ActorRef;
       import akka.actor.Cancellable;
       import akka.actor.Props;
-      
+
       public class Application extends Controller {
           public static WebSocket<String> pingWs() {
               return new WebSocket<String>() {
@@ -159,7 +109,7 @@ class RegexTest < Minitest::Test
                                                          Akka.system().dispatcher(),
                                                          null
                                                          );
-      
+
                       in.onClose(new Callback0() {
                         @Override
                         public void invoke() throws Throwable {
@@ -167,14 +117,14 @@ class RegexTest < Minitest::Test
                         }
                       });
                   }
-      
+
               };
           }
-      
+
           public static Result pingJs() {
               return ok(views.js.ping.render());
           }
-      
+
           public static Result index() {
               return ok(index.render());
           }
@@ -182,7 +132,7 @@ class RegexTest < Minitest::Test
       ```
     RUBY
 
-    regex = Rundoc::Parser::CODEBLOCK_REGEX
+    regex = Rundoc::Document::CODEBLOCK_REGEX
     match = contents.match(regex)
     assert_equal "java", match[:lang]
     assert_equal "```", match[:fence]
@@ -205,7 +155,7 @@ class RegexTest < Minitest::Test
       :::>> $ echo "hello"
       ```
     MD
-    regex = Rundoc::Parser::CODEBLOCK_REGEX
+    regex = Rundoc::Document::CODEBLOCK_REGEX
     match = code_block_with_newline.match(regex)
     assert_equal expected, match.to_s.strip
 

data/test/test_helper.rb

@@ -19,12 +19,11 @@ class Minitest::Test
     source_path: nil,
     screenshots_dirname: nil
   )
-
     Rundoc::Context::Execution.new(
-      output_dir: output_dir || Pathname("/dev/null"),
-      source_path: source_path || Pathname("/dev/null"),
+      output_dir: output_dir || Pathname(File::NULL),
+      source_path: source_path || Pathname(File::NULL),
       with_contents_dir: nil,
-      screenshots_dirname: screenshots_dirname || Pathname("/dev/null")
+      screenshots_dirname: screenshots_dirname || Pathname(File::NULL)
     )
   end
 
@@ -39,7 +38,7 @@ class Minitest::Test
       source_path: source_path,
       screenshots_dirname: screenshots_dirname
     )
-    Rundoc::Parser.new(
+    Rundoc::Document.new(
       contents,
       context: context
     )
@@ -60,7 +59,7 @@ class Minitest::Test
   end
 
   def strip_autogen_warning(string)
-    string.gsub!(Rundoc::CodeSection::AUTOGEN_WARNING, "")
+    string.gsub!(Rundoc::FencedCodeBlock::AUTOGEN_WARNING, "")
     string.gsub!(/<!-- STOP.*STOP -->/m, "")
     string
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rundoc
 version: !ruby/object:Gem::Version
-  version: 4.0.0
+  version: 4.1.0
 platform: ruby
 authors:
 - Richard Schneeman
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-11-30 00:00:00.000000000 Z
+date: 2024-12-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -215,6 +215,7 @@ files:
 - lib/rundoc/code_command/file_command/remove.rb
 - lib/rundoc/code_command/no_such_command.rb
 - lib/rundoc/code_command/pipe.rb
+- lib/rundoc/code_command/pre/erb.rb
 - lib/rundoc/code_command/print/erb.rb
 - lib/rundoc/code_command/print/text.rb
 - lib/rundoc/code_command/raw.rb
@@ -227,10 +228,10 @@ files:
 - lib/rundoc/code_command/website/screenshot.rb
 - lib/rundoc/code_command/website/visit.rb
 - lib/rundoc/code_command/write.rb
-- lib/rundoc/code_section.rb
 - lib/rundoc/context/after_build.rb
 - lib/rundoc/context/execution.rb
-- lib/rundoc/parser.rb
+- lib/rundoc/document.rb
+- lib/rundoc/fenced_code_block.rb
 - lib/rundoc/peg_parser.rb
 - lib/rundoc/version.rb
 - rundoc.gemspec
@@ -264,6 +265,7 @@ files:
 - test/integration/after_build_test.rb
 - test/integration/background_stdin_test.rb
 - test/integration/failure_test.rb
+- test/integration/pre_erb_test.rb
 - test/integration/print_test.rb
 - test/integration/require_test.rb
 - test/integration/website_test.rb

data/lib/rundoc/code_section.rb

@@ -1,155 +0,0 @@
-# frozen_string_literal: true
-
-module Rundoc
-  # A code secttion respesents a block of fenced code
-  #
-  # A document can have multiple code sections
-  class CodeSection
-    class ParseError < StandardError
-      def initialize(options = {})
-        keyword = options[:keyword]
-        command = options[:command]
-        line_number = options[:line_number]
-        block = options[:block].lines.map do |line|
-          if line == command
-            "    > #{line}"
-          else
-            "      #{line}"
-          end
-        end.join("")
-
-        msg = "Error parsing (line:#{line_number}):\n"
-        msg << ">  '#{command.strip}'\n"
-        msg << "No such registered command: '#{keyword}'\n"
-        msg << "registered commands: #{Rundoc.known_commands.inspect}\n\n"
-        msg << block
-        msg << "\n"
-        super(msg)
-      end
-    end
-
-    COMMAND_REGEX = Rundoc::Parser::COMMAND_REGEX # todo: move whole thing
-    AUTOGEN_WARNING = "\n<!-- STOP. This document is autogenerated. Do not manually modify. See the top of the doc for more details. -->"
-    attr_accessor :original, :fence, :lang, :code, :commands, :keyword
-
-    PARTIAL_RESULT = []
-    PARTIAL_ENV = {}
-
-    def initialize(match, keyword:, context:)
-      @original = match.to_s
-      @commands = []
-      @stack = []
-      @keyword = keyword
-      @context = context
-      @fence = match[:fence]
-      @lang = match[:lang]
-      @code = match[:contents]
-      parse_code_command
-      PARTIAL_RESULT.clear
-      PARTIAL_ENV.clear
-    end
-
-    def render
-      result = []
-      env = {}
-      env[:commands] = []
-      env[:fence_start] = "#{fence}#{lang}"
-      env[:fence_end] = "#{fence}#{AUTOGEN_WARNING}"
-      env[:before] = []
-      env[:after] = []
-      env[:context] = @context
-
-      @stack.each do |s|
-        unless s.respond_to?(:call)
-          result << s
-          next
-        end
-
-        code_command = s
-        code_output = code_command.call(env) || ""
-        code_line = code_command.to_md(env) || ""
-
-        env[:commands] << {object: code_command, output: code_output, command: code_line}
-
-        tmp_result = []
-        tmp_result << code_line if code_command.render_command?
-        tmp_result << code_output if code_command.render_result?
-
-        result << tmp_result unless code_command.hidden?
-
-        PARTIAL_RESULT.replace(result)
-        PARTIAL_ENV.replace(env)
-      end
-
-      return "" if hidden?
-
-      self.class.to_doc(result: result, env: env)
-    end
-
-    def self.partial_result_to_doc
-      to_doc(result: PARTIAL_RESULT, env: PARTIAL_ENV)
-    end
-
-    def self.to_doc(result:, env:)
-      array = [env[:before]]
-
-      result.flatten!
-      result.compact!
-      result.map! { |s| s.respond_to?(:rstrip) ? s.rstrip : s }
-      result.reject!(&:empty?)
-      result.map!(&:to_s)
-
-      if !result.empty?
-        array << env[:fence_start]
-        array << result
-        array << env[:fence_end]
-      end
-      array << env[:after]
-
-      array.flatten!
-      array.compact!
-      array.map! { |s| s.respond_to?(:rstrip) ? s.rstrip : s }
-      array.reject!(&:empty?)
-      array.map!(&:to_s)
-
-      array.join("\n") << "\n"
-    end
-
-    # all of the commands are hidden
-    def hidden?
-      !not_hidden?
-    end
-
-    # one or more of the commands are not hidden
-    def not_hidden?
-      return true if commands.empty?
-      commands.map(&:not_hidden?).detect { |c| c }
-    end
-
-    def parse_code_command
-      parser = Rundoc::PegParser.new.code_block
-      tree = parser.parse(@code)
-      actual = Rundoc::PegTransformer.new.apply(tree)
-      actual = [actual] unless actual.is_a?(Array)
-      actual.each do |code_command|
-        @stack << "\n" if commands.last.is_a?(Rundoc::CodeCommand)
-        @stack << code_command
-        commands << code_command
-      end
-    rescue ::Parslet::ParseFailed => e
-      raise "Could not compile code:\n#{@code}\nReason: #{e.message}"
-    end
-
-    # def check_parse_error(command, code_block)
-    #   return unless code_command = @stack.last
-    #   return unless code_command.is_a?(Rundoc::CodeCommand::NoSuchCommand)
-    #   @original.lines.each_with_index do |line, index|
-    #     next unless line == command
-    #     raise ParseError.new(keyword:     code_command.keyword,
-    #                          block:       code_block,
-    #                          command:     command,
-    #                          line_number: index.next)
-    #   end
-    # end
-  end
-end