plywood 1.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9cb35cf97e0f00639e9c3ec01c009100eef846ae77c245daeb0f80f124f3d59d
+  data.tar.gz: eb0c36061977ab643b328daed9b33b569ee78df08c30594f4a93c9bccf024e55
+SHA512:
+  metadata.gz: 3b5c5fb7d6f88f80ca2d46ffa2566eda56adf76e20128e87dfe02f4a2c1bcff34e88260b3f9c12377205638265031456dc6846a9c1ed552668f5dab608c2d45e
+  data.tar.gz: de6f5e1b9ac405eaf3322ed9c35ce1b9e5d3aaeb04d06a811cf9ac9e32a60eb6b2e1135e6ce4a38bf94318909bc3e3d4ea16e9acf80d8b290ad128a470789e4d

data/README.md

@@ -0,0 +1,47 @@
+![logo](logo.jpeg)
+
+# Plywood
+
+A simple way to get multiplexing; run commands concurrently, combine their output streams.
+
+# Usage
+
+Typically you feed it an array of items; Plywood yields the items one by one and expects you to make a command using that thing.
+
+It then runs all the commands at the same time.
+
+```ruby
+require "plywood"
+
+items = %w[foo bar baz]
+
+# There is no need to do this concurrently but this is just an example
+Plywood::Commands.map(items) do |item|
+  "touch #{item}.txt" # the command that should be run
+end
+```
+
+Plywood, by default, will use `item.to_s` to use as the "process identifier". This identifier must be unique; and you are responsible for that. Often this is not a problem at all, say when you loop over a bunch of hostnames or chemical elements, but when you loop over a group of people it's very well possible that two of them share the same name.
+
+To help with that you can specify the `id` parameter. If it's a `Symbol` Plywood will assume it's the name of a method on the item with arity 0 and call it. The return value is used as the process identifier. If it's a `Proc`; Plywood will call it with the item as the only argument.
+
+```ruby
+my_favorite_things = [
+  Thing.new("raindrops on roses"),
+  Thing.new("whiskers on kittens"),
+  Thing.new("bright copper kettles"),
+  Thing.new("warm woolen mittens"),
+  Thing.new("brown paper packages tied up with strings")]
+
+Plywood::Commands.map(my_favorite_things, id: :object_id) do |thing|
+  "touch #{thing.underscore}.txt"
+end
+```
+
+You can disable concurrent execution by using `sequential: true`:
+
+```ruby
+Plywood::Commands.map(my_favorite_things, sequential: true) do |thing|
+  "touch #{thing.underscore}.txt"
+end
+```

data/lib/plywood/color.rb

@@ -0,0 +1,38 @@
+module Plywood
+  module Color
+    ANSI = {
+      reset: 0,
+      black: 30,
+      red: 31,
+      green: 32,
+      yellow: 33,
+      blue: 34,
+      magenta: 35,
+      cyan: 36,
+      white: 37,
+      bright_black: 30,
+      bright_red: 31,
+      bright_green: 32,
+      bright_yellow: 33,
+      bright_blue: 34,
+      bright_magenta: 35,
+      bright_cyan: 36,
+      bright_white: 37 }.freeze
+
+    def self.enable(io)
+      io.extend(self)
+    end
+
+    def color?
+      return false unless respond_to?(:isatty)
+      isatty && ENV["TERM"]
+    end
+
+    def color(name)
+      return "" unless color?
+      ansi = ANSI[name.to_sym]
+      return "" if ansi.nil?
+      "\e[#{ansi}m"
+    end
+  end
+end

data/lib/plywood/command.rb

@@ -0,0 +1,36 @@
+require_relative "named_io"
+
+module Plywood
+  class Command
+    attr_reader :command, :name
+    attr_reader :err, :out, :pid
+
+    def initialize(name, command)
+      @name = name.to_s
+      @command = command.to_s
+      @err, @err_writer = build_pipe(:err)
+      @out, @out_writer = build_pipe(:out)
+    end
+
+    def to_s
+      "#{name} `#{@command}`"
+    end
+
+    def ios
+      [err, out]
+    end
+
+    def run
+      @pid = ::Process.spawn(@command, err: @err_writer, out: @out_writer)
+      @err_writer.puts "started with pid #{@pid}"
+      self
+    end
+
+    private
+
+    def build_pipe(stream)
+      reader, writer = IO.pipe
+      [NamedIO.new(reader, @name, stream), writer]
+    end
+  end
+end

data/lib/plywood/command_report.rb

@@ -0,0 +1,32 @@
+require "forwardable"
+require_relative "command"
+
+module Plywood
+  # A small report to show after the command has run.
+  class CommandReport
+    extend Forwardable
+
+    def_delegators :@command, :command, :name, :pid
+    def_delegators :@status, :success?, :to_i
+
+    def initialize(command, status)
+      raise ArgumentError, "command is nil" if command.nil?
+      raise ArgumentError, "status is nil" if status.nil?
+      @command = command
+      @status = status
+    end
+
+    def self.gather(status, commands)
+      command = commands.find { |item| item.pid == status.pid }
+      new(command, status)
+    end
+
+    def to_s
+      if success?
+        "#{name} was successful."
+      else
+        "#{name} failed with exit status #{to_i} (`#{command}`)."
+      end
+    end
+  end
+end

data/lib/plywood/commands.rb

@@ -0,0 +1,108 @@
+require_relative "command"
+require_relative "command_report"
+require_relative "logger"
+
+module Plywood
+  class Commands
+    def initialize(io_handler_class: Logger, sequential: false)
+      @list = {}
+      @io_handler_class = io_handler_class
+      @sequential = sequential
+      yield self
+      run
+    end
+
+    def self.map(array, io_handler_class: Logger, id: :to_s, sequential: false)
+      new(io_handler_class: io_handler_class, sequential: sequential) do |ply|
+        array.each do |item|
+          command = yield item
+          name = name_for_item(item, id: id)
+          ply.register(name, command)
+        end
+      end
+    end
+
+    def register(name, command)
+      @list[name.to_s] = Command.new(name, command)
+      self
+    end
+
+    private
+
+    private_class_method def self.name_for_item(item, id:)
+      case id
+      when Symbol
+        item.send(id)
+      when Proc
+        id.call(item)
+      else
+        raise ArgumentError, "What is #{id.inspect}?!"
+      end
+    end
+
+    def run
+      if @sequential
+        run_sequentially
+      else
+        run_concurrently
+      end
+    end
+
+    def run_concurrently
+      statuses = []
+      with_io_handler do |io_handler|
+        commands.each(&:run)
+        threads = commands.map do |command|
+          Thread.new do
+            pid_and_status = ::Process.wait2(command.pid)
+            io_handler.handle_exit_statuses!([pid_and_status], commands)
+            statuses << pid_and_status
+          end
+        end
+        threads.each(&:join)
+      end
+      verify_exit_statuses(statuses, commands)
+    end
+
+    def run_sequentially
+      with_io_handler do |io_handler|
+        commands.each do |command|
+          command.run
+          statuses = ::Process.waitall
+          io_handler.handle_exit_statuses!(statuses, commands)
+          verify_exit_statuses(statuses, commands)
+        end
+      end
+    end
+
+    def with_io_handler
+      io_handler = @io_handler_class.new(ios)
+      io_handler.start
+      thread = Thread.new { io_handler.handle_io! }
+      result = yield io_handler
+      thread.terminate
+      io_handler.stop
+      result
+    end
+
+    def ios
+      commands.flat_map(&:ios)
+    end
+
+    def commands
+      @list.values
+    end
+
+    def verify_exit_statuses(statuses, commands)
+      failure_reports = statuses
+        .map(&:last)
+        .reject(&:success?)
+        .map { |status| CommandReport.gather(status, commands) }
+      return if failure_reports.none?
+
+      warn ""
+      warn failure_reports.join("\n")
+      raise Failure, "Not every process was successful; #{failure_reports.size} failed"
+    end
+  end
+end

data/lib/plywood/fancy_logger/fancy_log.rb

@@ -0,0 +1,55 @@
+require "concurrent/array"
+
+module Plywood
+  class FancyLogger < IOHandler
+    class FancyLog
+      attr_reader :exit_status, :name, :output
+
+      def initialize(name)
+        @name = name
+        @exit_status = nil
+        @output = Concurrent::Array.new
+      end
+
+      def add_line(stream)
+        raise "Process exited" unless exit_status.nil?
+        stream.gets.each_line do |line|
+          @output << [(stream.err? ? :stderr : :stdout), line]
+        end
+        self
+      end
+
+      def exit_status=(status)
+        @exit_status = status.to_i
+      end
+
+      def running?
+        @exit_status.nil?
+      end
+
+      def success?
+        @exit_status&.zero?
+      end
+
+      def to_s
+        "#{icon} #{name} | #{status}"
+      end
+
+      def status
+        case exit_status
+        when nil then "running"
+        when 0 then "success"
+        else "failed (#{exit_status})"
+        end
+      end
+
+      def icon
+        case exit_status
+        when nil then "⏵"
+        when 0 then "✔"
+        else "‼"
+        end
+      end
+    end
+  end
+end

data/lib/plywood/fancy_logger/frame.rb

@@ -0,0 +1,44 @@
+require "io/console"
+
+module Plywood
+  class FancyLogger < IOHandler
+    class Frame
+      def initialize(io, rows = nil, cols = nil)
+        rows, cols = IO.console.winsize if rows.nil? || cols.nil?
+        @io = io
+        @rows = rows.to_i - 1
+        @cols = cols.to_i
+        @lines = []
+      end
+
+      def self.render(*, &)
+        frame = new(*)
+        yield frame
+        frame.render
+      end
+
+      def line(string, color = nil)
+        return if @lines.size >= @rows
+        string = string.to_s[0, @cols].ljust(@cols)
+        string = @io.color(color) + string + @io.color(:reset) if color
+        @lines << string
+        self
+      end
+
+      def render
+        @lines << "".ljust(@cols) until @lines.size == @rows
+        @lines.each.with_index do |line, index|
+          # position_cursor(@rows - @lines.size + index + 1, 1)
+          position_cursor(index + 1, 1)
+          @io << line
+        end
+      end
+
+      private
+
+      def position_cursor(row, col)
+        @io.write "#{CSI}#{row};#{col}H"
+      end
+    end
+  end
+end

data/lib/plywood/fancy_logger.rb

@@ -0,0 +1,150 @@
+require_relative "color"
+require_relative "io_handler"
+require_relative "fancy_logger/fancy_log"
+require_relative "fancy_logger/frame"
+
+module Plywood
+  class FancyLogger < IOHandler
+    CSI = "\e[".freeze
+    FPS = 20 # frames per second
+    STOP_DELAY = 0.6 # seconds
+
+    def initialize(ios)
+      super
+      @names = ios.map(&:name).uniq
+      @logs = @names
+        .map { |name, _index| [name, FancyLog.new(name)] }
+        .to_h
+      Color.enable($stdout)
+    end
+
+    def start
+      @initial_console_mode = $stdout.console_mode
+      IO.console.raw!
+      hide_cursor
+      use_alternate_screen_buffer
+      @render_thread = Thread.new do
+        loop do
+          render
+          sleep(1.0 / FPS)
+        end
+      end
+      self
+    end
+
+    def stop
+      sleep STOP_DELAY
+      Thread.kill(@render_thread) unless @render_thread.nil?
+      # IO.console.cooked!
+      $stdout.console_mode = @initial_console_mode
+      use_main_screen_buffer
+      show_cursor
+      render_report
+      self
+    end
+
+    def handle_io!
+      loop do
+        readers, _writers = IO.select(@ios)
+        readers.each { |stream| copy_stream(stream) }
+      end
+      self
+    end
+
+    def handle_exit_statuses!(statuses, commands)
+      statuses.each do |pid, status|
+        command = commands.detect { |item| item.pid == pid }
+        @logs[command.name].exit_status = status
+      end
+      self
+    end
+
+    private
+
+    def copy_stream(stream)
+      if stream.eof?
+        @ios.delete(stream)
+        return self
+      end
+      @logs[stream.name].add_line(stream)
+      self
+    end
+
+    def render
+      Frame.render($stdout) do |frame|
+        @logs.each_value do |log|
+          frame.line(log, color(log.name))
+          next unless log.running?
+          gather_output(log).each do |line|
+            frame.line(line)
+          end
+        end
+      end
+    end
+
+    # show last x lines of output
+    def gather_output(log, amount = 8)
+      lines = log.output.last(amount).map(&:last)
+      lines << "" until lines.size == amount
+      lines
+    end
+
+    def render_report
+      render_success_report
+      render_failures_report
+    end
+
+    def render_success_report
+      @logs.each_value do |log|
+        next unless log.success?
+        header = $stdout.color color(log.name)
+        header << log.to_s
+        header << $stdout.color(:reset)
+        puts header
+      end
+    end
+
+    def render_failures_report
+      @logs.each_value do |log|
+        next if log.success?
+        puts
+        $stdout.puts failure_log_header(log)
+        log.output.each do |line|
+          case line.first
+          when :stdout
+            $stdout.puts line.last
+          when :stderr
+            $stderr.puts line.last
+          end
+        end
+      end
+    end
+
+    def failure_log_header(log)
+      $stdout.color(color(log.name)) << "-" * 40 << "\n" << log.to_s << $stdout.color(:reset)
+    end
+
+    COLORS = %w[cyan yellow green magenta red blue bright_cyan bright_yellow
+                bright_green bright_magenta bright_red bright_blue].freeze
+
+    def color(name)
+      COLORS[@names.index(name) % COLORS.length]
+    end
+
+    def use_alternate_screen_buffer
+      $stdout.write "#{CSI}?1049h"
+    end
+
+    def use_main_screen_buffer
+      $stdout.write "#{CSI}?1049l"
+    end
+
+    def hide_cursor
+      $stdout.write "#{CSI}?25l"
+    end
+
+    def show_cursor
+      $stdout.write "#{CSI}?25h"
+    end
+  end
+end

data/lib/plywood/io_handler.rb

