cliutils 1.2.5 → 1.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 00fd89b1aa359ab732d3a436b51aa26d515f0ef3
-  data.tar.gz: 1aa1aa258ca1a09fe55e8fdf9c2d336e54b8ba9b
+  metadata.gz: 069c2e2c3141bb0295825c6a7ddcbaa9e5fce3b5
+  data.tar.gz: bd67db92f1833ecec791f0d58974687d2e5dae5a
 SHA512:
-  metadata.gz: 607089b0e6bce175030d6304b411c4e58947c3573653b90f55247d54a6f6353c2896946fa99fe844cb8e87afd8aecc00e540c392d50b5a17df5c72a34ea10544
-  data.tar.gz: e763d764171825dc2391413c7f7a822ccfbe8af1ef219401539aa6313bc70c3a321667640163386b281f6d3e04e829425ca227b73267fbb4511fabd2d053ceb7
+  metadata.gz: d2a266ed437b59e7a41733ac86659f75def0aebb7dda0566530d2f7debd22ba7573acb6c4376cc7447a8a98cba505d96af9c452bb6cc1da6ebed6cf2e63b9c70
+  data.tar.gz: d5860547ff62f94989e8de94fa9502295b1f4439db0b8e9eac2638fe7d8beb38d9c173eeea7697935c4898bf975c0d261651383d35eeee4384c2f76875472d96

data/HISTORY.md

@@ -1,3 +1,8 @@
+# 1.2.6 (2014-04-08)
+
+* More documentation
+* Small refactorings
+
 # 1.2.5 (2014-04-07)
 
 * Added Configurator version checking

data/README.md

