rexe 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79b7eb979cbeb0ba6d95c150e58bccecef867212b4783808f06381d9e247aa55
-  data.tar.gz: e737abbe83eee2bd71d83466a336db48b49ceea1ef88a51615557dcfa623d1d5
+  metadata.gz: 38c1bab41a36c75950db8a2a8aa05f46d324f3c221b66181cc8df302b97aabe7
+  data.tar.gz: 6a3e33b62857804eb18179233aa3de385ee7b44785dbb1fdd27de4a95e9aa0bc
 SHA512:
-  metadata.gz: 729475e954a39717db0f64b1dbfa2e267c41cf23742fb26de919ba2c80347b25adb1951d4c9ae2a3069068a5ac3baa52c9e8761b235bb72491a1fd0b32f82d94
-  data.tar.gz: 53b3ae64d2f92db487299ce46a2808cb82afea02e8b1ed66dbe4d3dfd5d2eddcc31f2697a1f87194f60c9ac7ffa15cfef8d5d11f5bc0e04b666e9e6d4f7d6f79
+  metadata.gz: 52d97220ae00afd76ecb7253f626c135be6f33622130cf43edcabb90bb63f93b8ee3e143734059a6f69a80d57800c29d47adc4c8569c7b08e54676853a6eb36a
+  data.tar.gz: ea666de41864df7f84315e69e4481fd1a1b79bf4c32da29b1e76a4483a4a3276a99e494ecf47850e124170ac43ba00cb5c8e10d81421620d3f2b27bbe5c3af21

data/CHANGELOG.md

@@ -1,6 +1,17 @@
 ## rexe -- Ruby Command Line Executor
 
 
+### v0.13.0
+
+* Much refactoring.
+* Allow omitting source code in no-op mode.
+* Add ability to remove load or require files using minus sign preceding name.
+* Requires needed for parsing and formatting will now be included in log output.
+* Change license from MIT to Apache version 2.
+* Add undocumented '--open-project' command line option to launch Github project page in Mac OS and possibly other OS's.
+* Fix and add tests.
+
+
 ### v0.12.0
 
 * Change verbose -v boolean option to log output format -g option.

data/LICENSE.txt

@@ -1,21 +1,201 @@
-The MIT License (MIT)
-
-Copyright (c) 2019 Keith Bennett
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2019 Bennett Business Solutions, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -42,11 +42,10 @@ make the command long and tedious, discouraging this approach.
 
 ### Rexe
 
-Enter the `rexe` script: [^1]
-
+The `rexe` script [^1] can simplify such commands.
 Among other things, `rexe` provides switch-activated input parsing and output formatting so that converting 
 from one format to another is trivial.
-This command does the same thing as the previous `ruby` command:
+The previous `ruby` command can be expressed in `rexe` as:
 
 ```
 ➜  ~   echo $EUR_RATES_JSON | rexe -mb -ij -oy self
@@ -61,7 +60,7 @@ line, tipping the scale so that it is practical to do it more often.
 Here is `rexe`'s help text as of the time of this writing:
 
 ```
-rexe -- Ruby Command Line Executor/Filter -- v0.12.0 -- https://github.com/keithrbennett/rexe
+rexe -- Ruby Command Line Executor/Filter -- v0.13.0 -- https://github.com/keithrbennett/rexe
 
 Executes Ruby code on the command line, optionally taking standard input and writing to standard output.
 
@@ -77,12 +76,13 @@ Options:
                              -im  Marshal
                              -in  None
                              -iy  YAML
--l, --load RUBY_FILE(S)    Ruby file(s) to load, comma separated, or ! to clear
+-l, --load RUBY_FILE(S)    Ruby file(s) to load, comma separated;
+                             ! to clear all, or precede a name with '-' to remove
 -m, --input_mode MODE      Mode with which to handle input (i.e. what `self` will be in your code):
                              -ml  line mode; each line is ingested as a separate string
                              -me  enumerator mode
                              -mb  big string mode; all lines combined into single multiline string
-                             -mn  (default) no input mode; no special handling of input; self is an Object.new
+                             -mn  (default) no input mode; no special handling of input; self is an Object.new 
 -n, --[no-]noop            Do not execute the code (useful with -g); the following are valid:
                              -n no, -n yes, -n false, -n true, -n n, -n y, -n +, but not -n -
 -o, --output_format FORMAT Output format (defaults to puts):
@@ -94,9 +94,10 @@ Options:
                              -op  Puts (default)
                              -os  to_s
                              -oy  YAML
--r, --require REQUIRE(S)   Gems and built-in libraries to require, comma separated, or ! to clear
+-r, --require REQUIRE(S)   Gems and built-in libraries to require, comma separated;
+                             ! to clear all, or precede a name with '-' to remove
 
-If there is an .rexerc file in your home directory, it will be run as Ruby code
+If there is an .rexerc file in your home directory, it will be run as Ruby code 
 before processing the input.
 
 If there is a REXE_OPTIONS environment variable, its content will be prepended to the command line
@@ -105,7 +106,7 @@ so that you can specify options implicitly (e.g. `export REXE_OPTIONS="-r awesom
 
 ### Simplifying the Rexe Invocation
 
-There are two main ways we can simplify the `rexe` command line:
+There are two main ways we can make the `rexe` command line even more concise:
 
 * by extracting configuration into the `REXE_OPTIONS` environment variable
 * by extracting low level and/or shared code into files that are loaded using `-l`,
@@ -137,10 +138,12 @@ def valkyries
 end
 ```
 
-Why would you want this? You might want to be able to go to another room until a long job completes, and be notified when it is done. The `valkyries` method will launch a browser window pointed to Richard Wagner's "Ride of the Valkyries" starting at a lively point in the music. (The `open` command is Mac specific and could be replaced with `start` on Windows, a browser command name, etc.) If you like this sort of thing, you could download public domain audio files and use a command like player like `afplay` on Mac OS, or `mpg123` or `ogg123` on Linux. This approach is lighter weight, requires no network access, and will not leave an open browser window for you to close.
+To digress a bit, why would you want this? You might want to be able to go to another room until a long job completes, and be notified when it is done. The `valkyries` method will launch a browser window pointed to Richard Wagner's "Ride of the Valkyries" starting at a lively point in the music. (The `open` command is Mac specific and could be replaced with `start` on Windows, a browser command name, etc.) [^2]
+ 
+ If you like this kind of audio notification, you could download public domain audio files and use a command like player like `afplay` on Mac OS, or `mpg123` or `ogg123` on Linux. This approach is lighter weight, requires no network access, and will not leave an open browser window for you to close.
 
-Here is an example of how you might use this, assuming the above configuration is loaded from your `~/.rexerc` file or 
-an explicitly loaded file:
+Here is an example of how you might use the `valkyries` method, assuming the above configuration 
+is loaded from your `~/.rexerc` file or an explicitly loaded file:
 
 ```
 ➜  ~   tar czf /tmp/my-whole-user-space.tar.gz ~ ; rexe valkyries
@@ -180,7 +183,7 @@ Alternatively you could escape the parentheses with backslashes.)
 
 A log entry is optionally output to standard error after completion of the code.
 The entry is a hash containing the version, date/time of execution, source code
-to be evaluated, options (specified by all approaches),
+to be evaluated, options (after parsing both the `REXE_OPTIONS` environment variable and the command line),
 and the execution time of your Ruby code:
  
 ```
@@ -188,8 +191,8 @@ and the execution time of your Ruby code:
 ...
 ---
 :count: 0
-:rexe_version: 0.11.0
-:start_time: '2019-03-11T20:16:02+07:00'
+:rexe_version: 0.12.0
+:start_time: '2019-03-19T19:39:18+08:00'
 :source_code: ap JSON.parse(STDIN.read)
 :options:
   :input_format: :none
@@ -199,10 +202,14 @@ and the execution time of your Ruby code:
   :requires:
   - json
   - awesome_print
-  :verbose: true
+  - yaml
+  :log_format: :yaml
   :noop: false
-:duration_secs: 0.032174
+:duration_secs: 0.116171
 ``` 
+
+The `yaml` require was not explicitly specified but is automatically added because
+`rexe` will add any requires needed for automatic parsing and formatting.
  
 This extra output is sent to standard error (_stderr_) instead of standard output
 (_stdout_) so that it will not pollute the "real" data when stdout is piped to
@@ -232,17 +239,19 @@ and in different ways. Here is the help text relating to input modes:
 ```
 
 The first three are _filter_ modes; they make standard input available
-to your code as `self`, and automatically output to standard output
-the last value evaluated by your code.
+to your code as `self`.
 
 The last (and default) is the _executor_ mode. It merely assists you in
 executing the code you provide without any special implicit handling of standard input.
 
+All input modes automatically output to standard output the last value evaluated by your code.
+You can suppress automatic output with the `-on` option.
+
 
 #### -ml "Line" Filter Mode
 
 In this mode, your code would be called once per line of input,
-and in each call, `self` would evaluate to the line of text:
+and in each call, `self` would evaluate to each line of text:
 
 ```
 ➜  ~   echo "hello\ngoodbye" | rexe -ms reverse
@@ -251,13 +260,13 @@ eybdoog
 ```
 
 `reverse` is implicitly called on each line of standard input.  `self`
- is the input line in each call (we could also have used `self.reverse` but the `self` would have been redundant.).
+ is the input line in each call (we could also have used `self.reverse` but the `self.` would have been redundant.).
   
-Be aware that although you can control the _content_ of output records, 
+Be aware that, in this mode, although you can control the _content_ of output records, 
 there is no way to selectively _exclude_ records from being output. Even if the result of the code
 is nil or the empty string, a newline will be output. If this is an issue, you could do one of the following:
  
- * use Enumerator mode and call `select`, `filter`, `reject`, etc.
+ * use `-me` Enumerator mode and call `select`, `filter`, `reject`, etc.
  * use the `-on` _no output_ mode and call `puts` explicitly for the output you _do_ want
 
 
@@ -284,7 +293,7 @@ Since `self` is an enumerable, we can call `first` and then `each_with_index`.
 
 #### -mb "Big String" Filter Mode
 
-In this mode, all standard input is combined into a single, (possibly
+In this mode, all standard input is combined into a single (possibly
 large) string, with newline characters joining the lines in the string.
 
 A good example of when you would use this is when you parse JSON or YAML text; 
@@ -306,8 +315,8 @@ if you defined methods, constants, instance variables, etc., in your code.
 If you may have more input than would fit in memory, you can do the following:
 
 * use `-ml` (line) mode so you are fed only 1 line at a time
-* use an Enumerator, either by specifying the `-me` (enumerator) mode option,
- or using `-mn` (no input) mode in conjunction with something like `STDIN.each_line`. Then: 
+* use an Enumerator, either by a) specifying the `-me` (enumerator) mode option,
+ or b) using `-mn` (no input) mode in conjunction with something like `STDIN.each_line`. Then: 
   * Make sure not to call any methods (e.g. `map`, `select`)
  that will produce an array of all the input because that will pull all the records into memory, or:
   * use [lazy enumerators](https://www.honeybadger.io/blog/using-lazy-enumerators-to-work-with-large-files-in-ruby/)
@@ -332,7 +341,7 @@ since there is no preprocessing of standard input in that mode.
 
 ### Output Formats
 
-Several output formats are provided for your convenience. Here they are:
+Several output formats are provided for your convenience:
 
 * `-oa` - Awesome Print - calls `.ai` on the object to get the string that `ap` would print
 * `-oi` - Inspect - calls `inspect` on the object
@@ -349,7 +358,7 @@ You may wonder why these formats are provided, given that their functionality
 could be included in the custom code instead. Here's why:
 
 * The savings in command line length goes a long way to making these commands more readable and feasible.
-* It's much simpler to use multiple formats, as there is no need to change the code itself. This also enables
+* It's much simpler to switch formats, as there is no need to change the code itself. This also enables
 parameterization of the output format.
 
 
@@ -359,7 +368,7 @@ For your convenience, the information displayed in verbose mode is available to
 by accessing the `$RC` global variable, which contains an OpenStruct. Probably most useful in that object
 is the record count, accessible with both `$RC.count` and `$RC.i`.
 This is only really useful in line mode, because in the others
-it will always be 0 or 1. Here is an example of how you might use it:
+it will always be 0 or 1. Here is an example of how you might use it as a kind of progress indicator:
 
 ```
 ➜  ~   ➜  ~   find / | rexe -ml -on \
@@ -371,6 +380,11 @@ File entry #108000 is /usr/local/Cellar/go/1.11.5/libexec/src/runtime/os_linux_n
 ...
 ```
 
+Note that a single quote was used for the Ruby code here; 
+if a double quote were used, the `$RC` would have been interpreted
+and removed by the shell.
+  
+
 ### Implementing Domain Specific Languages (DSL's)
 
 Defining methods in your loaded files enables you to effectively define a [DSL](https://en.wikipedia.org/wiki/Domain-specific_language) for your command line use. You could use different load files for different projects, domains, or contexts, and define aliases or one line scripts to give them meaningful names. For example, if I wrote code to work with Ansible and put it in `~/projects/rexe-ansible.rb`, I could define an alias in my startup script:
@@ -393,7 +407,7 @@ trivially easily. Just to illustrate, here's how you would open a REPL on the Fi
 `self` would evaluate to the `File` class, so you could call class methods implicitly using only their names:
 
 ```
-➜  rock_books git:(master) ✗   rexe  -r pry File.pry
+➜  ~   rexe  -r pry File.pry
 
 [6] pry(File)> size '/etc/passwd'
 6804
@@ -403,7 +417,11 @@ true
 true
 ```
 
-This could be really handy if you call `pry` on a custom object that has methods especially suited to your task.
+This could be really handy if you call `pry` on a custom object that has methods especially suited to your task:
+
+```
+➜  ~   rexe  -r  wifi-wand,pry  WifiWand::MacOsModel.new.pry
+```
 
 Ruby is supremely well suited for DSL's since it does not require parentheses for method calls, 
 so calls to your custom methods _look_ like built in language commands and keywords. 
@@ -417,7 +435,11 @@ necessary to quote the Ruby code. You can use single or double quotes to have th
 as a single argument. 
 An excellent reference for how they differ is [here](https://stackoverflow.com/questions/6697753/difference-between-single-and-double-quotes-in-bash).
 
-Feel free to fall back on Ruby's super useful `%q{}` and `%Q{}`, equivalent to single and double quotes, respectively.
+Personally, I find single quotes more useful since special characters like `$` in my Ruby code will
+not be disturbed.
+
+When specifying the Ruby code, feel free to fall back on Ruby's super useful `%q{}` and `%Q{}`,
+equivalent to single and double quotes, respectively.
 
 
 ### No Op Mode
@@ -429,15 +451,19 @@ you want to see the configuration options before running it for real.
 
 ### Mimicking Method Arguments
 
-You may want to support arguments in your code. One of the previous examples downloaded currency conversion rates. Let's find out the available currency codes:
+You may want to support arguments in your `rexe` commands. 
+You could do this by piping in the arguments as `rexe`'s stdin.
+
+One of the previous examples downloaded currency conversion rates. 
+To prepare for an example of how to do this, let's find out the available currency codes:
 
 ```
-➜  /   echo $EUR_RATES_JSON | rexe -rjson -mb \
-        "JSON.parse(self)['rates'].keys.sort.join(' ')"
+➜  /   echo $EUR_RATES_JSON | rexe -ij -mb "self['rates'].keys.sort.join(' ')"
 AUD BGN BRL CAD CHF CNY CZK DKK GBP HKD HRK HUF IDR ILS INR ISK JPY KRW MXN MYR NOK NZD PHP PLN RON RUB SEK SGD THB TRY USD ZAR
 ```
- 
- Here would be a way to output a single rate:
+
+The codes output are the legal arguments that could be sent to `rexe`'s stdin as an argument.
+Let's find out the Euro exchange rate for _PHP_, Philippine Pesos:
  
 ```
 ➜  ~   echo PHP | rexe -ml -rjson \
@@ -449,6 +475,12 @@ AUD BGN BRL CAD CHF CNY CZK DKK GBP HKD HRK HUF IDR ILS INR ISK JPY KRW MXN MYR
 
 In this code, `self` is the currency code `PHP` (Philippine Peso). We have accessed the JSON text to parse from the environment variable we previously populated.
 
+Because we "used up" stdin for the argument, we could not make use of automatic parsing
+ of the currency exchange data (using the `-ij` option),
+which would have greatly simplified the command. One possible solution to this would be 
+to pipe in the JSON or YAML representation of a hash
+with entries for both the argument and the currency exchange data...but this might
+make the command line too complex to be practical.
 
 ### Using the Clipboard for Text Processing
 
@@ -486,11 +518,9 @@ when you change the content of the clipboard.
 ### Multiline Ruby Commands
 
 Although `rexe` is cleanest with short one liners, you may want to use it to include nontrivial Ruby code
-in your shell script as well. If you do this, you may need to:
+in your shell script as well. If you do this, you may need to add trailing backslashes to the lines of Ruby code.
 
-* add trailing backslashes to lines of Ruby code
-* use %q{} and %Q{} in your Ruby code instead of single and double quotes, 
-  since the quotes have special meaning to the shell
+In addition, don't forget you can use `%q{}` and `%Q{}` in your Ruby code instead of single and double quotes.
 
 
 ### The Use of Semicolons
@@ -536,9 +566,20 @@ puts to_a"
 
 There may be times when you have specified a load or require on the command line
 or in the `REXE_OPTIONS` environment variable,
-but you want to override it for a single invocation. Currently you cannot
-unspecify a single resource, but you can unspecify _all_ the requires or loads
-with the `-r!` and `-l!` command line options, respectively.
+but you want to override it for a single invocation. Here are your options:
+ 
+1) Unspecify _all_ the requires or loads with the `-r!` and `-l!` command line options, respectively.
+
+2) Unspecify individual requires or loads by preceding the name with `-`, e.g. `-r -rails`.
+Array subtraction is used, so:
+
+```
+➜  ~   rexe -n -r rails,rails,rails,-rails -ga
+```
+
+...would show that the final `-rails` cancelled all the previous `rails` specifications.
+
+
 
 
 ### Clearing _All_ Options
@@ -567,27 +608,49 @@ Files loaded with the `-l` option are treated the same way.
 Requiring gems and modules for _all_ invocations of `rexe` will make your commands simpler and more concise, but will be a waste of execution time if they are not needed. You can inspect the execution times to see just how much time is being wasted. For example, we can find out that nokogiri takes about 0.15 seconds to load on my laptop by observing and comparing the execution times with and without the require (output has been abbreviated using the redirection and grep):
 
 ```
-➜  ~   rexe -gy 2>&1 | grep duration
+➜  ~    rexe -gy 2>&1 "''" | grep duration
 :duration_secs: 0.0012
 
-➜  ~   rexe -gy -r nokogiri 2>&1 | grep duration
+➜  ~   rexe -gy -r nokogiri "''" 2>&1 | grep duration
 :duration_secs: 0.148671
 ```
 
+(For the above to work, the `nokogiri` gem needs to be installed.)
+
+
+### Operating System Support
+
+`rexe` has been tested successfully on Mac OS, Linux, and Windows Subsystem for Linux (WSL).
+It is intended as a tool for the Unix shell, and, as such, no attempt is made to support
+Windows non-Unix shells.
 
 
 ### More Examples
 
 Here are some more examples to illustrate the use of `rexe`.
 
+----
+Output the contents of `ENV` using AwesomePrint:
+
+```
+➜  ~   rexe -oa ENV
+{
+...
+                          "LANG" => "en_US.UTF-8",
+                           "PWD" => "/Users/kbennett/work/rexe",
+                         "SHELL" => "/bin/zsh",
+...
+}
+```
+
 ----
 
 Show disk space used/free on a Mac's main hard drive's main partition:
 
 ```
 ➜  ~   df -h | grep disk1s1 | rexe -ml \
-"x = split; puts %Q{#{x[4]} Used: #{x[2]}, Avail #{x[3]}}"
-91% Used: 412Gi, Avail 44Gi
+"x = split; puts %Q{#{x[4]} Used: #{x[2]}, Avail: #{x[3]}}"
+91% Used: 412Gi, Avail: 44Gi
 ```
 
 (Note that `split` is equivalent to `self.split`, and because the `-ml` option is used, `self` is the line of text.
@@ -729,7 +792,7 @@ Then when I issue a command that succeeds, the Hallelujah Chorus is played:
 
 ----
 
-Another formatting example...I wanted to reformat this help text:
+Another formatting example...I wanted to reformat this help text...
 
 ```
                                  'i' => Inspect
@@ -741,6 +804,7 @@ Another formatting example...I wanted to reformat this help text:
                                  'y' => YAML
 ```
 
+...into something more suitable for my help text.
 Admittedly, the time it took to do this with rexe probably exceeded the time to do it manually,
 but it was an interesting exercise and made it easy to try different formats. Here it is:
 
@@ -759,14 +823,15 @@ but it was an interesting exercise and made it easy to try different formats. He
 
 ### Conclusion
 
-`rexe` is not revolutionary technology, it's just plumbing that removes low level
+`rexe` is not revolutionary technology, it's just plumbing that removes parsing,
+formatting, and low level
 configuration from your command line so that you can focus on the high level
 task at hand.
 
-When we think of a new piece of software, we usually think "what would this be
+When we consider a new piece of software, we usually think "what would this be
 helpful with now?". However, for me, the power of `rexe` is not so much what I can do
 with it in a single use case now, but rather what will I be able to do with it over time
-as I get used to the concept and my supporting code and its uses evolve.
+as I accumulate more experience and expertise.
 
 I suggest starting to use `rexe` even for modest improvements in workflow, even
 if it doesn't seem compelling. There's a good chance that as you use it over
@@ -779,10 +844,32 @@ will be proportional to the extent to which you use environment variables
 and loaded files for configuration and shared code.
 Be responsible and disciplined in making this configuration and code as clean and organized as possible.
 
+----
+
 #### Footnotes
 
 [^1]: `rexe` is an embellishment of the minimal but excellent `rb` script at
 https://github.com/thisredone/rb. I started using `rb` and thought of lots of
 other features I would like to have, so I started working on `rexe`.
 
-[^2]: You might wonder why we don't just refrain from sending output to stdout on null or false. That is certainly easy to implement, but there are other ways to accomplish this (using _enumerable_ or _no input_ modes), and the lack of output might be surprising and disconcerting to the user. What do _you_ think, which approach makes more sense to you?
+[^2]: Making this truly OS-portable is a lot more complex than it looks on the surface.
+On Linux, `xdg-open` may not be installed by default. Also, Windows Subsystem for Linux (WSL)
+out of the box is not able to launch graphical applications.
+
+Here is a _start_ at a method that opens a resource portably across operating systems:
+
+```ruby
+  def open_resource(resource_identifier)
+    command = case (`uname`.chomp)
+    when 'Darwin'
+      'open'
+    when 'Linux'
+      'xdg-open'
+    else
+      'start'
+    end
+
+    `#{command} #{resource_identifier}`
+  end
+```
+