rexe 0.14.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 982527b8b9d991102d3a3a1eb5ae83e7235cea0b77b782921ab6e203a5c70f42
-  data.tar.gz: a586d1f5c68beaf81692f23920e1c2e8c435e44e7095b38e90a70f4b113fa32c
+  metadata.gz: 3a85b226f2d7d337d03476286bbe79f7b594519f93370198f8ae0581cec3616c
+  data.tar.gz: 77e944cb23215f4ed522e5c13b8f4457f0cbefcac67b26da8218d700d729a079
 SHA512:
-  metadata.gz: ffb97f15aae0ed61a2acabdfa2d330d15814d2c4ada682c1eae0099d8b5dd9262d1fa7e47142051d18ca5f5efddee2ef755efeb9b22d555bf2621327305e572c
-  data.tar.gz: ce5ae9551e7fad281a7505bb99c4749098eb9560fd377dc33ea3341ae29e5d4d490bfea807b426e36bf79f7cfbc597416da2cf50ab475343854908d49d131708
+  metadata.gz: 4c88dd6b11138b9339f73439687a847332957cb50b66a1c7bde4e38d6fbc4cc4c9931e0e40111054d9b0e784ec7ac0201e172d6a1224b4aa72b5fde8593087f6
+  data.tar.gz: 30e2902d826c9f32b12a2508152039752bd0c0f9738aa792fbadf133f57a19af28b0f8ea0ebc8ea85a052678ec8a748b5b1974ef4ffe811243b33cd2b20abd4d

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## rexe -- Ruby Command Line Executor
 
+### 0.15.0
+
+* Source code now defaults to 'self' (#3).
+* Change parse errors to not output help text and stack trace, but instead a short message with suggestion to use -h.
+
 
 ### 0.14.0
 

data/README.md

@@ -3,8 +3,10 @@ title: The `rexe` Command Line Executor and Filter
 date: 2019-02-15
 ---
 
-_[Caution: This is a long article! If you lose patience reading it, I suggest skimming the headings
-and the source code, and at minimum, reading the Conclusion.]_
+[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. 
+]
 
 ----
 
@@ -42,7 +44,7 @@ make the command long and tedious, discouraging this approach.
 
 ### Rexe
 
-The `rexe` script [^1] can simplify such commands.
+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 
 from one format to another is trivial.
 The previous `ruby` command can be expressed in `rexe` as:
@@ -66,7 +68,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.14.0 -- https://github.com/keithrbennett/rexe
+rexe -- Ruby Command Line Executor/Filter -- v0.15.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.
@@ -106,6 +108,9 @@ 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).
+
 If there is an .rexerc file in your home directory, it will be run as Ruby code 
 before processing the input.
 
@@ -160,7 +165,7 @@ 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.) [^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. (The `open` command is Mac specific and could be replaced with `start` on Windows, a browser command name, etc.) [see footnote ^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.
 
@@ -206,12 +211,13 @@ One of the examples at the end of this articles shows how you could have differe
 ### Logging
 
 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
+This entry is a hash representation (to be precise, `to_h`) of the `$RC` OpenStruct described in the $RC section below.
+It contains the version, date/time of execution, source code
 to be evaluated, options (after parsing both the `REXE_OPTIONS` environment variable and the command line),
 and the execution time of your Ruby code:
  
 ```
-➜  ~   echo $EUR_RATES_JSON | rexe -gy -ij -oa self
+➜  ~   echo $EUR_RATES_JSON | rexe -gy -ij -mb -oa self
 ...
 ---
 :count: 0
@@ -268,9 +274,7 @@ 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.
+Here is more detail on these modes:
 
 
 #### -ml "Line" Filter Mode
@@ -279,26 +283,29 @@ In this mode, your code would be called once per line of input,
 and in each call, `self` would evaluate to each line of text:
 
 ```
-➜  ~   echo "hello\ngoodbye" | rexe -ms reverse
+➜  ~   echo "hello\ngoodbye" | rexe -ml puts reverse
 olleh
 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, in this mode, although you can control the _content_ of output records, 
+Be aware that, in this mode, if you are using an automatic output mode
+(anything other than the default `-on` no output 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. To prevent this, you can do one of the following:
  
- * 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
+ * use `-me` Enumerator mode instead and call `select`, `filter`, `reject`, etc.
+ * use the (default) `-on` _no output_ mode and call `puts` explicitly for the output you _do_ want
 
 
 #### -me "Enumerator" Filter Mode
 
 In this mode, your code is called only once, and `self` is an enumerator
-dispensing all lines of standard input. To be more precise, it is the enumerator returned by `STDIN.each_line`.
+dispensing all lines of standard input. To be more precise, it is the enumerator returned by the `each_line` method,
+on `$stdin` or the input file, whichever is applicable.
 
 Dealing with input as an enumerator enables you to use the wealth of `Enumerable` methods such as `select`, `to_a`, `map`, etc.
 
@@ -306,7 +313,7 @@ Here is an example of using `-me` to add line numbers to the first 3
 files in the directory listing:
 
 ```
-➜  ~   ls / | rexe -me -on "first(3).each_with_index { |ln,i| puts '%5d  %s' % [i, ln] }"
+➜  ~   ls / | rexe -me "first(3).each_with_index { |ln,i| puts '%5d  %s' % [i, ln] }"
 
     0  AndroidStudioProjects
     1  Applications
@@ -314,7 +321,8 @@ files in the directory listing:
 ```
 
 Since `self` is an enumerable, we can call `first` and then `each_with_index`.
-The `-on` says don't do any automatic output, just the output explicitly specified by `puts` in the source code.
+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.
 
 
 #### -mb "Big String" Filter Mode
@@ -338,7 +346,8 @@ if you defined methods, constants, instance variables, etc., in your code.
 
 #### Filter Input Mode Memory Considerations
 
-If you may have more input than would fit in memory, you can do the following:
+If you are using one of the filter modes, and may have more input than would fit in memory,
+you can do one of the following:
 
 * use `-ml` (line) mode so you are fed only 1 line at a time
 * use an Enumerator, either by a) specifying the `-me` (enumerator) mode option,
@@ -373,7 +382,7 @@ Several output formats are provided for your convenience:
 * `-oi` - Inspect - calls `inspect` on the object
 * `-oj` - JSON - calls `to_json` on the object
 * `-oJ` - Pretty JSON calls `JSON.pretty_generate` with the object
-* `-on` - No Output - output is suppressed
+* `-on` - (default) No Output - output is suppressed
 * `-op` - Puts - produces what `puts` would output
 * `-os` - To String - calls `to_s` on the object
 * `-oy` - YAML - calls `to_yaml` on the object
@@ -384,14 +393,14 @@ 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 switch formats, as there is no need to change the code itself. This also enables
-parameterization of the output format.
+* It's much simpler to switch formats, as there is no need to change the code itself.
+* This approach enables parameterization of the output format.
 
 
 ### Reading Input from a File
 
 `rexe` also simplifies getting input from a file rather than standard input. The `-f` option takes a filespec
-and does with exactly what it would have done with standard input. This shortens:
+and does with its content exactly what it would have done with standard input. This shortens:
 
 ```
 ➜  ~   cat filename.ext | rexe ...
@@ -424,6 +433,29 @@ 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.
 
+
+### '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:
+
+```
+➜ ~  rexe -f eur_rates.json -oy
+# or
+➜ ~  echo $EUR_RATES_JSON | rexe -mb -ij -oy
+
+---
+rates:
+  JPY: 126.63
+  BRL: 4.3012
+  NOK: 9.6915
+  ...
+```
+
+This feature is probably only useful in the filter modes, since in the executor mode (`-mn`) self is a new
+instance of `Object` and hardly ever useful as an output value.
+
 ### The $RC Global OpenStruct
 
 For your convenience, the information displayed in verbose mode is available to your code at runtime
@@ -450,7 +482,7 @@ OpenStruct {
 }
 ``` 
  
-Probably most useful in that object
+Probably most useful in that object at runtime
 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 as a kind of progress indicator:
@@ -472,10 +504,15 @@ 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:
+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:
 
 ```
-➜  ~   alias rxans="rexe -l ~/projects/rexe-ansible.rb $*"
+➜  ~   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`.
 
@@ -505,32 +542,81 @@ true
 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
+➜  ~   rexe -r wifi-wand,pry  WifiWand::MacOsModel.new.pry
+[1] pry(#<WifiWand::MacOsModel>)> random_mac_address
+"a1:ea:69:d9:ca:05"
+[2] pry(#<WifiWand::MacOsModel>)> connected_network_name
+"My WiFi"
 ```
 
 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. 
 
 
-### Quoting Strings in Your Ruby Code
+### Quotation Marks and Quoting Strings in Your Ruby Code
 
-One complication of using utilities like `rexe` where Ruby code is specified on the shell 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 [here](https://stackoverflow.com/questions/6697753/difference-between-single-and-double-quotes-in-bash).
+as a single argument. An excellent reference for how they differ is on StackOverflow at
+https://stackoverflow.com/questions/6697753/difference-between-single-and-double-quotes-in-bash.
+
+Personally, I find single quotes more useful since I usually don't want special characters in my Ruby code
+like `$` to be processed by the shell.
+
+Sometimes it doesn't matter:
+
+```
+➜  ~   rexe 'puts "hello"'
+hello
+➜  ~   rexe "puts 'hello'"
+hello
+```
+
+We can also use `%q` or `%Q`, and sometimes this eliminates the needs for the outer quotes:
+
+```
+➜  ~   rexe puts %q{hello}
+hello
+➜  ~   rexe puts %Q{hello}
+hello
+```
+
+Sometimes the quotes to use on the outside (quoting your command in the shell) need to be chosen
+based on which quotes are needed on the inside. For example, in the following command, we need
+double quotes in Ruby in order for interpolation to work, so we use single quotes on the outside:
+
+```
+➜  ~   rexe puts '"The time is now #{Time.now}"'
+The time is now 2019-03-29 16:41:26 +0800
+```
+
+In this case we also need to use single quotes on the outside,
+because we need literal double quotes in a `%Q{}` expression:
+
+```
+➜  ~   rexe 'puts %Q{The operating system name is "#{`uname`.chomp}".}'
+The operating system name is "Darwin".
+```
+
+We can eliminate the need for any quotes in the Ruby code using `%Q{}`:
+
+```
+➜  ~   rexe puts '%Q{The time is now #{Time.now}}'
+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.
 
-Personally, I find single quotes more useful since I usually don't want special characters in my Ruby code  like `$` to be processed by the shell.
 
-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
 
 The `-n` no-op mode will result in the specified source code _not_ being executed. This can sometimes be handy
-in conjunction with a `-g` (logging) option; if you have a command ready to go but 
-you want to see the configuration options before running it for real.
+in conjunction with a `-g` (logging) option, if you have are building a rexe command and
+want to inspect the configuration options before executing the Ruby code.
 
 
 ### Mimicking Method Arguments
@@ -542,15 +628,16 @@ 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 -ij -mb "self['rates'].keys.sort.join(' ')"
+➜  /   echo $EUR_RATES_JSON | \
+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.
+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:
  
 ```
-➜  ~   echo PHP | rexe -ml -rjson \
+➜  ~   echo PHP | rexe -ml -op -rjson \
         "rate = JSON.parse(ENV['EUR_RATES_JSON'])['rates'][self];\
         %Q{1 EUR = #{rate} #{self}}"
 
@@ -570,21 +657,32 @@ make the command line too complex to be practical.
 
 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, the `pbpaste` command outputs to stdout
-the clipboard content, and the `pbcopy` command copies its stdin to the clipboard.
-
-Let's say I have the following currency codes displayed on the screen:
+this can easily be done. 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
+ 
+Let's say I have the following currency codes displayed on the screen
+(data abridged for brevity):
 
 ```
-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
+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
 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:
+
+```
+➜  ~   echo AUD BGN BRL PHP TRY USD ZAR | pbcopy
+```
+
 After copying this line to the clipboard, I could run this:
 
 ```
-➜  ~   pbpaste | rexe -ml "split.map(&:downcase).map { |s| %Q{    #{s}: '',} }.join(%Q{\n})"
+➜  ~   pbpaste | rexe -ml -op "split.map(&:downcase).map { |s| %Q{    #{s}: '',} }.join(%Q{\n})"
     aud: '',
     bgn: '',
     brl: '',
@@ -592,7 +690,7 @@ After copying this line to the clipboard, I could run this:
 ```
 
 If I add `| pbcopy` to the rexe command, then that output text would be copied into the clipboard instead of
-displayed in the terminal, and I could then paste it in my editor.
+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
@@ -604,7 +702,8 @@ when you change the content of the clipboard.
 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. For example, here is an example without a semicolon:
+What might not be so obvious is that you will often need to use semicolons as statement separators.
+For example, here is an example without a semicolon:
 
 ```
 ➜  ~   cowsay hello | rexe -me "print %Q{\u001b[33m} \
@@ -617,7 +716,13 @@ puts to_a"
 ```
 
 The shell combines all backslash terminated lines into a single line of text, so when the Ruby
-interpreter sees your code, it's all in a single line. Adding the semicolon fixes the problem:
+interpreter sees your code, it's all in a single line:
+
+```
+➜  ~   cowsay hello | rexe -me "print %Q{\u001b[33m} puts to_a"
+```
+
+Adding the semicolon fixes the problem:
 
 ```
 ➜  ~   cowsay hello | rexe -me "print %Q{\u001b[33m}; \
@@ -642,15 +747,24 @@ 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:
+Array subtraction is used, and array subtraction removes _all_
+occurrences of each element of the subtracted (subtrahend) array, so:
 
 ```
-➜  ~   rexe -n -r rails,rails,rails,-rails -ga
+➜  ~   rexe -n -r rails,rails,rails,-rails -gP
+...
+   :requires=>["pp"],
+...
 ```
 
 ...would show that the final `-rails` cancelled all the previous `rails` specifications.
 
+We could have also extracted the requires list programmatically using `$RC` (described above) by doing this:
 
+```
+➜  ~   rexe -oP -r rails,rails,rails,-rails '$RC[:options][:requires]'
+["pp"]
+```    
 
 
 ### Clearing _All_ Options
@@ -676,7 +790,7 @@ 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 the redirection and 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 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`):
 
 ```
 ➜  ~   rexe -gy -r rails 123 2>&1 | grep duration
@@ -700,40 +814,18 @@ Here are some more examples to illustrate the use of `rexe`.
 
 ----
 
-### Format Conversions -- JSON, YAML, AwesomePrint
-
-You may work with YAML or JSON a lot and need to inspect files from time to time.
-`rexe` makes it easy to convert from one format to another. For example, here's a
-command to convert from `countries.yaml` to AwesomePrint:
-
-```
-cat countries.yaml | rexe -iy -oa -mb self
-```
-
-You can easily create a script that automates this. Using your favorite editor,
-put this in a file:
-
-```
-cat $1 | rexe -iy -oa -mb self
-```
-
-I put mine in a file called `y2a` in my `~/bin` directory where I keep custom scripts like this.
-
-Now you can call `y2a` to output any YAML file using AwesomePrint.
-
-----
 
 #### Outputting ENV
 
-Output the contents of `ENV` using AwesomePrint [^3]:
+Output the contents of `ENV` using AwesomePrint [see footnote ^3]:
 
 ```
 ➜  ~   rexe -oa ENV
 {
 ...
-                          "LANG" => "en_US.UTF-8",
-                           "PWD" => "/Users/kbennett/work/rexe",
-                         "SHELL" => "/bin/zsh",
+  "LANG" => "en_US.UTF-8",
+   "PWD" => "/Users/kbennett/work/rexe",
+ "SHELL" => "/bin/zsh",
 ...
 }
 ```
@@ -759,7 +851,7 @@ Show disk space used/free on a Mac's main hard drive's main partition:
 Show the 3 longest file names of the current directory, with their lengths, in descending order:
 
 ```
-➜  ~   ls  | rexe -ml "%Q{[%4d] %s} % [length, self]" | sort -r | head -3
+➜  ~   ls  | rexe -ml -op "%Q{[%4d] %s} % [length, self]" | sort -r | head -3
 [  50] Agoda_Booking_ID_9999999 49_–_RECEIPT_enclosed.pdf
 [  40] 679a5c034994544aab4635ecbd50ab73-big.jpg
 [  28] 2018-abc-2019-01-16-2340.zip
@@ -789,13 +881,11 @@ alphabetically will result in sorting them numerically as well.
 ```
 
 
-----
-
 ----
 
 #### More YouTube: Differentiating Success and Failure 
 
-Let's go a little crazy with the YouTube example.
+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.
 
@@ -818,6 +908,8 @@ def play_result(success)
 end
 
 
+# Must pipe the exit code into this Ruby process, 
+# e.g. using `echo $? | rexe play_result_by_exit_code
 def play_result_by_exit_code
   play_result(STDIN.read.chomp == '0')
 end
@@ -844,30 +936,33 @@ Then when I issue a command that succeeds, the Hallelujah Chorus is played:
 Another formatting example...I wanted to reformat this source code...
 
 ```
-                                 'i' => Inspect
-                                 'j' => JSON
-                                 'J' => Pretty JSON
-                                 'n' => No Output
-                                 'p' => Puts (default)
-                                 's' => to_s
-                                 'y' => YAML
+         'i' => Inspect
+         'j' => JSON
+         'J' => Pretty JSON
+         'n' => No Output
+         'p' => Puts (default)
+         's' => to_s
+         '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:
+but it was an interesting exercise and made it easy to try different formats. Here it is, after
+copying the original text to the clipboard:
 
 ```
-➜  ~   pbpaste | rexe -ml "sub(%q{'}, '-o').sub(%q{' =>}, %q{ })"
-                                 -oi  Inspect
-                                 -oj  JSON
-                                 -oJ  Pretty JSON
-                                 -on  No Output
-                                 -op  Puts (default)
-                                 -os  to_s
-                                 -oy  YAML
-```                                 
-                                 
+➜  ~   pbpaste | rexe -ml -op "sub(%q{'}, '-o').sub(%q{' =>}, %q{ })"
+         -oi  Inspect
+         -oj  JSON
+         -oJ  Pretty JSON
+         -on  No Output
+         -op  Puts (default)
+         -os  to_s
+         -oy  YAML
+```         
+         
+
+----
 
 #### Reformatting Grep Output
 
@@ -887,7 +982,7 @@ lib/rock_books/documents/journal_entry.rb:
 So this is what worked well for me:
 
 ```
-➜  ~   grep Struct **/*.rb | grep -v OpenStruct | rexe -ml \
+➜  ~   grep Struct **/*.rb | grep -v OpenStruct | rexe -ml -op \
 "a = \
  gsub('lib/rock_books/', '')\
 .gsub('< Struct.new',    '')\
@@ -913,7 +1008,8 @@ types/acct_amount.rb                     class AcctAmount (:date, :code, :amount
 types/journal_entry_context.rb           class JournalEntryContext (:journal, :linenum, :line)
 ``` 
 
-Although there's a lot going on here, the vertical and horizontal alignments and spacing make the code
+Although there's a lot going on in this code,
+the vertical and horizontal alignments and spacing make the code
 straightforward to follow. Here's what it does:
 
 * grep the code base for `"Struct"`
@@ -923,6 +1019,8 @@ straightforward to follow. Here's what it does:
 * strip unwanted space because that will mess up the horizontal alignment of the output.
 * use C-style printf formatting to align the text into two columns
 
+----
+
  
 ### Conclusion
 
@@ -933,8 +1031,8 @@ 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
-with it in a single use case now, but rather what will I be able to do with it over time
-as I accumulate more experience and expertise.
+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
 if it doesn't seem compelling. There's a good chance that as you use it over
@@ -942,7 +1040,7 @@ 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.
@@ -976,4 +1074,7 @@ 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, most of the other output formats will return some form of `"ENV"`. You can handle this by specifying `ENV.to_h`.
+[^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)
+

data/exe/rexe

@@ -12,11 +12,20 @@ require 'shellwords'
 
 class Rexe
 
-  VERSION = '0.14.0'
+  VERSION = '0.15.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)
+    end
+  end
+
+
   class Options < Struct.new(
       :input_filespec,
       :input_format,
@@ -127,6 +136,8 @@ class Rexe
 
   class CommandLineParser
 
+    include Helpers
+
     attr_reader :lookups, :options
 
     def initialize
@@ -195,6 +206,9 @@ 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).
+
     If there is an .rexerc file in your home directory, it will be run as Ruby code 
     before processing the input.
 
@@ -218,7 +232,21 @@ class Rexe
     end
 
 
-    # Using 'optparse', parses the command line.
+    def open_resource(resource_identifier)
+      command = case (`uname`.chomp)
+                when 'Darwin'
+                  'open'
+                when 'Linux'
+                  'xdg-open'
+                else
+                  'start'
+                end
+
+      `#{command} #{resource_identifier}`
+    end
+
+
+  # Using 'optparse', parses the command line.
     # Settings go into this instance's properties (see Struct declaration).
     def parse
 
@@ -230,7 +258,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)
-            raise "File #{v} does not exist."
+            error_exit "File #{v} does not exist."
           end
           options.input_filespec = v
           options.input_format = autodetect_file_format(v)
@@ -242,8 +270,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?
-            puts help_text
-            raise "Output mode was '#{v}' but must be one of #{lookups.output_formats.keys}."
+            error_exit("Output mode was '#{v}' but must be one of #{lookups.output_formats.keys}.")
           end
         end
 
@@ -257,8 +284,7 @@ class Rexe
 
           options.input_format = lookups.input_formats[v]
           if options.input_format.nil?
-            puts help_text
-            raise "Input mode was '#{v}' but must be one of #{lookups.input_formats.keys}."
+            error_exit("Input mode was '#{v}' but must be one of #{lookups.input_formats.keys}.")
           end
         end
 
@@ -271,7 +297,7 @@ class Rexe
 
             existent, nonexistent = adds.partition { |filespec| File.exists?(filespec) }
             if nonexistent.any?
-              raise("\nDid not find the following files to load: #{nonexistent}\n\n")
+              error_exit("\nDid not find the following files to load: #{nonexistent}\n\n")
             else
               existent.each { |filespec| options.loads << filespec }
             end
@@ -285,8 +311,7 @@ class Rexe
 
           options.input_mode = lookups.input_modes[v]
           if options.input_mode.nil?
-            puts help_text
-            raise "Input mode was '#{v}' but must be one of #{lookups.input_modes.keys}."
+            error_exit("Input mode was '#{v}' but must be one of #{lookups.input_modes.keys}.")
           end
         end
 
@@ -295,8 +320,7 @@ class Rexe
 
           options.output_format = lookups.output_formats[v]
           if options.output_format.nil?
-            puts help_text
-            raise "Output mode was '#{v}' but must be one of #{lookups.output_formats.keys}."
+            error_exit("Output mode was '#{v}' but must be one of #{lookups.output_formats.keys}.")
           end
         end
 
@@ -355,6 +379,8 @@ class Rexe
 
   class Main
 
+    include Helpers
+
     attr_reader :callable, :input_parser, :lookups,
                 :options, :output_formatter,
                 :log_formatter, :start_time, :user_source_code
@@ -366,20 +392,6 @@ class Rexe
     end
 
 
-    def open_resource(resource_identifier)
-      command = case (`uname`.chomp)
-      when 'Darwin'
-        'open'
-      when 'Linux'
-        'xdg-open'
-      else
-        'start'
-      end
-
-      `#{command} #{resource_identifier}`
-    end
-
-
     private def load_global_config_if_exists
       filespec = File.join(Dir.home, '.rexerc')
       load(filespec) if File.exists?(filespec)
@@ -428,10 +440,6 @@ class Rexe
 
 
     private def create_callable
-      if user_source_code.empty? && (! options.noop)
-        raise "No source code provided.  Use -h to display help."
-      end
-
       eval("Proc.new { #{user_source_code} }")
     end
 
@@ -483,6 +491,8 @@ class Rexe
       options.loads.each { |file| load(file) }
 
       @user_source_code = ARGV.join(' ')
+      @user_source_code = 'self' if @user_source_code == ''
+
       @callable = create_callable
 
       init_rexe_context

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rexe
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.15.0
 platform: ruby
 authors:
 - Keith Bennett
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-03-24 00:00:00.000000000 Z
+date: 2019-03-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: awesome_print