hash-joiner 0.0.0 → 0.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 59929742e9ae8e1a493994a7a2efba4074853eb3
-  data.tar.gz: 601562cd7b3f86a0f9c760464eee837d100f652f
+  metadata.gz: 49618706629e42c71fde8cb81f186d1c16a65468
+  data.tar.gz: cee8620a4dc55411b95385d9f01dae8fd1ab40c8
 SHA512:
-  metadata.gz: dec6c8351873c228ed08acf94a02876e001ae8f000fdd86f0a1bc27e7295d564181c7ea6ff35f9137cceb76b2e9919e4ee63cdeab98aef77d02bd8b3ab3d9716
-  data.tar.gz: 2788e3125ef91567e210c4841c17f63cbe009a7102820d76e9fe598ac954e85804f5b7cc7a9b5edd6efef16ea529913a502766b3cf790db002c75d12eb4d41c8
+  metadata.gz: a57bca28a0d760274250824714f0e8033ec1ad3a59e925fb878910c435ea20c61aae0ac23d20054f591d9a1d133c381c42812001082432e9a0eb650c5e394686
+  data.tar.gz: 0aeba3a5e17a911d7449b10da5efd80f510f56be597b0631d54dc39b196ff0e17cd441e8318055b4cc7fc49551d35af4c31aaf776a601c8afe7358dd38a51cb7

data/README.md

