rundoc 4.1.3 → 5.0.0

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,3 +1,5 @@
+# frozen_string_literal: true
+
 require "erb"
 
 class EmptyBinding
@@ -10,14 +12,36 @@ class EmptyBinding
   end
 end
 
-class Rundoc::CodeCommand
+module Rundoc::CodeCommand
   RUNDOC_ERB_BINDINGS = Hash.new { |h, k| h[k] = EmptyBinding.create }
   RUNDOC_DEFAULT_ERB_BINDING = "default"
 
-  class PrintERB < Rundoc::CodeCommand
+  class PrintERBArgs
+    attr_reader :line, :binding_name
+
     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 +69,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/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)

data/lib/rundoc/code_command/rundoc_command.rb

@@ -1,8 +1,22 @@
+# frozen_string_literal: true
+
 module ::Rundoc
-  class CodeCommand
-    class ::RundocCommand < ::Rundoc::CodeCommand
-      def initialize(contents = "")
-        @contents = contents
+  module CodeCommand
+    class RundocCommandArgs
+      attr_reader :code
+
+      def initialize(code = "")
+        @code = code
+      end
+    end
+
+    class RundocCommandRunner
+      attr_reader :io, :contents
+
+      def initialize(user_args:, render_command:, render_result:, io:, contents: nil)
+        @io = io
+        @contents = contents.dup if contents && !contents.empty?
+        @contents = user_args.code + (@contents || +"")
       end
 
       def to_md(env = {})
@@ -10,7 +24,7 @@ module ::Rundoc
       end
 
       def call(env = {})
-        puts "Running: #{contents}"
+        io.puts "Running: #{contents}"
         eval(contents) # rubocop:disable Security/Eval
         ""
       end
@@ -18,8 +32,7 @@ module ::Rundoc
   end
 end
 
-Rundoc.register_code_command(:rundoc, RundocCommand)
-Rundoc.register_code_command(:"rundoc.configure", RundocCommand)
+Rundoc.register_code_command(keyword: :rundoc, args_klass: Rundoc::CodeCommand::RundocCommandArgs, runner_klass: Rundoc::CodeCommand::RundocCommandRunner)
+Rundoc.register_code_command(keyword: :"rundoc.configure", args_klass: Rundoc::CodeCommand::RundocCommandArgs, runner_klass: Rundoc::CodeCommand::RundocCommandRunner)
 
-require "rundoc/code_command/rundoc/depend_on"
 require "rundoc/code_command/rundoc/require"

data/lib/rundoc/code_command/website/driver.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "capybara"
 
 Capybara::Selenium::Driver.load_selenium
@@ -6,7 +8,8 @@ class Rundoc::CodeCommand::Website
   class Driver
     attr_reader :session
 
-    def initialize(name:, url:, width: 1024, height: 720, visible: false)
+    def initialize(name:, url:, width: 1024, height: 720, visible: false, io: $stdout, read_timeout: 60)
+      @io = io
       browser_options = ::Selenium::WebDriver::Chrome::Options.new
       browser_options.args << "--headless" unless visible
       browser_options.args << "--disable-gpu" if Gem.win_platform?
@@ -15,7 +18,10 @@ class Rundoc::CodeCommand::Website
       @width = width
       @height = height
 
-      @driver = Capybara::Selenium::Driver.new(nil, browser: :chrome, options: browser_options)
+      client = Selenium::WebDriver::Remote::Http::Default.new
+      client.read_timeout = read_timeout
+
+      @driver = Capybara::Selenium::Driver.new(nil, browser: :chrome, options: browser_options, http_client: client)
       driver_name = :"rundoc_driver_#{name}"
       Capybara.register_driver(driver_name) do |app|
         @driver
@@ -24,8 +30,20 @@ class Rundoc::CodeCommand::Website
       @session = Capybara::Session.new(driver_name)
     end
 
-    def visit(url)
-      @session.visit(url)
+    def visit(url, max_attempts: 3, delay: 1)
+      attempts = 0
+      begin
+        @session.visit(url)
+      rescue ::Net::ReadTimeout => e
+        attempts += 1
+        if attempts > max_attempts
+          raise e
+        else
+          @io.puts "Error visiting url (#{attempts}/#{max_attempts}) `#{url}`:\n#{e}"
+          sleep delay
+          retry
+        end
+      end
     end
 
     def timestamp
@@ -54,7 +72,7 @@ class Rundoc::CodeCommand::Website
       msg = +""
       msg << "Error running code #{code.inspect} at #{current_url.inspect}\n"
       msg << "saving a screenshot to: `tmp/error.png`"
-      puts msg
+      @io.puts msg
       error_path = env[:context].screenshots_dir.join("error.png")
       session.save_screenshot(error_path)
       raise e
@@ -66,13 +84,13 @@ class Rundoc::CodeCommand::Website
       file_name = self.class.next_screenshot_name
       file_path = screenshots_dir.join(file_name)
       session.save_screenshot(file_path)
-      puts "Screenshot saved to #{file_path}"
+      @io.puts "Screenshot saved to #{file_path}"
 
       return file_path unless upload
 
       case upload
       when "s3", "aws"
-        puts "Uploading screenshot to S3"
+        @io.puts "Uploading screenshot to S3"
         require "aws-sdk-s3"
         ENV.fetch("AWS_ACCESS_KEY_ID")
         s3 = Aws::S3::Resource.new(region: ENV.fetch("AWS_REGION"))

data/lib/rundoc/code_command/website/navigate.rb

@@ -1,8 +1,22 @@
+# frozen_string_literal: true
+
 class Rundoc::CodeCommand::Website
-  class Navigate < Rundoc::CodeCommand
+  class NavigateArgs
+    attr_reader :name
+
     def initialize(name:)
       @name = name
+    end
+  end
+
+  class NavigateRunner
+    attr_reader :io, :contents
+
+    def initialize(user_args:, render_command:, render_result:, io:, contents: nil)
+      @name = user_args.name
       @driver = nil
+      @io = io
+      @contents = contents.dup if contents && !contents.empty?
     end
 
     def driver
@@ -14,20 +28,12 @@ class Rundoc::CodeCommand::Website
     end
 
     def call(env = {})
-      puts "website.navigate [#{@name}]: #{contents}"
+      io.puts "website.navigate [#{@name}]: #{contents}"
       driver.safe_eval(contents, env)
       ""
     end
-
-    def hidden?
-      true
-    end
-
-    def not_hidden?
-      !hidden?
-    end
   end
 end
 
-Rundoc.register_code_command(:"website.nav", Rundoc::CodeCommand::Website::Navigate)
-Rundoc.register_code_command(:"website.navigate", Rundoc::CodeCommand::Website::Navigate)
+Rundoc.register_code_command(keyword: :"website.nav", args_klass: Rundoc::CodeCommand::Website::NavigateArgs, runner_klass: Rundoc::CodeCommand::Website::NavigateRunner)
+Rundoc.register_code_command(keyword: :"website.navigate", args_klass: Rundoc::CodeCommand::Website::NavigateArgs, runner_klass: Rundoc::CodeCommand::Website::NavigateRunner)