@@ -0,0 +1,19 @@
+module Plywood
+  class IOHandler
+    def initialize(ios)
+      @ios = ios
+    end
+
+    def handle_io!
+    end
+
+    def handle_exit_statuses!(statuses)
+    end
+
+    def start
+    end
+
+    def stop
+    end
+  end
+end

data/lib/plywood/logger.rb

@@ -0,0 +1,79 @@
+require_relative "color"
+require_relative "io_handler"
+
+module Plywood
+  # An IOHandler that outputs all process output, line by line, prefixed with "name   | ".
+  #
+  # It keeps stderr and stdout separated which may be convenient if you want to pipe
+  # the output to another program.
+  class Logger < IOHandler
+    def initialize(ios)
+      super
+      @name_padding = [6, ios.map(&:name).map(&:size).max].max
+      @names = ios.map(&:name).uniq
+      Color.enable($stderr)
+      Color.enable($stdout)
+    end
+
+    def handle_io!
+      loop do
+        readers, _writers = IO.select(@ios)
+        readers.each { |stream| copy_stream_to_io(stream) }
+      end
+      self
+    end
+
+    def handle_exit_statuses!(statuses, commands)
+      statuses.each do |pid, status|
+        next if status.success?
+        command = commands.detect { |item| item.pid == pid }
+        log($stderr, command.name, "`#{command}` failed with status #{status.to_i}")
+      end
+      self
+    end
+
+    private
+
+    def copy_stream_to_io(stream)
+      if stream.eof?
+        @ios.delete(stream)
+        return self
+      end
+
+      io = stream.err? ? $stderr : $stdout
+      log(io, stream.name, stream.gets)
+      self
+    end
+
+    def log(io, name, string)
+      output = io.color color(name)
+      output << name.ljust(@name_padding, " ") << " | "
+      output << io.color(:reset)
+      output << string
+      io.puts output
+      io.flush
+    end
+
+    def name_process_and_io(stream)
+      @processes.each do |name, process|
+        return [name, process, $stderr] if process.stderr == stream
+        return [name, process, $stdout] if process.stdout == stream
+      end
+      raise IndexError
+    end
+
+    def name_and_process(pid)
+      @processes.each do |name, process|
+        return [name, process] if process.pid == pid
+      end
+      raise IndexError
+    end
+
+    COLORS = %w[cyan yellow green magenta red blue bright_cyan bright_yellow
+                bright_green bright_magenta bright_red bright_blue].freeze
+
+    def color(name)
+      COLORS[@names.index(name) % COLORS.length]
+    end
+  end
+end

data/lib/plywood/named_io.rb

@@ -0,0 +1,31 @@
+require "delegate"
+
+module Plywood
+  # This class is used as a wrapper around an io.
+  # It adds extra methods that are useful to distinguish it from other IOs in an efficient way.
+  class NamedIO < SimpleDelegator
+    attr_reader :name, :stream
+
+    def initialize(io, name, stream)
+      super(io)
+      @name = name.to_s
+      @stream = stream.to_sym
+      validate_stream
+    end
+
+    def err?
+      @stream == :err
+    end
+
+    def out?
+      @stream == :out
+    end
+
+    private
+
+    def validate_stream
+      return if [:err, :out].include? @stream
+      raise ArgumentError, "stream cannot be #{@stream}"
+    end
+  end
+end

data/lib/plywood/version.rb

@@ -0,0 +1,3 @@
+module Plywood
+  VERSION = "1.1.1".freeze
+end

data/lib/plywood.rb

@@ -0,0 +1,5 @@
+require_relative "plywood/commands"
+
+module Plywood
+  Failure = Class.new(StandardError)
+end

metadata

@@ -0,0 +1,173 @@
+--- !ruby/object:Gem::Specification
+name: plywood
+version: !ruby/object:Gem::Version
+  version: 1.1.1
+platform: ruby
+authors:
+- Tijn Schuurmans
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-04-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest-focus
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: spy
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Run multiple commands in parallel; consolidate the output
+email: plywood@tijnschuurmans.nl
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+- logo.jpeg
+files:
+- README.md
+- lib/plywood.rb
+- lib/plywood/color.rb
+- lib/plywood/command.rb
+- lib/plywood/command_report.rb
+- lib/plywood/commands.rb
+- lib/plywood/fancy_logger.rb
+- lib/plywood/fancy_logger/fancy_log.rb
+- lib/plywood/fancy_logger/frame.rb
+- lib/plywood/io_handler.rb
+- lib/plywood/logger.rb
+- lib/plywood/named_io.rb
+- lib/plywood/version.rb
+- logo.jpeg
+homepage: https://github.com/Jobport/plywood
+licenses:
+- Copyright 2023 Jobport B.V.
+- MIT
+metadata:
+  homepage_uri: https://github.com/Jobport/plywood
+  changelog_uri: https://github.com/Jobport/plywood/releases
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: The simplest multiplexer
+test_files: []