cliutils 1.2.4 → 1.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: cca92462495e55bd03893b1ce6a19c1830288b56
-  data.tar.gz: dd8f5e2ed4434f381f0bca8a66d34fcab3cf6834
+  metadata.gz: 00fd89b1aa359ab732d3a436b51aa26d515f0ef3
+  data.tar.gz: 1aa1aa258ca1a09fe55e8fdf9c2d336e54b8ba9b
 SHA512:
-  metadata.gz: 226d3b909c6a8f887818491f4611db68128e991c818c4aeb8268316f3f3d0415bf06a5a6967e961c6377f0cfbc3149b8dd94e3ad68dd1e4dcb18086cecdbc46a
-  data.tar.gz: 0404033a25e60197ec39c4e58cde3a72616d1a09c9d051a44d0c4e74a85e349d3c1b949c33516bc847f38ab77c959de3cf5a1c1109bdc5cbd43d8e9b57e33c82
+  metadata.gz: 607089b0e6bce175030d6304b411c4e58947c3573653b90f55247d54a6f6353c2896946fa99fe844cb8e87afd8aecc00e540c392d50b5a17df5c72a34ea10544
+  data.tar.gz: e763d764171825dc2391413c7f7a822ccfbe8af1ef219401539aa6313bc70c3a321667640163386b281f6d3e04e829425ca227b73267fbb4511fabd2d053ceb7

data/HISTORY.md

@@ -1,3 +1,7 @@
+# 1.2.5 (2014-04-07)
+
+* Added Configurator version checking
+
 # 1.2.4 (2014-04-06)
 
 * Cleanup and refactoring

data/README.md

@@ -220,14 +220,14 @@ include CLIUtils::Configuration
 ### Loading a Configuration File
 
 ```Ruby
-CLIUtils::Configuration.configuration = '~/.my-app-config'
+load_configuration('~/.my-app-config')
 ```
 
-If there's data in there, it will be consumed into `configuration`'s `data` property.
+If there's data in there, it will be consumed into the `configurator`'s `data` property.
 
 ### Adding/Removing Sections
 
-Sections are top levels of the configuration file and are managed via the `configuration` object:
+Sections are top levels of the configuration file and are managed via the `configurator` object:
 
 ```Ruby
 configuration.add_section(:user_data)
@@ -237,7 +237,7 @@ configuration.delete_section(:program_data)
 
 ### Adding Data to Sections
 
-There are two ways data can be managed in `configuration`: via its `@data` property or via some magic methods; your call:
+There are two ways data can be managed in `configurator`: via its `@data` property or via some magic methods; your call:
 
 ```Ruby
 configuration.data[:user_data].merge!(username: 'bob')
@@ -261,6 +261,33 @@ user_data:
   username: bob
 ```
 
+### Checking Configuration Versions
+
+Often, you'll want to check the user's current version of your app against the last version that required some sort of configuration change. `configurator` allows for this via its `compare_version` method:
+
+```Ruby
+# Tell your configurator the name of the key that
+# stores the app's version in its configuration file.
+configuration.cur_version_key = :APP_VERSION
+
+# Tell your configurator the name of the key that
+# stores the last version that needed a configuration
+# change.
+configuration.last_version_key = :NEWEST_CONFIG_VERSION
+
+# Run the check and use a block to get
+# the current and "last-needing-changes"
+# versions (and do something about it).
+configuration.compare_version do |c, l|
+  if c < l
+    puts "You need to update your app; here's how:"
+    # ...do stuff...
+  else
+    puts "No need to update your app's config file!"
+  end
+end
+```
+
 ## Prefs
 
 Many times, CLI apps need to ask their users some questions, collect the feedback, validate it, and store it. CLIUtils makes this a breeze via the `Prefs` class.
@@ -419,7 +446,7 @@ prompts:
       - local_filepath
 ```
 
-This will expand the user's answer as a filepath (e.g., `~/.ssh` will get saved as `/Users/bachya/.ssh/`).
+The `local_filepath` behavior will expand the user's answer as a filepath (e.g., `~/.ssh` will get saved as `/Users/bachya/.ssh/`).
 
 `Prefs` currently supports these behaviors:
 
@@ -430,7 +457,11 @@ This will expand the user's answer as a filepath (e.g., `~/.ssh` will get saved
 Once the user has answered all the preference prompts, you can fold those answers back into a Configurator using the `ingest` method:
 
 ```Ruby
+# Ingest the Prefs answers into our
+# Configurator.
 configuration.ingest_prefs(prefs)
+
+# Save it to the filesystem.
 configuration.save
 ```
 
@@ -439,6 +470,9 @@ configuration.save
 Note that you can also initialize a `Prefs` object with a Configurator:
 
 ```Ruby
+# Scans my_configurator for values to the
+# questions posed by prefs; if found, use
+# them as defaults.
 prefs = CLIUtils::Prefs.new('path/to/yaml/file', my_configurator)
 ```
 

data/lib/cliutils/configuration.rb

@@ -33,7 +33,7 @@ module CLIUtils
     # a Configurator.
     # @param [String] path The filepath to use
     # @return [void]
-    def self.configuration=(path)
+    def load_configuration(path)
       @@configuration = Configurator.new(path)
     end
   end

data/lib/cliutils/configurator.rb

@@ -5,6 +5,17 @@ module CLIUtils
   #  Manages any configuration values and the flat YAML file
   #  into which they get stored.
   class Configurator
+    # Stores the Configurator key that refers
+    # to the current configuration version.
+    # @return [Symbol]
+    attr_accessor :cur_version_key
+
+    # Stores the Configurator key that refers
+    # to the value at which the app last changed
+    # config versions.
+    # @return [Symbol]
+    attr_accessor :last_version_key
+
     # Stores the path to the configuration file.
     # @return [String]
     attr_reader :config_path
@@ -13,6 +24,11 @@ module CLIUtils
     # @return [Hash]
     attr_reader :data
 
+    # Stores the section that contains the version
+    # keys.
+    # @return [Symbol]
+    attr_accessor :version_section
+
     # Initializes configuration from a flat file.
     # @param [String] path The filepath to the config YAML
     # @return [void]
@@ -39,6 +55,41 @@ module CLIUtils
       end
     end
 
+    # Checks to see whether the passed key (and a
+    # non-nil value) exist in the @data Hash.
+    # @param [Symbol] key The key to search for
+    # @return [Boolean]
+    def check_key_and_value(key)
+      !@data.recursive_find_by_key(key).nil? &&
+      !@data.recursive_find_by_key(key).empty?
+    end
+
+    # Compares the current version (if it exists) to
+    # the last version that needed a configuration
+    # change (if it exists). Assuming they exist and
+    # that the current version is behind the "last-config"
+    # version, execute a passed block.
+    # @return [void]
+    def compare_version
+      unless check_key_and_value(@cur_version_key)
+        fail 'Cannot check version; no current version found'
+      end
+      
+      unless check_key_and_value(@last_version_key)
+        fail 'Cannot check version; no previous version found'
+      end
+      
+      c_version = @data.recursive_find_by_key(@cur_version_key)
+      c_version_gem = Gem::Version.new(c_version)
+
+      l_version = @data.recursive_find_by_key(@last_version_key)
+      l_version_gem = Gem::Version.new(l_version)
+
+      if c_version_gem < l_version_gem
+        yield c_version, l_version
+      end
+    end
+
     # Removes a section to the config file (if it exists).
     # @param [String] section_name The section to remove
     # @return [void]

data/lib/cliutils/constants.rb

@@ -1,5 +1,5 @@
 # Stores constants to use.
 module CLIUtils
   # The current version of the gem
-  VERSION = '1.2.4'
+  VERSION = '1.2.5'
 end

data/lib/cliutils/ext/hash_extensions.rb

@@ -62,6 +62,33 @@ class Hash
     _deep_transform_keys_in_object!(self, &block)
   end
 
+  # Recursively searches a hash for the passed
+  # key and returns the value (if there is one).
+  # http://stackoverflow.com/a/2239847/327179
+  # @param [<Symbol, String>] key The key to search for
+  # @return [Multiple]
+  def recursive_find_by_key(key)
+    # Create a stack of hashes to search through for the needle which
+    # is initially this hash
+    stack = [ self ]
+
+    # So long as there are more haystacks to search...
+    while (to_search = stack.pop)
+      # ...keep searching for this particular key...
+      to_search.each do |k, v|
+        # ...and return the corresponding value if it is found.
+        return v if (k == key)
+
+        # If this value can be recursively searched...
+        if (v.respond_to?(:recursive_find_by_key))
+          # ...push that on to the list of places to search.
+          stack << v
+        end
+      end
+    end
+    yield if block_given?
+  end
+
   private
 
   # Modification to deep_transform_keys that allows for

data/lib/cliutils/prefs/pref_validation.rb

@@ -4,6 +4,8 @@ module CLIUtils
   # PrefValidation Module
   # Validation rules that can be applied to a Pref.
   module PrefValidation
+    # Struct to contain a validation result
+    # and a result message.
     Validator = Struct.new(:code, :message)
 
     # Validates that a value is only letters.

data/lib/cliutils/prefs.rb

@@ -96,7 +96,7 @@ module CLIUtils
 
     # Generates an Array of Prefs based on passed
     # in data.
-    # @param [Hash] pref_data Loaded pref data
+    # @param [Hash] pref_data_hash Loaded pref data
     # @return [Array]
     def _generate_prefs(pref_data_hash)
       pref_data_hash[:prompts].map { |p| CLIUtils::Pref.new(p) }

data/test/configurator_test.rb

@@ -48,4 +48,16 @@ class TestConfigurator < Test::Unit::TestCase
       assert_output("---\nsection1:\n  a: test\n  b: test\n") { puts f.read }
     end
   end
+  
+  def test_compare_version
+    @config.add_section(:app_data)
+    @config.app_data.merge!({ VERSION: '1.0.0', NEWEST_CONFIG_VERSION: '1.8.8' })
+
+    @config.cur_version_key = :VERSION
+    @config.last_version_key = :NEWEST_CONFIG_VERSION
+
+    @config.compare_version do |c, l|
+      assert_output('true') { print c < l }
+    end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cliutils
 version: !ruby/object:Gem::Version
-  version: 1.2.4
+  version: 1.2.5
 platform: ruby
 authors:
 - Aaron Bach
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-04-06 00:00:00.000000000 Z
+date: 2014-04-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler