README.md in cliutils-1.4.0 vs README.md in cliutils-1.4.1
- old
+ new
@@ -49,11 +49,11 @@
include CLIUtils
```
Alternatively, as described below, mix in only the libraries that you want.
-Note that although this README.md is extensive, it may not cover all methods. Check out the [YARD documentation](http://rubydoc.info/github/bachya/cli-utils/master/frames) and the [tests](https://github.com/bachya/cli-utils/tree/master/test) to see more examples.
+Note that although this README.md is extensive, it may not cover all methods. Check out the [YARD documentation](http://rubydoc.info/github/bachya/cliutils/master/frames) and the [tests](https://github.com/bachya/cliutils/tree/master/test) to see more examples.
# Libraries
CLIUtils offers:
@@ -75,11 +75,11 @@
To start, `PrettyIO` affords you colorized strings:
```ruby
puts 'A sample string'.red
```
-
+
You get a stable of utility methods for the common ANSI color codes:
```ruby
String.blue
@@ -94,18 +94,18 @@
You also get the `colorize` method, which allows you to define more complex color combinations. For example, to get some nice purple text on a gnarly green background:
```ruby
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
color_chart
```
-
+
# Messaging
Throughout the life of your application, you will most likely want to send several messages to your user (warnings, errors, info, etc.). `Messaging` makes this a snap. It, too, is a mixin:
@@ -116,11 +116,11 @@
Once mixed in, you get access to `messenger`, a type of Logger that uses `PrettyIO` to send nicely-formatted messages to your user. For example, if you'd like to warn your user:
```ruby
messenger.warn('Hey pal, you need to be careful.')
```
-
+
## Messaging Methods
`messenger` gives you access to several basic "read-only" methods:
@@ -137,11 +137,11 @@
messenger.info('Beginning strafing run...')
messenger.warn('WARNING: Tie Fighters approaching!')
messenger.error('Porkins died :(')
messenger.success('But Luke still blew up the Death Star!')
```
-
+
`messenger` also includes two "block" methods that allow you to wrap program execution in messages that are "longer-term".
```Ruby
# Outputs 'Starting up...', runs the code in
@@ -174,21 +174,21 @@
messenger.info(long_string)
puts ''
CLIUtils::PrettyIO.wrap = false
messenger.info(long_string)
```
-
+
## Prompting
`messenger` also carries a convenient method to prompt your users to give input (including an optional default). It makes use of `readline`, so you can do cool things like text expansion of paths.
```Ruby
p = messenger.prompt('Are you a fan of Battlestar Galactica?', default = 'Y')
messenger.info("You answered: #{ p }")
```
-
+
When you pass a default to `messaging.prompt`, hitting `Enter` (i.e., leaving the prompt blank) will return the value of the default.
## Logging
@@ -215,11 +215,11 @@
messenger.section('This section message should appear only in STDOUT')
```
In STDOUT:
-
+
...and in `file.txt`:
```
W, [2014-03-29T15:14:34.844406 #4497] WARN -- : This warning should appear in STDOUT and file.txt
@@ -431,11 +431,11 @@
With valid preferences loaded, simply use `ask` to begin prompting your user:
```Ruby
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; using our previously-used YAML prefs file:
@@ -472,11 +472,11 @@
`prereqs` checks for already-answered preferences (based on a Configurator key and value); assuming everything checks out, the subsequent preferences are collected:
```Ruby
prefs.ask
```
-
+
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
@@ -516,11 +516,11 @@
Once in place:
```Ruby
prefs.ask
```
-
+
## Validators
"But," you say, "I want to ensure that my user gives answers that conform to certain specifications!" Not a problem, dear user: `Prefs` gives you Validators. Currently supported Validators are:
@@ -554,11 +554,11 @@
```
```Ruby
prefs.ask
```
-
+
Note that validators are evaluated in order, from top to bottom. If any validator fails, `messenger` will display an error and prompt the user to try again.
## Behaviors
@@ -591,11 +591,11 @@
```
```Ruby
prefs.ask
```
-
+
Note that behaviors are executed in order, which might give you different results than you're expecting. Using the YAML above, for example, placing the `uppercase` behavior last in the list will uppercase *the entire string* (including prefix and suffix).
## Pre- and Post-Messages/Actions
@@ -644,23 +644,24 @@
Several items to note:
1. The action class needs to be wrapped in the CLIUtils module.
2. The class name needs to be the camel-case version of the `action` key in the YAML.
3. The class name needs to end with "Action".
-4. The class needs to inherit from the PrefAction class.
-5. The class needs to implement one method: `method(parameters)`
+4. The class needs to inherit from the PrefAction class. This allows it to have access to:
+ * `@pref`: the Pref that implemented this action
+5. The class needs to implement one method: `run(parameters = {})`
### Testing
Let's run it!
```Ruby
prefs.ask
```
-
-
-
+
+
+
## Adding Pref Responses to a Configurator
Once the user has answered all the preference prompts, you can fold those answers back into a Configurator using the `ingest` method:
@@ -692,10 +693,10 @@
# Bugs and Feature Requests
To view my current roadmap and objectives, check out the [Trello board](https://trello.com/b/qXs7Yeir/cliutils "CLIUtils on Trello").
-To report bugs with or suggest features/changes for CLIUtils, please use the [Issues Page](http://github.com/bachya/cli-utils/issues).
+To report bugs with or suggest features/changes for CLIUtils, please use the [Issues Page](http://github.com/bachya/cliutils/issues).
# Contributing
Contributions are welcome and encouraged. To contribute: