README.md in cliutils-1.2.8 vs README.md in cliutils-1.2.9
- old
+ new
@@ -120,11 +120,11 @@
* `messenger.error`: used to show a formatted-red error message.
* `messenger.info`: used to show a formatted-blue infomational message.
* `messenger.section`: used to show a formatted-purple sectional message.
* `messenger.success`: used to show a formatted-green success message.
-* `messenger.yellow`: used to show a formatted-yellow warning message.
+* `messenger.warn`: used to show a formatted-yellow warning message.
Let's see an example that uses them all:
```Ruby
messenger.section('STARTING ATTACK RUN...')
@@ -136,28 +136,41 @@
`messenger` also includes two "block" methods that allow you to wrap program execution in messages that are "longer-term".
```Ruby
-messenger.info_block('Starting up...', 'Done!', multiline = false) { # do stuff here }
+# Outputs 'Starting up...', runs the code in
+# `# do stuff here`, and once complete,
+# outputs 'Done!' on the same line.
+messenger.info_block('Starting up...', 'Done!', multiline = false) {
+ # ...do stuff here...
+}
+
+# Outputs 'MY SECTION' and then runs
+# the code in `# do stuff here` before
+# proceeding.
+section_block('MY SECTION', multiline = true) {
+ # ...do stuff here...
+}
```
-`messenger` outputs 'Starting up...', runs the code in `# do stuff here`, and once complete, outputs 'Done!' on the same line. Note that `section_block` is the same exact signature (except for the method name, of course!).
-
### 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
+long_string = 'This is a really long message, okay? ' \
+'It should wrap at some point. Seriously. Wrapping is nice.'
+
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.')
+messenger.info(long_string)
puts ''
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.')
+messenger.info(long_string)
puts ''
CLIUtils::PrettyIO.wrap = false
-messenger.info('This is a really long message, okay? It should wrap at some point. Seriously. Wrapping is nice.')
+messenger.info(long_string)
```
### Prompting
@@ -206,11 +219,11 @@
W, [2014-03-29T15:14:34.844406 #4497] WARN -- : This warning should appear in STDOUT and file.txt
E, [2014-03-29T15:14:34.844553 #4497] ERROR -- : This error should appear in STDOUT and file.txt
D, [2014-03-29T15:14:34.844609 #4497] DEBUG -- : This debug message should only appear in file.txt
```
-Since you can attach Logger objects, each can have it's own format and severity level. Cool!
+Since you are attaching Logger objects, each can have it's own format and severity level. Cool!
## Configuration
CLIUtils offers a `Configurator` class and a `Configuration` module (which provides access to a shared instance of `Configurator`) that make managing a user's configuration parameters easy. Mix it in!
@@ -240,13 +253,13 @@
### Adding Data to Sections
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')
+configuration.data[:user_data].merge!({ username: 'bob', age: 45 })
# OR
-configuration.user_data.merge!(username: 'bob')
+configuration.user_data.merge!({ username: 'bob', age: 45 })
```
### Saving to a File
When you're ready to save your configuration data to a YAML file:
@@ -260,10 +273,11 @@
```YAML
---
app_data:
user_data:
username: bob
+ age: 45
```
### 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.
@@ -290,12 +304,11 @@
# 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.
+# 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
# the current and "last-needing-changes"
@@ -314,11 +327,11 @@
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.
### Basic Schema
-`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:
+`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
* `config_key` (**required**): the Configurator key that this preference will use
* `config_section` (**required**): the Configurator section that this preference applies to
@@ -345,11 +358,11 @@
```Ruby
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:
+`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: [
@@ -373,13 +386,13 @@
}
]
}
prefs = CLIUtils::Prefs.new(h)
-
+```
+```Ruby
# Instantiation through an Array
-
a = [
{
prompt: 'What is your name?',
default: 'Bob Cobb',
config_key: :name,
@@ -500,16 +513,19 @@
"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:
```YAML
validators:
- - alphabetic # Must be made up of letters and spaces
- - alphanumeric # Must be made up of letters, numbers, and spaces
- - date # Must be a parsable date (e.g., 2014-04-03)
- - non_nil # Must be a non-nil value
- - numeric # Must be made up of numbers
- - url # Must be a fully-qualified URL
+ - alphabetic # Must be made up of letters and spaces
+ - alphanumeric # Must be made up of letters, numbers, and spaces
+ - date # Must be a parsable date (e.g., 2014-04-03)
+ - datetime # Must be a parsable datetime (e.g., 2014-04-03 9:34am)
+ - non_nil # Must be a non-nil value
+ - number # Must be made up of numbers
+ - filepath_exists # Must be a local filepath that exists (e.g., `/tmp/`)
+ - time # Must be a parsable time (e.g., 12:45pm or 21:08)
+ - url # Must be a fully-qualified URL
```
An example:
```YAML
@@ -521,11 +537,11 @@
- alphabetic
- prompt: How old are you?
config_key: age
config_section: personal_info
validators:
- - numeric
+ - number
```
```Ruby
prefs.ask
```
@@ -538,11 +554,11 @@
Finally, a common desire might be to modify the user's answer in some way before storing it. `Prefs` accomplishes this via Behaviors. Currently supported Behaviors are:
```YAML
validators:
- capitalize # Turns "answer" into "Answer"
- - local_filepath # Runs File.expand_path on the answer
+ - expand_filepath # Runs File.expand_path on the answer
- lowercase # Turns "AnSwEr" into "answer"
- prefix: 'test ' # Prepends 'test ' to the answer
- suffix: 'test ' # Appends 'test ' to the answer
- titlecase # Turns "the answer" into "The Answer"
- uppercase # Turns "answer" to "ANSWER"
@@ -566,10 +582,10 @@
```Ruby
prefs.ask
```
-Note that behaviors are executed in order, which might give you different results than you're expecting. In the example above, for example, placing the `uppercase` behavior last in the list will uppercase *the entire string* (including prefix and suffix).
+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).
### 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: