rexe 0.15.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1e109ac92787742884d19056f18b7b6cc36bd93f017f8e06857b733c6532f607
-  data.tar.gz: b1eb347fee1f87826f73f3afb246de542ee145b484b1497cc5f2ff29eada7265
+  metadata.gz: ad9ebb60746e9796db2a6f284cf0d0aee226db27e665710cdfc18714ec0e6363
+  data.tar.gz: f2cbb93e42bca15ffab3d9b240785427c70a6ed507b33c9673eb9536d0a0a343
 SHA512:
-  metadata.gz: f7a5886ca0a29bc61bdd37cb27ecb8e328aeed12aa7dcf4c3c4a7bb15bf8d2009d8b2ffab45f334f7e5b50fe8ca9ea30dd4ef02448077acaab935ee33671b52b
-  data.tar.gz: 4567e8126e315260b9c07583f0c7a028ce237b83e634103552b08a0d43f240271ebed5c49d13f2dee29256201f8a88d632fae2a0761c612816e764d3a70c5ec3
+  metadata.gz: 17a9cf1e2ece63be47427236a3803ff2ddd7bf144774755c567e7074ad43c6aff19799a2e3651bc8a81fcc7a7550eae3968e9525942f4d4bccb4127e0c481fe4
+  data.tar.gz: 484af00828303109e4b9904316700f25340cee8314e0a4e038b5166b2b5410c8e5731b0b6bb6ab91414b03c1bf709d532048d2cf975fcffac782d47db07c0209

data/CHANGELOG.md

@@ -1,4 +1,14 @@
-## rexe -- Ruby Command Line Executor
+## rexe -- Ruby Command Line Executor/Filter
+
+
+### 1.0.0
+
+* Suppress help message on SystemExit.
+* Eliminate stack trace from all error messages.
+* Fix Awesome Print output to have a "\n" at the end of it.
+* Add eur_rates.json sample data.
+* Remove gem post-commit message.
+
 
 ### 0.15.1
 

data/README.md

@@ -1,28 +1,32 @@
----
-title: The `rexe` Command Line Executor and Filter
-date: 2019-02-15
----
+# Rexe
 
-[Caution: This is a long article!
-You might want to skim the section headings and source code first.
-Many sections can be skipped without sacrificing comprehensibility of the rest of them. 
-]
+__Rexe__ is a Ruby script and gem that multiplies Ruby's usefulness and conciseness on the command line by:
+
+* automating parsing and formatting using JSON, YAML, Ruby marshalling, Awesome Print, and others
+* simplifying the use of Ruby as a shell filter, optionally predigesting input as lines, an enumerator, or one big string
+* extracting the plumbing from the command line; requires and other options can be set in an environment variable
+* enabling the loading of Ruby helper files to keep your code DRY and your command line code high level
+* reading and evaluating a ~/.rexerc file on startup for your shared custom code and common requires
 
 ----
 
 Shell scripting is great for simple tasks but for anything nontrivial
 it can easily get cryptic and awkward (pun intended!).
- 
-Often, I solve this problem by writing a Ruby script instead. Ruby gives me fine
+
+This problem can often be solved by writing a Ruby script instead. Ruby provides fine
 grained control in a language that is all about clarity, conciseness, and expressiveness.
 
 Unfortunately, when there are multiple OS commands to be called, then Ruby can be
 awkward too.
 
+Sometimes a good solution is to combine Ruby and shell scripting on the same
+command line. Rexe multiplies your power to do so.
+
+
 ### Using the Ruby Interpreter on the Command Line
 
-Sometimes a good solution is to combine Ruby and shell scripting on the same
-command line. Here's an example, using an intermediate environment variable to
+Let's start by seeing what the Ruby interpreter already provides.
+Here we use `ruby` on the command line, using an intermediate environment variable to
 simplify the logic and save the data for use by future commands.
 An excerpt of the output follows the code:
 
@@ -39,13 +43,13 @@ base: EUR
 date: '2019-03-08'
 ```
 
-However, the configuration setup (the `require`s) along with the reading, parsing, and formatting
+Unfortunately, the configuration setup (the `require`s) along with the reading, parsing, and formatting
 make the command long and tedious, discouraging this approach.
 
 ### Rexe
 
-The `rexe` script [see footnote ^1] can simplify such commands.
-Among other things, `rexe` provides switch-activated input parsing and output formatting so that converting 
+Rexe [see footnote ^1 regarding its origin] 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.
 The previous `ruby` command can be expressed in `rexe` as:
 
@@ -53,27 +57,40 @@ The previous `ruby` command can be expressed in `rexe` as:
 ➜  ~   echo $EUR_RATES_JSON | rexe -mb -ij -oy self
 ```
 
+Or, even more concisely (`self` is the default Ruby source code for rexe commands):
+
+```
+➜  ~   echo $EUR_RATES_JSON | rexe -mb -ij -oy
+```
+
 The command options may seem cryptic, but they're logical so it shouldn't take long to learn them:
 
 * `-mb` - __mode__ to consume all standard input as a single __big__ string
 * `-ij` - parse that __input__ with __JSON__; `self` will be the parsed object
 * `-oy` - __output__ the final value as __YAML__
  
