popro 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 23e8aecacb06e0bfe98467ac74b74f0b5e90ddc65f57069ae4bf29bdc7073b8a
+  data.tar.gz: 6a220ecf6de03a768aeed0d4998983ada21d037859a9deafe6263b4604b201d7
+SHA512:
+  metadata.gz: cb458d4d2a5169342ede984048be23c86d101db7546585e408e7470fe799f3344df4d2c691e42e43ff5ddd915e9af284a44ae59a7780890b06340a70a5e56419
+  data.tar.gz: 6a8fc7aef7feec2b0c39af0f1478f1cebaf4ccb8667edcc0842d119019dec709998e2d0a3930869646b51a210f4758eaa2b721894b7a1b79d554f44294996ce3

data/CHANGELOG

@@ -0,0 +1 @@
+0.0.1 initial version

data/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2020 MikeSmithEU
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,321 @@
+# Po'Pro: The Poor-Man's Progress Indicator
+
+## Why?
+
+Easier and cleaner progress indication.
+
+## How?
+
+TODO: properly update documentation, simplify some stuff. 100% code coverage
+
+### Basic usage
+
+The invocation `Popro#did(yielded)` is used to signify that one step in progress has been finished.
+
+1. Create a `Progress` object
+   ```ruby
+   progress = Popro.new(500)
+   ```
+
+2. Use the progress indicator
+  ```ruby
+  (0..499).each { progress.did }
+  ```
+
+  Will result in a default progress outputted to STDOUT, e.g.
+
+  ```bash
+  irb> (0..499).each { |n| sleep(0.1) & "Just did #{n}" }
+  [221/500] 44.2% Just did 220
+  ```
+
+  Note, `Popro#did` can be passed as a `Proc` using the shortcut `&progress`.
+  So below code would be equivalent and slightly more concise:
+
+  ```ruby
+  (0.499).each &progress
+  ```
+
+Block notation is usually preferable (cleaner) to using the `Progress` instance directly (see below).
+The functionality is the same though.
+
+### Using block context
+
+`Popro.new` can be called with a block. This block will then be executed after `Progress` has initialized
+and will receive a `Context` instance as the first parameter.  On this instance you can call e.g.
+`each`, `did`, `will` and `formatter`.
+
+E.g.
+
+```ruby
+Popro.new(500) do |p|
+  (1..500).each &p
+end
+```
+
+or
+
+```ruby
+Popro.new do |progress|
+  progress.each(1..500)
+end
+```
+
+### Using `Proc` shortcut notation
+
+`&Popro.new`  can be used for a more concise syntax. This is just syntactical sugar for calling
+`Popro#did` directly.
+
+For example:
+
+```ruby
+def job(size=100)
+  (1..size).each do
+    sleep 0.01
+    yield
+  end
+end
+
+# Below invocations are all equivalent.
+
+puts "\n job(&progress)"
+progress = Popro.new(100)
+job(&progress)
+
+puts "\n job { progress.did }"
+progress = Popro.new(100)
+job { progress.did }
+
+puts "\n using Popro.new(100)"
+
+# below code is a more concise equivalent to:
+#   `progress = Popro.new(100); job &progress`
+# or
+#   `progress = Popro.new(100); job { |*args| progress.did(*args) }`
+
+job(&Popro.new(100))
+```
+
+### Using each notation
+
+`Popro.each` or `Popro#each` can be used to loop over enumerables while providing progress
+feedback.
+
+`Popro.each(enumerable, size=nil)` will use `enumerable.size` to determine the total amount of elements
+only if the `size` argument is `nil`.
+If this method is not available you should manually provide a `size` argument, i.e.  `Popro.each(enumerable, 50)`.
+
+Shortcut methods `Popro.each0(enumerable)` and `Popro#each0(enumerable)` are available for enumerables
+that are used if you do not want to update the total with `enumerable.size`.
+I.e. this is equivalent to `Popro.each(enumerable, 0)` and `Popro#each(enumerable, 0)` respectively.
+
+E.g. below are all equivalent.
+
+```ruby
+sleeper = proc { sleep 0.05 }
+
+Popro.each(1..50) { sleep 0.05 }
+Popro.new.each(1..50, 50) { sleep 0.05 }
+Popro.new(50).each(1..50, 0) { sleep 0.05 }
+Popro.new(50).each0(1..50) { sleep 0.05 }
+
+Popro.each(1..50, &sleeper)
+Popro.new(50).each(1..50, 0, &sleeper)
+Popro.new(50).each0(1..50, &sleeper)
+
+Popro.each(1..50, 50, &sleeper)
+Popro.new.each(1..50, 50, &sleeper)
+```
+
+It is easy to chain multiple items, the total will be updated at the start of each `each` block. It
+might be preferable to provide a total sum in advance, and passing a `size` argument of `0` to
+`Popro#each` (or using `Popro#each0`), e.g.
+
+```ruby
+
+Popro.new(200)
+  .each0(1..50) { |n| sleep(0.1) && "#{n} of first 50" }
+  .each0(1..100) { |n| sleep(0.1) && "#{n} of second 100" }
+  .each0(1..50) { |n| sleep(0.1) && "#{n} of last 50" }
+
+```
+
+Or, using a block:
+
+```ruby
+
+Popro.new(200) do |p|
+  p.each0(1..50) { |n| sleep(0.1) && "#{n} of first 50" }
+  p.each0(1..100) { |n| sleep(0.1) && "#{n} of second 100" }
+  p.each0(1..50) { |n| sleep(0.1) && "#{n} of last 50" }
+end
+
+```
+
+Note that when using `Popro.each(enumberable, &block)` or `Popro#each(enumerable, &block)` the arguments
+passed to `block` on invocation are not the same as for `Popro.new`.
+
+`Popro.each` invokes `enumerable.each` and the argument signature of the `Popro.each` `&block` is the
+same as the signature that `enumerable.each` uses to call the block. Only the named argument `progress` is
+added (as opposed to being the first argument as for `Popro.new`).
+
+E.g.
+
+```ruby
+
+Popro.each(1..100) do |number, progress:|
+  progress.will "count sheep ##{number} and sleep for a bit" do
+    sleep 0.1
+  end
+end
+
+```
+
+would be equivalent to:
+
+```ruby
+
+Popro.new(100) do |p|
+  p.each(1..100) do |number, progress:|
+    # note, `p == progress`, only added `progress:` to `each` call for example purposes
+    p.will "count sheep ##{number} and sleep for a bit" do
+      sleep 0.1
+    end
+  end
+end
+
+```
+
+### Using `Popro#will`
+
+The helper `Popro#will(message, &block)` can be used to signify intention. When given a block, it will mark
+this intention as done when the block has finished (using a call to `Popro#did`). If no block is passed,
+`Popro#did` needs to be invoked manually once the intention has been fulfilled.
+
+This method sends the `message` passed to `Popro#will` to the `Indicator` so it can handle it (usually output to
+screen).
+
+Thus `Popro#will` can be used to signify the action about to take place instead of the action that has just finished.
+If the script encounters some kind of error, we can now see in which context this error occured instead of seeing
+the last invocation that did not cause an error.
+
+E.g.
+
+```ruby
+Popro.each(1..200) do |progress:|
+  progress.will "sleep a bit" do
+    sleep 0.1
+  end
+end
+
+# equivalent to
+
+Popro.new(200) do |p|
+  200.times do
+    p.will "sleep a bit" do
+      sleep 0.01
+    end
+  end
+end
+
+# equivalent to
+
+Popro.new(200) do |p|
+  200.times do
+    p.will "sleep a bit"
+    sleep 0.01
+    p.done "sleep a bit: DONE"
+  end
+end
+```
+
+### Using `Popro.each_will`
+
+`Popro.each_will(enumerator, titler, size = nil, &block)` is a shortcut for:
+
+```ruby
+Popro.each(enumerator, size) do |*args, **kwargs, progress:|
+  progress.will titler.call(*args) do
+    block.call(*args, **kwargs)
+  end
+end
+```
+
+So instead of e.g.
+
+```ruby
+Popro.each(SomeModel.all) do |model, progress:|
+  progress.will "Delete #{model.id}" do
+    model.destroy
+  end
+end
+```
+
+A more concise syntax is available:
+
+```ruby
+titler = ->(model) { "Delete #{model.id}" }
+Popro.each_will(SomeModel.all, titler) do |model|
+  model.destroy
+end
+```
+
+## Formatters
+
+You can set your own formatters using `Popro#formatter(&block)`. Each formatter can be a `Proc`, `block` or
+class implementing the `call` method (e.g. the `PoproFormatter::*` classes).
+
+The formatter will be invoked with 2 arguments:
+
+  1. `info`, an instance of `PoproInfo` containing e.g. `current` and `total`.
+  2. `yielded`, whatever was passed to the `Popro#did` method.
+
+It can also be used inside blocks.
+
+E.g.
+
+```ruby
+
+progress = Popro.new
+progress.formatter do |info, yielded|
+  "#{info.current}, yielded #{yielded}\n"
+end
+progress.each(1..8) { |i| i**2 }
+progress.formatter { "." } # output a dot
+progress.each(1..8) { |i| i**2 }
+
+# or equivalent, more concise:
+
+Popro.new do |p|
+  p.formatter { |info, yielded| "#{info.current}, yielded #{yielded}\n" }
+  p.each(1..8) { |i| i**2 }
+
+  p.formatter { "." } # output a dot
+  p.each(1..8) { |i| i**2 }
+end
+
+```
+
+would output:
+
+```
+ 1, yielded 1
+ 2, yielded 4
+ 3, yielded 9
+ 4, yielded 16
+ 5, yielded 25
+ 6, yielded 36
+ 7, yielded 49
+ 8, yielded 64
+ ........
+```
+
+
+## Indicator Classes
+
+Indicator classes are responsible for communicating the progress (or not, as the case may be).
+
+It is possible to provide your own "indicators" or use one of the provided ones (see `PoproIndicator` module).
+
+The default `PoproIndicator` class is `PoproIndicator.default` (which returns an instance of `PoproIndicator::Stream`), which outputs the progress to STDOUT each time `Popro#did` or `Popro#will` is called.
+

data/bin/popro

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'popro'
+Popro.command_line(*ARGV)

data/lib/popro.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# shortcut methods to Popro::Progress usage
+module Popro
+  class OutOfSyncError < StandardError; end
+  class ConfigError < StandardError; end
+
+  require_relative 'popro/progress'
+
+  def self.new(total, **options, &block)
+    raise ConfigError, 'using :total is not supported in new' if options.key?(:total) && (options[:total] != total)
+
+    options[:total] = total
+    Progress.new(**options, &block)
+  end
+
+  def self.each(obj, _total = nil, **options, &block)
+    new(0, **options).each(obj, total, &block).done
+  end
+
+  def self.each0(obj, **options, &block)
+    raise ConfigError, 'using :step is not supported in each0' if options.key?(:step)
+
+    options[:step] = 0
+    each(obj, 0, **options, &block)
+  end
+
+  def self.command_line(*_args)
+    raise 'TODO: implement a `ps` style progress indicator for command line'
+  end
+end

data/lib/popro/context.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Popro
+  # the progress context passed as first argument to blocks (or named argument for `Progress#each` and `Popro.each`)
+
+  WILL_CHECK_MARKS ||= '☐☑'
+
+  class Context
+    def initialize(progress:, info:, indicator:, step: 1)
+      @progress = progress
+      @indicator = indicator
+      @info = info
+      @step = step
+    end
+
+    def each(obj, total = nil, &block)
+      total = obj.size if total.nil?
+      @info.total += total if total.positive?
+      block = proc { |d| d } unless block_given?
+
+      obj.each do |*args|
+        did block.call(*args, progress: self)
+      end
+
+      self
+    end
+
+    def each0(obj, &block)
+      each(obj, 0, &block)
+    end
+
+    def each_will(obj, titler, total = nil)
+      each(obj, total) do |*args, **kwargs|
+        kwargs[:progress].will titler.call(*args) do
+          yield(*args, **kwargs)
+        end
+      end
+    end
+
+    def start
+      raise OutOfSyncError, 'trying to start when already running' if @info.running?
+
+      @info.start
+    end
+
+    def done
+      raise OutOfSyncError, 'done while not started' unless @info.running?
+
+      @info.finish
+      @indicator.finish if @indicator.respond_to? :finish
+    end
+
+    def formatter(&block)
+      unless @indicator.respond_to?(:formatter=)
+        raise ConfigError, "seems formatter is not available for #{@indicator.class}"
+      end
+
+      @indicator.formatter = block
+      block
+    end
+
+    def did(yielded = nil, amount = 1)
+      @info.start unless @info.running?
+      inc amount, yielded
+
+      self
+    end
+
+    def will(title = nil, use_block_result_as_title = nil, step = nil)
+      @info.start unless @info.running?
+      inc 0, "#{WILL_CHECK_MARKS[0]} #{title}"
+
+      return self unless block_given?
+
+      step = @step if step.nil?
+      yielded = yield @context
+      yielded = "#{WILL_CHECK_MARKS[1]} #{title}" unless title.nil? || use_block_result_as_title
+
+      # no need to communicate to Indicator if we are not advancing (avoid double calls)
+      did yielded, step unless step.zero?
+      yielded
+    end
+
+    def to_proc
+      proc { |yielded| did(yielded) }
+    end
+
+    private
+
+    def inc(amount, yielded = nil)
+      raise TypeError('expected an integer') unless amount.is_a? Integer
+
+      @info.current += amount unless amount.zero?
+      @indicator.call(@info, yielded)
+    end
+  end
+end

data/lib/popro/formatter.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Popro
+  module Formatter
+    class Aggregate
+      def initialize(*formatters, &block)
+        @formatters = formatters
+        @join = if block_given?
+                  block
+                else
+                  proc(&:join)
+                end
+      end
+
+      def call(info, *args)
+        @join.call(
+          @formatters.collect do |formatter|
+            formatter.call(info, *args)
+          end
+        )
+      end
+    end
+
+    class RewriteLine
+      def initialize(formatter)
+        @formatter = formatter
+        @longest = 0
+      end
+
+      def call(info, *args)
+        result = @formatter.call(info, *args)
+        @longest = [@longest, result.size].max
+        "\r" + result.ljust(@longest, ' ')
+      end
+    end
+
+    module Concat
+      # Factory for calling Aggregate with a join block
+      def self.new(*formatters, separator: '')
+        Aggregate.new(*formatters) do |results|
+          results.join separator
+        end
+      end
+    end
+
+    class Sprintf
+      def initialize(format_string = nil)
+        @format_string = format_string
+      end
+
+      def call(info, *_args)
+        string_params = Hash.new { |_, k| info.public_send(k) }
+        format_string.gsub('{n}', info.total_length.to_s) % string_params
+      end
+
+      def format_string
+        @format_string ||= '[%<current>{n}s/%<total>-{n}s] %<pct_formatted>4s%%'
+      end
+    end
+
+    class Looper
+      def initialize(enumerable = nil)
+        enumerable = '.' if enumerable.nil?
+        enumerable = enumerable.split '' if enumerable.is_a? String
+
+        @enumerator = Enumerator.new do |e|
+          loop do
+            enumerable.each do |item|
+              e.yield item
+            end
+          end
+        end
+      end
+
+      def call(...)
+        @enumerator.next
+      end
+    end
+
+    class Spinner < Looper
+      STYLES ||= {
+        slashes: '-\\|/',
+        hbar: '▁▂▃▄▅▆▇█',
+        vbar: '▉▊▋▌▍▎',
+        heartbeat: '♥♡',
+        dots: '⣀⣄⣤⣦⣶⣷⣿',
+        block: '░▒▓█',
+        circle: '◜◝◞◟'
+      }.freeze
+
+      def initialize(style_type = nil, bounce: false, reverse: false)
+        style = STYLES[style_type] || STYLES[:slashes]
+        style = style.reverse if reverse
+        style += style.reverse if bounce
+        super style
+      end
+    end
+  end
+end

