rexe 0.10.1 → 0.10.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c0055b60141171c65564e56db902aeb407184a8dae5abc89a1957238b3b35eb
-  data.tar.gz: 801efa318ca3a7dc8eeaea81e44d0f96331428465789c0cf9899196d6501c934
+  metadata.gz: bdd31e24705dfe69cc4f83f5529d1fd528401cb1a675e4203c037c92c4d88eae
+  data.tar.gz: '08e378d2729a9af62773deed3f4b653e702b97835e08ceb1b77622eda78d63be'
 SHA512:
-  metadata.gz: 1a87be47727dd851c36f93af89034f86ad7e268caa888a44018da344a6b1f9752f5e4e2bbf7460699f84b51bc47b2faf4b66cc6bac4f7b4f3b444856475cffd5
-  data.tar.gz: 9cdc86c7a7547e84c20286f6185162365453d5a3f0d556e98bc3b28dd6a2338b62999f722222394d4e749269535549cd22c1fa53ec68082fe0943377e8a6afb9
+  metadata.gz: bb5f6e5d5a8a19b18fd6ebdd6e5a12bdd6defe25638a91a9602697ba36057bbc905f1c0fb64ba30f830651bb825566eec455d94570f21751458e8c29ad371a0a
+  data.tar.gz: 676a94dfa2890c7711b6863dd9840c22cc402d09c940d4eace18832f78e254ff96fb1bf226e0f795c42da8c9f3c17f7630df68d54a7544bf54f8033a71cf2dfb

data/CHANGELOG.md

@@ -1,6 +1,11 @@
 ## rexe -- Ruby Command Line Executor
 
 
+### v0.10.2
+
+* Fix problem in :none input format mode.
+
+
 ### v0.10.1
 
 * Fix help text for input formats.

data/README.md

@@ -3,6 +3,9 @@ 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.]
+
 I love the power of the command line, but not the awkwardness of shell scripting
 languages. Sure, there's a lot that can be done with them, but it doesn't take
 long before I get frustrated with their bluntness and verbosity.
@@ -21,24 +24,31 @@ An excerpt of the output follows the code:
 
 ```
 ➜  ~   export EUR_RATES_JSON=`curl https://api.exchangeratesapi.io/latest`
-➜  ~   echo $EUR_RATES_JSON | ruby -r json -r awesome_print -e 'ap JSON.parse(STDIN.read)'
-{
-    "rates" => {
-        "MXN" => 21.781,
-        ...
-        "DKK" => 7.462
-    },
-     "base" => "EUR",
-     "date" => "2019-02-22"
-}
+➜  ~   echo $EUR_RATES_JSON | ruby -r json -r yaml -e 'puts JSON.parse(STDIN.read).to_yaml'
+---
+rates:
+  MXN: 21.96
+  AUD: 1.5964
+  HKD: 8.8092
+  ...
+base: EUR
+date: '2019-03-08'
 ```
 
-However, the configuration setup (the `require`s) make the command long and tedious, discouraging this
-approach.
+However, the configuration setup (the `require`s) along with the reading, parsing, and formatting
+make the command long and tedious, discouraging this approach.
 
 ### Rexe
 
-Enter the `rexe` script. [^1]
+Enter the `rexe` script: [^1]
+
+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:
+
+```
+➜  ~   echo $EUR_RATES_JSON | rexe -mb -ij -oy self
+```
  
 `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
@@ -47,10 +57,12 @@ 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.10.1 -- https://github.com/keithrbennett/rexe
+rexe -- Ruby Command Line Executor/Filter -- v0.10.2 -- https://github.com/keithrbennett/rexe
 
 Executes Ruby code on the command line, optionally taking standard input and writing to standard output.
 
+rexe [options] 'Ruby source code'
+
 Options:
 
 -c  --clear_options        Clear all previous command line options specified up to now
@@ -65,7 +77,7 @@ Options:
                              -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 
+                             -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 -v); see note (1) below
 -o, --output_format FORMAT Output format (puts is default):
                              -oi  Inspect
@@ -76,7 +88,7 @@ Options:
                              -op  Puts (default)
                              -os  to_s
                              -oy  YAML
--r, --require REQUIRES     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, or ! to clear
 -v, --[no-]verbose         verbose mode (logs to stderr); see note (1) below
 
 If there is an .rexerc file in your home directory, it will be run as Ruby code 
@@ -89,16 +101,6 @@ so that you can specify options implicitly (e.g. `export REXE_OPTIONS="-r awesom
 -v no, -v yes, -v false, -v true, -v n, -v y, -v +, but not -v -
 ```
 
-For consistency with the `ruby` interpreter we called previously, `rexe` supports requires with the `-r` option, but as one tiny improvement it also allows grouping them together using commas:
-
-```
-                                    vvvvvvvvvvvvvvvvvvvvv
-➜  ~   echo $EUR_RATES_JSON | rexe -r json,awesome_print 'ap JSON.parse(STDIN.read)'
-                                    ^^^^^^^^^^^^^^^^^^^^^
-```
-
-This command produces the same results as the previous `ruby` one.
-
 ### Simplifying the Rexe Invocation with Configuration
 
 `rexe` provides two approaches to configuration:
@@ -271,9 +273,12 @@ 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.).
   
-Be aware that 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 might be better off using Enumerator
-mode and calling `select`, `filter`, `reject`, etc.
+Be aware that 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 the `-on` _no output_ mode and call `puts` explicitly for the output you _do_ want
 
 
 #### -me "Enumerator" Filter Mode
@@ -299,23 +304,21 @@ 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)
-large string, with newline characters joining the lines in the string.
+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; you need to pass the entire (probably) multiline string to the parse method.
+A good example of when you would use this is when you parse JSON or YAML text; 
+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.
 
-An earlier example would be more simply specified using this mode, since `STDIN.read` could be replaced with `self`:
-
-```
-➜  ~   echo $EUR_RATES_JSON | rexe -mb -r awesome_print,json 'ap JSON.parse(self)'
-```
 
 #### -mn "No Input" Executor Mode -- The Default
 
-Examples up until this point have all used the default
-`-mn` mode. This is the simplest use case, where `self`
-does not evaluate to anything useful, and if you cared about standard
-input, you would have to code it yourself (e.g. as we did earlier with `STDIN.read`).
+In this mode, no special handling of standard input is done at all;
+if you want standard input you need to code it yourself (e.g. with `STDIN.read`).
+
+`self` evaluates to a new instance of `Object`, which would be used 
+if you defined methods, constants, instance variables, etc., in your code.
 
 
 #### Filter Input Mode Memory Considerations
@@ -325,9 +328,9 @@ 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: 
-** Make sure not to call any methods (e.g. `map`, `select`)
+  * 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
+  * use [lazy enumerators](https://www.honeybadger.io/blog/using-lazy-enumerators-to-work-with-large-files-in-ruby/)
  
 
 
@@ -396,7 +399,8 @@ so calls to your custom methods _look_ like built in language commands and keywo
 
 One complication of using utilities like `rexe` where Ruby code is specified on the shell 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. 
+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).
 
 Feel free to fall back on Ruby's super useful `%q{}` and `%Q{}`, equivalent to single and double quotes, respectively.
@@ -454,6 +458,70 @@ If I add `| pbcopy` to the rexe command, then that output text would be copied i
 displayed in the terminal, and I could then paste it in my editor.
 
 
+### 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:
+
+* 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
+
+
+### The Use of Semicolons
+
+You will probably find yourself using semicolons much more often than usual when you use `rexe`.
+Obviously you would need them to separate statements on the same line:
+
+```
+➜  ~   cowsay hello | rexe -me "print %Q{\u001b[33m}; puts to_a"
+```
+
+What might not be so obvious is that you _also_ need them if each statement is on its own line.
+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)
+...new { print %Q{\u001b[33m} 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:
+
+```
+➜  ~   cowsay hello | rexe -me "print %Q{\u001b[33m}; \
+puts to_a"
+
+eval_context_object: #<Enumerator:0x00007f92b1972840>
+ _______
+< hello >
+ -------
+        \   ^__^
+         \  (oo)\_______
+            (__)\       )\/\
+                ||----w |
+                ||     ||
+```
+
+
+### Comma Separated Requires and Loads
+
+For consistency with the `ruby` interpreter, `rexe` supports requires with the `-r` option, but 
+also allows grouping them together using commas:
+
+```
+                                    vvvvvvvvvvvvvvvvvvvvv
+➜  ~   echo $EUR_RATES_JSON | rexe -r json,awesome_print 'ap JSON.parse(STDIN.read)'
+                                    ^^^^^^^^^^^^^^^^^^^^^
+```
+
+Files loaded with the `-l` option are treated the same way.
+
 ### More Examples
 
 Here are some more examples to illustrate the use of `rexe`.
@@ -642,15 +710,20 @@ 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
-helpful with now?". However, the power of `rexe` is not so much what can be done
-with it in a single use case now, but rather what will it do for me as I get
-used to the concept and my supporting code and its uses evolve.
+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.
 
 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
+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 as organized as possible.
 
 #### Footnotes
 

data/exe/rexe

@@ -10,7 +10,7 @@ require 'shellwords'
 
 class Rexe < Struct.new(:input_format, :input_mode, :loads, :output_format, :requires, :verbose, :noop)
 
-  VERSION = '0.10.1'
+  VERSION = '0.10.2'
 
   def initialize
     clear_options
@@ -19,6 +19,7 @@ class Rexe < Struct.new(:input_format, :input_mode, :loads, :output_format, :req
 
   # Used as an initializer and also when `-!` is specified on the command line.
   def clear_options
+    self.input_format = :none
     self.input_mode = :no_input
     self.output_format = :puts
     self.loads = []
@@ -36,6 +37,8 @@ class Rexe < Struct.new(:input_format, :input_mode, :loads, :output_format, :req
 
     Executes Ruby code on the command line, optionally taking standard input and writing to standard output.
 
+    rexe [options] 'Ruby source code'
+
     Options:
 
     -c  --clear_options        Clear all previous command line options specified up to now
@@ -50,7 +53,7 @@ class Rexe < Struct.new(:input_format, :input_mode, :loads, :output_format, :req
                                  -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 
+                                 -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 -v); see note (1) below
     -o, --output_format FORMAT Output format (puts is default):
                                  -oi  Inspect
@@ -61,7 +64,7 @@ class Rexe < Struct.new(:input_format, :input_mode, :loads, :output_format, :req
                                  -op  Puts (default)
                                  -os  to_s
                                  -oy  YAML
-    -r, --require REQUIRES     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, or ! to clear
     -v, --[no-]verbose         verbose mode (logs to stderr); see note (1) below
 
     If there is an .rexerc file in your home directory, it will be run as Ruby code 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rexe
 version: !ruby/object:Gem::Version
-  version: 0.10.1
+  version: 0.10.2
 platform: ruby
 authors:
 - Keith Bennett