trick_bag 0.66.0 → 0.67.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1d232e6acd5101ddede4f818540a495f8cb9a454
-  data.tar.gz: b8b773b9d5b40ec1e7e8fe2d61888d59d9a35be0
+  metadata.gz: 7f8d5b7a9f77fdc75d8672b5947fd8075cca1ab5
+  data.tar.gz: e61fd4ec8b3d7dc55023e2323e7cf75f853d9389
 SHA512:
-  metadata.gz: d90de4a2b882180737bc7ac377b75521e173b1796be0c1204a37a617c3221dfd3140fd391e3da8e9de2c19dff4c16c2b9b05011dc06fabd76a9324cf924aba75
-  data.tar.gz: e9d782a5aebcd295387481e6551600747f36539b3ae20a31f4f6db69ec659efd04ac2ee35f3643781ddffa45fcbcbbbad49adbf32a0c1efaaa9d3fa252b29f8f
+  metadata.gz: 50b8e5a3407f1b725598a1f22de963682b5e68f154f575989af03e6a84f4e18c39e17c4975978eb8ea2e32c0f705f05fecd41701619524e7e20c40571342d7b6
+  data.tar.gz: edf428cd0e32c8f282ae0f80c84ba5a274d481e6973ba065ba4f1adeb3ebb5e2a43c70f40ccdde6ac5cfc98741faeab7b8b109519ea0b7bc0725c36129699561

data/.travis.yml

@@ -7,8 +7,9 @@ before_install:
 
 
 rvm:
+- 2.4.2
 - 2.0.0
-- 1.9.3
-- jruby-19mode
+- jruby-1.7.26
+- jruby-9.1.9.0
 
 script: "bundle exec rspec spec"

data/README.md

@@ -21,7 +21,159 @@ Or install it yourself as:
 
 ## Usage
 
-See the unit tests in the spec directory tree for usage examples.
+The best ways to understand the usage are to look at a) the unit tests in the spec directory tree,
+b) the comments in the source files, and c) the source code itself. That said, here is a summary:
+
+### CollectionAccess
+
+* `accessor` - returns lambda to simplify access to a deeply nested hash, as in 
+  `customer_accessor['contact_info.address.city']`
+  instead of `customer['contact_info']['address']['city']`
+* `#access` - worker method for above, also publicly available for use; called as:
+  `access(customer, 'contact_info', 'address', 'city')` 
+* `LinkedList` - a linked list implementation in Ruby
+
+### Enumerables
+
+* `BufferedEnumerable` - enumerable handling the buffering and the timing of fetching;
+  you provide fetcher and (optionally) fetch notifier callables
+* `CompoundEnumberable` - an enumerator used to provide all combinations of a set of Enumerables.
+* `EndlessLastEnumerable` - wraps another enumerable, and after it is exhausted, yields the same value on successive calls
+* `FileLineReader` - Reads a file containing strings, one on each line, and feeds them
+  in its each() method.  Strips all lines' leading and trailing whitespace,
+  and ignores all empty lines and lines beginning with the comment character `#`.
+  Especially useful in reading configuration files.
+* `FilteredEnumerable` - like `my_enumerable.lazy.select { ... }.lazy`, but supports changing the filter at any time
+
+### Formatters
+
+* `BinaryToHexAndAscii` - formats bytes in hex and ASCII, e.g.: 
+```
+0x   0  00 07 0E 15 | 1C 23 2A 31 | 38 3F 46 4D | 54 5B 62 69  .....#*18?FMT[bi
+0x  10  70 77 7E 85 | 8C 93 9A A1 | A8 AF B6 BD | C4 CB D2 D9  pw~.............
+```
+* `ErbRenderer` - convenience class  for ERB rendering; simplifies using a specific set of key/value pairs
+  as opposed to the current binding
+* `Formatters.duration_to_s` - formats number of seconds to string like `11 d, 13 h, 46 m, 40 s`
+* `Formatters.end_with_n` - reverse of `String#chomp` - 
+  useful for use with utilities like Diffy that complain about lines without line endings.
+* `Formatters.timestamp` - returns a timestamp string suitable for use in file names
+  in the year-month-day-hour-minute-second form, e.g. `2014-03-24_15-25-57`.
+* `Formatters.replace_with_timestamp` - replaces a token with the timestamp, as in:
+  `my-app-result-{dt}.txt` => `my-app-result-2014-03-24_15-25-57.txt`
+  Especially useful for generating file names.
+* `Formatters.dos2unix[!]` - formats a string with Unix line endings
+* `Formatters.array_diff` - returns a nicely formatted string output of the difference 
+  between 2 arrays
+* `Formatters.string_to_verbose_char_list` - returns a list of chars in a string, 1 per line,
+  with several representations of the values, e.g.:
+```
+     Index     Decimal        Hex              Binary    Character
+     -----     -------        ---              ------    ---------
+         0          97         61 x          110 0001 b       a
+         1          49         31 x           11 0001 b       1
+```  
+* `Formatters.thousands_separated` - adds thousands separators to an Integer 
+  string representation as appropriate
+
+
+### Functional
+
+These methods provide a shorthand for testing whether or not an object
+meets an Enumerable of conditional callables.
+
+
+### IO
+
+* `Gitignore` - these methods simulate the results of git's file pattern matching
+  based on the .gitignore file. They can be useful, for example,
+  in determining which files to include in a gem build when git is not present.
+* `Tempfiles.file_containing` - for the easy creation and deletion of a temp file
+  populated with text, wrapped around the code block you provide.
+* `TextModeStatusUpdater` - provides an updatable and customizable status/information
+  line in a terminal, typically used to display progress.
+
+
+### Meta
+
+* `attr` methods provide cleaner and more concise creation of attribute methods that
+  require control over accessibility (public, protected, private).
+* `class?` - is this name the name of a class?
+* `undef_class` - undefines a class; useful for unit testing code that dynamically creates classes.
+
+
+### Networking
+
+* `SshOutputReader` - Runs an ssh command, collecting the stdout and stderr produced by it.
+Optionally a predicate can be specified that, when called with the
+instance of this class, returns true to close the channel or false to continue
+(for example, when a certain string appears in the command's output).
+There are instance methods to return the most recent and all accumulated text
+for both stdout and stderr, so the predicate can easily inspect the text.
+
+
+### Numeric
+
+* `Bitmapping` - methods for converting from binary string and bit array to number and back 
+* `Bitmap` - a simple bitmap implementation, with several initialization methods
+* `KmgtNumericString` - converts number strings with optional suffixes of [kKmMgGtT] to integers.
+  Upper case letters represent powers of 1024, and lower case letters represent powers of 1000.
+  Also supports ranges, e.g. '1k..5k' will be converted by to_range to (1000..5000).
+* `Multicounter` - simplifies accumulating counts of multiple objects.
+* `StartAndMax` - provides an object that will tell you if the number exceeds
+  the starting point and if the number is >= the maximum (or if no maximum has been specified).
+* `Totals` - provides methods for working with percent of total
+
+
+### Operators
+
+* `multi_eq` - returns whether or not _all_ values passed are equal to each other
+
+
+### Timing
+
+* `Elapser` - provides ways to specify and test for elapsed state
+* `retry_until_true_or_timeout` -  calls a predicate proc repeatedly,
+  sleeping the specified interval between calls, returning if the predicate returns true,
+  and giving up after the specified number of seconds.
+  Displays elapsed and remaining times on the terminal.
+* `benchmark` - simplifies the output of benchmarking data with a text caption
+* `try_with_timeout` - runs the passed block in a new thread, ensuring that its execution time
+  does not exceed the specified duration.
+  
+  
+### Validations
+
+* hash validations - methods to see if any of the specified keys are missing from the hash,
+  and a method to raise an error with descriptive message if so
+* object validations - method to see if any of the specified instance variables are nil, and another
+  method that raises an error with descriptive message if so
+* `raise_on_invalid_value` - if the passed value is not in the list of valid values, raise an error
+  with descriptive message
+* regex validations - for working with multiple regexes and strings with which to match them  
+  
+  
+### Core Types
+
+`clone_hash_except` - creates a copy of a hash except for the specified keys (this functionality
+is already included in Rails, but not in Ruby itself)
+
+
+## Why?
+
+This library was born when I was writing a lot of testing tools and data collection and analysis software.
+At that time I also mentored a team of software testers using Ruby and Cucumber. I saw coding patterns that existed
+in multiple places, in varying levels of functionality and quality, or sometimes, totally absent when
+they would have been helpful. Why not implement these patterns once in a shared and tested library?
+
+Some may be very thin layers over the underlying Ruby implementations (e.g. the _Elapser_ class),
+and their usefulness may be questioned...but in the calling code, the use of these is more intention-revealing,
+object oriented, and results in more concise calling code.
+
+This gem's files, classes, and methods are for the most part isolated from each other and self-contained.
+This means that if you like you can easily copy single methods or files from the gem and copy them into
+your code base to eliminate a dependency on this gem. If you do this, then I suggest you include an
+attribution to this gem so that future developers can consult it for fixes and enhancements.
 
 
 ## Contributing

data/RELEASE_NOTES.md

@@ -1,9 +1,14 @@
+## v0.67.0
+
+* Move Functional methods into Functional module.
+* Improve README, esp. add class/method summaries.
+
+
 ## v0.66.0
 
 * Add TrickBag::Io::Gitignore.list_ignored_files.
 
 
-
 ## v0.65.1
 
 * Fix bug in TrickBag::Validations when raise_on_missing_keys was passed an array.

data/lib/trick_bag/enumerables/endless_last_enumerable.rb

@@ -3,9 +3,9 @@ require 'set'
 module TrickBag
 module Enumerables
 
-# Takes an array as input.  On successive calls to next, it returns the next
-# element in the array until the array has been exhausted, and then returns
-# the last element every time it's called.
+# Takes an enumerable or number as input.  On successive calls to next, it returns the next
+# element in the that enumerable until it has been exhausted, and then returns
+# the last element every time it's called. Especially useful in reading configuration files.
 #
 # You can use Ruby's array addition and multiplication features
 # to provide rich functionality, e.g.:

data/lib/trick_bag/enumerables/filtered_enumerable.rb

@@ -8,6 +8,14 @@ module Enumerables
 #
 # The filter is an optional parameter on the constructor, but can
 # also be set after creation with a mutator.
+#
+# If you do not intend to change the filter after it is created,
+# you should probably just use Ruby's built in lazy enumerators, as in:
+# e = (1..10000000000000000000000000000).lazy.select { |n| n.even? }.lazy
+#
+# This class really comes in handy when the filter needs to be changed during
+# the enumerator's lifetime.
+
 class FilteredEnumerable
 
   include Enumerable

data/lib/trick_bag/formatters/formatters.rb

@@ -55,6 +55,7 @@ module Formatters
   end
 
 
+  # Reverse of String#chomp.
   # Convert to string if not already a string.
   # Append new line to string if the string is not empty and does not already end with one.
   # This is to disable the Diffy warning message "No newline at end of file"
@@ -80,7 +81,7 @@ module Formatters
   # for example:
   #
   # replace_with_timestamp('my-app-result-{dt}.txt') => "my-app-result-2014-03-24_15-25-57.txt"
-    def replace_with_timestamp(string, marker = '{dt}', datetime = DateTime.now)
+  def replace_with_timestamp(string, marker = '{dt}', datetime = DateTime.now)
     string.gsub(marker, timestamp(datetime))
   end
 

data/lib/trick_bag/functional/functional.rb

@@ -1,4 +1,8 @@
 module TrickBag
+module Functional
+
+  # These methods provide a shorthand for testing whether or not an object
+  # meets an Enumerable of conditional callables.
 
   module_function
 
@@ -23,3 +27,4 @@ module TrickBag
     conditions.any? { |condition| condition.(object) }
   end
 end
+end

data/lib/trick_bag/io/temp_files.rb

@@ -6,8 +6,8 @@ module TempFiles
 
     module_function
 
-    # Creates a temporary file containing the specified text,
-    # passes its filespec to the passed block, then deletes the file.
+    # For the easy creation and deletion of a temp file populated with text,
+    # wrapped around the code block you provide.
     #
     # @param text the text to write to the temporary file
     # @param file_prefix optional prefix for the temporary file's name

data/lib/trick_bag/io/text_mode_status_updater.rb

@@ -1,6 +1,8 @@
 module TrickBag
 module Io
 
+# Provides an updatable and customizable status/information line in a terminal,
+# typically used to display progress.
 # Updates the terminal line with text, erasing the original content and displaying at the same place.
 # Uses ANSI escape sequences for cursor positioning and clearing
 # (see http://www.oldlinux.org/Linux.old/Ref-docs/ASCII/ANSI%20Escape%20Sequences.htm).

data/lib/trick_bag/numeric/multi_counter.rb

@@ -1,7 +1,7 @@
 module TrickBag
 module Numeric
 
-# Supports multiple counts, each identified by a key.
+# Simplifies accumulating counts of multiple objects.
 # Like a hash, but does not allow []=; increment is the only way to modify a value.
 class MultiCounter
 

data/lib/trick_bag/numeric/start_and_max.rb

@@ -1,8 +1,10 @@
 module TrickBag
 module Numeric
 
-  # Like a Range, but includes useful functions with understandable names
-  # that account for the limits or absences of limits.
+  # Provides an object that will tell you if the number exceeds the starting point
+  # and if the number is >= the maximum (or if no maximum has been specified).
+  # While this functionality can easily be duplicated with more primitive
+  # code, this class provides an object whose use will be simpler and more readable.
   class StartAndMax
 
   attr_reader :start_pos, :max_count

data/lib/trick_bag/timing/timing.rb

@@ -9,8 +9,10 @@ module Timing
 
 
   # Calls a predicate proc repeatedly, sleeping the specified interval
-  # between calls, and giving up after the specified number of seconds.
+  # between calls, returning if the predicate returns true,
+  # and giving up after the specified number of seconds.
   # Displays elapsed and remaining times on the terminal.
+  # Outputs the time elapsed and the time to go.
   #
   # @param predicate something that can be called with .() or .call
   #   that returns a truthy value that indicates no further retries are necessary

data/lib/trick_bag/validations/gem_dependency_script.rb

@@ -5,7 +5,7 @@ module TrickBag
 
   # NOTE! If the gem you are testing defines a .gemspec file,
   # then this approach may be eliminated by instead
-  # running the following command in the project root (thank you, Rob Kidd):
+  # running the following command in the project root (thank you, Robb Kidd):
 
   # bundle exec ruby -e "require 'my_gem_name'"
 

data/lib/trick_bag/version.rb

@@ -1,3 +1,3 @@
 module TrickBag
-  VERSION = '0.66.0'
+  VERSION = '0.67.0'
 end

data/spec/trick_bag/{core_types_spec.rb → core_types/core_types_spec.rb}

@@ -1,5 +1,5 @@
-require_relative '../spec_helper'
-require 'trick_bag/core_types'
+require_relative '../../spec_helper'
+require_relative '../../../lib/trick_bag/core_types/core_types'
 
 module TrickBag
 

data/spec/trick_bag/functional/functional_spec.rb

@@ -5,6 +5,7 @@ require 'trick_bag/functional/functional'
 
 
 module TrickBag
+module Functional
 
   describe 'Composite predicates' do
 
@@ -17,15 +18,15 @@ module TrickBag
     context "none?" do
 
       specify "returns true when all are false" do
-        expect(TrickBag.none_with_object?(all_false_funcs, 1)).to eq(true)
+        expect(TrickBag::Functional.none_with_object?(all_false_funcs, 1)).to eq(true)
       end
 
       specify "returns false when all are true" do
-        expect(TrickBag.none_with_object?(all_true_funcs, 1)).to eq(false)
+        expect(TrickBag::Functional.none_with_object?(all_true_funcs, 1)).to eq(false)
       end
 
       specify "returns false when some are false and some are true" do
-        expect(TrickBag.none_with_object?(mixed_true_false_funcs, 1)).to eq(false)
+        expect(TrickBag::Functional.none_with_object?(mixed_true_false_funcs, 1)).to eq(false)
       end
     end
 
@@ -33,15 +34,15 @@ module TrickBag
     context "any?" do
 
       specify "returns false when all are false" do
-        expect(TrickBag.any_with_object?(all_false_funcs, 1)).to eq(false)
+        expect(TrickBag::Functional.any_with_object?(all_false_funcs, 1)).to eq(false)
       end
 
       specify "returns true when all are true" do
-        expect(TrickBag.any_with_object?(all_true_funcs, 1)).to eq(true)
+        expect(TrickBag::Functional.any_with_object?(all_true_funcs, 1)).to eq(true)
       end
 
       specify "returns true when some are false and some are true" do
-        expect(TrickBag.any_with_object?(mixed_true_false_funcs, 1)).to eq(true)
+        expect(TrickBag::Functional.any_with_object?(mixed_true_false_funcs, 1)).to eq(true)
       end
     end
 
@@ -49,16 +50,17 @@ module TrickBag
     context "all?" do
 
       specify "returns false when all are false" do
-        expect(TrickBag.all_with_object?(all_false_funcs, 1)).to eq(false)
+        expect(TrickBag::Functional.all_with_object?(all_false_funcs, 1)).to eq(false)
       end
 
       specify "returns true when all are true" do
-        expect(TrickBag.all_with_object?(all_true_funcs, 1)).to eq(true)
+        expect(TrickBag::Functional.all_with_object?(all_true_funcs, 1)).to eq(true)
       end
 
       specify "returns false when some are false and some are true" do
-        expect(TrickBag.all_with_object?(mixed_true_false_funcs, 1)).to eq(false)
+        expect(TrickBag::Functional.all_with_object?(mixed_true_false_funcs, 1)).to eq(false)
       end
     end
   end
 end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: trick_bag
 version: !ruby/object:Gem::Version
-  version: 0.66.0
+  version: 0.67.0
 platform: ruby
 authors:
 - Keith Bennett
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-09-24 00:00:00.000000000 Z
+date: 2017-09-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: os
@@ -140,7 +140,7 @@ files:
 - lib/trick_bag.rb
 - lib/trick_bag/collections/collection_access.rb
 - lib/trick_bag/collections/linked_list.rb
-- lib/trick_bag/core_types.rb
+- lib/trick_bag/core_types/core_types.rb
 - lib/trick_bag/enumerables/buffered_enumerable.rb
 - lib/trick_bag/enumerables/compound_enumerable.rb
 - lib/trick_bag/enumerables/endless_last_enumerable.rb
@@ -174,7 +174,7 @@ files:
 - spec/spec_helper.rb
 - spec/trick_bag/collections/collection_access_spec.rb
 - spec/trick_bag/collections/linked_list_spec.rb
-- spec/trick_bag/core_types_spec.rb
+- spec/trick_bag/core_types/core_types_spec.rb
 - spec/trick_bag/enumerables/buffered_enumerable_spec.rb
 - spec/trick_bag/enumerables/compound_enumerable_spec.rb
 - spec/trick_bag/enumerables/endless_last_enumerable_spec.rb
@@ -231,7 +231,7 @@ test_files:
 - spec/spec_helper.rb
 - spec/trick_bag/collections/collection_access_spec.rb
 - spec/trick_bag/collections/linked_list_spec.rb
-- spec/trick_bag/core_types_spec.rb
+- spec/trick_bag/core_types/core_types_spec.rb
 - spec/trick_bag/enumerables/buffered_enumerable_spec.rb
 - spec/trick_bag/enumerables/compound_enumerable_spec.rb
 - spec/trick_bag/enumerables/endless_last_enumerable_spec.rb