data/lib/popro/indicator.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Popro
+  module Indicator
+    require_relative 'formatter'
+
+    class Aggregate
+      def initialize(*indicators)
+        @indicators = indicators
+      end
+
+      def call(*args)
+        @indicators.each do |indicator|
+          indicator.call(*args)
+        end
+      end
+
+      def finish
+        @indicators.each(&:finish)
+      end
+    end
+
+    class Stream
+      attr_accessor :formatter
+
+      def initialize(stream: nil, formatter: nil)
+        formatter = self.class.default_formatter(formatter) if formatter.nil? || formatter.is_a?(String)
+
+        @formatter = formatter
+        @stream = stream || STDOUT
+      end
+
+      def call(*args)
+        @stream << @formatter.call(*args)
+        @stream.flush
+      end
+
+      def finish
+        @stream << "\n"
+        @stream.flush
+      end
+
+      def self.default_formatter(format_string = nil)
+        ::Popro::Formatter::Sprintf.new(format_string)
+      end
+    end
+
+    def self.default_formatter
+      ::Popro::Formatter::RewriteLine.new(
+        ::Popro::Formatter::Concat.new(
+          ::Popro::Formatter::Spinner.new(:dots, bounce: true),
+          ::Popro::Formatter::Sprintf.new,
+          (proc do |_, yielded = nil|
+            yielded if yielded.is_a?(String) || yielded.is_a?(Numeric)
+          end),
+          separator: ' '
+        )
+      )
+    end
+
+    def self.default
+      Stream.new(formatter: default_formatter)
+    end
+  end
+end