-`rexe` is at https://github.com/keithrbennett/rexe and can be installed with
-`gem install rexe`. `rexe` provides several ways to simplify Ruby on the command
+If input comes from a JSON or YAML file, rexe determines the input format from the file's extension,
+and it's even simpler:
+
+```
+➜  ~   rexe -f eur_rates.json -oy
+```
+
+Rexe is at https://github.com/keithrbennett/rexe and can be installed with
+`gem install rexe`. Rexe provides several ways to simplify Ruby on the command
 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:
+Here is rexe's help text as of the time of this writing:
 
 ```
-rexe -- Ruby Command Line Executor/Filter -- v0.15.1 -- https://github.com/keithrbennett/rexe
+rexe -- Ruby Command Line Executor/Filter -- v1.0.0 -- https://github.com/keithrbennett/rexe
 
 Executes Ruby code on the command line, optionally automating management of standard input
 and standard output, and optionally parsing input and formatting output with YAML, JSON, etc.
 
-rexe [options] 'Ruby source code'
+rexe [options] [Ruby source code]
 
 Options:
 
@@ -108,29 +125,34 @@ Options:
 -r, --require REQUIRE(S)   Gems and built-in libraries to require, comma separated;
                              ! to clear all, or precede a name with '-' to remove
 
-If source code is not specified, it will default to 'self', which is most likely useful
-only in a filter mode (-ml, -me, -mb).
+---------------------------------------------------------------------------------------
+                                                                                            
+In many cases you will need to enclose your source code in single or double quotes.
+
+If source code is not specified, it will default to 'self', 
+which is most likely useful only in a filter mode (-ml, -me, -mb).
 
 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
-so that you can specify options implicitly (e.g. `export REXE_OPTIONS="-r awesome_print,yaml"`)
+If there is a REXE_OPTIONS environment variable, its content will be prepended
+to the command line so that you can specify options implicitly 
+(e.g. `export REXE_OPTIONS="-r awesome_print,yaml"`)
 ```
 
 ### Simplifying the Rexe Invocation
 
-There are two main ways we can make the `rexe` command line even more concise:
+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`,
+* by extracting low level and/or shared code into helper files that are loaded using `-l`,
   or implicitly with `~/.rexerc`
 
 
 ### The REXE_OPTIONS Environment Variable
 
 The `REXE_OPTIONS` environment variable can contain command line options that would otherwise
-be specified on the `rexe` command line:
+be specified on the rexe command line:
 
 Instead of this:
 
@@ -147,16 +169,17 @@ you can do this:
 ```
 
 Putting configuration options in `REXE_OPTIONS` effectively creates custom defaults,
- and is useful when you use options in most or all of your commands. Any options specified on the `rexe`
+ and is useful when you use the same options in most or all of your commands.
+Any options specified on the rexe
 command line will override the environment variable options.
 
 Like any environment variable, `REXE_OPTIONS` could also be set in your startup script, input on a command line using `export`, or in another script loaded with `source` or `.`.
 
 ### Loading Files
 
-The environment variable approach works well for command line _options_, but what if we want to specify Ruby _code_ (e.g. methods) that can be used by your `rexe` code?
+The environment variable approach works well for command line _options_, but what if we want to specify Ruby _code_ (e.g. methods) that can be used by your rexe code?
 
-For this, `rexe` lets you _load_ Ruby files, using the `-l` option, or implicitly (without your specifying it) in the case of the `~/.rexerc` file. Here is an example of something you might include in such a file:
+For this, rexe lets you _load_ Ruby files, using the `-l` option, or implicitly (without your specifying it) in the case of the `~/.rexerc` file. Here is an example of something you might include in such a file:
 
 ```
 # Open YouTube to Wagner's "Ride of the Valkyries"
@@ -165,7 +188,13 @@ def valkyries
 end
 ```
 
-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.) [see footnote ^2]
+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 [see footnote ^2 regarding autoplay]. 
+(The `open` command is Mac specific and could be replaced with `start` on Windows,
+a browser command name, etc.) [see footnote ^3 regarding OS portability].
  
  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.
 
@@ -178,9 +207,12 @@ is loaded from your `~/.rexerc` file or an explicitly loaded file:
 
 (Note that `;` is used rather than `&&` because we want to hear the music whether or not the command succeeds.)
 
-You might be thinking that creating an alias or a minimal shell script for this `open` would be a simpler and more natural
+You might be thinking that creating an alias or a minimal shell script (instead of a Ruby script)
+for this `open` would be a simpler and more natural
 approach, and I would agree with you. However, over time the number of these could become unmanageable, whereas using Ruby
-you could build a pretty extensive and well organized library of functionality. Moreover, that functionality could be made available to _all_ your Ruby code (for example, by putting it in a gem), and not just command line one liners.
+you could build a pretty extensive and well organized library of functionality. 
+Moreover, that functionality could be made available to _all_ your Ruby code 
+(for example, by putting it in a gem), and not just command line one liners.
 
 For example, you could have something like this in a gem or loaded file:
 
@@ -220,29 +252,30 @@ and the execution time of your Ruby code:
 ➜  ~   echo $EUR_RATES_JSON | rexe -gy -ij -mb -oa self
 ...
 ---
-:count: 0
-:rexe_version: 0.13.0
-:start_time: '2019-03-21T20:58:51+08:00'
-:source_code: ap JSON.parse(STDIN.read)
+:count: 1
+:rexe_version: 1.0.0
+:start_time: '2019-04-14T19:15:50+08:00'
+:source_code: self
 :options:
-  :input_format: :none
-  :input_mode: :no_input
+  :input_filespec:
+  :input_format: :json
+  :input_mode: :one_big_string
   :loads: []
-  :output_format: :puts
+  :output_format: :awesome_print
   :requires:
   - awesome_print
   - json
   - yaml
   :log_format: :yaml
   :noop: false
-:duration_secs: 0.070381
+:duration_secs: 0.064798
 ``` 
 
 We specified `-gy` for YAML format; there are other formats as well (see the help output or this document)
 and the default is `-gn`, which means don't output the log entry at all.
 
 The requires you see were not explicitly specified but were automatically added because
-`rexe` will add any requires needed for automatic parsing and formatting, and
+Rexe will add any requires needed for automatic parsing and formatting, and
 we specified those formats in the command line options `-gy -ij -oa`.
  
 This extra output is sent to standard error (_stderr_) instead of standard output
@@ -258,15 +291,15 @@ If you would like to append this informational output to a file(e.g. `rexe.log`)
 
 ### Input Modes
 
-`rexe` tries to make it simple and convenient for you to handle standard input, 
+Rexe tries to make it simple and convenient for you to handle standard input, 
 and in different ways. Here is the help text relating to input modes:
 
 ```
 -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 not input 
+  -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
 ```
 
 The first three are _filter_ modes; they make standard input available
@@ -320,7 +353,7 @@ files in the directory listing:
     2  Desktop
 ```
 
-Since `self` is an enumerable, we can call `first` and then `each_with_index`.
+Since `self` is an enumerable, we can call `first` on it.
 We've used the default output mode `-on` (_no output_ mode), which says don't do any automatic output,
 just the output explicitly specified by `puts` in the source code.
 
@@ -328,11 +361,11 @@ just the output explicitly specified by `puts` in the source code.
 #### -mb "Big String" Filter Mode
 
 In this mode, all standard input is combined into a single (possibly
-large) string, with newline characters joining the lines in the string.
+large and possibly multiline) string.
 
 A good example of when you would use this is when you need to parse a multiline JSON or YAML representation of an object; 
-you need to pass the entire (probably) multiline string to the parse method. 
-This is the mode that was used in the first `rexe` example in this article.
+you need to pass all the standard input to the parse method. 
+This is the mode that was used in the first rexe example in this article.
 
 
 #### -mn "No Input" Executor Mode -- The Default
@@ -359,7 +392,7 @@ you can do one of the following:
 
 ### Input Formats
 
-`rexe` can parse your input in any of several formats if you like. 
+Rexe can parse your input in any of several formats if you like. 
 You would request this in the _input format_ (`-i`) option.
 Legal values are:
 
@@ -389,6 +422,9 @@ Several output formats are provided for your convenience:
 
 All formats will implicitly `require` anything needed to accomplish their task (e.g. `require 'yaml'`).
 
+The default is `-on` to produce no output at all (unless explicitly coded to do so). If you prefer a different
+default such as `-op` for _puts_ mode, you can specify that in your `REXE_OPTIONS` environment variable.
+
 You may wonder why these formats are provided, given that their functionality 
 could be included in the custom code instead. Here's why:
 
@@ -399,7 +435,7 @@ could be included in the custom code instead. Here's why:
 
 ### Reading Input from a File
 
-`rexe` also simplifies getting input from a file rather than standard input. The `-f` option takes a filespec
+Rexe also simplifies getting input from a file rather than standard input. The `-f` option takes a filespec
 and does with its content exactly what it would have done with standard input. This shortens:
 
 ```
@@ -433,12 +469,21 @@ So the example we gave above:
 Another possible win for using `-f` is that since it is a command line option, it could be specified in `REXE_OPTIONS`.
 This could be useful if you are doing many operations on the same file.
 
+If you need to override the input mode and format automatically configured for file input, you can simply specify
+the desired options on the command line _after_ the `-f`:
+
+```
+➜  ~   rexe -f eur_rates.json -mb -in 'puts self.class, self[0..20]'
+String
+{"base":"EUR","rates"
+```
+
 
 ### 'self' as Default Source Code
 
-To make `rexe` even more concise, you do not need to specify any source code when you want that source code
-to be `self`. This would be the case for simple format conversions, such as the following JSON to YAML conversion
-of the currency coversion rates:
+To make rexe even more concise, you do not need to specify any source code when you want that source code
+to be `self`. This would be the case for simple format conversions, as in JSON to YAML conversion
+mentioned above:
 
 ```
 ➜ ~  rexe -f eur_rates.json -oy
@@ -465,19 +510,20 @@ by accessing the `$RC` global variable, which contains an OpenStruct. Let's prin
 ➜  ~   rexe -oa '$RC'
 OpenStruct {
            :count => 0,
-    :rexe_version => "0.13.0",
-      :start_time => "2019-03-23T20:17:59+08:00",
+    :rexe_version => "1.0.0",
+      :start_time => "2019-04-14T19:16:26+08:00",
      :source_code => "$RC",
          :options => {
-         :input_format => :none,
-           :input_mode => :no_input,
-                :loads => [],
-        :output_format => :awesome_print,
-             :requires => [
+        :input_filespec => nil,
+          :input_format => :none,
+            :input_mode => :none,
+                 :loads => [],
+         :output_format => :awesome_print,
+              :requires => [
             [0] "awesome_print"
         ],
-           :log_format => :none,
-                 :noop => false
+            :log_format => :none,
+                  :noop => false
     }
 }
 ``` 
@@ -508,13 +554,13 @@ 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/ansible-tools/rexe-ansible.rb`, 
-I could define an alias in my startup script:
+For example, if you had Ansible helper code in `~/projects/ansible-tools/rexe-ansible.rb`, 
+you could define an alias in your startup script:
 
 ```
 ➜  ~   alias rxans="rexe -l ~/projects/ansible-tools/rexe-ansible.rb $*"
 ```
-...and then I would have an Ansible DSL available for me to use by calling `rxans`.
+...and then you would have an Ansible DSL available for me to use by calling `rxans`.
 
 In addition, since you can also call `pry` on the context of any object, you
 can provide a DSL in a [REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop) (shell)
@@ -555,7 +601,7 @@ so calls to your custom methods _look_ like built in language commands and keywo
 
 ### Quotation Marks and Quoting Strings in Your Ruby Code
 
-One complication of using utilities like `rexe` where Ruby code is specified on the command line is that
+One complication of using utilities like rexe where Ruby code is specified on the command line is that
 you need to be careful about the shell's special treatment of certain characters. For this reason, it is often
 necessary to quote the Ruby code. You can use single or double quotes to have the shell treat your source code
 as a single argument. An excellent reference for how they differ is on StackOverflow at
@@ -573,7 +619,7 @@ hello
 hello
 ```
 
-We can also use `%q` or `%Q`, and sometimes this eliminates the needs for the outer quotes:
+We can also use `%q` or `%Q`, and sometimes this eliminates the needs for the outer quotes altogether:
 
 ```
 ➜  ~   rexe puts %q{hello}
@@ -606,8 +652,7 @@ We can eliminate the need for any quotes in the Ruby code using `%Q{}`:
 The time is now 2019-03-29 17:06:13 +0800
 ```
 
-Of course you can always escape the quotes with backslashes instead, but in my experience
-that becomes difficult to read.
+Of course you can always escape the quotes with backslashes instead, but that is probably more difficult to read.
 
 
 
@@ -621,8 +666,8 @@ want to inspect the configuration options before executing the Ruby code.
 
 ### Mimicking Method Arguments
 
-You may want to support arguments in your `rexe` commands. 
-You could do this by piping in the arguments as `rexe`'s stdin.
+You may want to support arguments in your rexe commands.
+It's a little kludgy, but 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:
@@ -633,7 +678,7 @@ rexe -ij -mb -op "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
 ```
 
-The codes output are the legal arguments that could be sent to `rexe`'s stdin as an argument in the command below.
+The codes output are the legal arguments that could be sent to rexe's stdin as an argument in the command below.
 Let's find out the Euro exchange rate for _PHP_, Philippine Pesos:
  
 ```
@@ -644,42 +689,42 @@ Let's find out the Euro exchange rate for _PHP_, Philippine Pesos:
 1 EUR = 58.986 PHP
 ```
 
-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.
+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.
+Because we "used up" stdin for the `PHP` argument, we needed to read the JSON data explicitly from
+the environment variable, and that made the command more complex. A regular Ruby script would handle this more nicely.
+ 
 
 ### Using the Clipboard for Text Processing
 
-Sometimes when editing text I need to do some one off text manipulation.
-Using the system's commands for pasting to and copying from the clipboard,
-this can easily be done. On the Mac, we have the following commands:
+For editing text in an editor,
+rexe can be used for text transformations that would otherwise need to be done manually.
+
+The system's commands for pasting to and copying from the clipboard can handle the moving of the text
+between the editor and rexe. On the Mac, we have the following commands:
  
-* `pbcopy` - copies the content of stdin _to_ the clipboard
-* `pbpaste` - copies the content _from_ the clipboard to stdout
+* `pbcopy` - copies the content of its stdin _to_ the clipboard
+* `pbpaste` - copies the content _from_ the clipboard to its stdout
  
-Let's say I have the following currency codes displayed on the screen
+Let's say we have the following currency codes displayed on the screen
 (data abridged for brevity):
 
 ```
 AUD BGN BRL PHP TRY USD ZAR
 ```
 
-...and I want to turn them into Ruby symbols for inclusion in Ruby source code as keys in a hash
+...and we want to turn them into Ruby symbols for inclusion in Ruby source code as keys in a hash
 whose values will be the display names of the currencies, e.g "Australian Dollar").
 
-I could manually select that text and use system menu commands or keys to copy it to the clipboard, 
-or I could do this:
+We could manually select that text and use system menu commands or keys to copy it to the clipboard, 
+or we could do this:
 
 ```
 ➜  ~   echo AUD BGN BRL PHP TRY USD ZAR | pbcopy
 ```
 
-After copying this line to the clipboard, I could run this:
+After copying this line to the clipboard, we could run this:
 
 ```
 ➜  ~   pbpaste | rexe -ml -op "split.map(&:downcase).map { |s| %Q{    #{s}: '',} }.join(%Q{\n})"
@@ -694,12 +739,12 @@ displayed in the terminal, and I could then paste it into my editor.
 
 Using the clipboard in manual operations is handy, but using it in automated scripts is a very bad idea, since
 there is only one clipboard per user session. If you use the clipboard in an automated script you risk
-an error situation if its content is changed by others, or, conversely, you could mess up another task
+an error situation if its content is changed by another process, or, conversely, you could mess up another process
 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
+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 add trailing backslashes to the lines of Ruby code.
 
 What might not be so obvious is that you will often need to use semicolons as statement separators.
@@ -709,8 +754,7 @@ For example, here is an example without a semicolon:
 ➜  ~   cowsay hello | rexe -me "print %Q{\u001b[33m} \
 puts to_a"
 
-/Users/kbennett/.rvm/gems/ruby-2.6.0/gems/rexe-0.10.1/exe/rexe:256:in `eval':
-   (eval):1: syntax error, unexpected tIDENTIFIER, expecting '}' (SyntaxError)
+rexe: (eval):1: syntax error, unexpected tIDENTIFIER, expecting '}'
 ...new { print %Q{\u001b[33m} puts to_a }
 ...                           ^~~~
 ```
@@ -776,7 +820,7 @@ and want to ignore all of them.
 
 ### Comma Separated Requires and Loads
 
-For consistency with the `ruby` interpreter, `rexe` supports requires with the `-r` option, but 
+For consistency with the `ruby` interpreter, rexe supports requires with the `-r` option, but 
 also allows grouping them together using commas:
 
 ```
@@ -790,12 +834,12 @@ Files loaded with the `-l` option are treated the same way.
 
 ### Beware of Configured Requires
 
-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 rails takes about 0.63 seconds to load on my laptop by observing and comparing the execution times with and without the require (output has been abbreviated using `grep`):
+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 consumed. For example, we can find out that rails takes about 0.63 seconds to load on one system by observing and comparing the execution times with and without the require (output has been abbreviated using `grep`):
 
 ```
-➜  ~   rexe -gy -r rails 123 2>&1 | grep duration
+➜  ~   rexe -gy -r rails 2>&1 | grep duration
 :duration_secs: 0.660138
-➜  ~   rexe -gy          123 2>&1 | grep duration
+➜  ~   rexe -gy          2>&1 | grep duration
 :duration_secs: 0.027781
 ```
 (For the above to work, the `rails` gem and its dependencies need to be installed.)
@@ -803,21 +847,55 @@ Requiring gems and modules for _all_ invocations of `rexe` will make your comman
 
 ### Operating System Support
 
-`rexe` has been tested successfully on Mac OS, Linux, and Windows Subsystem for Linux (WSL).
+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`.
+Here are some more examples to illustrate the use of rexe.
+
+----
+
+#### Using Rexe as a Simple Calculator
+
+To output the result to stdout, you can either call `puts` or specify the `-op` option:
+
+```
+➜  ~   rexe puts 1 / 3.0
+0.3333333333333333
+```
+
+or:
+
+```
+➜  ~   rexe -op 1 / 3.0
+0.3333333333333333
+```
+
+Since `*` is interpreted by the shell, if we do multiplication, we need to quote the expression:
+
+```
+➜  ~   rexe -op '2 * 7'
+14
+```
+
+Of course, if you put the `-op` in the `REXE_OPTIONS` environment variable,
+you don't need to be explicit about the output:
+
+```
+➜  ~   export REXE_OPTIONS=-op
+➜  ~   rexe '2 * 7'
+14
+```
 
 ----
 
 
 #### Outputting ENV
 
-Output the contents of `ENV` using AwesomePrint [see footnote ^3]:
+Output the contents of `ENV` using AwesomePrint [see footnote ^4 regarding ENV.to_s]:
 
 ```
 ➜  ~   rexe -oa ENV
@@ -864,6 +942,9 @@ alphabetically will result in sorting them numerically as well.
 
 #### Print yellow (trust me!):
 
+This uses an [ANSI escape code](https://en.wikipedia.org/wiki/ANSI_escape_code)
+to output text to the terminal in yellow:
+
 ```
 ➜  ~   cowsay hello | rexe -me "print %Q{\u001b[33m}; puts to_a"
 ➜  ~     # or
@@ -889,7 +970,7 @@ Let's take the YouTube example from the "Loading Files" section further.
 Let's have the video that loads be different for the success or failure
 of the command.
 
-If I put this in a load file (such as ~/.rexerc):
+If we put this in a load file (such as ~/.rexerc):
 
 ```
 def play(piece_code)
@@ -909,14 +990,14 @@ end
 
 
 # Must pipe the exit code into this Ruby process, 
-# e.g. using `echo $? | rexe play_result_by_exit_code
+# e.g. using `echo $? | rexe play_result_by_exit_code`
 def play_result_by_exit_code
   play_result(STDIN.read.chomp == '0')
 end
 
 ```
 
-Then when I issue a command that succeeds, the Hallelujah Chorus is played:
+Then when we issue a command that succeeds, the Hallelujah Chorus is played [see footnote ^2]:
 
 ```
 ➜  ~   uname; echo $? | rexe play_result_by_exit_code
@@ -962,6 +1043,35 @@ copying the original text to the clipboard:
 ```         
          
 
+----
+
+#### Currency Conversion
+
+I travel a lot, and when I visit a country for the first time I often get confused by the exchange rate.
+I put this in my `~/.rexerc`:
+
+```
+# Conversion rate to US Dollars
+module Curr
+  module_function
+  def myr;      4.08  end  # Malaysian Ringits
+  def thb;     31.72  end  # Thai Baht
+  def usd;      1.00  end  # US Dollars
+  def vnd;  23199.50  end  # Vietnamese Dong
+end
+```
+
+If I'm lucky enough to be at my computer when I need to do a conversion,
+for example, to find the value of 150 Malaysian ringits in US dollars, I can do this:
+
+```
+➜  rexe git:(master) ✗   rexe puts 150 / Curr.myr
+36.76470588235294
+```
+
+Obviously rates will change over time, but this will give me a general idea, which is usually all I need.
+
+
 ----
 
 #### Reformatting Grep Output
@@ -983,13 +1093,13 @@ So this is what worked well for me:
 
 ```
 ➜  ~   grep Struct **/*.rb | grep -v OpenStruct | rexe -ml -op \
-"a = \
- gsub('lib/rock_books/', '')\
-.gsub('< Struct.new',    '')\
-.gsub('; end',           '')\
-.split('.rb:')\
-.map(&:strip);\
-\
+"a =                            \
+ gsub('lib/rock_books/', '')    \
+.gsub('< Struct.new',    '')    \
+.gsub('; end',           '')    \
+.split('.rb:')                  \
+.map(&:strip);                  \
+                                \
 %q{%-40s %-s} % [a[0] + %q{.rb}, a[1]]"
 ```
 
@@ -1024,23 +1134,23 @@ straightforward to follow. Here's what it does:
  
 ### Conclusion
 
-`rexe` is not revolutionary technology, it's just plumbing that removes parsing,
+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 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
+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 over time
 as I accumulate more experience and expertise with it.
 
-I suggest starting to use `rexe` even for modest improvements in workflow, even
+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
 time, new ideas will come to you and the workflow improvements will increase
 exponentially.
 
 A word of caution though -- 
-the complexity and difficulty of _sharing_ your `rexe` scripts across systems
+the complexity and difficulty of _sharing_ your rexe scripts across systems
 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.
@@ -1049,11 +1159,17 @@ Be responsible and disciplined in making this configuration and code as clean an
 
 #### Footnotes
 
-[^1]: `rexe` is an embellishment of the minimal but excellent `rb` script at
+[^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`.
+other features I would like to have, so I started working on rexe.
 
-[^2]: Making this truly OS-portable is a lot more complex than it looks on the surface.
+[^2]: It's possible that when this page opens in your browser it will not play automatically.
+You may need to change your default browser, or change the code that opens the URL.
+Firefox's new (as of March 2019) version 66 suppresses autoplay; you can register
+exceptions to this policy: open Firefox Preferences, search for "autoplay" and add
+"https://www.youtube.com".
+ 
+[^3]: 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.
 
@@ -1074,7 +1190,4 @@ Here is a _start_ at a method that opens a resource portably across operating sy
   end
 ```
 
-[^3]: It is an interesting quirk of the Ruby language that `ENV.to_s` returns `"ENV"` and not the contents of the `ENV` object. As a result, many of the other output formats will also return some form of `"ENV"`. You can handle this by specifying `ENV.to_h`.
-
-- Keith Bennett (@keithrbennett on Github and Twitter)
-
+[^4]: It is an interesting quirk of the Ruby language that `ENV.to_s` returns `"ENV"` and not the contents of the `ENV` object. As a result, many of the other output formats will also return some form of `"ENV"`. You can handle this by specifying `ENV.to_h`.

data/exe/rexe

@@ -12,16 +12,24 @@ require 'shellwords'
 
 class Rexe
 
-  VERSION = '0.15.1'
+  VERSION = '1.0.0'
 
   PROJECT_URL = 'https://github.com/keithrbennett/rexe'
 
 
   module Helpers
-    def error_exit(message)
-      $stderr.puts(message)
-      $stderr.puts("Use the -h option to get help.")
-      exit(-1)
+
+    # Try executing code. If error raised, print message (but not stack trace) & exit -1.
+    def try
+      begin
+        yield
+      rescue Exception => e
+        unless e.class == SystemExit
+          $stderr.puts('rexe: ' << e.class.to_s)
+          $stderr.puts("Use the -h option to get help.")
+          exit(-1)
+        end
+      end
     end
   end
 
@@ -82,10 +90,10 @@ class Rexe
 
     def input_parsers
       @input_parsers ||= {
-          json:    ->(obj)  { JSON.parse(obj) },
-          marshal: ->(obj)  { Marshal.load(obj) },
-          none:    ->(obj)  { obj },
-          yaml:    ->(obj)  { YAML.load(obj) },
+          json:    ->(string)  { JSON.parse(string) },
+          marshal: ->(string)  { Marshal.load(string) },
+          none:    ->(string)  { string },
+          yaml:    ->(string)  { YAML.load(string) },
       }
     end
 
@@ -108,7 +116,7 @@ class Rexe
 
     def formatters
       @formatters ||=  {
-          awesome_print: ->(obj)  { obj.ai },
+          awesome_print: ->(obj)  { obj.ai << "\n" },
           inspect:       ->(obj)  { obj.inspect + "\n" },
           json:          ->(obj)  { obj.to_json },
           marshal:       ->(obj)  { Marshal.dump(obj) },
@@ -121,6 +129,7 @@ class Rexe
       }
     end
 
+
     def format_requires
       @format_requires ||= {
           json:          'json',
@@ -156,14 +165,14 @@ class Rexe
     end
 
 
-    def add_format_requires_to_requires_list
+    private def add_format_requires_to_requires_list
       formats = [options.input_format, options.output_format, options.log_format]
       requires = formats.map { |format| lookups.format_requires[format] }.uniq.compact
       requires.each { |r| options.requires << r }
     end
 
 
-    def help_text
+    private def help_text
       <<~HEREDOC
 
     rexe -- Ruby Command Line Executor/Filter -- v#{VERSION} -- #{PROJECT_URL}
@@ -171,7 +180,7 @@ class Rexe
     Executes Ruby code on the command line, optionally automating management of standard input
     and standard output, and optionally parsing input and formatting output with YAML, JSON, etc.
 
-    rexe [options] 'Ruby source code'
+    rexe [options] [Ruby source code]
 
     Options:
 
@@ -206,21 +215,26 @@ class Rexe
     -r, --require REQUIRE(S)   Gems and built-in libraries to require, comma separated;
                                  ! to clear all, or precede a name with '-' to remove
 
-    If source code is not specified, it will default to 'self', which is most likely useful
-    only in a filter mode (-ml, -me, -mb).
+    ---------------------------------------------------------------------------------------
+                                                                                                
+    In many cases you will need to enclose your source code in single or double quotes.
+
+    If source code is not specified, it will default to 'self', 
+    which is most likely useful only in a filter mode (-ml, -me, -mb).
 
     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
-    so that you can specify options implicitly (e.g. `export REXE_OPTIONS="-r awesome_print,yaml"`)
+    If there is a REXE_OPTIONS environment variable, its content will be prepended
+    to the command line so that you can specify options implicitly 
+    (e.g. `export REXE_OPTIONS="-r awesome_print,yaml"`)
 
       HEREDOC
     end
 
 
     # File file input mode; detects the input mode (JSON, YAML, or None) from the extension.
-    def autodetect_file_format(filespec)
+    private def autodetect_file_format(filespec)
       extension = File.extname(filespec).downcase
       if extension == '.json'
         :json
@@ -232,7 +246,7 @@ class Rexe
     end
 
 
-    def open_resource(resource_identifier)
+    private def open_resource(resource_identifier)
       command = case (`uname`.chomp)
                 when 'Darwin'
                   'open'
@@ -258,7 +272,7 @@ class Rexe
         parser.on('-f', '--input_file FILESPEC',
             'Use this file instead of stdin; autodetects YAML and JSON file extensions') do |v|
           unless File.exist?(v)
-            error_exit "File #{v} does not exist."
+            raise "File #{v} does not exist."
           end
           options.input_filespec = v
           options.input_format = autodetect_file_format(v)
@@ -270,7 +284,7 @@ class Rexe
         parser.on('-g', '--log_format FORMAT', 'Log format, logs to stderr, defaults to none (see -o for format options)') do |v|
           options.log_format = lookups.output_formats[v]
           if options.log_format.nil?
-            error_exit("Output mode was '#{v}' but must be one of #{lookups.output_formats.keys}.")
+            raise("Output mode was '#{v}' but must be one of #{lookups.output_formats.keys}.")
           end
         end
 
@@ -284,7 +298,7 @@ class Rexe
 
           options.input_format = lookups.input_formats[v]
           if options.input_format.nil?
-            error_exit("Input mode was '#{v}' but must be one of #{lookups.input_formats.keys}.")
+            raise("Input mode was '#{v}' but must be one of #{lookups.input_formats.keys}.")
           end
         end
 
@@ -297,7 +311,7 @@ class Rexe
 
             existent, nonexistent = adds.partition { |filespec| File.exists?(filespec) }
             if nonexistent.any?
-              error_exit("\nDid not find the following files to load: #{nonexistent}\n\n")
+              raise("\nDid not find the following files to load: #{nonexistent}\n\n")
             else
               existent.each { |filespec| options.loads << filespec }
             end
@@ -311,7 +325,7 @@ class Rexe
 
           options.input_mode = lookups.input_modes[v]
           if options.input_mode.nil?
-            error_exit("Input mode was '#{v}' but must be one of #{lookups.input_modes.keys}.")
+            raise("Input mode was '#{v}' but must be one of #{lookups.input_modes.keys}.")
           end
         end
 
@@ -320,7 +334,7 @@ class Rexe
 
           options.output_format = lookups.output_formats[v]
           if options.output_format.nil?
-            error_exit("Output mode was '#{v}' but must be one of #{lookups.output_formats.keys}.")
+            raise("Output mode was '#{v}' but must be one of #{lookups.output_formats.keys}.")
           end
         end
 
@@ -353,7 +367,7 @@ class Rexe
 
         parser.on('-v', '--version', 'Print version') do
           puts VERSION
-          exit
+          exit(0)
         end
 
         # Undocumented feature
@@ -484,24 +498,27 @@ class Rexe
     # This class' entry point.
     def call
 
-      @options = CommandLineParser.new.parse
+      try do
 
-      options.requires.each { |r| require!(r) }
-      load_global_config_if_exists
-      options.loads.each { |file| load(file) }
+        @options = CommandLineParser.new.parse
 
-      @user_source_code = ARGV.join(' ')
-      @user_source_code = 'self' if @user_source_code == ''
+        options.requires.each { |r| require!(r) }
+        load_global_config_if_exists
+        options.loads.each { |file| load(file) }
 
-      @callable = create_callable
+        @user_source_code = ARGV.join(' ')
+        @user_source_code = 'self' if @user_source_code == ''
 
-      init_rexe_context
-      init_parser_and_formatters
+        @callable = create_callable
 
-      # This is where the user's source code will be executed; the action will in turn call `execute`.
-      lookup_action(options.input_mode).call unless options.noop
+        init_rexe_context
+        init_parser_and_formatters
 
-      output_log_entry
+        # This is where the user's source code will be executed; the action will in turn call `execute`.
+        lookup_action(options.input_mode).call unless options.noop
+
+        output_log_entry
+      end
     end
   end
 end

data/rexe.gemspec

@@ -45,18 +45,4 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rake", "~> 12.3"
   spec.add_development_dependency "rspec", "~> 3.0"
 
-  spec.post_install_message =
-      <<~HEREDOC
-      
-      !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-      
-      WARNING!
-
-      The default output format has been changed from -op (:puts) to -on (:none)
-      in version 0.14.0.
-
-      !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-
-      HEREDOC
-
 end

data/sample-data/eur_rates.json

@@ -0,0 +1,38 @@
+{
+  "base": "EUR",
+  "rates": {
+    "BGN": 1.9558,
+    "NZD": 1.6748,
+    "ILS": 4.0389,
+    "RUB": 72.6133,
+    "CAD": 1.5082,
+    "USD": 1.1321,
+    "PHP": 58.553,
+    "CHF": 1.1326,
+    "ZAR": 15.7631,
+    "AUD": 1.5771,
+    "JPY": 126.76,
+    "TRY": 6.535,
+    "HKD": 8.8788,
+    "MYR": 4.658,
+    "THB": 35.955,
+    "HRK": 7.435,
+    "NOK": 9.602,
+    "IDR": 15954.12,
+    "DKK": 7.4643,
+    "CZK": 25.623,
+    "HUF": 321.9,
+    "GBP": 0.8629,
+    "MXN": 21.236,
+    "KRW": 1283.0,
+    "ISK": 135.2,
+    "SGD": 1.5318,
+    "BRL": 4.3884,
+    "PLN": 4.2796,
+    "INR": 78.2915,
+    "RON": 4.7598,
+    "CNY": 7.5939,
+    "SEK": 10.4788
+  },
+  "date": "2019-04-12"
+}

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rexe
 version: !ruby/object:Gem::Version
-  version: 0.15.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Keith Bennett
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-03-29 00:00:00.000000000 Z
+date: 2019-04-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: awesome_print
@@ -100,6 +100,7 @@ files:
 - bin/setup
 - exe/rexe
 - rexe.gemspec
+- sample-data/eur_rates.json
 homepage: https://github.com/keithrbennett/rexe
 licenses:
 - MIT
@@ -108,17 +109,7 @@ metadata:
   homepage_uri: https://github.com/keithrbennett/rexe
   source_code_uri: https://github.com/keithrbennett/rexe
   changelog_uri: https://github.com/keithrbennett/rexe/blob/master/README.md
-post_install_message: |2+
-
-  !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-
-  WARNING!
-
-  The default output format has been changed from -op (:puts) to -on (:none)
-  in version 0.14.0.
-
-  !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib