rexe 0.0.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 89d0c2488db063c926dcbdcc71311538e0aa6a6cea5508174adbb251b1583cd0
-  data.tar.gz: 86f099c8ef308584df094492a5e64765e3b26d3d7fc872442ec05e7963f578b0
+  metadata.gz: facbd7a97a0fba70fb40170f61f53a127b6cb1ec05d44aed85a653a97b711d88
+  data.tar.gz: f742717a826d26f719485bf7cb562e598d1c3130ca3abe4065c2bd1bc90c34c0
 SHA512:
-  metadata.gz: 8fd605f513730ec939e57a6ccc0c3b21974af416f6c0c7c1bcb033a9ed421375eecb55a6a871017dac2cffa2edc6c150c018e3532f88725bbff31505efdd59dc
-  data.tar.gz: 2cd444bb1b7300ac7d41238335c5c62432584b13474f87f3134f3bcd06be6d5304c81a69bbe9b278a249283fd932fa07cc2d11d8bacc18d6044a03c6fdc39b6d
+  metadata.gz: 819cf812598dfb9612310a71c4b9bb5c8fa00442e16650b9cb8441b2e21a36e39a9e1ead336ca4be9451edf26edf9599f14b1c75ac5935fd069535118f5d78c2
+  data.tar.gz: fe8998aab47ae22b8082439305b28f719296117f183cf49e632ecfe6192cb02bcc99a2536ba9b7b37361642c27619c0cff7d92bae14cd5a8f2a0017369aaab6d

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 ## rexe -- Ruby Command Line Executor
 
+
+### v0.2.0
+
+* Improve README and verbose logging.
+
+### v0.1.0
+
+* Add ability to handle input as a single multiline string (using -mb option).
+* Add -mn mode for no input at all.
+* Fix and improve usage examples in README.
+
+
+### v0.0.2
+
+* Fix running-as-script test.
+
+
 ### v0.0.1
 
 * Initial version.

data/README.md

@@ -1,5 +1,8 @@
 # Rexe
 
+A configurable Ruby command line filter/executor.
+
+
 
 ## Installation
 
@@ -16,85 +19,194 @@ chmod +x rexe
 
 ## Usage
 
+rexe is a _filter_ in that it can consume standard input and emit standard output; but it is also an _executor_, meaning it can be used without either standard input or output.
+
+### Help Text
+
+As a summary, here is the help text printed out by the application:
+
 ```
 
-rexe -- Ruby Command Line Filter -- v0.0.1 -- https://github.com/keithrbennett/rexe
 
-Takes standard input and runs the specified code on it, sending the result to standard output.
-Your Ruby code can operate on each line individually (-ms) (the default),
-or operate on the enumerator of all lines (-me). If the latter, you will probably need to
-call chomp on the lines yourself to remove the trailing newlines.
+rexe -- Ruby Command Line Filter -- v1.1.0 -- https://github.com/keithrbennett/rexe
+
+Optionally takes standard input and runs the specified code on it, sending the result to standard output.
 
 Options:
 
 -h, --help               Print help and exit
--m, --mode MODE          Mode with which to handle input, (-ms for string (default), -me for enumerator)
+-l, --load A_RUBY_FILE   Load this Ruby source code file
+-m, --mode MODE          Mode with which to handle input (i.e. what `self` will be in the code):
+                           -ms for each line to be handled separately as a string (default)
+                           -me for an enumerator of lines (least memory consumption for big data)
+                           -mb for 1 big string (all lines combined into single multiline string)
+                           -mn to execute the specified Ruby code on no input at all 
 -r, --require REQUIRES   Gems and built-in libraries (e.g. shellwords, yaml) to require, comma separated
 -v, --[no-]verbose       Verbose mode, writes to stderr
 
-If there is an .rexerc file in your home directory, it will be run as Ruby code before processing the input.
+If there is an .rexerc file in your home directory, it will be run as Ruby code 
+before processing the input.
 
 If there is an 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"`)
 
 ```
-## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+### Input Mode
+
+When it is used as a filter, the input is accessed differently in the source code depending on the mode that was specified (see example section below for examples). The mode letter is appended to `-m` on the command line; `s` (_string_) mode is the default.
+
+* `s` - _string_ mode - the source code is run once on each line of input, and `self` is each line of text
+* `e` - _enumerator_ mode - the code is run once on the enumerator of all lines; `self` is the enumerator, so you can call `map`, `to_a`, `select`, etc without explicitly specifying `self`.
+* `b` - _big string_ mode - all input is treated as one large (probably) multiline string with the newlines intact; `self` is this large string; this mode is required, for example, for parsing the text into a single object from JSON or YAML formatted data.
+* `n` - _no input_ mode - this instructs the program to proceed without looking for input
+
+
+### Requires
+
+As with the Ruby interpreter itself, `require`s can be specified on the command line with the `-r` option. Multiple requires can be combined with commas between them.
+
+
+### Loading Ruby Files
+
+Other Ruby files can be loaded by `rexe`, to, for example, define classes and methods to use, set up resources, etc. They are specified with the `-l` option.
+
+If there is a file named `.rexerc` in the home directory, that will always be loaded without explicitly requesting it on the command line.
+
+
+### Verbose Mode
+
+Verbose mode outputs information to standard error (stderr). This information can be redirected, for example to a file named `rexe.log`, by adding `2>& rexe.log` to the command line.
+
+Here is an example of some text that might be output in verbose mode:
+
+```
+rexe version 1.1.0 -- 2019-02-04 21:50:34 +0700
+Source Code: sort.to_a.first(3).ai
+Requiring awesome_print
+Loading global config file /Users/kbennett/.rexerc
+```
+
+### The REXE_OPTIONS Environment Variable
+
+Very often you will want to call `rexe` several times with similar options. Instead of having to clutter the command line each time with these options, you can put them in an environment variable named `REXE_OPTIONS`, and they will be prepended automatically. Since they will be processed before the options on the command line, they are of lower precedence and can be overridden.
+
 
+## Troubleshooting
+
+One common problem relates to the shell's special handling of characters. Remember that the shell will process special characters, thereby changing your text before passing it on to the Ruby code. It is good to get in the habit of putting your source code in double quotes; and if the source code itself uses quotes, use `q{}` or `Q{}` instead. For example:
+
+```
+➜   rexe -mn "puts %Q{The time is now #{Time.now}}"
+The time is now 2019-02-04 18:49:31 +0700
+```
+
+If you are troubleshooting the setup (i.e. the command line options, loaded files, and `REXE_OPTIONS` environment variable) using the verbose option, you may have the problem of the logging scrolling off the screen due to the length of your output. In this case you could easily fake or disable the output adding `; nil`, `; 'foo'`', etc. to the end of your expression. This way you don't have to mess with your code's logic.
 
 ## Examples
 
 ```
-➜  rexe git:(master) ✗   ls | exe/rexe "map(&:reverse).to_s"
-["\nelifmeG", "\ntxt.ESNECIL", "\ndm.EMDAER", "\nelifekaR", "\nnib", "\nexe", "\nbil", "\ncepsmeg.cbr", "\nceps"]
+# Call reverse on listed file.
+# No need to specify the mode, since it defaults to "s" ("-ms"),
+# which treats every line separately.
+➜  rexe git:(master) ✗   ls | head -2 | exe/rexe "self + ' --> ' + reverse"
+CHANGELOG.md --> dm.GOLEGNAHC
+Gemfile --> elifmeG
 
-➜  rexe git:(master) ✗   uptime | exe/rexe -l split.first
-20:51
+----
 
+# Use input data to create a human friendly message:
+➜  ~   uptime | rexe "%Q{System has been up: #{split.first}.}"
+System has been up: 17:10.
 
-➜  rexe git:(master) ✗   ls | exe/rexe -r json "to_a.to_json"
-["Gemfile\n","LICENSE.txt\n","README.md\n","Rakefile\n","bin\n","exe\n","lib\n","rexe.gemspec\n","spec\n"]
+----
 
+# Create a JSON array of a file listing.
+# Use the "-me" flag so that all input is treated as a single enumerator of lines.
+➜  /etc   ls | head -3 | rexe -me -r json "map(&:strip).to_a.to_json"
+["AFP.conf","afpovertcp.cfg","afpovertcp.cfg~orig"]
 
-➜  rexe git:(master) ✗   ls | exe/rexe -r yaml "map(&:chomp).to_a.to_yaml"
----
-- Gemfile
-- LICENSE.txt
-- README.md
-- Rakefile
-- bin
-- exe
-- lib
-- rexe.gemspec
-- spec
+----
 
+# Create a "pretty" JSON array of a file listing:
+➜  /etc   ls | head -3 | rexe -me -r json "JSON.pretty_generate(map(&:strip).to_a)"
+[
+  "AFP.conf",
+  "afpovertcp.cfg",
+  "afpovertcp.cfg~orig"
+]
 
-➜  rexe git:(master) ✗   export REXE_OPTIONS="-r yaml,awesome_print"
+----
 
-➜  rexe git:(master) ✗   ls | exe/rexe "map(&:chomp).to_a.to_yaml"
+# Create a YAML array of a file listing:
+➜  /etc   ls | head -3 | rexe -me -r yaml "map(&:strip).to_a.to_yaml"
 ---
-- Gemfile
-- LICENSE.txt
-- README.md
-- Rakefile
-- bin
-- exe
-- lib
-- rexe.gemspec
-- spec
-
-➜  rexe git:(master) ✗   ls | exe/rexe "map(&:chomp).to_a.ai"
+- AFP.conf
+- afpovertcp.cfg
+- afpovertcp.cfg~orig
+
+----
+
+# Use AwesomePrint to print a file listing.
+# (Rather than calling the `ap` method on the object to print, 
+# call the `ai` method _on_ the object to print:
+➜  /etc   ls | head -3 | rexe -me -r awesome_print "map(&:chomp).ai"
 [
-    [0] "Gemfile",
-    [1] "LICENSE.txt",
-    [2] "README.md",
-    [3] "Rakefile",
-    [4] "bin",
-    [5] "exe",
-    [6] "lib",
-    [7] "rexe.gemspec",
-    [8] "spec"
+    [0] "AFP.conf",
+    [1] "afpovertcp.cfg",
+    [2] "afpovertcp.cfg~orig"
 ]
 
-```
+----
+
+# Don't use input at all, so use "-mn" to tell rexe not to expect input.
+➜  /etc   rexe -mn "%Q{The time is now #{Time.now}}"
+The time is now 2019-02-04 17:20:03 +0700
+
+----
+
+# Use REXE_OPTIONS environment variable to eliminate the need to specify
+# options on each invocation:
+
+# First it will fail since these symbols have not been loaded via require:
+➜  /etc   rexe -mn "[JSON, YAML, AwesomePrint]"
+Traceback (most recent call last):
+...
+(eval):1:in `block in call': uninitialized constant Rexe::JSON (NameError)
+
+# Now we specify the requires in the REXE_OPTIONS environment variable.
+# Contents of this variable will be prepended to the arguments
+# specified on the command line.
+➜  /etc   export REXE_OPTIONS="-r json,yaml,awesome_print"
+
+# Now that command that previously failed will succeed:
+➜  /etc   rexe -mn "[JSON, YAML, AwesomePrint].to_s"
+[JSON, Psych, AwesomePrint]
+
+----
+
+Access public JSON data and print it with awesome_print:
+
+➜  /etc   curl https://data.lacity.org/api/views/nxs9-385f/rows.json\?accessType\=DOWNLOAD \
+ | rexe -mb -r awesome_print,json "JSON.parse(self).ai"
+ {
+     "meta" => {
+         "view" => {
+                                   "id" => "nxs9-385f",
+                                 "name" => "2010 Census Populations by Zip Code",
+...
+
+----
+
+# Print the environment variables, sorted, with Awesome Print:
+➜  /etc   env | rexe -me -r awesome_print sort.to_a.ai
+[
+...
+    [ 4] "COLORFGBG=15;0\n",
+    [ 5] "COLORTERM=truecolor\n",
+...    
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/exe/rexe

@@ -1,20 +1,21 @@
 #!/usr/bin/env ruby
 #
-# rexe - Ruby Command Line Filter
+# rexe - Ruby Command Line Executor Filter
 #
 # Inspired by https://github.com/thisredone/rb
-#
+
 
 require 'optparse'
 require 'shellwords'
 
+# Rexe - Ruby Executor
+class Rexe < Struct.new(:input_mode, :loads, :requires, :verbose)
 
-class Rexe < Struct.new(:line_mode, :requires, :verbose)
-
-  VERSION = '0.0.1'
+  VERSION = '0.2.0'
 
   def initialize
-    self.line_mode = :string
+    self.input_mode = :string
+    self.loads = []
     self.requires = []
     self.verbose = false
   end
@@ -25,19 +26,22 @@ class Rexe < Struct.new(:line_mode, :requires, :verbose)
 
     rexe -- Ruby Command Line Filter -- v#{VERSION} -- https://github.com/keithrbennett/rexe
 
-    Takes standard input and runs the specified code on it, sending the result to standard output.
-    Your Ruby code can operate on each line individually (-ms) (the default),
-    or operate on the enumerator of all lines (-me). If the latter, you will probably need to
-    call chomp on the lines yourself to remove the trailing newlines.
+    Optionally takes standard input and runs the specified code on it, sending the result to standard output.
 
     Options:
 
     -h, --help               Print help and exit
-    -m, --mode MODE          Mode with which to handle input, (-ms for string (default), -me for enumerator)
+    -l, --load A_RUBY_FILE   Load this Ruby source code file
+    -m, --mode MODE          Mode with which to handle input (i.e. what `self` will be in the code):
+                               -ms for each line to be handled separately as a string (default)
+                               -me for an enumerator of lines (least memory consumption for big data)
+                               -mb for 1 big string (all lines combined into single multiline string)
+                               -mn to execute the specified Ruby code on no input at all 
     -r, --require REQUIRES   Gems and built-in libraries (e.g. shellwords, yaml) to require, comma separated
     -v, --[no-]verbose       Verbose mode, writes to stderr
 
-    If there is an .rexerc file in your home directory, it will be run as Ruby code before processing the input.
+    If there is an .rexerc file in your home directory, it will be run as Ruby code 
+    before processing the input.
 
     If there is an 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"`)
@@ -65,17 +69,25 @@ class Rexe < Struct.new(:line_mode, :requires, :verbose)
         exit
       end
 
+      parser.on('-l', '--load RUBY_FILE', 'Loads and runs this Ruby file') do |v|
+        self.loads << v
+      end
+
       parser.on('-m', '--mode MODE',
                 'Mode with which to handle input (-ms for string (default), -me for enumerator)') do |v|
-        self.line_mode = case v
-                         when 's'
-                           self.line_mode = :string
-                         when 'e'
-                           self.line_mode = :enumerator
-                         else
-                           puts "Mode must be either 's' for string or 'e' for enumerator"
-                           exit -1
-                         end
+
+        modes = {
+            's' => :string,
+            'e' => :enumerator,
+            'b' => :one_big_string,
+            'n' => :no_input
+        }
+
+        self.input_mode = modes[v]
+        if self.input_mode.nil?
+          puts help_text
+          raise "Input mode must be one of #{modes.keys}."
+        end
       end
 
       parser.on('-r', '--require REQUIRES', 'Gems and modules to require, comma separated') do |v|
@@ -92,13 +104,20 @@ class Rexe < Struct.new(:line_mode, :requires, :verbose)
   def load_global_config_if_exists
     filespec = File.join(Dir.home, '.rexerc')
     exists = File.exists?(filespec)
-    load(filespec) if exists
+    if exists
+      log_if_verbose("Loading global config file #{filespec}")
+      load(filespec)
+    end
     exists ? filespec : nil
   end
 
 
-  def execute(line_or_enumerator, code)
-    puts line_or_enumerator.instance_eval(&code)
+  def execute(eval_context_object, code)
+    if eval_context_object
+      puts eval_context_object.instance_eval(&code)
+    else
+      puts code.call
+    end
   rescue Errno::EPIPE
     exit(-13)
   end
@@ -110,21 +129,46 @@ class Rexe < Struct.new(:line_mode, :requires, :verbose)
 
 
   def call
+    start_time = Time.now
+
     parse_command_line
 
-    log_if_verbose("Requiring #{requires}") if requires.any?
-    requires.each { |r| require r }
+    log_if_verbose("rexe version #{VERSION} -- #{Time.now}")
+    log_if_verbose('Source Code: ' + ARGV.join(' '))
 
-    filespec = load_global_config_if_exists
-    log_if_verbose("Loaded #{filespec}") if filespec
+    requires.each do |r|
+      log_if_verbose("Requiring #{r}")
+      require(r)
+    end
+
+    load_global_config_if_exists
+
+    loads.each do |file|
+      log_if_verbose("Loading #{file}")
+      load(file)
+    end
 
     source_code = "Proc.new { #{ARGV.join(' ')} }"
-    log_if_verbose("Source code: #{source_code}")
     code = eval(source_code)
 
-    (line_mode == :string) ? STDIN.each { |l| execute(l.chomp, code) } : execute(STDIN.each_line, code)
+
+    actions = {
+        string:         -> { STDIN.each { |l| execute(l.chomp, code) } },
+        enumerator:     -> { execute(STDIN.each_line, code) },
+        one_big_string: -> { big_string = STDIN.each_line.to_a.join; execute(big_string, code) },
+        no_input:       -> { execute(nil, code) }
+    }
+
+    actions[input_mode].()
+
+    duration = Time.now - start_time
+    log_if_verbose("rexe time elapsed: #{duration} seconds.")
   end
 end
 
-Rexe.new.call if $0 == __FILE__
+# This is needed because the gemspec file loads this file to access Rexe::VERSION
+# and must not have it run at that time:
+called_as_script = (File.basename($0) == File.basename(__FILE__))
+Rexe.new.call if called_as_script
+
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rexe
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Keith Bennett
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-02-03 00:00:00.000000000 Z
+date: 2019-02-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -97,7 +97,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.1
+rubygems_version: 3.0.2
 signing_key: 
 specification_version: 4
 summary: Ruby Command Line Executor