@@ -0,0 +1,153 @@
+## hash-joiner Gem
+
+[![Gem Version](https://badge.fury.io/rb/hash-joiner.svg)](http://badge.fury.io/rb/hash-joiner)
+[![Build Status](https://travis-ci.org/18F/hash-joiner.svg?branch=doc-update)](https://travis-ci.org/18F/hash-joiner)
+[![Code Climate](https://codeclimate.com/github/18F/hash-joiner/badges/gpa.svg)](https://codeclimate.com/github/18F/hash-joiner)
+[![Test Coverage](https://codeclimate.com/github/18F/hash-joiner/badges/coverage.svg)](https://codeclimate.com/github/18F/hash-joiner)
+
+Performs pruning or one-level promotion of `Hash` attributes (typically labeled `private:`), and deep merges and joins of `Hash` objects. Works on `Array` objects containing `Hash` objects as well.
+
+Downloads and API docs are available on the [hash-joiner RubyGems page](https://rubygems.org/gems/hash-joiner). API documentation is written using [YARD markup](http://yardoc.org/).
+
+Contributed by the 18F team, part of the United States General Services Administration: https://18f.gsa.gov/
+
+### Motivation
+
+This gem was extracted from [the 18F Hub Joiner plugin](https://github.com/18F/hub/blob/master/_plugins/joiner.rb). That plugin manipulates [Jekyll-imported data](http://jekyllrb.com/docs/datafiles/) by removing or promoting private data, building indices, and performing joins between different data files so that the results appear as unified collections in Jekyll's `site.data` object. It serves as the first stage in a pipeline that also builds cross-references and canonicalizes data before generating static HTML pages and other artifacts.
+
+### Installation
+
+```
+$ gem install hash-joiner
+```
+
+### Usage
+
+The typical use case is to have a YAML file containing both public and private data, with all private data nested within `private:` properties:
+
+```ruby
+> require 'hash-joiner'
+> my_data_collection = {
+    'name' => 'mbland', 'full_name' => 'Mike Bland',
+    'private' => {
+      'email' => 'michael.bland@gsa.gov', 'location' => 'DCA',
+    },
+  }
+```
+
+The following examples, except for **Join an Array of Hash values**, all begin with `my_data_collection` in the above state.  Further examples can be found in the [test/](test/) directory.
+
+#### Strip private data
+
+```ruby
+# Everything within the `private:` property will be deleted.
+> HashJoiner.remove_data my_data_collection, "private"
+=> {"name"=>"mbland", "full_name"=>"Mike Bland"}
+```
+
+#### Promote private data
+
+This will render `private:` data at the same level as other, nonprivate data:
+
+```ruby
+# Everything within the `private:` property will be
+# promoted up one level.
+> HashJoiner.promote_data my_data_collection, "private"
+=> {"name"=>"mbland", "full_name"=>"Mike Bland",
+    "email"=>"michael.bland@gsa.gov", "location"=>"DCA"}
+```
+
+#### Perform a deep merge with other Hash values
+
+```ruby
+> extra_info = {
+  'languages' => ['C++', 'Python'], 'full_name' => 'Michael S. Bland',
+  'private' => {
+    'location' => 'Alexandria, VA', 'previous_companies' => ['Google'],
+    },
+  }
+
+# The original Hash will have information added for
+# `full_name`, `languages', and `private => location`.
+> HashJoiner.deep_merge my_data_collection, extra_info
+=> {"name"=>"mbland", "full_name"=>"Michael S. Bland",
+    "private"=>{
+      "email"=>"michael.bland@gsa.gov", "location"=>"Alexandria, VA",
+      "previous_companies"=>["Google"]},
+    "languages"=>["C++", "Python"]}
+
+> extra_info = {
+    'languages' => ['Ruby'],
+    'private' => {
+      'previous_companies' => ['Northrop Grumman'],
+    },
+  }
+
+# The Hash will now have added information for
+# `languages` and `private => previous_companies`.
+> HashJoiner.deep_merge my_data_collection, extra_info
+=> {"name"=>"mbland", "full_name"=>"Michael S. Bland",
+    "private"=>{
+      "email"=>"michael.bland@gsa.gov", "location"=>"Alexandria, VA",
+      "previous_companies"=>["Google", "Northrop Grumman"]},
+    "languages"=>["C++", "Python", "Ruby"]}
+```
+
+#### Join an Array of Hash values
+
+This corresponds to the process of joining different collections of Jekyll-imported data within the 18F Hub, such as joining `site.data['private']['team']` into `site.data['team']`.
+
+```ruby
+# This defines a fake object emulating a Jekyll::Site.
+> class DummySite
+    attr_accessor :data
+    def initialize
+      @data = {'private' => {}}
+    end
+  end
+
+> site = DummySite.new
+
+# This data would correspond to _data/team.yml
+# in a Jekyll project.
+> site.data['team'] = [
+    {'name' => 'mbland', 'languages' => ['C++']},
+    {'name' => 'foobar', 'full_name' => 'Foo Bar'},
+  ]
+
+# This data would correspond to _data/private/team.yml
+# in a Jekyll project.
+> site.data['private']['team'] = [
+    {'name' => 'mbland', 'languages' => ['Python', 'Ruby']},
+    {'name' => 'foobar', 'email' => 'foo.bar@gsa.gov'},
+    {'name' => 'bazquux', 'email' => 'baz.quux@gsa.gov'},
+  ]
+
+# After joining, each element of `site.data['team']` contains
+# the union of the original element and the corresponding
+# element in `site.data['private']['team']`.
+#
+# `site.data['private']` can now be safely discarded.
+> HashJoiner.join_data 'team', 'name', site.data, site.data['private']
+=> {"private"=>{
+      "team"=>[
+        {"name"=>"mbland", "languages"=>["Python", "Ruby"]},
+        {"name"=>"foobar", "email"=>"foo.bar@gsa.gov"},
+        {"name"=>"bazquux", "email"=>"baz.quux@gsa.gov"}]},
+    "team"=>[
+      {"name"=>"mbland", "languages"=>["C++", "Python", "Ruby"]},
+      {"name"=>"foobar", "full_name"=>"Foo Bar", "email"=>"foo.bar@gsa.gov"},
+      {"name"=>"bazquux", "email"=>"baz.quux@gsa.gov"}]}
+```
+
+### Contributing
+
+Just fork [18F/hash-joiner](https://github.com/18F/hash-joiner) and start sending pull requests! Feel free to ping [@mbland](https://github.com/mbland) with any questions you may have, especially if the current documentation should've addressed your needs, but didn't.
+
+### Public domain
+
+This project is in the worldwide [public domain](LICENSE.md). As stated in [CONTRIBUTING](CONTRIBUTING.md):
+
+> This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the [CC0 1.0 Universal public domain dedication](https://creativecommons.org/publicdomain/zero/1.0/).
+>
+> All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.

data/lib/hash-joiner.rb

@@ -1,32 +1,13 @@
-# Performs pruning or one-level promotion of Hash attributes (typically
-# labeled "private") and deep joins of Hash objects. Works on Array objects
-# containing Hash objects as well.
-#
-# The typical use case is to have a YAML file containing both public and
-# private data, with all private data nested within "private" properties:
-#
-# my_data_collection = {
-#   'name' => 'mbland', 'full_name' => 'Mike Bland',
-#   'private' => {
-#     'email' => 'michael.bland@gsa.gov', 'location' => 'DCA',
-#    },
-# }
-#
-# Contributed by the 18F team, part of the United States
-# General Services Administration: https://18f.gsa.gov/
-#
-# Author: Mike Bland (michael.bland@gsa.gov)
+# @author: Mike Bland (michael.bland@gsa.gov)
 module HashJoiner
   # Recursively strips information from +collection+ matching +key+.
   #
-  # To strip all private data from the example collection in the module
-  # comment:
-  #   HashJoiner.remove_data my_data_collection, "private"
-  # resulting in:
-  #   {'name' => 'mbland', 'full_name' => 'Mike Bland'}
-  #
-  # +collection+:: Hash or Array from which to strip information
-  # +key+:: key determining data to be stripped from +collection+
+  # @param collection [Hash,Array<Hash>] collection from which to strip
+  #   information
+  # @param key [String] property to be stripped from +collection+
+  # @return [Hash,Array<Hash>] +collection+ if +collection+ is a +Hash+ or
+  #   +Array<Hash>+
+  # @return [nil] if +collection+ is not a +Hash+ or +Array<Hash>+
   def self.remove_data(collection, key)
     if collection.instance_of? ::Hash
       collection.delete key
@@ -41,15 +22,12 @@ module HashJoiner
   # same level as +key+ itself. After promotion, each +key+ reference will
   # be deleted.
   #
-  # To promote private data within the example collection in the module
-  # comment, rendering it at the same level as other, nonprivate data:
-  #   HashJoiner.promote_data my_data_collection, "private" 
-  # resulting in:
-  #   {'name' => 'mbland', 'full_name' => 'Mike Bland',
-  #    'email' => 'michael.bland@gsa.gov', 'location' => 'DCA'}
-  #
-  # +collection+:: Hash or Array from which to promote information
-  # +key+:: key determining data to be promoted within +collection+
+  # @param collection [Hash,Array<Hash>] collection in which to promote
+  #   information
+  # @param key [String] property to be promoted within +collection+
+  # @return [Hash,Array<Hash>] +collection+ if +collection+ is a +Hash+ or
+  #   +Array<Hash>+
+  # @return [nil] if +collection+ is not a +Hash+ or +Array<Hash>+
   def self.promote_data(collection, key)
     if collection.instance_of? ::Hash
       if collection.member? key
@@ -76,20 +54,21 @@ module HashJoiner
     end
   end
 
-  # Raised by deep_merge() if lhs and rhs are of different types.
+  # Raised by +deep_merge+ if +lhs+ and +rhs+ are of different types.
+  # @see deep_merge
   class MergeError < ::Exception
   end
 
-  # Performs a deep merge of Hash and Array structures. If the collections
-  # are Hashes, Hash or Array members of +rhs+ will be deep-merged with
-  # any existing members in +lhs+. If the collections are Arrays, the values
-  # from +rhs+ will be appended to lhs.
-  #
-  # Raises MergeError if lhs and rhs are of different classes, or if they
-  # are of classes other than Hash or Array.
+  # Performs a deep merge of +Hash+ and +Array+ structures. If the collections
+  # are +Hash+es, +Hash+ or +Array+ members of +rhs+ will be deep-merged with
+  # any existing members in +lhs+. If the collections are +Array+s, the values
+  # from +rhs+ will be appended to +lhs+.
   #
-  # +lhs+:: merged data sink (left-hand side)
-  # +rhs+:: merged data source (right-hand side)
+  # @param lhs [Hash,Array] merged data sink (left-hand side)
+  # @param rhs [Hash,Array] merged data source (right-hand side)
+  # @return [Hash,Array] +lhs+
+  # @raise [MergeError] if +lhs+ and +rhs+ are of different classes, or if
+  #   they are of classes other than Hash or Array.
   def self.deep_merge(lhs, rhs)
     mergeable_classes = [::Hash, ::Array]
 
@@ -112,25 +91,33 @@ module HashJoiner
     elsif rhs.instance_of? ::Array
       lhs.concat rhs
     end
+    lhs
   end
 
-  # Raised by join_data() if an error is encountered.
+  # Raised by +join_data+ if an error is encountered.
+  # @see join_data
   class JoinError < ::Exception
   end
 
-  # Joins objects in +lhs[category]+ with data from +rhs[category]+. If the
-  # object collections are of type Array of Hash, key_field will be used as
-  # the primary key; otherwise key_field is ignored.
+  # Joins objects in +lhs+[category] with data from +rhs+[category]. If the
+  # +category+ objects are of type +Array<Hash>+, +key_field+ will be used as
+  # the primary key to join the objects in the two collections; otherwise
+  # +key_field+ is ignored.
   #
-  # Raises JoinError if an error is encountered.
-  #
-  # +category+:: determines member of +lhs+ to join with +rhs+
-  # +key_field+:: if specified, primary key for Array of joined objects
-  # +lhs+:: joined data sink of type Hash (left-hand side)
-  # +rhs+:: joined data source of type Hash (right-hand side)
+  # @param category [String] determines member of +lhs+ to join with +rhs+
+  # @param key_field [String] primary key for objects in each +Array<Hash>+
+  #   collection specified by +category+
+  # @param lhs [Hash,Array<Hash>] joined data sink of type Hash (left-hand
+  #   side)
+  # @param rhs [Hash,Array<Hash>] joined data source of type Hash (right-hand
+  #   side)
+  # @return [Hash,Array<Hash>] +lhs+
+  # @raise [JoinError] if an error is encountered
+  # @see deep_merge
+  # @see join_array_data
   def self.join_data(category, key_field, lhs, rhs)
     rhs_data = rhs[category]
-    return unless rhs_data
+    return lhs unless rhs_data
 
     lhs_data = lhs[category]
     if !(lhs_data and [::Hash, ::Array].include? lhs_data.class)
@@ -140,10 +127,17 @@ module HashJoiner
     else
       self.join_array_data key_field, lhs_data, rhs_data
     end
+    lhs
   end
 
-  # Raises JoinError if +h+ is not a Hash, or if
-  # +key_field+ is absent from any element of +lhs+ or +rhs+.
+  # Asserts that +h+ is a hash containing +key+. Used to ensure that a +Hash+
+  # can be joined with another +Hash+ object.
+  #
+  # @raise [JoinError] if +h+ is not a +Hash+, or if +key_field+ is absent
+  #   from any element of +lhs+ or +rhs+.
+  # @return [NilClass] +nil+
+  # @see join_data
+  # @see join_array_data
   def self.assert_is_hash_with_key(h, key, error_prefix)
     if !h.instance_of? ::Hash
       raise JoinError.new("#{error_prefix} is not a Hash: #{h}")
@@ -152,17 +146,20 @@ module HashJoiner
     end
   end
 
-  # Joins data in the +lhs+ Array with data from the +rhs+ Array based on
-  # +key_field+. Both +lhs+ and +rhs+ should be of type Array of Hash.
-  # Performs a deep_merge on matching objects; assigns values from +rhs+ to
-  # +lhs+ if no corresponding object yet exists in lhs.
-  #
-  # Raises JoinError if either lhs or rhs is not an Array of Hash, or if
-  # +key_field+ is absent from any element of +lhs+ or +rhs+.
+  # Joins data in +lhs+ with data from +rhs+ based on +key_field+. Both +lhs+
+  # and +rhs+ should be of type +Array<Hash>+. Performs a +deep_merge+ on
+  # matching objects; assigns values from +rhs+ to +lhs+ if no corresponding
+  # value yet exists in +lhs+.
   #
-  # +key_field+:: primary key for joined objects
-  # +lhs+:: joined data sink (left-hand side)
-  # +rhs+:: joined data source (right-hand side)
+  # @param key_field [String] primary key for joined objects
+  # @param lhs [Array<Hash>] joined data sink (left-hand side)
+  # @param rhs [Array<Hash>] joined data source (right-hand side)
+  # @return [Array<Hash>] +lhs+
+  # @raise [JoinError] if either +lhs+ or +rhs+ is not an +Array<Hash>+, or if
+  #   +key_field+ is absent from any element of +lhs+ or +rhs+
+  # @see deep_merge
+  # @see join_data
+  # @see assert_is_hash_with_key
   def self.join_array_data(key_field, lhs, rhs)
     unless lhs.instance_of? ::Array and rhs.instance_of? ::Array
       raise JoinError.new("Both lhs (#{lhs.class}) and " +
@@ -175,6 +172,8 @@ module HashJoiner
       lhs_index[i[key_field]] = i
     end
 
+    # TODO(mbland): Make exception-safe by splitting into two loops: one for
+    # the assert; one to modify lhs after all the assertions have succeeded.
     rhs.each do |i|
       self.assert_is_hash_with_key(i, key_field, "RHS element")
       key = i[key_field]
@@ -184,5 +183,6 @@ module HashJoiner
         lhs << i
       end
     end
+    lhs
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hash-joiner
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.0.1
 platform: ruby
 authors:
 - Mike Bland
@@ -9,15 +9,58 @@ autorequire:
 bindir: bin
 cert_chain: []
 date: 2014-12-19 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !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: 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: codeclimate-test-reporter
+  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: Performs pruning or one-level promotion of Hash attributes (typically
-  labeled "private") and deep joins of Hash objects. Works on Array objects containing
-  Hash objects as well.
+  labeled "private:"), and deep merges and joins of Hash objects. Works on Array objects
+  containing Hash objects as well.
 email: michael.bland@gsa.gov
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- README.md
 - lib/hash-joiner.rb
 homepage: https://github.com/18F/hash-joiner
 licenses:
@@ -42,5 +85,5 @@ rubyforge_project:
 rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
-summary: Module for pruning, promoting, and deep-merging Hash data
+summary: Module for pruning, promoting, deep-merging, and joining Hash data
 test_files: []