@@ -54,7 +54,7 @@ Note that although this README.md is extensive, it may not cover all methods. Ch
 CLIUtils offers:
 
 * [PrettyIO](#prettyio): nicer-looking CLI messages
-* [Messenging](#messenging): a full-featured Logger
+* [Messenging](#messenging): a system to display nicely-formatted messages to one or more tagets
 * [Configuration](#configuration): a app configuration manager
 * [Prefs](#prefs): a preferences prompter and manager
 
@@ -73,7 +73,7 @@ puts 'A sample string'.red
 ```
 ![alt text](https://raw.githubusercontent.com/bachya/cli-utils/master/res/readme-images/prettyio-red-text.png "Colored Text via PrettyIO")
 
-PrettyIO gives you utility methods for the common ANSI color codes:
+You get a stable of utility methods for the common ANSI color codes:
 
 ```ruby
 String.blue
@@ -95,7 +95,7 @@ puts 'A sample string'.colorize('35;42')
 Naturally, memorizing the ANSI color scheme is a pain, so PrettyIO gives you a convenient method to look up these color combinations:
 
 ```ruby
-CLIUtils::PrettyIO.color_chart
+color_chart
 ```
 ![alt text](https://raw.githubusercontent.com/bachya/cli-utils/master/res/readme-images/prettyio-color-chart.png "PrettyIO Color Chart")
 
@@ -178,6 +178,7 @@ Often, it's desirable to log messages as they appear to your user. `messenging`
 For instance, let's say you wanted to log a few messages to both your user's STDOUT and to `file.txt`:
 
 ```Ruby
+# By default, messenger only outputs to STDOUT.
 messenger.info('This should only appear in STDOUT.')
 
 # messenger.attach takes a Hash of string/symbol keys
@@ -230,6 +231,7 @@ If there's data in there, it will be consumed into the `configurator`'s `data` p
 Sections are top levels of the configuration file and are managed via the `configurator` object:
 
 ```Ruby
+configuration.add_section(:app_data)
 configuration.add_section(:user_data)
 configuration.add_section(:program_data)
 configuration.delete_section(:program_data)
@@ -257,22 +259,42 @@ Note that all your keys are converted to strings before saving (and, likewise, a
 
 ```YAML
 ---
+app_data:
 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:
+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.
+
+Assume you have a config file that looks like this:
+
+```YAML
+---
+app_data:
+  # The current version of the app
+  APP_VERSION: 1.0.0
+
+  # The last version that required
+  # a configuration change
+  NEWEST_CONFIG_VERSION: 1.8.0
+
+  # ...other keys...
+```
+
+...this will initiate a version check (and give you the option to do something with that information):
 
 ```Ruby
 # Tell your configurator the name of the key that
 # stores the app's version in its configuration file.
+# NOTE that you don't have to specify the section.
 configuration.cur_version_key = :APP_VERSION
 
 # Tell your configurator the name of the key that
 # stores the last version that needed a configuration
 # change.
+# NOTE that you don't have to specify the section.
 configuration.last_version_key = :NEWEST_CONFIG_VERSION
 
 # Run the check and use a block to get
@@ -325,6 +347,63 @@ Assuming the above, `Prefs` is instantiated like so:
 prefs = CLIUtils::Prefs.new('path/to/yaml/file')
 ```
 
+`Prefs` can also be instantiated via a Hash or an array of prompts; the overall schema remains the same:
+
+```Ruby
+# Instantiation through a Hash
+h = {
+  prompts: [
+    {
+      prompt: 'What is your name?',
+      default: 'Bob Cobb',
+      config_key: :name,
+      config_section: :personal_info
+    },
+    {
+      prompt: 'What is your age?',
+      default: '45',
+      config_key: :age,
+      config_section: :personal_info
+    },
+    {
+      prompt: 'Batman or Superman?',
+      default: 'Batman',
+      config_key: :superhero,
+      config_section: :personal_info
+    }
+  ]
+}
+
+prefs = CLIUtils::Prefs.new(h)
+
+# Instantiation through an Array
+
+a = [
+  {
+    prompt: 'What is your name?',
+    default: 'Bob Cobb',
+    config_key: :name,
+    config_section: :personal_info
+  },
+  {
+    prompt: 'What is your age?',
+    default: '45',
+    config_key: :age,
+    config_section: :personal_info
+  },
+  {
+    prompt: 'Batman or Superman?',
+    default: 'Batman',
+    config_key: :superhero,
+    config_section: :personal_info
+  }
+]
+
+prefs = CLIUtils::Prefs.new(a)
+```
+
+### Prompting the User
+
 With valid preferences loaded, simply use `ask` to begin prompting your user:
 
 ```Ruby
@@ -334,7 +413,7 @@ prefs.ask
 
 ### Prerequisites
 
-Sometimes, you need to answer certain prompts before others become relevant. `Prefs` allows this via a `prereqs` key, which can contain multiple already-answered key/value pairs to check for. For instance, imagine we want to drill into a user's superhero preference a bit further:
+Sometimes, you need to answer certain prompts before others become relevant. `Prefs` allows this via a `prereqs` key, which can contain multiple already-answered key/value pairs to check for. For instance, imagine we want to drill into a user's superhero preference a bit further; using our previously-used YAML prefs file:
 
 ```YAML
 prompts:
@@ -356,6 +435,14 @@ prompts:
     prereqs:
       - config_key: superhero
         config_value: Superman
+  - prompt: Why don't you have a clue?
+    config_key: no_clue
+    config_section: personal_info
+    prereqs:
+      - config_key: superhero
+        config_value: Superman
+      - config_key: superman_answer
+        config_value: No clue
 ```
 
 `prereqs` checks for already-answered preferences (based on a Configurator key and value); assuming everything checks out, the subsequent preferences are collected:
@@ -365,7 +452,7 @@ prefs.ask
 ```
 ![alt text](https://raw.githubusercontent.com/bachya/cli-utils/master/res/readme-images/prefs-ask-prereqs.png "Prerequisities")
 
-Be careful tht you don't define any circular prerequisities (e.g., A requires B and B requires A). In that case, neither preference will be collected.
+Be careful that you don't define any circular prerequisities (e.g., A requires B and B requires A). In that case, both preferences will be ignored by `Prefs.ask`.
 
 ### Options
 
@@ -392,6 +479,14 @@ prompts:
     prereqs:
       - config_key: superhero
         config_value: Superman
+  - prompt: Why don't you have a clue?
+    config_key: no_clue
+    config_section: personal_info
+    prereqs:
+      - config_key: superhero
+        config_value: Superman
+      - config_key: superman_answer
+        config_value: No clue
 ```
 
 Once in place:
@@ -446,7 +541,7 @@ prompts:
       - local_filepath
 ```
 
-The `local_filepath` behavior 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/bob/.ssh/`).
 
 `Prefs` currently supports these behaviors:
 
@@ -492,7 +587,7 @@ To report bugs with or suggest features/changes for CLIUtils, please use the [Is
 
 Contributions are welcome and encouraged. To contribute:
 
-1. Fork it ( http://github.com/bachya/cliutils/fork )
+1. Fork it (http://github.com/bachya/cliutils/fork)
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)

data/lib/cliutils/constants.rb

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

data/lib/cliutils/prefs/pref.rb

@@ -101,7 +101,7 @@ module CLIUtils
       ret = true
       if @options
         unless @options.include?(text)
-          @last_error_message = "Invalid option chosen (\"#{ text }\");"\
+          @last_error_message = "Invalid option chosen (\"#{ text }\"); " \
           "valid options are: #{ options }"
           ret = false
         end

data/lib/cliutils/pretty_io.rb

@@ -35,7 +35,7 @@ module CLIUtils
     # Displays a chart of all the possible ANSI foreground
     # and background color combinations.
     # @return [void]
-    def self.color_chart
+    def color_chart
       [0, 1, 4, 5, 7].each do |attr|
         puts '----------------------------------------------------------------'
         puts "ESC[#{attr};Foreground;Background"

data/test/test_files/prefstest.yaml

@@ -3,6 +3,7 @@ prompts:
     default: Batman
     config_key: superhero
     config_section: personal_info
+    options: ['Batman', 'Superman']
   - prompt: Do you feel smart for preferring Batman?
     default: Y
     config_key: batman_answer
@@ -16,4 +17,12 @@ prompts:
     config_section: personal_info
     prereqs:
       - config_key: superhero
-        config_value: Superman
+        config_value: Superman
+  - prompt: Why don't you have a clue?
+    config_key: no_clue
+    config_section: personal_info
+    prereqs:
+      - config_key: superhero
+        config_value: Superman
+      - config_key: superman_answer
+        config_value: No clue

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cliutils
 version: !ruby/object:Gem::Version
-  version: 1.2.5
+  version: 1.2.6
 platform: ruby
 authors:
 - Aaron Bach