rundoc 4.1.4 → 5.0.0

data/lib/rundoc/code_command/write.rb

@@ -1,5 +1,7 @@
+# frozen_string_literal: true
+
 module Rundoc
-  class CodeCommand
+  module CodeCommand
     module FileUtil
       def filename
         files = Dir.glob(@filename)
@@ -15,16 +17,42 @@ module Rundoc
       end
     end
 
-    class Write < Rundoc::CodeCommand
-      include FileUtil
+    class WriteArgs
+      attr_reader :path
+
+      def initialize(path)
+        @path = Pathname(path)
+      end
+    end
+
+    class WriteRunner
+      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.path.to_s
+        @io = io
+        @render_command = render_command
+        @contents = contents.dup if contents && !contents.empty?
+      end
 
-      def initialize(filename)
-        @filename = filename
+      def render_command?
+        @render_command
       end
 
       def to_md(env)
         if render_command?
-          if env[:commands].any? { |c| c[:object].not_hidden? }
+          if env[:commands].any? { |c| c[:visibility].not_hidden? }
             raise "must call write in its own code section"
           end
           env[:before] << "In file `#{filename}` write:"
@@ -34,7 +62,7 @@ module Rundoc
       end
 
       def call(env = {})
-        puts "Writing to: '#{filename}'"
+        io.puts "Writing to: '#{filename}'"
         mkdir_p
         File.write(filename, contents)
         contents
@@ -43,8 +71,8 @@ module Rundoc
   end
 end
 
-Rundoc.register_code_command(:write, Rundoc::CodeCommand::Write)
-Rundoc.register_code_command(:"file.write", Rundoc::CodeCommand::Write)
+Rundoc.register_code_command(keyword: :write, args_klass: Rundoc::CodeCommand::WriteArgs, runner_klass: Rundoc::CodeCommand::WriteRunner)
+Rundoc.register_code_command(keyword: :"file.write", args_klass: Rundoc::CodeCommand::WriteArgs, runner_klass: Rundoc::CodeCommand::WriteRunner)
 
 require "rundoc/code_command/file_command/append"
 require "rundoc/code_command/file_command/remove"

data/lib/rundoc/code_command.rb

@@ -1,55 +1,11 @@
-module Rundoc
-  # Generic CodeCommand class to be inherited
-  #
-  class CodeCommand
-    # Newlines are stripped and re-added, this tells the project that
-    # we're intentionally wanting an extra newline
-    NEWLINE = Object.new
-    def NEWLINE.to_s
-      ""
-    end
-
-    def NEWLINE.empty?
-      false
-    end
-
-    attr_accessor :render_result, :render_command,
-      :command, :contents, :keyword,
-      :original_args
-
-    alias_method :render_result?, :render_result
-    alias_method :render_command?, :render_command
-
-    def initialize(*args)
-    end
+# frozen_string_literal: true
 
-    def hidden?
-      !render_command? && !render_result?
-    end
-
-    def not_hidden?
-      !hidden?
-    end
-
-    def push(contents)
-      @contents ||= ""
-      @contents << contents
-    end
-    alias_method :<<, :push
-
-    # Executes command to build project
-    # Is expected to return the result of the command
-    def call(env = {})
-      raise "not implemented on #{inspect}"
-    end
-
-    # the output of the command, i.e. `$ cat foo.txt`
-    def to_md(env = {})
-      raise "not implemented on #{inspect}"
-    end
+module Rundoc
+  module CodeCommand
   end
 end
 
+require "rundoc/code_command/deferred"
 require "rundoc/code_command/bash"
 require "rundoc/code_command/pipe"
 require "rundoc/code_command/write"
@@ -61,3 +17,4 @@ require "rundoc/code_command/website"
 require "rundoc/code_command/print/text"
 require "rundoc/code_command/print/erb"
 require "rundoc/code_command/pre/erb"
+require "rundoc/code_command/comment"

data/lib/rundoc/context/after_build.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Rundoc
   module Context
     # Public interface for the `Rundoc.after_build` proc

data/lib/rundoc/context/execution.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Rundoc
   module Context
     # Holds configuration for the currently executing script

data/lib/rundoc/document.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Rundoc
   # Represents a single rundoc file on disk,
   #
@@ -11,7 +13,8 @@ module Rundoc
 
     attr_reader :contents, :stack, :context
 
-    def initialize(contents, context:)
+    def initialize(contents, context:, io: $stdout)
+      @io = io
       @context = context
       @contents = contents
       @original = contents.dup
@@ -59,7 +62,8 @@ module Rundoc
             fence: match[:fence],
             lang: match[:lang],
             code: match[:contents],
-            context: context
+            context: context,
+            io: @io
           )
         end
         @contents = tail

data/lib/rundoc/fenced_code_block.rb

@@ -15,7 +15,7 @@ module Rundoc
     def executed_commands
       raise "Nothing executed" unless @env[:commands].any?
 
-      @env[:commands].map { |c| c[:object] }
+      @env[:commands].map { |c| c[:visibility] }
     end
 
     # @param fence [String] the fence used to start the code block like "```".
@@ -24,7 +24,8 @@ module Rundoc
     # @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:)
+    def initialize(fence:, lang:, code:, context:, io: $stdout)
+      @io = io
       @fence = fence
       @lang = lang
       @code = code
@@ -54,12 +55,13 @@ module Rundoc
       env[:after] = []
       env[:context] = @context
       env[:stack] = @stack
+      while (item = @stack.pop)
+        code_command = item.build(io: @io)
 
-      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?
+        result << code_line if item.render_command?
+        result << code_output if item.render_result?
 
         PARTIAL_RESULT.replace(result)
         PARTIAL_ENV.replace(env)
@@ -67,11 +69,12 @@ module Rundoc
         env[:commands] << {
           object: code_command,
           output: code_output,
-          command: code_line
+          command: code_line,
+          visibility: item
         }
       end
 
-      if env[:commands].any? { |c| c[:object].not_hidden? }
+      if env[:commands].any? { |c| c[:visibility].not_hidden? }
         @rendered = self.class.to_doc(result: result, env: env)
       end
       self

data/lib/rundoc/peg_parser.rb

@@ -1,9 +1,12 @@
+# frozen_string_literal: true
+
 require "parslet"
 
 module Rundoc
   class PegParser < Parslet::Parser
     rule(:spaces) { match('\s').repeat(1) }
     rule(:spaces?) { spaces.maybe }
+    rule(:horizontal_spaces) { match('[ \t]').repeat(1) }
     rule(:comma) { spaces? >> str(",") >> spaces? }
     rule(:digit) { match("[0-9]") }
     rule(:lparen) { str("(") >> spaces? }
@@ -87,7 +90,7 @@ module Rundoc
     }
 
     rule(:seattle_method) {
-      funcall >> spaces >>
+      funcall >> horizontal_spaces >>
         args.as(:args)
     }
 
@@ -242,8 +245,8 @@ module Rundoc
         raise TransformError.new(message: message, line_and_column: line_and_column)
       end
       Visability.new(
-        command: command.to_s == ">".freeze,
-        result: result.to_s == ">".freeze
+        command: command.to_s == ">",
+        result: result.to_s == ">"
       )
     }
 
@@ -265,16 +268,21 @@ module Rundoc
       code_command
     }
 
-    # The lines before a CodeCommand are rendered
-    # without running any code
     rule(raw_code: simple(:raw_code)) {
-      CodeCommand::Raw.new(raw_code)
+      deferred = CodeCommand::Deferred.new(args_instance: nil, runner_klass: CodeCommand::Raw)
+      deferred.render_command = false
+      deferred.render_result = true
+      deferred.push(raw_code.to_s)
+      deferred
     }
 
-    # Sometimes
     rule(raw_code: sequence(:raw_code)) {
-      hidden = raw_code.nil? || raw_code.empty?
-      CodeCommand::Raw.new(raw_code, visible: !hidden)
+      visible = !raw_code.nil? && !raw_code.empty?
+      deferred = CodeCommand::Deferred.new(args_instance: nil, runner_klass: CodeCommand::Raw)
+      deferred.render_command = false
+      deferred.render_result = visible
+      deferred.push(raw_code.map(&:to_s).join)
+      deferred
     }
   end
 end

data/lib/rundoc/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Rundoc
-  VERSION = "4.1.4"
+  VERSION = "5.0.0"
 end

data/lib/rundoc.rb

@@ -5,43 +5,78 @@ require "rundoc/version"
 module Rundoc
   extend self
 
+  class UnknownCommand < StandardError; end
+
   def code_command_from_keyword(keyword, args)
-    klass = code_command(keyword.to_sym) || Rundoc::CodeCommand::NoSuchCommand
-    original_args = args.dup
-    if args.is_a?(Array) && args.last.is_a?(Hash)
-      kwargs = args.pop
-      cc = klass.new(*args, **kwargs)
-    elsif args.is_a?(Hash)
-      cc = klass.new(**args)
+    args_klass = code_command(keyword.to_sym)
+    original_args = args&.dup
+
+    if args_klass
+      runner_klass = user_args_runner[keyword]
+
+      if args.is_a?(Array) && args.last.is_a?(Hash)
+        kwargs = args.pop
+        user_args = args_klass.new(*args, **kwargs)
+      elsif args.is_a?(Hash)
+        user_args = args_klass.new(**args)
+      else
+        user_args = args_klass.new(*args)
+      end
+    elsif keyword.start_with?("#")
+      args_klass = Rundoc::CodeCommand::CommentArgs
+      runner_klass = Rundoc::CodeCommand::CommentRunner
+      remainder = keyword.to_s.delete_prefix("#")
+      comment_text = [remainder, args].compact.join(" ").strip
+      user_args = args_klass.new(comment_text.empty? ? nil : comment_text)
     else
-      cc = klass.new(*args)
+      runner_klass = Rundoc::CodeCommand::NoSuchCommand
+      user_args = nil
     end
 
-    cc.original_args = original_args
-    cc.keyword = keyword
-    cc
+    deferred = CodeCommand::Deferred.new(
+      args_instance: user_args,
+      runner_klass: runner_klass,
+      always_hidden: always_hidden_commands[keyword] || keyword.start_with?("#")
+    )
+    deferred.original_args = original_args
+    deferred.keyword = keyword
+    deferred
   rescue ArgumentError => e
     raise ArgumentError, "Wrong method signature for #{keyword} with arguments: #{original_args.inspect}, error:\n #{e.message}"
   end
 
+  def user_code_runner_klass
+    @user_code_runner_klass ||= {}
+  end
+
   def parser_options
     @parser_options ||= {}
   end
 
-  def code_lookup
-    @code_lookup ||= {}
+  def user_args_runner
+    @user_args_runner ||= {}
+  end
+
+  def user_args
+    @user_args ||= {}
   end
 
   def code_command(keyword)
-    code_lookup[:"#{keyword}"]
+    user_args[:"#{keyword}"]
   end
 
   def known_commands
-    code_lookup.keys
+    user_args.keys
+  end
+
+  def register_code_command(keyword:, args_klass:, runner_klass:, always_hidden: false)
+    user_args[keyword] = args_klass
+    user_args_runner[keyword] = runner_klass
+    always_hidden_commands[keyword] = always_hidden
   end
 
-  def register_code_command(keyword, klass)
-    code_lookup[keyword] = klass
+  def always_hidden_commands
+    @always_hidden_commands ||= {}
   end
 
   def configure(&block)

data/rundoc.gemspec

@@ -16,6 +16,8 @@ Gem::Specification.new do |gem|
   gem.executables = gem.files.grep(%r{^bin/}).map { |f| File.basename(f) }
   gem.require_paths = ["lib"]
 
+  gem.required_ruby_version = ">= 3.2"
+
   gem.add_dependency "thor"
   gem.add_dependency "parslet", "~> 2"
   gem.add_dependency "capybara", "~> 3"

data/test/rundoc/code_commands/append_file_test.rb

@@ -7,8 +7,13 @@ class AppendFileTest < Minitest::Test
         file = "foo.rb"
         `echo 'foo' >> #{file}`
 
-        cc = Rundoc::CodeCommand::FileCommand::Append.new(file)
-        cc << "bar"
+        cc = Rundoc::CodeCommand::FileCommand::AppendRunner.new(
+          render_command: false,
+          render_result: false,
+          io: StringIO.new,
+          user_args: Rundoc::CodeCommand::FileCommand::AppendArgs.new(file),
+          contents: "bar"
+        )
         cc.call
 
         result = File.read(file)
@@ -16,8 +21,13 @@ class AppendFileTest < Minitest::Test
         assert_match(/foo/, result)
         assert_match(/bar/, result)
 
-        cc = Rundoc::CodeCommand::FileCommand::Append.new(file)
-        cc << "baz"
+        cc = Rundoc::CodeCommand::FileCommand::AppendRunner.new(
+          render_command: false,
+          render_result: false,
+          io: StringIO.new,
+          user_args: Rundoc::CodeCommand::FileCommand::AppendArgs.new(file),
+          contents: "baz"
+        )
         cc.call
 
         actual = File.read(file)
@@ -39,8 +49,13 @@ class AppendFileTest < Minitest::Test
         line = 2
         `echo '#{contents}' >> #{file}`
 
-        cc = Rundoc::CodeCommand::FileCommand::Append.new("#{file}##{line}")
-        cc << "gem 'pg'"
+        cc = Rundoc::CodeCommand::FileCommand::AppendRunner.new(
+          render_command: false,
+          render_result: false,
+          io: StringIO.new,
+          user_args: Rundoc::CodeCommand::FileCommand::AppendArgs.new("#{file}##{line}"),
+          contents: "gem 'pg'"
+        )
         cc.call
 
         expected = "source https://rubygems.org\ngem 'pg'\ngem rails, 4.0.0\n\n"
@@ -54,8 +69,13 @@ class AppendFileTest < Minitest::Test
       Dir.chdir(dir) do
         filename = "file-#{Time.now.utc.strftime("%Y%m%d%H%M%S")}.txt"
         FileUtils.touch(filename)
-        cc = Rundoc::CodeCommand::FileCommand::Append.new("file-*.txt")
-        cc << "some text"
+        cc = Rundoc::CodeCommand::FileCommand::AppendRunner.new(
+          render_command: false,
+          render_result: false,
+          io: StringIO.new,
+          user_args: Rundoc::CodeCommand::FileCommand::AppendArgs.new("file-*.txt"),
+          contents: "some text"
+        )
         cc.call
 
         assert_equal "\nsome text\n", File.read(filename)
@@ -69,8 +89,13 @@ class AppendFileTest < Minitest::Test
         FileUtils.touch("file-1234.txt")
         FileUtils.touch("file-5678.txt")
         assert_raises do
-          cc = Rundoc::CodeCommand::FileCommand::Append.new("file-*.txt")
-          cc << "some text"
+          cc = Rundoc::CodeCommand::FileCommand::AppendRunner.new(
+            render_command: false,
+            render_result: false,
+            io: StringIO.new,
+            user_args: Rundoc::CodeCommand::FileCommand::AppendArgs.new("file-*.txt"),
+            contents: "some text"
+          )
           cc.call
         end
       end

data/test/rundoc/code_commands/background_test.rb

@@ -6,33 +6,35 @@ class BackgroundTest < Minitest::Test
       Dir.chdir(dir) do
         # Intentionally out of order, should not raise an error as long as "cat"
         # command exists at execution time
-        stdin_write = Rundoc::CodeCommand::Background::StdinWrite.new(
+        stdin_write = Rundoc::CodeCommand::Background::StdinWriteRunner.new(render_command: false, render_result: false, io: StringIO.new, user_args: Rundoc::CodeCommand::Background::StdinWriteArgs.new(
           "hello there",
           name: "cat",
           wait: "hello"
-        )
+        ))
 
-        background_start = Rundoc::CodeCommand::Background::Start.new("cat",
-          name: "cat")
+        background_start = Rundoc::CodeCommand::Background::StartRunner.new(render_command: false, render_result: false, io: StringIO.new, user_args: Rundoc::CodeCommand::Background::StartArgs.new("cat",
+          name: "cat"))
 
         background_start.call
         output = stdin_write.call
         assert_equal("hello there" + $/, output)
 
-        Rundoc::CodeCommand::Background::Wait.new(
-          name: "cat",
-          wait: "hello"
-        ).call
+        Rundoc::CodeCommand::Background::WaitRunner.new(render_command: false, render_result: false, io: StringIO.new,
+          user_args: Rundoc::CodeCommand::Background::WaitArgs.new(
+            name: "cat",
+            wait: "hello"
+          )).call
 
-        Rundoc::CodeCommand::Background::Log::Clear.new(
-          name: "cat"
-        ).call
+        Rundoc::CodeCommand::Background::Log::ClearRunner.new(render_command: false, render_result: false, io: StringIO.new,
+          user_args: Rundoc::CodeCommand::Background::Log::ClearArgs.new(
+            name: "cat"
+          )).call
 
-        output = Rundoc::CodeCommand::Background::StdinWrite.new(
+        output = Rundoc::CodeCommand::Background::StdinWriteRunner.new(render_command: false, render_result: false, io: StringIO.new, user_args: Rundoc::CodeCommand::Background::StdinWriteArgs.new(
           "general kenobi",
           name: "cat",
           wait: "general"
-        ).call
+        )).call
         assert_equal("general kenobi" + $/, output)
       end
     end
@@ -44,9 +46,9 @@ class BackgroundTest < Minitest::Test
         file = "foo.txt"
         run!("echo 'foo' >> #{file}")
 
-        background_start = Rundoc::CodeCommand::Background::Start.new("tail -f #{file}",
+        background_start = Rundoc::CodeCommand::Background::StartRunner.new(render_command: false, render_result: false, io: StringIO.new, user_args: Rundoc::CodeCommand::Background::StartArgs.new("tail -f #{file}",
           name: "tail2",
-          wait: "f")
+          wait: "f"))
 
         GC.start
 
@@ -55,7 +57,7 @@ class BackgroundTest < Minitest::Test
         assert_match("foo", output)
         assert_equal(true, background_start.alive?)
 
-        background_stop = Rundoc::CodeCommand::Background::Stop.new(name: "tail2")
+        background_stop = Rundoc::CodeCommand::Background::StopRunner.new(render_command: false, render_result: false, io: StringIO.new, user_args: Rundoc::CodeCommand::Background::StopArgs.new(name: "tail2"))
         background_stop.call
 
         assert_equal(false, background_start.alive?)
@@ -69,20 +71,20 @@ class BackgroundTest < Minitest::Test
         file = "foo.txt"
         run!("echo 'foo' >> #{file}")
 
-        background_start = Rundoc::CodeCommand::Background::Start.new("tail -f #{file}",
+        background_start = Rundoc::CodeCommand::Background::StartRunner.new(render_command: false, render_result: false, io: StringIO.new, user_args: Rundoc::CodeCommand::Background::StartArgs.new("tail -f #{file}",
           name: "tail",
-          wait: "f")
+          wait: "f"))
         output = background_start.call
 
         assert_match("foo", output)
         assert_equal(true, background_start.alive?)
 
-        log_read = Rundoc::CodeCommand::Background::Log::Read.new(name: "tail")
+        log_read = Rundoc::CodeCommand::Background::Log::ReadRunner.new(render_command: false, render_result: false, io: StringIO.new, user_args: Rundoc::CodeCommand::Background::Log::ReadArgs.new(name: "tail"))
         output = log_read.call
 
         assert_equal("foo", output.chomp)
 
-        log_clear = Rundoc::CodeCommand::Background::Log::Clear.new(name: "tail")
+        log_clear = Rundoc::CodeCommand::Background::Log::ClearRunner.new(render_command: false, render_result: false, io: StringIO.new, user_args: Rundoc::CodeCommand::Background::Log::ClearArgs.new(name: "tail"))
         output = log_clear.call
         assert_equal("", output)
 
@@ -90,12 +92,12 @@ class BackgroundTest < Minitest::Test
 
         background_start.background.wait("bar")
 
-        log_read = Rundoc::CodeCommand::Background::Log::Read.new(name: "tail")
+        log_read = Rundoc::CodeCommand::Background::Log::ReadRunner.new(render_command: false, render_result: false, io: StringIO.new, user_args: Rundoc::CodeCommand::Background::Log::ReadArgs.new(name: "tail"))
         output = log_read.call
 
         assert_equal("bar", output.chomp)
 
-        background_stop = Rundoc::CodeCommand::Background::Stop.new(name: "tail")
+        background_stop = Rundoc::CodeCommand::Background::StopRunner.new(render_command: false, render_result: false, io: StringIO.new, user_args: Rundoc::CodeCommand::Background::StopArgs.new(name: "tail"))
         background_stop.call
 
         assert_equal(false, background_start.alive?)

data/test/rundoc/code_commands/bash_test.rb

@@ -3,7 +3,7 @@ require "test_helper"
 class BashTest < Minitest::Test
   def test_bash_returns_cd
     original_dir = `pwd`
-    Rundoc::CodeCommand::Bash.new("cd ..").call
+    Rundoc::CodeCommand::BashRunner.new(render_command: false, render_result: false, io: StringIO.new, user_args: Rundoc::CodeCommand::BashArgs.new("cd ..")).call
     now_dir = `pwd`
     refute_equal original_dir, now_dir
   ensure
@@ -12,14 +12,14 @@ class BashTest < Minitest::Test
 
   def test_bash_stderr_with_or_is_capture
     command = "1>&2 echo 'msg to STDERR 1' || 1>&2 echo 'msg to STDERR 2'"
-    bash = Rundoc::CodeCommand::Bash.new(command)
+    bash = Rundoc::CodeCommand::BashRunner.new(render_command: false, render_result: false, io: StringIO.new, user_args: Rundoc::CodeCommand::BashArgs.new(command))
     assert_equal "$ #{command}", bash.to_md
     assert_equal "msg to STDERR 1\n", bash.call
   end
 
   def test_bash_shells_and_shows_correctly
     ["pwd", "ls"].each do |command|
-      bash = Rundoc::CodeCommand::Bash.new(command)
+      bash = Rundoc::CodeCommand::BashRunner.new(render_command: false, render_result: false, io: StringIO.new, user_args: Rundoc::CodeCommand::BashArgs.new(command))
       assert_equal "$ #{command}", bash.to_md
       assert_equal `#{command}`, bash.call
     end
@@ -27,8 +27,13 @@ class BashTest < Minitest::Test
 
   def test_stdin
     command = "tail -n 2"
-    bash = Rundoc::CodeCommand::Bash.new(command)
-    bash << "foo\nbar\nbaz\n"
+    bash = Rundoc::CodeCommand::BashRunner.new(
+      render_command: false,
+      render_result: false,
+      io: StringIO.new,
+      user_args: Rundoc::CodeCommand::BashArgs.new(command),
+      contents: "foo\nbar\nbaz\n"
+    )
     assert_equal "bar\nbaz\n", bash.call
   end
 end