helpema 2.1.200129 → 3.0.210108

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d18fa86fd912cfcc45ebb9efbdae0f9ae2a207399660fca0b3f0e3ce3b2bad64
-  data.tar.gz: c18e1447a10e90e878644d982e1578965309264eae84c7badc3676c31e1c018b
+  metadata.gz: 0f73de852bf1c5e430ed5b5a0887e0b16ad37f3f4156843b40738065400b40e9
+  data.tar.gz: 111bed98f5e6f8c7cba8c1f2353ea8a1d94e24ac84cda4351380d54283bc779a
 SHA512:
-  metadata.gz: e7b98dfb0588da2070870131947cff69d9777d586fe72a7d513e3156c3f78b405e9d513d195ae18a952d099894965c44d0ba06fddd605825c6f06fe86297f604
-  data.tar.gz: f9cedadc0afe83aa718c637fe017555f50931023343ebc24519742b8cc17f89fe87367f4de4eafbfdcf30305b66ce4e0d23c8355ad344e62efa89e3827d42239
+  metadata.gz: 6b39435438e44edef870ed22e4b0a5acb6f2c2439cbe99906606fa62d6b224cbb1ce2fcc453f91c3b64bee6b70367d97605343c4a892db1e89eea0fac2a7fb39
+  data.tar.gz: 567e0d4eb2be6863b3f6fb9d183b77b3c549755dee855a629e282f544514dcf51b00cbc4ba9a4a5fdedb67e113ef963efd6a406a06c978182ea03f2cbaa7ee91

data/README.md

@@ -1,90 +1,116 @@
-# helpema
+# Helpema
 
-* [VERSION 2.1.200129](https://github.com/carlosjhr64/helpema/releases)
-* [github](https://github/carlosjhr64/helpema)
-* [rubygems](https://rubygems/gems/helpema)
+* [VERSION 3.0.210108](https://github.com/carlosjhr64/helpema/releases)
+* [github](https://github.com/carlosjhr64/helpema)
+* [rubygems](https://rubygems.org/gems/helpema)
 
 ## DESCRIPTION:
 
 Meant to be an eclectic collection of useful single functions and wrappers.
 
-Wrappers:
-
-* ssss-split
-* ssss-combine
-* zbarcam
-* youtube-dl -j
-
-Functions:
-
-* requires("gemname version",...)
-* params(arg,...){|h Hash[Class,Obj]|...}
-
-More later.
-
-## SYNOPSIS:
-
-    require 'helpema'
-    include HELPEMA
-
-    Helpema.requires <<-GEMS
-      awesome_print ~>1.8
-      base_convert ~>4.0
-      entropia ~>0.1
-    GEMS
-    #=> ["awesome_print", "base_convert", "entropia"]
-    # Returns the list of loaded gems.
-    # For those quick little scripts one writes in one's bin
-    # that annoyingly keep falling out of maintainance... right?
-
-    s0 = s1  = i = f0 = f1 = r = nil
-    Helpema.params(1, 2.0, 3, "Five", /Six/, "Seven", /Eight/) do |params|
-      s0 = params[String][0]
-      s1 = params[String][1]
-      i  = params[Integer][0]
-      f0 = params[Float][0]
-      f1 = params[Float][1]
-      r  = params[Regexp][0]
-    end
-    s0 #=> "Five"
-    s1 #=> "Seven"
-    i  #=> 1
-    f0 #=> 2.0
-    f1 #=> nil
-    r  #=> /Six/
-
-    SSSS.split("Top Secret!", threshold: 2, shares: 3)
-    #~> ^\["1-\h+", "2-\h+", "3-\h+"\]$
-    # Note that the split has random outputs on the same inputs.
-
-    SSSS.combine("3-055562917c41e68c6ab2c8", "1-27bf3cbfe8d2c25c7e8928")
-    #=> Top Secret!
-    # Pregenerated splits combine to reproduce the secret.
-
-    list = []
-    url = 'https://www.youtube.com/watch?v=u4oK3ZSccZI'
-    YouTubeDL.json(url){|json| list.push json}
-    # The url was for just one video
-    list.length #=> 1
-    json = list[0]
-    json['title'] #=> "Fortnite Easy Last Ten"
-
-    ZBar.cam( timeout=3 ) # Reads qrcodes on camera.
-    ZBar.screen # Reads qrcodes on screen.
+Featured method: `requires "good ~>3.0", "bad ~>2.7", "ugly ~>1.8"`
 
 ## INSTALL:
 
-    $ sudo gem install helpema
+```shell
+$ gem install helpema
+```
 
-## FEATURES:
+## SYNOPSIS:
 
-* Autoloaded: no need to pick and choose which library component to require.
+```ruby
+require 'helpema'
+include Helpema
+using Helpema
+
+### requires ###
+# Ensure ruby's and helpema's version.
+# Returns the list of loaded gems.
+# For those quick little scripts one writes in one's bin
+# that annoyingly keep falling out of maintainance... right?
+requires'
+ruby          ~>3.0
+helpema       ~>3.0
+base_convert  ~>4.0
+entropia      ~>0.1'
+#=> ["base_convert", "entropia"]
+
+### String#satisfies? ###
+# Uses Gem::Requirement and Gem::Version to check version strings.
+'1.2.3'.satisfies? '~>1.1' #=> true
+'1.2.3'.satisfies? '~>1.3' #=> false
+
+### run_command ###
+# Automates pipe creation to a system command.
+# See the code for all available features.
+run_command('date',{d: 'Dec 31, 2020'}) #=> "Thu Dec 31 12:00:00 AM PST 2020\n"
+
+### define_command ###
+# Creates a method out of a system command.
+# See the code for all available features.
+define_command(:date, cmd: 'date', usage: {d: nil}, synonyms: {string: :d})
+date(string: 'Dec 31, 2020') #=> "Thu Dec 31 12:00:00 AM PST 2020\n"
+
+### to_arg ###
+# A helper function to do system command calls.
+to_arg :q, true             #=> "-q"
+to_arg :quiet, true         #=> "--quiet"
+to_arg :verbose, false      #=> nil
+to_arg :f, '/path-to/file'  #=> ["-f", "/path-to/file"]
+to_arg :geo=, '10x20'       #=> "--geo=10x20"
+to_arg :arg0, 'Hello World' #=> "Hello World"
+
+### Hash#to_args ###
+{q: true, quiet: true, verbose: false, f: '/path-to/file', :geo= => '10x20', arg0: 'Hello World'}.to_args
+#=> ["-q", "--quiet", "-f", "/path-to/file", "--geo=10x20", "Hello World"]
+
+### Array#classify ###
+# Groups items in Array by class.
+[1, 2.0, :Three, 'Four', /Five/, :Six, 'Seven'].classify
+#=> {Integer=>[1], Float=>[2.0], Symbol=>[:Three, :Six], String=>["Four", "Seven"], Regexp=>[/Five/]}
+
+### SSSS.split ####
+SSSS.split(secret: "Top Secret!", threshold: 2, shares: 3)
+#~> ^\["1-\h+", "2-\h+", "3-\h+"\]$
+# Note that the split has random outputs on the same inputs.
+
+#### SSSS.combine ###
+# Pregenerated splits combine to reproduce the secret.
+SSSS.combine(secrets: ["3-055562917c41e68c6ab2c8", "1-27bf3cbfe8d2c25c7e8928"], threshold: 2)
+#=> "Top Secret!"
+
+### YouTubeDL.json ###
+list = []
+url = 'https://www.youtube.com/watch?v=u4oK3ZSccZI'
+YouTubeDL.json(url){|json| list.push json}
+# The url was for just one video
+list.length #=> 1
+json = list[0]
+json['title'] #=> "Fortnite Easy Last Ten"
+
+### ZBar.screen ###
+# Reads qrcodes on screen.
+string_or_nil = ZBar.screen
+
+### ZBar.cam ###
+# Reads qrcodes from camera.
+# You may want to wrap this one in a Timeout block.
+string = ZBar.cam
+```
+
+## TROUBLESHOOTING:
+
+Command version mismatch
+: set `Helpema::WRAPPER.version = "your.version"` or just nil it.
+
+More documentation
+: see [sig/helpema.rb](sig/helpema.rbs) for the expected method signatures.
 
 ## LICENSE:
 
 (The MIT License)
 
-Copyright (c) 2020 carlosjhr64
+Copyright (c) 2021 carlosjhr64
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/lib/helpema.rb

@@ -1,14 +1,18 @@
-module HELPEMA
-  VERSION = '2.1.200129'
+module Helpema
+  VERSION = '3.0.210108'
+
+  require_relative     'helpema/helpema'
 
-  autoload :Helpema,   'helpema/helpema.rb'
   autoload :SSSS,      'helpema/ssss.rb'
   autoload :YouTubeDL, 'helpema/youtubedl.rb'
   autoload :ZBar,      'helpema/zbar.rb'
 end
+
 # Requires:
 #`ruby`
+#`youtube-dl`
 #`ssss-split`
 #`ssss-combine`
 #`zbarcam`
+#`zbarimg`
 #`gnome-screenshot`

data/lib/helpema/helpema.rb

@@ -1,21 +1,112 @@
-module HELPEMA
 module Helpema
+  refine ::String do
+    def satisfies?(*reqs)
+      Gem::Requirement.new(*reqs).satisfied_by? Gem::Version.new(self)
+    end
+  end
+  refine ::Hash do
+    def to_args(usage:nil, synonyms:nil)
+      # create separate args from self with the translated synonyms
+      args = self.transform_keys(synonyms.to_h)
+      # pad usage's defaults to args
+      usage&.each{|key,default| args[key]=default unless args.has_key? key}
+      # order might be important so enforce usage
+      args = usage&.map{|k,v|[k,args[k]]} || args.to_a
+      # convert key,value tuples to final list of args
+      args.map!(&:to_arg)
+      # get rid of nil
+      args.select!{_1}
+      # ...and finally flatten!
+      args.flatten!
+      return args
+    end
+  end
+  refine ::Array do
+    def classify(hash: Hash.new{|h,k|h[k]=[]})
+      self.each{|v| hash[v.class] << v}
+      return hash
+    end
+    def to_arg
+      Helpema.to_arg(*self)
+    end
+  end
+  refine ::Symbol do
+    def to_flag
+      return nil if self[-1].match?(/\d/) # like :arg0
+      (self.length > 1)? "--#{self}": "-#{self}" # like --verbose or -V
+    end
+  end
+  using Helpema
+
+  def to_arg(key,value)
+    # keep only keys with value(no false or nil)
+    return nil unless value
+    # assume nil0/--long/-short
+    key = key.to_flag
+    if key
+      return key if value==true # a flag
+      return "#{key}#{value}" if key[-1]=='=' # joined key=value
+      return [key,value.to_s]
+    end
+    # It's a Nth arg, like arg0...
+    return value.to_s
+  end
+
+  def run_command(cmd, options={},
+    usage:nil, synonyms:nil, mode:'r',
+    exception:nil, forward_pass:nil, **popt, &blk)
+    args,ret = options.to_args(usage:usage,synonyms:synonyms),nil
+    $stderr.puts "#{cmd} #{args.join(' ')}" if $DEBUG
+    IO.popen([cmd, *args], mode, **popt) do |pipe|
+      ret = (forward_pass)? forward_pass.call(pipe, options, blk): (blk)? blk.call(pipe): pipe.read
+    end
+    (exception.nil? or $?.exitstatus==0)? ret : raise(exception)
+  end
+
+  def define_command(name,
+    cmd: name.to_s, version: nil, v: nil,
+    usage: nil, synonyms: nil,
+    mode: 'r',exception: nil,
+    **popt, &forward_pass)
+
+    # which version? --version or -v
+    if version and not `#{cmd} --version`.strip.match?(version)
+      raise "`#{cmd} --version` !~ #{version}"
+    end
+    if v and not `#{cmd} -v`.strip.match?(v)
+      raise "`#{cmd} -v` !~ #{v}"
+    end
+
+    define_method(name) do |**options, &blk|
+      run_command(cmd, options,
+        usage:usage, synonyms:synonyms, mode:mode,
+        exception:exception, forward_pass:forward_pass, **popt, &blk)
+    end
+  end
+
   def requires(*list)
     loaded = []
     list.each do |gems|
-      gems.lines.each do |gemname_version|
-        gemname, *version = gemname_version.split
-        gem gemname, *version  unless version.empty?
+      gems.lines.each do |gemname_reqs|
+        gemname, *reqs = gemname_reqs.split
+        next unless gemname
+        unless reqs.empty?
+          case gemname
+          when 'helpema'
+            raise "helpema #{VERSION} not #{reqs.join(', ')}" unless VERSION.satisfies?(*reqs)
+            next
+          when 'ruby'
+            raise "ruby #{RUBY_VERSION} not #{reqs.join(', ')}" unless RUBY_VERSION.satisfies?(*reqs)
+            next
+          else
+            gem gemname, *reqs
+          end
+        end
         require gemname and loaded.push gemname
       end
     end
-    loaded
-  end
-
-  def params(*args)
-    yield args.inject(Hash.new{|h,k|h[k]=[]}){|h,v|h[v.class].push(v) && h}
+    return loaded
   end
 
   extend self
 end
-end

data/lib/helpema/ssss.rb

@@ -1,34 +1,36 @@
-require 'open3'
-
-module HELPEMA
+module Helpema
 module SSSS
-  # Note how the function mirrors the command line options.
-  def self.split(secret, t0=2, n0=3,
-                 t: t0, n: n0,
-                 threshold: t, shares: n,
-                 w: nil, s: nil, x: false,
-                 token: w, level: s, hexmode: x)
-    pwds = nil
-    command = "ssss-split -Q -t #{threshold} -n #{shares}"
-    command << " -w #{token}"  if token
-    command << " -s #{level}"  if level
-    command << " -x"           if hexmode
-    Open3.popen3(command) do |stdin, stdout, stderr|
-      stdin.puts secret
-      stdin.close
-      pwds = stdout.read.split("\n")
-    end
-    return pwds
+class << self
+  attr_accessor :version
+  SSSS.version = 'Version: 0\.[567]\b' # version as of this writing is 0.5
+
+  def split(secret:, threshold:, shares:, token:nil, level:nil, hexmode:false) =
+     _split(secret:secret, threshold:threshold, shares:shares, token:token, level:level, hexmode:hexmode)
+  define_command(:_split,
+    cmd: 'ssss-split', v: SSSS.version,
+    usage: {Q:true,t:2,n:3,w:nil,s:nil,x:false},
+    synonyms: {threshold: :t, shares: :n, token: :w,  level: :s, hexmode: :x},
+    mode: 'w+', exception: 'ssss-split failed.',
+    err: [:child, :out]
+  ) do |pipe, options, blk|
+    pipe.puts options.fetch(:secret)
+    pipe.read.split.last(options[:shares])
   end
 
-  def self.combine(*pwds)
-    pwd = ''
-    Open3.popen3("ssss-combine -q -t #{pwds.length}") do |stdin, stdout, stderr|
-      pwds.each{|p| stdin.puts p}
-      stdin.close
-      pwd = stderr.read.split("\n").last
-    end
-    return pwd
+  def combine(secrets:, threshold:, hexmode:false)
+    raise 'Need threshold number of secrets.' unless secrets.size >= threshold
+    _combine(secrets:secrets, threshold:threshold, hexmode:hexmode)
   end
+  define_command(:_combine,
+    cmd: 'ssss-combine', v: SSSS.version,
+    usage: {Q:true,t:2,x:false}, synonyms: {threshold: :t, hexmode: :x},
+    mode: 'w+', exception: 'ssss-combine failed.',
+    err: [:child, :out]
+  ) do |pipe, options, blk|
+    secrets,n = options.fetch_values(:secrets,:threshold)
+    secrets.first(n).each{pipe.puts _1}
+    pipe.read.lines.last.chomp
+  end
+end
 end
 end

data/lib/helpema/youtubedl.rb

@@ -1,20 +1,25 @@
 require 'json'
-require 'open3'
 
-module HELPEMA
+module Helpema
 module YouTubeDL
-  def self.json(url, pwd=nil)
-    Open3.popen2e("youtube-dl -j '#{url}'") do |i, o|
-      i.puts pwd if pwd
-      i.close
-      o.each do |line|
-        begin
-          yield JSON.parse line
-        rescue JSON::ParserError
-          yield line
-        end
+class << self
+  attr_accessor :version
+  YouTubeDL.version = '^202\d\.[01]\d\.[0123]\d$'
+
+  def json(url, &blk) = _json(url:url, &blk)
+  define_command(:_json,
+    cmd: 'youtube-dl', version: YouTubeDL.version,
+    usage: {j:true, arg0:nil}, synonyms: {url: :arg0},
+    err: '/dev/null'
+  ) do |pipe, options, blk|
+    pipe.each do |data|
+      begin
+        data = JSON.parse data
+      ensure
+        blk.call data
       end
     end
   end
 end
 end
+end

data/lib/helpema/zbar.rb

@@ -1,38 +1,42 @@
-require 'timeout'
 require 'tmpdir'
 
-module HELPEMA
+module Helpema
 module ZBar
-  def self.cam(timeout=3)
-    raw = ''
-    IO.popen('zbarcam --nodisplay --raw --prescale=800x800', 'r') do |io|
-      begin
-        Timeout.timeout(timeout) do
-          raw << io.gets
-          while q = io.gets
-            break if q=="\n"
-            raw << q
-          end
-          raw.strip!
-        end
-      rescue Timeout::Error
-        raw = nil
-        $stderr.puts $!
-      ensure
-        Process.kill('INT', io.pid)
-      end
+class << self
+  attr_accessor :version, :screenshot
+  ZBar.version = '^0\.2[345]\b' # version as of this writing is 0.23
+  ZBar.screenshot = ['gnome-screenshot', '-f']
+
+  def cam() = _cam()
+  define_command(:_cam,
+    cmd: 'zbarcam', version: ZBar.version,
+    usage: {raw:true,quiet:true,nodisplay:true, :prescale= => '800x800'},
+    synonyms: {prescale: :prescale=}
+  ) do |pipe, kw, blk|
+    begin
+      pipe.gets.chomp # This is the return value!
+    ensure
+      Process.kill('TERM', pipe.pid)
     end
-    raw
   end
 
-  def self.screen
+  def img(filename) = _img(filename:filename)
+  define_command(:_img, cmd: 'zbarimg', version: ZBar.version,
+                 usage: {q:true,raw:true,arg0:nil}, synonyms: {filename: :arg0})
+
+  def screen
     raw = nil
     Dir.mktmpdir do |tmpdir|
-      screenshot = File.join(tmpdir, "#{$$}.#{Time.now.to_f}.png")
-      system "gnome-screenshot -f #{screenshot}"
-      raw = `zbarimg -q --raw #{screenshot}`.strip
+     _ = File.join(tmpdir, "#{$$}.#{Time.now.to_f}.png")
+     raw = _ if snapshot(_) and not (_=ZBar.img(_).chomp).empty?
     end
     raw
   end
+
+  private
+  def snapshot(filename)
+    system(*ZBar.screenshot, filename)
+  end
+end
 end
 end

metadata

@@ -1,21 +1,19 @@
 --- !ruby/object:Gem::Specification
 name: helpema
 version: !ruby/object:Gem::Version
-  version: 2.1.200129
+  version: 3.0.210108
 platform: ruby
 authors:
 - carlosjhr64
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-01-29 00:00:00.000000000 Z
+date: 2021-01-08 00:00:00.000000000 Z
 dependencies: []
 description: |
   Meant to be an eclectic collection of useful single functions and wrappers.
-  Wrappers: ssss-split, ssss-combine, zbarcam, youtube-dl -j.
-  Funtions: requires("gemname version",...).
 
-  More later.
+  Featured method: `requires "good ~>3.0", "bad ~>2.7", "ugly ~>1.8"`
 email: carlosjhr64@gmail.com
 executables: []
 extensions: []
@@ -31,7 +29,7 @@ homepage: https://github.com/carlosjhr64/helpema
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -46,15 +44,15 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements:
-- 'ruby: ruby 2.7.0p0 (2019-12-25 revision 647ee6f091) [x86_64-linux]'
+- 'ruby: ruby 3.0.0p0 (2020-12-25 revision 95aff21468) [x86_64-linux]'
+- 'youtube-dl: 2020.12.31'
 - 'ssss-split: 0.5'
 - 'ssss-combine: 0.5'
 - 'zbarcam: 0.23'
-- 'gnome-screenshot: gnome-screenshot 3.34.0'
-rubygems_version: 3.1.2
-signing_key: 
+- 'zbarimg: 0.23'
+- 'gnome-screenshot: gnome-screenshot 3.38.0'
+rubygems_version: 3.2.3
+signing_key:
 specification_version: 4
-summary: 'Meant to be an eclectic collection of useful single functions and wrappers.
-  Wrappers: ssss-split, ssss-combine, zbarcam, youtube-dl -j. Funtions: requires("gemname
-  version",...).'
+summary: Meant to be an eclectic collection of useful single functions and wrappers.
 test_files: []