README.md in cliutils-1.0.3 vs README.md in cliutils-1.0.4
- old
+ new
@@ -1,7 +1,9 @@
CLIUtils
====
+[](https://travis-ci.org/bachya/cliutils)
+[](http://badge.fury.io/rb/cliutils)
CLIUtils is a library of functionality designed to alleviate common tasks and headaches when developing command-line (CLI) apps in Ruby.
# Why?
@@ -49,14 +51,14 @@
# Libraries
CLIUtils offers:
-* [PrettyIO](https://github.com/bachya/cli-utils#prettyio): nicer-looking CLI messages
-* [Messenging](https://github.com/bachya/cli-utils#messenging): a full-featured Logger
-* [Configuration](https://github.com/bachya/cli-utils#configuration): a app configuration manager
-* [Prefs](https://github.com/bachya/cli-utils#prefs): a preferences prompter and manager
+* [PrettyIO](#prettyio): nicer-looking CLI messages
+* [Messenging](#messenging): a full-featured Logger
+* [Configuration](#configuration): a app configuration manager
+* [Prefs](#prefs): a preferences prompter and manager
## PrettyIO
First stop on our journey is better client IO. To activate, simply mix into your project:
@@ -144,17 +146,17 @@
### Message Wrapping
PrettyIO also gives `messenger` the ability to wrap your messages so that they don't span off into infinity. You can even control what the wrap limit (in characters) is:
```Ruby
-CLIUtils::PrettyIO::wrap_at(50)
+CLIUtils::PrettyIO.wrap_char_limit = 50
messenger.info('This is a really long message, okay? It should wrap at some point. Seriously. Wrapping is nice.')
puts ''
-CLIUtils::PrettyIO::wrap_at(20)
+CLIUtils::PrettyIO.wrap_char_limit = 20
messenger.info('This is a really long message, okay? It should wrap at some point. Seriously. Wrapping is nice.')
puts ''
-CLIUtils::PrettyIO::wrap(false)
+CLIUtils::PrettyIO.wrap = false
messenger.info('This is a really long message, okay? It should wrap at some point. Seriously. Wrapping is nice.')
```
### Prompting
@@ -252,9 +254,82 @@
```YAML
---
user_data:
username: bob
```
+
+## 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.
+
+`Prefs` can load preferences information from either a YAML file (via a filepath) or from an array of preferences. In either case, the schema is the same; each prompt includes the following:
+
+* prompt (**required**): the string to prompt your user with
+* default (*optional*): an optional default to offer
+* key (**required**): the key that refers to this preference
+* section (**required**): the Configuration section that this preference applies to
+* options (*optional*): an optional array of values; the user's choice must be in this array
+* requirements (*optional*): an optional list of key/value pairs that must exist for this preference to be displayed
+
+Here's an example YAML preferences file.
+
+```YAML
+prompts:
+ - prompt: What is the hostname of your DD-WRT router?
+ default: 192.168.1.1
+ key: hostname
+ section: ssh_info
+ - prompt: What is the SSH username of your DD-WRT router?
+ default: root
+ key: username
+ section: ssh_info
+ - prompt: What SSH port does your DD-WRT router use?
+ default: 22
+ key: port
+ section: ssh_info
+ - prompt: Do you use password or key authentication?
+ default: password
+ key: auth_method
+ section: ssh_info
+ options: ['password', 'key']
+ - prompt: Where is your key located?
+ default: ~/.ssh
+ key: key_location
+ section: ssh_info
+ requirements:
+ - key: auth_method
+ value: key
+ - prompt: What is your password?
+ key: password
+ section: ssh_info
+ requirements:
+ - key: auth_method
+ value: password
+```
+
+Assuming the above, `Prefs` is instantiated like so:
+
+```Ruby
+prefs = CLIUtils::Prefs.new('path/to/yaml/file')
+```
+
+With valid preferences loaded, simply use `ask` to begin prompting your user:
+
+```Ruby
+prefs.ask
+```
+
+
+Once the user has answered all the preference prompts, you can fold those answers back into a Configurator using the `ingest` method:
+
+```Ruby
+configuration.ingest(prefs)
+configuration.save
+```
+
+### Why a Prefs Class?
+
+I've written apps that need to request user input at various times for multiple different things; as such, I thought it'd be easier to have those scenarios chunked up. You can always wrap `Prefs` into a module singleton if you wish.
# Known Issues
* LoggerDelegator doesn't currently know what to do with `messenger.prompt`, so you'll have to manually log a `debug` message if you want that information logged.