rundoc 4.1.4 → 6.0.0

data/lib/rundoc/code_command/deferred.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Rundoc
+  module CodeCommand
+    # Hold enough information to construct commands, but don't yet
+    #
+    # Allows us to separate parse time constructs from runtime injectables
+    # (such as IO). Which gives us a cleaner running model.
+    class Deferred
+      attr_accessor :render_result, :render_command,
+        :contents, :keyword, :original_args
+
+      alias_method :render_result?, :render_result
+      alias_method :render_command?, :render_command
+
+      attr_reader :runner_klass
+
+      def initialize(args_instance:, runner_klass:, always_hidden: false)
+        @args_instance = args_instance
+        @runner_klass = runner_klass
+        @always_hidden = always_hidden
+      end
+
+      def hidden?
+        !render_command? && !render_result?
+      end
+
+      def not_hidden?
+        !hidden?
+      end
+
+      def push(contents)
+        @contents ||= +""
+        @contents << contents
+      end
+      alias_method :<<, :push
+
+      def build(io: $stdout)
+        @built ||= begin
+          runner = @runner_klass.new(
+            user_args: @args_instance,
+            render_command: render_command,
+            render_result: render_result,
+            contents: @contents,
+            io: io
+          )
+          if @always_hidden
+            @render_command = false
+            @render_result = false
+          end
+          runner
+        end
+      rescue UnknownCommand
+        raise "No such command registered with rundoc #{keyword.inspect} for `#{keyword} #{original_args}`"
+      end
+
+      def call(env = {})
+        build.call(env)
+      end
+
+      def to_md(env = {})
+        build.to_md(env)
+      end
+    end
+  end
+end

data/lib/rundoc/code_command/empty_binding.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "erb"
+
+class EmptyBinding
+  def self.create
+    new.empty_binding
+  end
+
+  def empty_binding
+    binding
+  end
+end
+
+module Rundoc::CodeCommand
+  RUNDOC_ERB_BINDINGS = Hash.new { |h, k| h[k] = EmptyBinding.create }
+  RUNDOC_DEFAULT_ERB_BINDING = "default"
+end

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

@@ -1,18 +1,39 @@
+# frozen_string_literal: true
+
 class Rundoc::CodeCommand::FileCommand
-  class Append < Rundoc::CodeCommand
-    include FileUtil
+  class AppendArgs
+    attr_reader :filename
 
     def initialize(filename)
-      @filename, line = filename.split("#")
+      @filename = filename
+    end
+  end
+
+  class AppendRunner
+    NEWLINE = Rundoc::CodeCommand::WriteRunner::NEWLINE
+
+    include Rundoc::CodeCommand::FileUtil
+
+    attr_reader :io, :contents
+
+    def initialize(user_args:, render_command:, render_result:, io:, contents: nil)
+      @filename, line = user_args.filename.split("#")
       @line_number = if line
         Integer(line)
       end
+      @io = io
+      @render_command = render_command
+      @contents = contents.dup if contents && !contents.empty?
+    end
+
+    def render_command?
+      @render_command
     end
 
     def to_md(env)
       return unless render_command?
 
-      if env[:commands].any? { |c| c[:object].not_hidden? }
+      if env[:commands].any? { |c| c[:visibility].not_hidden? }
         raise "Must call append in its own code section"
       end
 
@@ -34,7 +55,7 @@ class Rundoc::CodeCommand::FileCommand
     end
 
     def concat_with_newline(str1, str2)
-      result = ""
+      result = +""
       result << str1
       result << "\n" unless ends_in_newline?(result)
       result << str2
@@ -61,10 +82,10 @@ class Rundoc::CodeCommand::FileCommand
       mkdir_p
       doc = File.read(filename)
       if @line_number
-        puts "Writing to: '#{filename}' line #{@line_number} with: #{contents.inspect}"
+        io.puts "Writing to: '#{filename}' line #{@line_number} with: #{contents.inspect}"
         doc = insert_contents_into_at_line(doc)
       else
-        puts "Appending to file: '#{filename}' with: #{contents.inspect}"
+        io.puts "Appending to file: '#{filename}' with: #{contents.inspect}"
         doc = concat_with_newline(doc, contents)
       end
 
@@ -74,4 +95,4 @@ class Rundoc::CodeCommand::FileCommand
   end
 end
 
-Rundoc.register_code_command(:"file.append", Rundoc::CodeCommand::FileCommand::Append)
+Rundoc.register_code_command(keyword: :"file.append", args_klass: Rundoc::CodeCommand::FileCommand::AppendArgs, runner_klass: Rundoc::CodeCommand::FileCommand::AppendRunner)

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

@@ -1,13 +1,35 @@
+# frozen_string_literal: true
+
 class Rundoc::CodeCommand::FileCommand
-  class Remove < Rundoc::CodeCommand
-    include FileUtil
+  class RemoveArgs
+    attr_reader :filename
 
     def initialize(filename)
       @filename = filename
     end
+  end
+
+  class RemoveRunner
+    NEWLINE = Object.new
+    def NEWLINE.to_s
+      ""
+    end
+
+    def NEWLINE.empty?
+      false
+    end
+    include Rundoc::CodeCommand::FileUtil
+
+    attr_reader :io, :contents
+
+    def initialize(user_args:, render_command:, render_result:, io:, contents: nil)
+      @filename = user_args.filename
+      @io = io
+      @contents = contents.dup if contents && !contents.empty?
+    end
 
     def to_md(env)
-      if env[:commands].any? { |c| c[:object].not_hidden? }
+      if env[:commands].any? { |c| c[:visibility].not_hidden? }
         raise "Must call remove in its own code section"
       end
 
@@ -17,7 +39,7 @@ class Rundoc::CodeCommand::FileCommand
     end
 
     def call(env = {})
-      puts "Deleting '#{contents.strip}' from #{filename}"
+      io.puts "Deleting '#{contents.strip}' from #{filename}"
       raise "#{filename} does not exist" unless File.exist?(filename)
 
       regex = /^\s*#{Regexp.quote(contents)}/
@@ -30,4 +52,4 @@ class Rundoc::CodeCommand::FileCommand
   end
 end
 
-Rundoc.register_code_command(:"file.remove", Rundoc::CodeCommand::FileCommand::Remove)
+Rundoc.register_code_command(keyword: :"file.remove", args_klass: Rundoc::CodeCommand::FileCommand::RemoveArgs, runner_klass: Rundoc::CodeCommand::FileCommand::RemoveRunner)

data/lib/rundoc/code_command/no_such_command.rb

@@ -1,8 +1,13 @@
+# frozen_string_literal: true
+
 module Rundoc
-  class CodeCommand
-    class NoSuchCommand < Rundoc::CodeCommand
+  module CodeCommand
+    class NoSuchCommand
+      def initialize(user_args: nil, render_command: false, render_result: false, io: nil, contents: nil)
+      end
+
       def call(env = {})
-        raise "No such command registered with rundoc: #{@keyword.inspect} for '#{@keyword} #{@original_args}'"
+        raise UnknownCommand
       end
     end
   end

data/lib/rundoc/code_command/pipe.rb

@@ -1,11 +1,21 @@
+# frozen_string_literal: true
+
 module Rundoc
-  class CodeCommand
-    class Pipe < Rundoc::CodeCommand
-      # ::: ls
-      # ::: | tail -n 2
-      # => "test\ntmp.file\n"
+  module CodeCommand
+    class PipeArgs
+      attr_reader :line
+
       def initialize(line)
-        @delegate = parse(line)
+        @line = line
+      end
+    end
+
+    class PipeRunner
+      attr_reader :io
+
+      def initialize(user_args:, render_command:, render_result:, io:, contents: nil)
+        @io = io
+        @delegate = parse(user_args.line)
       end
 
       # before: "",
@@ -14,10 +24,10 @@ module Rundoc
       #   [[cmd, output], [cmd, output]]
       def call(env = {})
         last_command = env[:commands].last
-        puts "Piping: results of '#{last_command[:command]}' to '#{@delegate}'"
+        io.puts "Piping: results of '#{last_command[:command]}' to '#{@delegate}'"
 
         @delegate.push(last_command[:output])
-        @delegate.call(env)
+        @delegate.build(io: io).call(env)
       end
 
       def to_md(env = {})
@@ -31,17 +41,27 @@ module Rundoc
 
         actual = actual.first if actual.is_a?(Array)
 
-        actual = Rundoc::CodeCommand::Bash.new(code) if actual.is_a?(Rundoc::CodeCommand::NoSuchCommand)
-        actual
-
-      # Since `| tail -n 2` does not start with a `$` assume any "naked" commands
-      # are bash
+        if actual.runner_klass == Rundoc::CodeCommand::NoSuchCommand
+          bash_deferred(code)
+        else
+          actual
+        end
       rescue Parslet::ParseFailed
-        Rundoc::CodeCommand::Bash.new(code)
+        bash_deferred(code)
+      end
+
+      private def bash_deferred(code)
+        deferred = Rundoc::CodeCommand::Deferred.new(
+          args_instance: Rundoc::CodeCommand::BashArgs.new(code),
+          runner_klass: Rundoc::CodeCommand::BashRunner
+        )
+        deferred.render_command = false
+        deferred.render_result = false
+        deferred
       end
     end
   end
 end
 
-Rundoc.register_code_command(:pipe, Rundoc::CodeCommand::Pipe)
-Rundoc.register_code_command(:|, Rundoc::CodeCommand::Pipe)
+Rundoc.register_code_command(keyword: :pipe, args_klass: Rundoc::CodeCommand::PipeArgs, runner_klass: Rundoc::CodeCommand::PipeRunner)
+Rundoc.register_code_command(keyword: :|, args_klass: Rundoc::CodeCommand::PipeArgs, runner_klass: Rundoc::CodeCommand::PipeRunner)

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

@@ -1,44 +1,54 @@
+# frozen_string_literal: true
+
 require_relative "../print/erb"
 
-class Rundoc::CodeCommand
-  class PreErb < Rundoc::CodeCommand
+module Rundoc::CodeCommand
+  class PreErbArgs
+    attr_reader :line
+
     def initialize(line)
       @line = line
+    end
+  end
+
+  class PreErbRunner
+    attr_reader :io, :contents
+
+    def initialize(user_args:, render_command:, render_result:, io:, contents: nil)
+      @line = user_args.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
+      @render_command = render_command
+      @render_result = render_result
+      @io = io
+      @contents = contents.dup if contents && !contents.empty?
     end
 
-    # Visibility is injected by the parser, capture it and pass it to the delegate
-    def render_result=(value)
-      @render_delegate_result = value
+    def render_command?
+      @render_command
     end
 
-    def render_command=(value)
-      @render_delegate_command = value
+    def render_result?
+      @render_result
     end
 
     def code
       @code ||= begin
         vis = +""
-        vis += @render_delegate_command ? ">" : "-"
-        vis += @render_delegate_result ? ">" : "-"
+        vis += render_command? ? ">" : "-"
+        vis += render_result? ? ">" : "-"
         code = [@line, @contents]
           .compact
           .reject(&:empty?)
           .join("\n")
         @template = ":::#{vis} #{code}"
 
-        puts "pre.erb: Applying ERB, template:\n#{@template}"
+        io.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"
+        io.puts "pre.erb: ERB result:\n#{result}"
+        io.puts "pre.erb: done, ready to delegate"
         result
       end
     end
@@ -60,4 +70,4 @@ class Rundoc::CodeCommand
     end
   end
 end
-Rundoc.register_code_command(:"pre.erb", Rundoc::CodeCommand::PreErb)
+Rundoc.register_code_command(keyword: :"pre.erb", args_klass: Rundoc::CodeCommand::PreErbArgs, runner_klass: Rundoc::CodeCommand::PreErbRunner, always_hidden: true)

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

@@ -1,23 +1,34 @@
-require "erb"
+# frozen_string_literal: true
 
-class EmptyBinding
-  def self.create
-    new.empty_binding
-  end
-
-  def empty_binding
-    binding
-  end
-end
+require_relative "../empty_binding"
 
-class Rundoc::CodeCommand
-  RUNDOC_ERB_BINDINGS = Hash.new { |h, k| h[k] = EmptyBinding.create }
-  RUNDOC_DEFAULT_ERB_BINDING = "default"
+module Rundoc::CodeCommand
+  class PrintERBArgs
+    attr_reader :line, :binding_name
 
-  class PrintERB < Rundoc::CodeCommand
     def initialize(line = nil, binding: RUNDOC_DEFAULT_ERB_BINDING)
       @line = line
-      @binding = RUNDOC_ERB_BINDINGS[binding]
+      @binding_name = binding
+    end
+  end
+
+  class PrintERBRunner
+    attr_reader :contents
+
+    def initialize(user_args:, render_command:, render_result:, io: nil, contents: nil)
+      @line = user_args.line
+      @binding = RUNDOC_ERB_BINDINGS[user_args.binding_name]
+      @render_command = render_command
+      @render_result = render_result
+      @contents = contents.dup if contents && !contents.empty?
+    end
+
+    def render_command?
+      @render_command
+    end
+
+    def render_result?
+      @render_result
     end
 
     def to_md(env)
@@ -45,4 +56,4 @@ class Rundoc::CodeCommand
     end
   end
 end
-Rundoc.register_code_command(:"print.erb", Rundoc::CodeCommand::PrintERB)
+Rundoc.register_code_command(keyword: :"print.erb", args_klass: Rundoc::CodeCommand::PrintERBArgs, runner_klass: Rundoc::CodeCommand::PrintERBRunner)

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

@@ -1,8 +1,31 @@
-class Rundoc::CodeCommand
-  class PrintText < Rundoc::CodeCommand
-    def initialize(line)
+# frozen_string_literal: true
+
+module Rundoc::CodeCommand
+  class PrintTextArgs
+    attr_reader :line
+
+    def initialize(line = nil)
       @line = line
     end
+  end
+
+  class PrintTextRunner
+    attr_reader :contents
+
+    def initialize(user_args:, render_command:, render_result:, io: nil, contents: nil)
+      @line = user_args.line
+      @render_command = render_command
+      @render_result = render_result
+      @contents = contents.dup if contents && !contents.empty?
+    end
+
+    def render_command?
+      @render_command
+    end
+
+    def render_result?
+      @render_result
+    end
 
     def to_md(env)
       if render_before?
@@ -12,10 +35,6 @@ class Rundoc::CodeCommand
       ""
     end
 
-    def hidden?
-      !render_result?
-    end
-
     def call(env = {})
       if render_before?
         ""
@@ -30,4 +49,4 @@ class Rundoc::CodeCommand
   end
 end
 
-Rundoc.register_code_command(:"print.text", Rundoc::CodeCommand::PrintText)
+Rundoc.register_code_command(keyword: :"print.text", args_klass: Rundoc::CodeCommand::PrintTextArgs, runner_klass: Rundoc::CodeCommand::PrintTextRunner)

data/lib/rundoc/code_command/raw.rb

@@ -1,9 +1,21 @@
+# frozen_string_literal: true
+
 module Rundoc
-  class CodeCommand
-    class Raw < CodeCommand
-      def initialize(contents, visible: true)
-        @contents = contents
-        @render_result = visible
+  module CodeCommand
+    # Wraps lines inside a fenced code block that are not rundoc commands.
+    # These are rendered as-is without executing any code.
+    #
+    # Example:
+    #
+    #   ```ruby
+    #   gem 'sqlite3'       <- parsed as Raw
+    #   :::>> $ echo "hi"   <- parsed as a code command
+    #   ```
+    class Raw
+      attr_reader :contents
+
+      def initialize(user_args: nil, render_command: true, render_result: true, io: nil, contents: nil)
+        @contents = contents.dup if contents && !contents.empty?
       end
 
       def call(env = {})

data/lib/rundoc/code_command/rundoc/ensure_later.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module ::Rundoc::CodeCommand
+  class RundocCommand
+    class EnsureLaterArgs
+      MAPPING = {
+        cwd: ->(context:) {
+          Dir.pwd
+        },
+        rundoc_root: ->(context:) {
+          context.output_dir.to_s
+        }
+      }.freeze
+
+      def initialize(dir:)
+        @dir = dir
+        @logic = MAPPING[dir] or raise ArgumentError, "Invalid argument dir: #{dir} must be one of #{MAPPING.keys}"
+      end
+
+      def call(context:)
+        @logic.call(context: context)
+      end
+
+      def to_s
+        @dir
+      end
+    end
+
+    class EnsureLaterRunner
+      attr_reader :io, :contents
+
+      def initialize(user_args:, render_command:, render_result:, io:, contents: nil)
+        @io = io
+        @contents = contents.dup if contents && !contents.empty?
+        @dir = user_args
+        @binding = RUNDOC_ERB_BINDINGS[RUNDOC_DEFAULT_ERB_BINDING]
+      end
+
+      def to_md(env = {})
+        ""
+      end
+
+      def call(env = {})
+        resolved_dir = @dir.call(context: env[:context])
+
+        io.puts "Registering ensure_later block (dir: #{@dir} => #{resolved_dir})"
+        Rundoc.add_ensure_later(dir: resolved_dir, code: @contents, binding: @binding)
+        ""
+      end
+    end
+  end
+end
+
+Rundoc.register_code_command(
+  keyword: :"rundoc.ensure_later",
+  args_klass: Rundoc::CodeCommand::RundocCommand::EnsureLaterArgs,
+  runner_klass: Rundoc::CodeCommand::RundocCommand::EnsureLaterRunner,
+  always_hidden: true
+)

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

@@ -1,13 +1,28 @@
-class ::Rundoc::CodeCommand
+# frozen_string_literal: true
+
+module ::Rundoc::CodeCommand
   class RundocCommand
-    class Require < ::Rundoc::CodeCommand
-      # Pass in the relative path of another rundoc document in order to
-      # run all of it's commands. Resulting contents will be displayed
-      # in current document
+    class RequireArgs
+      attr_reader :path
+
       def initialize(path)
         raise "Path must be relative (i.e. start with `.` or `..`. #{path.inspect} does not" unless path.start_with?(".")
         @path = Pathname.new(path)
       end
+    end
+
+    class RequireRunner
+      attr_reader :io
+
+      def initialize(user_args:, render_command:, render_result:, io:, contents: nil)
+        @path = user_args.path
+        @io = io
+        @render_result = render_result
+      end
+
+      def render_result?
+        @render_result
+      end
 
       def to_md(env = {})
         ""
@@ -24,28 +39,21 @@ class ::Rundoc::CodeCommand
             output_dir: execution_context.output_dir,
             screenshots_dirname: execution_context.screenshots_dir,
             with_contents_dir: execution_context.with_contents_dir
-          )
+          ),
+          io: io
         ).to_md
 
         if render_result?
-          puts "rundoc.require: Done executing #{@path.to_s.inspect}, putting contents into document"
+          io.puts "rundoc.require: Done executing #{@path.to_s.inspect}, putting contents into document"
           env[:before] << output
         else
-          puts "rundoc.require: Done executing #{@path.to_s.inspect}, quietly"
+          io.puts "rundoc.require: Done executing #{@path.to_s.inspect}, quietly"
         end
 
         ""
       end
-
-      def hidden?
-        !render_result?
-      end
-
-      def not_hidden?
-        !hidden?
-      end
     end
   end
 end
 
-Rundoc.register_code_command(:"rundoc.require", ::Rundoc::CodeCommand::RundocCommand::Require)
+Rundoc.register_code_command(keyword: :"rundoc.require", args_klass: ::Rundoc::CodeCommand::RundocCommand::RequireArgs, runner_klass: ::Rundoc::CodeCommand::RundocCommand::RequireRunner)