rundoc 0.0.1 → 1.1.1

data/bin/rundoc

@@ -15,12 +15,11 @@ $: << File.expand_path(File.dirname(File.realpath(__FILE__)) + '/../lib')
 require 'rundoc'
 require 'thor'
 
-class RundocCLI < Thor
+class RundocThorCLI < Thor
 
   def initialize(*args)
     super
-    @path         = options[:path]
-    @working_dir  = Pathname.new(File.expand_path("../", @path))
+    @path = options[:path]
   end
 
   default_task :help
@@ -28,55 +27,8 @@ class RundocCLI < Thor
   desc "build", "turns rundoc file into docs and a project"
   class_option  :path,   banner: "path/to/file.md",          optional: true, default: 'rundoc.md'
   def build
-    raise "#{@path} does not exist"   unless File.exist?(@path)
-    source_contents = File.read(@path)
-    tmp_dir         = @working_dir.join("tmp")
-
-    FileUtils.remove_entry_secure(tmp_dir) if tmp_dir.exist?
-    tmp_dir.mkdir
-
-    puts "== Running your docs"
-    Dir.chdir(tmp_dir) do
-      @output = Rundoc::Parser.new(source_contents, Rundoc.parser_options).to_md
-      Rundoc.sanitize(@output)
-      banner = "<!-- STOP\nThis file was generated by a rundoc script, don't modify it. \n"
-      banner << "Instead modify the rundoc script and re-run it.\nSTOP -->"
-      @output = "#{banner}\n#{@output}"
-    end
-
-    puts "== Done, run was successful"
-    project_name = if Rundoc.project_root
-      Rundoc.project_root.split('/').last
-    else
-      'project'
-    end
-
-    project_dir  = @working_dir.join(project_name)
-
-    FileUtils.remove_entry_secure(project_dir) if project_dir.exist?
-
-    cp_root = if Rundoc.project_root
-      tmp_dir.join(Rundoc.project_root, ".")
-    else
-      tmp_dir.join(".")
-    end
-
-    FileUtils.cp_r(cp_root, project_dir)
-
-    FileUtils.remove_entry_secure(tmp_dir) if tmp_dir.exist?
-
-    puts "== Done, writing original source to #{project_dir}/source.md"
-    source_path = project_dir.join("README.md")
-    File.open(source_path, "w") { |f| f.write @output }
-
-    puts "== Copying source"
-    source_path = project_dir.join("coppied-#{@path.split('/').last}")
-    File.open(source_path, "w") { |f| f.write source_contents }
-
-    Dir.chdir(project_dir) do
-      Rundoc.run_after_build
-    end
+    Rundoc::CLI.new.build(path: @path)
   end
 end
 
-RundocCLI.start(ARGV)
+RundocThorCLI.start(ARGV)

data/lib/rundoc.rb

@@ -7,9 +7,21 @@ module Rundoc
 
   def code_command_from_keyword(keyword, args)
     klass      = code_command(keyword.to_sym) || Rundoc::CodeCommand::NoSuchCommand
-    cc         = klass.new(args)
+    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)
+    else
+      cc = klass.new(*args)
+    end
+
+    cc.original_args = original_args
     cc.keyword = keyword
     cc
+  rescue ArgumentError => e
+    raise ArgumentError, "Wrong method signature for #{keyword} with arguments: #{original_args.inspect}, error:\n #{e.message}"
   end
 
   def parser_options
@@ -74,3 +86,5 @@ end
 require 'rundoc/parser'
 require 'rundoc/code_section'
 require 'rundoc/code_command'
+require 'rundoc/peg_parser'
+require 'rundoc/cli'

data/lib/rundoc/cli.rb

