dataMetaXtra 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 00761eca06212bd8aeb1fc0a7314ea2c6b617d0b
+  data.tar.gz: 0494fe83175c12733454a2be40b8830dfe80b255
+SHA512:
+  metadata.gz: 49dfcb62a7601f35d4a4438c78c4a993587571b2629300468edad1532d62b41fe18cb09bcfbb36d1fedb6f879b30c6e0ca3f6ffe953aa451f397dd6489fbb86f
+  data.tar.gz: 5392d0eced309ab9a28c7de1da92b69b3423b350062d3fbbfc1d148cba38eb4e22a4fe5e97fd5ed000ca1d55828bd19ffcc15840047e787ebf3281351db9ad5f

data/.yardopts

@@ -0,0 +1 @@
+--title "DataMeta Ruby Extras" -r README.md --charset UTF-8 lib/**/* - README.md

data/History.md

@@ -0,0 +1,5 @@
+# `dataMetaXtra` Release history:
+
+## `1.0.0` released `2017-01-15`
+* 1 major enhancement:
+    * Initial release

data/Manifest.txt

@@ -0,0 +1,8 @@
+History.txt
+Manifest.txt
+PostInstall.txt
+README.rdoc
+Rakefile
+lib/dataMetaXtra.rb
+test/test_helper.rb
+test/test_dataMetaXtra.rb

data/PostInstall.txt

@@ -0,0 +1,2 @@
+No special steps
+

data/README.md

@@ -0,0 +1,32 @@
+# dataMetaXtra
+
+A few small enhancements to some standard Ruby classes in one convenient place.
+
+References to this gem's:
+
+* [Source](https://https://github.com/eBayDataMeta/DataMeta-gems)
+
+## DESCRIPTION:
+
+See the [DataMeta Project](https://github.com/eBayDataMeta)
+
+## FEATURES/PROBLEMS:
+
+* None so far
+
+## SYNOPSIS:
+
+* No command line runnables in this gem, it is a library only.
+
+## REQUIREMENTS:
+
+* Standard Ruby 1.9.3 or later.
+
+## INSTALL:
+
+    gem install dataMetaXtra
+
+## LICENSE:
+
+[Apache v 2.0](https://github.com/eBayDataMeta/DataMeta/blob/master/LICENSE.md)
+

data/Rakefile

@@ -0,0 +1,13 @@
+%w(yard rdoc/task rake/testtask fileutils ./lib/dataMetaXtra).each{ |r| require r}
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+end
+
+desc 'Regen RDocs'
+task :default => :docs
+
+YARD::Rake::YardocTask.new('docs') {|r|
+    r.stats_options = ['--list-undoc']
+}
+

data/lib/dataMetaXtra/fileSys.rb

@@ -0,0 +1,335 @@
+
+module DataMetaXtra
+
+=begin rdoc
+File System utilities.
+=end
+    module FileSys
+
+=begin rdoc
+FileSystem Entry
+=end
+        class FsEntry
+=begin rdoc
+Entyr type - file.
+=end
+            FILE_TYPE = :f
+=begin rdoc
+Entyr type - directory.
+=end
+            DIR_TYPE = :d
+
+        end
+
+=begin rdoc
+A set of permissions: any mix of read, write and execute, including all set to false.
+@!attribute [rw] r
+    @return [Boolean] read access, true or false
+@!attribute [rw] w
+    @return [Boolean] write access, true or false
+@!attribute [rw] w
+    @return [Boolean] execute access, true or false
+
+=end
+        class Perm
+            attr_accessor :r, :w, :x
+
+# POSIX Read permission mask: binary 100
+            READ_MASK = 4
+
+# POSIX Write permission mask: binary 010
+            WRITE_MASK = 2
+
+# POSIX Execute permission mask: binary 1
+            EXEC_MASK = 1
+=begin rdoc
+Unix {http://en.wikipedia.org/wiki/Sticky_bit Sticky bit},
+the +S_ISVTX+ mask (or +S_ISTXT+ in BSD) defined in
+{http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_stat.h.html sys/stat.h}.
+Use with caution because the semantics is fuzzy and, by some is considered obsolete.
+=end
+            STICKY_MASK = 01000
+
+=begin rdoc
+Unix +S_ISUID+ flag defined in {http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_stat.h.html sys/stat.h}
+which sets the owner's ID on executable regardless of who actually activates the executable.
+See {http://en.wikipedia.org/wiki/Setuid this article for details.}
+=end
+            USER_ID_EXE_MASK = 04000
+
+=begin rdoc
+Unix +S_ISGID+ flag defined in {http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_stat.h.html sys/stat.h}
+which sets the owner's ID on executable regardless of who actually activates the executable.
+See {http://en.wikipedia.org/wiki/Setuid this article for details.}
+=end
+            GROUP_ID_EXE_MASK = 02000
+
+            def initialize(r, w, x)
+                @r, @w, @x = r, w, x
+            end
+
+=begin rdoc
+Standard Ruby object equality method for hashes and sets.
+=end
+            def eql?(other)
+                self.r == other.r && self.w == other.w && self.x == other.x
+            end
+
+=begin rdoc
+Redefine equality operator for simple comparison, not delegated to {#eql?}, code simply repeated here
+for speed
+=end
+            def ==(other)
+                self.r == other.r && self.w == other.w && self.x == other.x
+            end
+=begin rdoc
+Creates an instance from textual specification, up to tree letters +r+, +w+, +x+ in any order,
+'<tt>r</tt>' for 'read', '<tt>w</tt>' for 'write', '<tt>x</tt>' for 'execute.
+Letter present turns the setting on, letter absent turns it off.
+@param [String] specs String of letters as described or a Fixnum with usual Posix bitmask: 4 for read, 2 for write, 1 for exec.
+@raise [ArgumentError] if the specs contain invalid character when specified as a String or if it does not fall into the range
+    between 0 and 7 inclusively if passed as a Fixnum
+@return [Perm] instance per the specs
+=end
+            def self.of(specs)
+                result = Perm.new(false, false, false)
+                case
+                    when specs.kind_of?(String)
+                        specs.each_char { |c|
+                            case c
+                                when 'r'
+                                    result.r = true
+                                when 'w'
+                                    result.w = true
+                                when 'x'
+                                    result.x = true
+                                else
+                                    raise ArgumentError, %<Illegal perms letter "#{c}" in the string of "#{specs}">
+                            end
+                        }
+                    when specs.kind_of?(Fixnum)
+                        raise ArgumentError, %<Illegal perm mask value of #{specs}> if specs < 0 || specs > 7
+                        result.r = true if specs & READ_MASK != 0
+                        result.w = true if specs & WRITE_MASK != 0
+                        result.x = true if specs & EXEC_MASK != 0
+                    else
+                        raise ArgumentError, %<Illegal specs: "#{specs.inspect}">
+                end
+                result
+            end
+
+=begin rdoc
+Turns the permission into the 'rwx' format for brevity and serialization
+=end
+            def toRwx
+                result = ''
+                result << 'r' if r
+                result << 'w' if w
+                result << 'x' if x
+                result
+            end
+
+=begin rdoc
+Turns the permission into the bitmask format for brevity and serialization
+=end
+
+            def to_i
+                result = 0
+                result |= READ_MASK if r
+                result |= WRITE_MASK if w
+                result |= EXEC_MASK if x
+                result
+            end
+=begin rdoc
+Convenient instance - all perms
+=end
+            ALL = Perm.new(true, true, true)
+
+=begin rdoc
+Convenient instance - no perms
+=end
+            NONE = Perm.new(false, false, false)
+
+=begin rdoc
+Convenient instance - read only
+=end
+            R = Perm.new(true, false, false)
+
+=begin rdoc
+Convenient instance - write only
+=end
+            W = Perm.new(false, true, false)
+
+=begin rdoc
+Convenient instance - read/write
+=end
+            RW = Perm.new(true, true, false)
+
+=begin rdoc
+Convenient instance - read and exec
+=end
+            RX = Perm.new(true, false, true)
+# Not providing constants for just exec and write+exec, those are not very useful and hardly ever seen.
+
+=begin rdoc
+Creates an instance with 3 booleans: read, write, exec
+=end
+        end
+
+=begin rdoc
+POSIX access perms - per system, user, group and world
+
+@!attribute [rw] s
+    @return [Perm] Sticky flag
+
+@!attribute [rw] u
+    @return [Perm] user perms
+
+@!attribute [rw] g
+    @return [Perm] group perms
+
+@!attribute [rw] a
+    @return [Perm] world perms (all)
+=end
+        class PosixPerms
+            attr_accessor :s, :u, :g, :a
+=begin rdoc
+Parses the {Perm} instance from the given source.
+
+@param [String] source either a String or a Fixnum a {Perm} or +nil+, see the method {Perm.of} for details.
+@param [String] kind the kind of the permissions for diagnostics, like 'user', 'group', 'world' or 'system'
+@return [Perm] instance according to the description
+@raise [ArgumentError] if the specs contain invalid character in case of a String or if the source is neither
+    a String nor a {Perm} nor +nil+
+=end
+            def self.from(source, kind)
+                case
+                    when source.kind_of?(NilClass) || source.kind_of?(Perm)
+                        source
+                    when source.kind_of?(String) || source.kind_of?(Fixnum)
+                        Perm.of(source)
+                    else
+                        raise ArgumentError, %<For #{kind} perms, invalid perm source: #{source.inspect} >
+                end
+            end
+
+=begin rdoc
+Creates an instance
+@param [String] user user permissions, can be passed as {Perm} object or String or Fixnum, see the method {PosixPerms.from} for details.
+@param [String] group group permissions, can be passed as {Perm} object or String or Fixnum, see the method {PosixPerms.from} for details.
+@param [String] world world permissions, can be passed as {Perm} object or String or Fixnum, see the method {PosixPerms.from} for details.
+@param [String] sticky flag, can be passed as {Perm} object or String or Fixnum, see the method {PosixPerms.from} for details.
+=end
+            def initialize(user, group, world, sys = nil)
+                @u = PosixPerms.from(user, 'user')
+                @g = PosixPerms.from(group, 'group')
+                @a = PosixPerms.from(world, 'world')
+                @s = PosixPerms.from(sys, 'system')
+            end
+
+=begin rdoc
+Standard Ruby object equality method for hashes and sets.
+=end
+            def eql?(other)
+                self.u == other.u && self.g == other.g && self.a == other.a && self.s == other.s
+            end
+=begin rdoc
+Redefine equality operator for simple comparison, not delegated to {#eql?}, code simply repeated here
+for speed
+=end
+            def ==(other)
+                self.u == other.u && self.g == other.g && self.a == other.a && self.s == other.s
+            end
+
+=begin
+Converts to integer POSIX specification, 3 bits per each of User, Group, All aka World aka Others
+=end
+            def to_i; ('%d%d%d' % [@u, @g, @a]).to_i(8) end
+
+        end
+
+=begin rdoc
+Generic Id and Name pair, good for any such situation, but in this case used specifically for POSIX user/group ID+Name.
+
+Regarding equality of these instances, it's better to use one of the components straight, although the both the {#eql?}
+and <tt>==</tt> method override are provided.
+
+@!attribute [rw] id
+    @return [Fixnum] numeric ID associated with the name.
+
+@!attribute [rw] name
+    @return [String] the name associated with the ID
+
+=end
+        class IdName
+            attr_accessor :id, :name
+
+=begin rdoc
+Name-only instance, id set to nil. Useful for cases when ID is irrelevant, such as transferring directory structure
+between hosts.
+@raise [ArgumentError] if the name string is empty or contains invalid characters
+@param [String] name the {#name}
+=end
+            def self.forName(name)
+                IdName.new(nil, name)
+            end
+
+=begin rdoc
+Convenience constructor
+@raise [ArgumentError] if the name string is empty or contains invalid characters
+=end
+            def initialize(id, name)
+                raise ArgumentError, %<Invalid POSIX name: "#{name}"> unless name =~ /^[a-z][\w\.-]*$/
+                @id, @name = id, name
+            end
+
+=begin rdoc
+Standard Ruby object equality method for hashes and sets.
+=end
+            def eql?(other)
+                self.id == other.id && self.name == other.name
+            end
+=begin rdoc
+Redefine equality operator for simple comparison, not delegated to {#eql?}, code simply repeated here
+for speed
+=end
+            def ==(other)
+                self.id == other.id && self.name == other.name
+            end
+        end
+
+=begin rdoc
+POSIX ownership information - group and the user
+=end
+        class PosixOwn
+            attr_accessor :g, :u
+=begin rdoc
+@param [String] source either a String or a {IdName} or +nil+, see the method {IdName.forName} for details.
+@param [String] kind the kind of the ownership for diagnostics, user or group
+@return [IdName] instance according to the description
+@raise [ArgumentError] if the specs contain invalid character in case of a String or if the source is neither
+    a String nor a {Perm} nor +nil+
+
+=end
+            def self.from(source, kind)
+                case
+                    when source.kind_of?(NilClass) || source.kind_of?(IdName)
+                        source
+                    when source.kind_of?(String)
+                        IdName.forName(source)
+                    else
+                        raise ArgumentError, %<For #{kind} ownership, invalid ownership source: #{source.inspect} >
+                end
+            end
+=begin rdoc
+Convenience constructor
+@param [IdName] user either the IdName instance or a string, in case of a string, see {IdName.forName}
+=end
+            def initialize(user, group = nil)
+                @u = PosixOwn.from(user, 'user')
+                @g = PosixOwn.from(group, 'group')
+            end
+        end
+    end
+end
+

data/lib/dataMetaXtra.rb

@@ -0,0 +1,212 @@
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require 'logger'
+
+#Various extensions to the Ruby SDK addressing whatever shortcomings we run into.
+module DataMetaXtra
+    # Current version
+    VERSION = '1.0.0'
+
+    # Default Logger datetime format
+    LOGGER_DTTM_FMT = '%Y-%m-%d %H:%M:%S'
+
+# Constants to deal with the operational system, operational environment
+    module Sys
+        # Platform constant - +true+ if running under Microsoft Windows.
+        WINDOWS = (/mswin|mingw|bccwin|wince|emx/ =~ RUBY_PLATFORM) != nil
+
+        # Platform constant - +true+ if running under Cygwin.
+        CYGWIN = (/cygwin/ =~ RUBY_PLATFORM) != nil
+
+        # Platform constant - +true+ if running under MacOS X.
+        MAC_OS_X = (/darwin/ =~ RUBY_PLATFORM) != nil
+
+        # Platform constant - +true+ if running under Linux.
+        LINUX = (/linux|GNU/i =~ RUBY_PLATFORM) != nil
+
+        # Platform constant - +true+ if running under any Unix environment: Linux, MacOS X or Cygwin.
+        UNIX = LINUX || MAC_OS_X || CYGWIN
+
+        # Who's running this program - this won't change as long as the program is running.
+        OS_USER = ENV['USERNAME'] || ENV['USER']
+
+        # What's the current user's home path in the filesystem.
+        OS_USER_HOME= case
+            when WINDOWS
+                "#{ENV['HOMEDRIVE']}/#{ENV['HOMEPATH'].gsub(/\\/, '/')}"
+            when CYGWIN
+                "#{ENV['HOME']}" # changed in latest versions of CygWin, now you get /cygdrive/c/Users/mubergens/
+                #"/cygdrive/#{ENV['HOMEDRIVE'][0, 1].downcase}#{ENV['HOMEPATH'].gsub(/\\/, '/')}"
+            else # Linux, MacOS (verified)
+                "#{ENV['HOME']}"
+        end
+    end
+=begin rdoc
+Builds a default logger for the given trollop opts and parser.
+If the opts and parser passed, builds the logger according to the options,
+with daily rollover and max size 10 M.
+
+If no opts or no parser passed, returns the logger to STDOUT for the WARN level.
+
+There is no point in creating a more generic method, the bare <tt>Logger.new</tt> call
+creates a weekly logger with the 1M size, to STDOUT. Can call <tt>Logger.new('file.log')</tt>
+
+The default level is DEBUG, therefore you may want change it
+
+@param [Hash] opts standard Ruby options hash keyed by a sym, see individual options for details
+@param [Trollop::Parser] parser optional Trollop parser to call "educate" on.
+=end
+    def defaultLogger(opts=nil, parser=nil)
+        if opts && parser
+            #noinspection RubyArgCount
+            result = Logger.new(opts[:logFile] || 'dataMetaXtra.log', 'daily', 10*1024*1024)
+            result.level = case opts[:level] ? opts[:level].downcase[0] : 'i'
+               when 'd'
+                   Logger::DEBUG
+               when 'i'
+                   Logger::INFO
+               when 'w'
+                   Logger::WARN
+               when 'e'
+                   Logger::ERROR
+               else
+                   parser.educate
+                   raise "Invalid log level #{opts[:level]}"
+            end
+            result.datetime_format = '%Y-%m-%d %H:%M:%S'
+            result
+        else
+            result = Logger.new($stdout)
+            result.level = Logger::WARN
+            result
+        end
+    end
+
+=begin rdoc
+Hack for Windows that often the name of the executable into the first argument:
+Discard the first argument if any if it has the same base file name as the current runnable
+Pass the caller's <tt>__FILE__</tt>.
+=end
+    def winArgHack(file)
+        ARGV.shift if !ARGV.empty? && ARGV[0] && File.exist?(ARGV[0]) && File.basename(ARGV[0]) == File.basename(file)
+    end
+
+    # Empty block factory
+    class ProcFactory
+        # Creates a new Proc, Proc requires a block, that's why have to place it in a class in a method
+        def create; Proc.new {} end
+    end
+
+=begin rdoc
+New empty binding for evaluation to avoid exposing class variables
+
+Require anything that you may need here outside of the block, it bubbles into here.
+=end
+    def nilBinding; ProcFactory.new.create.binding end
+
+=begin rdoc
+Adding some methods to the standard Ruby String class, useful to generate code.
+
+For more useful String related methods, see {ActiveSupport's Inflections}[http://apidock.com/rails/ActiveSupport/Inflector/inflections]
+
+=end
+    module Str
+
+        # Capitalize just first letter, leave everything else as it is.
+        # In contrast to the standard method capitalize which leaves the tail lowercased.
+        def capFirst(original)
+            original[0].chr.upcase + original[1..-1]
+        end
+
+        # turn the first letter lowercase, leave everything else as it is.
+        def downCaseFirst(original)
+            original[0].chr.downcase + original[1..-1]
+        end
+
+=begin rdoc
+Turns underscored into camelcase, with first letter of the string and each after underscore
+turned uppercase and the rest lowercase. Useful for making class names.
+
+Note that there is one good implementation in the {ActiveSupport gem}[http://apidock.com/rails/ActiveSupport/Inflector/inflections]
+too.
+
+Examples:
+* +this_one_var+ => +ThisOneVar+
+* +That_oThEr_vAR+ => +ThatOtherVar+
+
+See also variablize.
+=end
+        def camelize(original)
+            return original.downcase.capitalize if original =~ /[A-Z]+/ && original !~ /_/
+            return original.capitalize if original !~ /_/
+            original.split('_').map { |e| e.capitalize }.join
+        end
+
+=begin rdoc
+Same as camelize but makes sure that the first letter stays lowercase,
+useful for making variable names.
+
+Example:
+* +That_oTHer_vAr+ => +thatOtherVar+
+
+See also camelize.
+=end
+        def variablize(original)
+            return original.downcase if original =~ /[A-Z]+/ && original !~ /_/
+            return original[0].downcase + original[1..-1] if original !~ /_/
+            camelized = original.split('_').map { |e| e.capitalize }.join
+            camelized[0].downcase + camelized[1..-1]
+        end
+        module_function :camelize, :variablize, :capFirst, :downCaseFirst
+    end
+
+=begin rdoc
+Returns a log name for the given filename, replacing the extension with "<tt>log</tt>".
+
+Normally would pass <tt>__FILE__</tt> to this method.
+
+To get a full path, can call <tt>File.extend_path</tt>
+=end
+    def logName(fullPath); "#{fullPath.chomp(File.extname(fullPath))}.log"  end
+
+    # Turns the given instance to milliseconds as integer.
+    def toMillis(time); (time.to_f * 1000).to_i end
+
+    # Turns the given instance to microseconds as integer.
+    def toMicros(time); (time.to_f * 1000000).to_i end
+
+    # likely to be lacking precision
+    # UTC millis of now.
+    # not delegated to {#toMillis} because method calls are still relatively expensive in Ruby, especially in
+    # older versions
+    def nowMillis; (Time.now.utc.to_f * 1000).to_i end
+
+    # UTC seconds of now.
+    def nowSeconds; Time.now.utc.to_i end
+
+    # UTC micros of now.
+    # not delegated to {#toMicros} because method calls are still relatively expensive in Ruby, especially in
+    # older versions
+    def nowMicros; (Time.now.utc.to_f * 1000000).to_i end
+
+    # Current-Directory-Basename - dash - seconds.
+    def nowWdSeconds; "#{File.basename(Dir.getwd)}-#{nowSeconds}" end
+
+
+=begin rdoc
+Collects several glob patterns to this array. This is so simple that can be inlined.
+
+@param [Array] arr array to append the globs to
+@param [Array] patterns array of glob patterns
+
+@return [Array] flattenned source array with the filenames by the glob patterns appended to the end
+=end
+    def appendGlobs(arr, patterns); patterns.each { |p| arr << Dir.glob(p) }; arr.flatten end
+
+    # Turns this array to a PATH list according to <tt>File::PATH_SEPARATOR</tt>.
+    def toPathList(arr); arr.join(File::PATH_SEPARATOR) end
+
+    module_function :winArgHack, :defaultLogger, :nilBinding, :appendGlobs, :toPathList,
+                    :nowWdSeconds, :logName, :toMillis, :toMicros, :nowMillis, :nowSeconds, :nowMicros
+end

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: dataMetaXtra
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Michael Bergens
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-01-15 00:00:00.000000000 Z
+dependencies: []
+description: A few small enhancements to some standard Ruby classes in one place convenient
+  place.
+email: michael.bergens@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".yardopts"
+- History.md
+- Manifest.txt
+- PostInstall.txt
+- README.md
+- Rakefile
+- lib/dataMetaXtra.rb
+- lib/dataMetaXtra/fileSys.rb
+homepage: https://github.com/eBayDataMeta
+licenses:
+- Apache-2.0
+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: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: Small enhancements to a few Ruby standard classes.
+test_files: []