data/lib/popro/indicator/rails.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Popro
+  module Indicator
+    module Rails
+      class ServerSentEvent
+        DEFAULT_HEADERS ||= {
+          'Last-Modified': 0,
+          'ETag': '',
+          'Cache-Control': 'no-cache, must-revalidate',
+          'X-Accel-Buffering': 'no',
+          'Content-Type': 'text/event-stream'
+        }.freeze
+
+        def initialize(response, **options)
+          response.status = 200
+          response.headers.merge!(options.delete(:headers) || DEFAULT_HEADERS)
+          formatter = options.delete(:formatter) || self.class.method(:default_formatter)
+
+          @stream = ::ActionController::Live::SSE.new(response.stream, **options)
+          @formatter = formatter
+          @response = response
+        end
+
+        def call(*args)
+          @stream.write(@formatter.call(*args))
+        rescue ::ActionController::Live::ClientDisconnected
+          # ignore disconnections
+        end
+
+        def finish
+          @stream.close
+        rescue ::ActionController::Live::ClientDisconnected
+          # ignore disconnections
+        end
+
+        def self.default_formatter(info, yielded)
+          info.to_h.merge(yielded: yielded)
+        end
+      end
+    end
+  end
+end

data/lib/popro/info.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Popro
+  class Info
+    attr_accessor :total, :current
+
+    def initialize(total: nil, current: nil)
+      @total = total
+      @current = current || 0
+      @started = false
+    end
+
+    def running?
+      @started
+    end
+
+    def start
+      @started = true
+      self
+    end
+
+    def finish
+      @started = false
+      self
+    end
+
+    def pct
+      return 0 if @total.nil? || @total.zero?
+
+      @current.to_f / @total
+    end
+
+    def pct_formatted
+      percentage = pct
+      return nil if percentage.nil?
+
+      format('%<percent>.1f', percent: pct * 100)
+    end
+
+    def total_length
+      num = [@total, @current].max
+      return 1 if num.zero?
+
+      Math.log10(num + 1).ceil
+    end
+
+    def to_f
+      pct
+    end
+
+    def next(num = 1)
+      raise TypeError, 'expected an integer' unless num.is_a? Integer
+
+      @current += num
+      self
+    end
+
+    def to_h
+      {
+        started: @started,
+        pct: pct,
+        pct_formatted: pct_formatted,
+        current: @current,
+        total: @total
+      }
+    end
+  end
+end

data/lib/popro/progress.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Popro
+  class Progress
+    require_relative 'context'
+    require_relative 'info'
+    require_relative 'indicator'
+
+    attr_reader :context
+
+    def initialize(**options)
+      @started = false
+      @info = Info.new(total: options.delete(:total), current: options.delete(:current))
+
+      options[:step] ||= (block_given? ? 0 : 1)
+      options[:progress] = self
+      options[:info] = @info
+      options[:indicator] = Indicator.default unless options.key? :indicator
+
+      @context = Context.new(**options)
+
+      register_aliases
+      return unless block_given?
+
+      yield self
+      done
+    end
+
+    private
+
+    def register_aliases
+      class << self
+        %i[each each0 each_will to_proc did will formatter start done].each do |method_name|
+          define_method method_name do |*args, &block|
+            @context.public_send(method_name, *args, &block)
+          end
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: popro
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- MikeSmithEU
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-06-01 00:00:00.000000000 Z
+dependencies: []
+description: The Poor-Man's Progress Indicator
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG
+- LICENSE
+- README.md
+- bin/popro
+- lib/popro.rb
+- lib/popro/context.rb
+- lib/popro/formatter.rb
+- lib/popro/indicator.rb
+- lib/popro/indicator/rails.rb
+- lib/popro/info.rb
+- lib/popro/progress.rb
+homepage: https://rubygems.org/gems/popro
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.2
+signing_key: 
+specification_version: 4
+summary: Po'Pro
+test_files: []