@@ -0,0 +1,84 @@
+module Rundoc
+  class CLI
+    def build(path: )
+      @path = Pathname.new(path).expand_path
+      raise "#{@path} does not exist" unless File.exist?(@path)
+      raise "Expecting #{@path} to be a rundoc markdown file" unless File.file?(@path)
+      @working_dir  = Pathname.new(File.expand_path("../", @path))
+
+
+      dot_env_path = File.expand_path("../.env", @path)
+      if File.exist?(dot_env_path)
+        require 'dotenv'
+        Dotenv.load(dot_env_path)
+        ENV['AWS_ACCESS_KEY_ID']     ||= ENV['BUCKETEER_AWS_ACCESS_KEY_ID']
+        ENV['AWS_REGION']            ||= ENV['BUCKETEER_AWS_REGION']
+        ENV['AWS_SECRET_ACCESS_KEY'] ||= ENV['BUCKETEER_AWS_SECRET_ACCESS_KEY']
+        ENV['AWS_BUCKET_NAME']       ||= ENV['BUCKETEER_BUCKET_NAME']
+      end
+
+      source_contents = File.read(@path)
+      tmp_dir         = @working_dir.join("tmp")
+
+      FileUtils.remove_entry_secure(tmp_dir) if tmp_dir.exist?
+      tmp_dir.mkdir
+      banner = <<~HEREDOC
+        <!-- STOP
+          This file was generated by a rundoc script, do not modify it.
+
+          Instead modify the rundoc script and re-run it.
+
+          Command: #{ $0 } #{$*.join(' ')}
+        STOP -->
+      HEREDOC
+
+      puts "== Running your docs"
+      Dir.chdir(tmp_dir) do
+        @output = Rundoc::Parser.new(source_contents, document_path: @path).to_md
+        Rundoc.sanitize(@output)
+        @output = "#{banner}\n#{@output}"
+      end
+
+      puts "== Done, run was successful"
+      project_name = if Rundoc.project_root
+        Rundoc.project_root.split('/').last
+      else
+        'project'
+      end
+
+      project_dir  = @working_dir.join(project_name)
+
+      FileUtils.remove_entry_secure(project_dir) if project_dir.exist?
+
+      cp_root = if Rundoc.project_root
+        tmp_dir.join(Rundoc.project_root, ".")
+      else
+        tmp_dir.join(".")
+      end
+
+      FileUtils.cp_r(cp_root, project_dir)
+
+      FileUtils.remove_entry_secure(tmp_dir) if tmp_dir.exist?
+
+      source_path = project_dir.join("README.md")
+      puts "== Done, writing original source to #{source_path}"
+      File.open(source_path, "w") { |f| f.write @output }
+
+      puts "== Copying source"
+      source_path = project_dir.join("coppied-#{@path.to_s.split('/').last}")
+      File.open(source_path, "w") { |f| f.write source_contents }
+
+      Dir.chdir(project_dir) do
+        Rundoc.run_after_build
+      end
+
+    ensure
+      Rundoc::CodeCommand::Background::ProcessSpawn.tasks.each do |name, task|
+        next unless task.alive?
+
+        puts "Warning background task is still running, cleaning up: name: #{name}"
+        task.stop
+      end
+    end
+  end
+end

data/lib/rundoc/code_command.rb

@@ -1,10 +1,19 @@
 module Rundoc
+  # Generic CodeCommand class to be inherited
+  #
   class CodeCommand
-    attr_accessor :hidden, :render_result, :command, :contents, :keyword
-    alias :hidden? :hidden
+    attr_accessor :render_result, :render_command,
+                  :command, :contents, :keyword,
+                  :original_args
+
     alias :render_result? :render_result
+    alias :render_command? :render_command
+
+    def initialize(*args)
+    end
 
-    def initialize(arg)
+    def hidden?
+      !render_command? && !render_result?
     end
 
     def not_hidden?
@@ -17,16 +26,26 @@ module Rundoc
     end
     alias :<< :push
 
-    # executes command to build project
+    # Executes command to build project
+    # Is expected to return the result of the command
     def call(env = {})
-      raise "not implemented"
+      raise "not implemented on #{self.inspect}"
+    end
+
+    # the output of the command, i.e. `$ cat foo.txt`
+    def to_md(env = {})
+      raise "not implemented on #{self.inspect}"
     end
   end
 end
 
+
 require 'rundoc/code_command/bash'
 require 'rundoc/code_command/pipe'
 require 'rundoc/code_command/write'
 require 'rundoc/code_command/repl'
 require 'rundoc/code_command/rundoc_command'
-require 'rundoc/code_command/no_such_command'
+require 'rundoc/code_command/no_such_command'
+require 'rundoc/code_command/raw'
+require 'rundoc/code_command/background'
+require 'rundoc/code_command/website'

data/lib/rundoc/code_command/background.rb

@@ -0,0 +1,9 @@
+class Rundoc::CodeCommand::Background
+end
+
+require 'rundoc/code_command/background/process_spawn'
+require 'rundoc/code_command/background/start'
+require 'rundoc/code_command/background/stop'
+require 'rundoc/code_command/background/wait'
+require 'rundoc/code_command/background/log/clear'
+require 'rundoc/code_command/background/log/read'

data/lib/rundoc/code_command/background/log/clear.rb

@@ -0,0 +1,17 @@
+class Rundoc::CodeCommand::Background::Log
+  class Clear < Rundoc::CodeCommand
+    def initialize(name: )
+      @spawn = Rundoc::CodeCommand::Background::ProcessSpawn.find(name)
+    end
+
+    def to_md(env = {})
+      ""
+    end
+
+    def call(env = {})
+      @spawn.log.truncate(0)
+      ""
+    end
+  end
+end
+Rundoc.register_code_command(:"background.log.clear", Rundoc::CodeCommand::Background::Log::Clear)

data/lib/rundoc/code_command/background/log/read.rb

@@ -0,0 +1,16 @@
+class Rundoc::CodeCommand::Background::Log
+  class Read < Rundoc::CodeCommand
+    def initialize(name: )
+      @spawn = Rundoc::CodeCommand::Background::ProcessSpawn.find(name)
+    end
+
+    def to_md(env = {})
+      ""
+    end
+
+    def call(env = {})
+      @spawn.log.read
+    end
+  end
+end
+Rundoc.register_code_command(:"background.log.read", Rundoc::CodeCommand::Background::Log::Read)

data/lib/rundoc/code_command/background/process_spawn.rb

@@ -0,0 +1,96 @@
+require 'shellwords'
+require 'timeout'
+require 'fileutils'
+
+class Rundoc::CodeCommand::Background
+  # This class is responsible for running processes in the background
+  #
+  # By default it logs output to a file. This can be used to "wait" for a
+  # specific output before continuing:
+  #
+  #   server = ProcessSpawn("rails server")
+  #   server.wait("Use Ctrl-C to stop")
+  #
+  # The process can be queried for it's status to check if it is still booted or not.
+  # the process can also be manually stopped:
+  #
+  #   server = ProcessSpawn("rails server")
+  #   server.alive? # => true
+  #   server.stop
+  #   server.alive? # => false
+  #
+  #
+  # There are class level methods that can be used to "name" and record
+  # background processes. They can be used like this:
+  #
+  #   server = ProcessSpawn("rails server")
+  #   ProcessSpawn.add("muh_server", server)
+  #   ProcessSpawn.find("muh_server") # => <# ProcessSpawn instance >
+  #   ProcessSpawn.find("foo") # => RuntimeError "Could not find task with name 'foo', ..."
+  class ProcessSpawn
+    def self.tasks
+      @tasks
+    end
+
+    @tasks = {}
+    def self.add(name, value)
+      raise "Task named #{name.inspect} is already started, choose a different name" if @tasks[name]
+      @tasks[name] = value
+    end
+
+    def self.find(name)
+      raise "Could not find task with name #{name.inspect}, known task names: #{@tasks.keys.inspect}" unless @tasks[name]
+      @tasks[name]
+    end
+
+    attr_reader :log, :pid
+
+    def initialize(command , timeout: 5, log: Tempfile.new("log"), out: "2>&1")
+      @command = command
+      @timeout_value = timeout
+      @log_reference = log # https://twitter.com/schneems/status/1285289971083907075
+
+      @log = Pathname.new(log)
+      @log.dirname.mkpath
+      FileUtils.touch(@log)
+
+      @command = "/usr/bin/env bash -c #{@command.shellescape} >> #{@log} #{out}"
+      @pid = nil
+    end
+
+    def wait(wait_value = nil, timeout_value = @timeout_value)
+      call
+      return unless wait_value
+
+      Timeout.timeout(Integer(timeout_value)) do
+        until @log.read.match(wait_value)
+          sleep 0.01
+        end
+      end
+    rescue Timeout::Error
+      raise "Timeout waiting for #{@command.inspect} to find a match using #{ wait_value.inspect } in \n'#{ log.read }'"
+      false
+    end
+
+    def alive?
+      return false unless @pid
+      Process.kill(0, @pid)
+    rescue Errno::ESRCH, Errno::EPERM
+      false
+    end
+
+    def stop
+      return unless alive?
+      Process.kill('TERM', -Process.getpgid(@pid))
+      Process.wait(@pid)
+    end
+
+    def check_alive!
+      raise "#{@original_command} has exited unexpectedly: #{@log.read}" unless alive?
+    end
+
+    private def call
+      @pid ||= Process.spawn(@command, pgroup: true)
+    end
+  end
+end

data/lib/rundoc/code_command/background/start.rb

@@ -0,0 +1,38 @@
+require 'tempfile'
+
+class Rundoc::CodeCommand::Background
+  class Start < Rundoc::CodeCommand
+    def initialize(command, name: , wait: nil, timeout: 5, log: Tempfile.new("log"), out: "2>&1", allow_fail: false)
+      @command = command
+      @name    = name
+      @wait    = wait
+      @allow_fail = allow_fail
+      FileUtils.touch(log)
+
+      @spawn = ProcessSpawn.new(
+        @command,
+        timeout: timeout,
+        log:     log,
+        out:     out
+      )
+      ProcessSpawn.add(@name, @spawn)
+    end
+
+    def to_md(env = {})
+      return "$ #{@command}"
+    end
+
+    def call(env = {})
+      @spawn.wait(@wait)
+      @spawn.check_alive! unless @allow_fail
+
+      @spawn.log.read
+    end
+
+    def alive?
+      !!@spawn.alive?
+    end
+  end
+end
+
+Rundoc.register_code_command(:"background.start", Rundoc::CodeCommand::Background::Start)

data/lib/rundoc/code_command/background/stop.rb

@@ -0,0 +1,17 @@
+class Rundoc::CodeCommand::Background
+  class Stop < Rundoc::CodeCommand
+    def initialize(name: )
+      @spawn = Rundoc::CodeCommand::Background::ProcessSpawn.find(name)
+    end
+
+    def to_md(env = {})
+      ""
+    end
+
+    def call(env = {})
+      @spawn.stop
+      ""
+    end
+  end
+end
+Rundoc.register_code_command(:"background.stop", Rundoc::CodeCommand::Background::Stop)

data/lib/rundoc/code_command/background/wait.rb

@@ -0,0 +1,19 @@
+class Rundoc::CodeCommand::Background
+  class Wait < Rundoc::CodeCommand
+    def initialize(name: , wait:, timeout: 5)
+      @spawn = Rundoc::CodeCommand::Background::ProcessSpawn.find(name)
+      @wait  = wait
+      @timeout_value = Integer(timeout)
+    end
+
+    def to_md(env = {})
+      ""
+    end
+
+    def call(env = {})
+      @spawn.wait(@wait, @timeout_value)
+      ""
+    end
+  end
+end
+Rundoc.register_code_command(:"background.wait", Rundoc::CodeCommand::Background::Wait)