ruby-sh 2.1.4 → 3.0.0

data/README.md

@@ -1,12 +1,12 @@
-# Rubsh
+# Rubsh (a.k.a. ruby-sh)
 
 Rubsh (a.k.a. ruby-sh) - Inspired by [python-sh], allows you to call any program as if it were a function:
 
 ```ruby
 require 'rubsh'
 
-sh = Rubsh::Shell.new
-print(sh.cmd('ifconfig').call_with('wlan0').stdout_data)
+ifconfig = Rubsh.cmd('ifconfig')
+print(ifconfig.call('wlan0').stdout_data)
 ```
 
 Output:
@@ -27,40 +27,11 @@ Note that these aren't Ruby functions, these are running the binary commands on
 
 When using this library you can:
 
-* Call any program as if it were a function.
-* Get an exception when exit code is not 0.
-* Force terminate the process if it does not finish within the timeout.
-* Always split the shell command into tokens, reduce command injection risk.
-* etc.
-
-
-## Table of Contents
-
-* [Installation](#installation)
-* [Usage](#usage)
-  * [Basic Syntax](#basic-syntax)
-  * [Passing Arguments](#passing-arguments)
-  * [Exit Codes](#exit-codes)
-  * [Redirection](#redirection)
-  * [Incremental Iteration](#incremental-iteration)
-  * [Background Processes](#background-processes)
-  * [Baking](#baking)
-  * [Subcommands](#subcommands)
-  * [Piping](#piping)
-* [Reference](#reference)
-  * [Special Kwargs](#special-kwargs)
-* [FAQ](#faq)
-  * [Why doesn’t `*` work as a command argument?](#why-doesnt--work-as-a-command-argument)
-  * [How do I execute a bash builtin?](#how-do-i-execute-a-bash-builtin)
-  * [How do I call a program that isn’t in $PATH?](#how-do-i-call-a-program-that-isnt-in-path)
-  * [How do I run a command and connect it to stdout and stdin?](#how-do-i-run-a-command-and-connect-it-to-stdout-and-stdin)
-  * [How do I order keyword arguments?](#how-do-i-order-keyword-arguments)
-* [Development](#development)
-* [Contributing](#contributing)
-* [Acknowledgements](#acknowledgements)
-* [License](#license)
-* [Code Of Conduct](#code-of-conduct)
-
+- Call any program as if it were a function.
+- Get an exception when exit code is not 0.
+- Force terminate the process if it does not finish within the timeout.
+- Always split the shell command into tokens, reduce command injection risk.
+- etc.
 
 ## Installation
 
@@ -72,50 +43,50 @@ gem 'ruby-sh', require: 'rubsh'
 
 And then execute:
 
-    $ bundle install
+```console
+$ bundle install
+```
 
 Or install it yourself as:
 
-    $ gem install ruby-sh
-
+```console
+$ gem install ruby-sh
+```
 
 ## Usage
 
 ### Basic Syntax
 
 ```ruby
-# Create a shell
-sh = Rubsh::Shell.new
-
-# Create a command, use `command`/`cmd`
-cmd = sh.cmd("ls")
+# Create a command
+ls = Rubsh.cmd("ls")
 
-# Invoke a command, use `call`/`call_with`
-result = cmd.call_with("-la")
+# Invoke it
+r = ls.call("-la")
 
 # Print result
-print result.stdout_data
+print(r.stdout_data)
 ```
 
 ### Passing Arguments
 
 ```ruby
-sh.cmd("ls").call_with("-l", "/tmp", color: "always", human_readable: true)
+Rubsh.cmd("ls").call("-l", "/tmp", color: "always", human_readable: true)
   # => ["/usr/bin/ls", "-l", "/tmp", "--color=always", "--human-readable"]
 
-sh.cmd("curl").call_with("https://www.ruby-lang.org/", o: "page.html", silent: true)
+Rubsh.cmd("curl").call("https://www.ruby-lang.org/", o: "page.html", silent: true)
   # => ["/usr/bin/curl", "https://www.ruby-lang.org/", "-opage.html", "--silent"]
 
-sh.cmd("git").call(:status, { v: true })
+Rubsh.cmd("git").call(:status, { v: true })
   # => ["/usr/bin/git", "status", "-v"]
 
-sh.cmd("git").call(:status, { v: true }, "--", ".")
+Rubsh.cmd("git").call(:status, { v: true }, "--", ".")
   # => ["/usr/bin/git", "status", "-v", "--", "."]
 
-sh.cmd("git").call(:status, { v: proc{ true }, short: true }, "--", ".")
+Rubsh.cmd("git").call(:status, { v: proc{ true }, short: true }, "--", ".")
   # => ["/usr/bin/git", "status", "-v", "--short", "--", "."]
 
-sh.cmd("git").call(:status, { v: true }, v: false)
+Rubsh.cmd("git").call(:status, { v: true }, v: false)
   # => ["/usr/bin/git", "status"]
 ```
 
@@ -123,19 +94,19 @@ sh.cmd("git").call(:status, { v: true }, v: false)
 
 ```ruby
 # Successful
-r = sh.cmd("ls").call_with("/")
+r = Rubsh.cmd("ls").call("/")
 r.exit_code # => 0
 
 # a `CommandReturnFailureError` raised when run failure
 begin
-  sh.cmd("ls").call_with("/some/non-existant/folder")
+  Rubsh.cmd("ls").call("/some/non-existant/folder")
 rescue Rubsh::Exceptions::CommandReturnFailureError => e
   e.exit_code # => 2
 end
 
 # Treats as success use `:_ok_code`
-r = sh.cmd("ls").call_with("/some/non-existant/folder", _ok_code: [0, 1, 2])
-r = sh.cmd("ls").call_with("/some/non-existant/folder", _ok_code: 0..2)
+r = Rubsh.cmd("ls").call("/some/non-existant/folder", _ok_code: [0, 1, 2])
+r = Rubsh.cmd("ls").call("/some/non-existant/folder", _ok_code: 0..2)
 r.exit_code # => 2
 ```
 
@@ -143,29 +114,29 @@ r.exit_code # => 2
 
 ```ruby
 # Filename
-sh.cmd("ls").call_with(_out: "/tmp/dir_content")
-sh.cmd("ls").call_with(_out: ["/tmp/dir_content", "w"])
-sh.cmd("ls").call_with(_out: ["/tmp/dir_content", "w", 0600])
-sh.cmd("ls").call_with(_out: ["/tmp/dir_content", File::WRONLY|File::EXCL|File::CREAT, 0600])
+Rubsh.cmd("ls").call(_out: "/tmp/dir_content")
+Rubsh.cmd("ls").call(_out: ["/tmp/dir_content", "w"])
+Rubsh.cmd("ls").call(_out: ["/tmp/dir_content", "w", 0600])
+Rubsh.cmd("ls").call(_out: ["/tmp/dir_content", File::WRONLY|File::EXCL|File::CREAT, 0600])
 
 # File object
-File.open("/tmp/dir_content", "w") { |f| sh.cmd("ls").call_with(_out: f) }
+File.open("/tmp/dir_content", "w") { |f| Rubsh.cmd("ls").call(_out: f) }
 
 # `stdout_data` & `stderr_data`
-r = sh.cmd("sh").call_with("-c", "echo out; echo err >&2")
+r = Rubsh.cmd("sh").call("-c", "echo out; echo err >&2")
 r.stdout_data # => "out\n"
 r.stderr_data # => "err\n"
 
 # Redirects stderr and stderr to the same place use `_err_to_out`
-r = sh.cmd("sh").call_with("-c", "echo out; echo err >&2", _err_to_out: true)
+r = Rubsh.cmd("sh").call("-c", "echo out; echo err >&2", _err_to_out: true)
 r.stdout_data # => "out\nerr\n"
 r.stderr_data # => nil
 
 # Read input from data
-sh.cmd("cat").call_with(_in_data: "hello").stdout_data # => "hello"
+Rubsh.cmd("cat").call(_in_data: "hello").stdout_data # => "hello"
 
 # Read input from file
-sh.cmd("cat").call_with(_in: "/some/existant/file")
+Rubsh.cmd("cat").call(_in: "/some/existant/file")
 ```
 
 ### Incremental Iteration
@@ -174,9 +145,9 @@ sh.cmd("cat").call_with(_in: "/some/existant/file")
 # By default, output is line-buffered, so the body of the loop will only run
 # when your process produces a newline. You can change this by changing the
 # buffer size of the command’s output with `_out_bufsize`/`_err_bufsize`.
-tail = sh.cmd("tail")
-tail.call_with("-f", "/var/log/some_log_file.log", _capture: ->(stdout, _stderr) {
-  print stdout
+tail = Rubsh.cmd("tail")
+tail.call("-f", "/var/log/some_log_file.log", _capture: ->(stdout, _stderr) {
+  print(stdout)
 })
 ```
 
@@ -184,123 +155,112 @@ tail.call_with("-f", "/var/log/some_log_file.log", _capture: ->(stdout, _stderr)
 
 ```ruby
 # Blocks
-sh.cmd("sleep").call_with(3)
-p "...3 seconds later"
+Rubsh.cmd("sleep").call(3)
+print("...3 seconds later")
 
 # Doesn't block
-r = sh.cmd("sleep").call_with(3, _bg: true)
-p "prints immediately!"
+r = Rubsh.cmd("sleep").call(3, _bg: true)
+print("prints immediately!")
 r.wait()
-p "...and 3 seconds later"
+print("...and 3 seconds later")
 
 # Timeout
-r = sh.cmd("sleep").call_with(30, _bg: true)
-p "prints immediately!"
+r = Rubsh.cmd("sleep").call(30, _bg: true)
+print("prints immediately!")
 r.wait(timeout: 3)
-p "...and 3 seconds later"
+print("...and 3 seconds later")
 ```
 
 ### Baking
 
 ```ruby
-ll = sh.cmd("ls").bake("-l")
-ll.call_with("/tmp") # => ["/usr/bin/ls", "-l", "/tmp"]
+ll = Rubsh.cmd("ls").bake("-l")
+ll.call("/tmp") # => ["/usr/bin/ls", "-l", "/tmp"]
 
 # Equivalent
-sh.cmd("ls").call_with("-l", "/tmp")
+Rubsh.cmd("ls").call("-l", "/tmp")
 
 # Calling whoami on a server. this is a lot to type out, especially if you wanted
 # to call many commands (not just whoami) back to back on the same server resolves
 # to "/usr/bin/ssh myserver.com -p 1393 whoami"
-sh.cmd('ssh').call_with("myserver.com", "-p 1393", "whoami")
+Rubsh.cmd('ssh').call("myserver.com", "-p 1393", "whoami")
 
 # Wouldn't it be nice to bake the common parameters into the ssh command?
-myserver = sh.cmd('ssh').bake("myserver.com", p: 1393)
-myserver.call_with('whoami')
-myserver.call_with('pwd')
+myserver = Rubsh.cmd('ssh').bake("myserver.com", p: 1393)
+myserver.call('whoami')
+myserver.call('pwd')
+
+# With a special kwarg
+sleep = Rubsh.cmd('sleep').bake(_timeout: 2)
+sleep.call(1) # => ok
+sleep.call(3) # => a `CommandReturnFailureError` raised
 ```
 
 ### Subcommands
 
 ```ruby
 # Use `bake`
-gst = sh.cmd("git").bake("status")
+gst = Rubsh.cmd("git").bake("status")
 
-gst.call_with() # => ["/usr/bin/git", "status"]
-gst.call_with("-s") # => ["/usr/bin/git", "status", "-s"]
+gst.call() # => ["/usr/bin/git", "status"]
+gst.call("-s") # => ["/usr/bin/git", "status", "-s"]
 ```
 
-### Piping
-
-```ruby
-# Run a series of commands connected by `_pipeline`
-r = sh.pipeline(_in_data: "hello world") do |pipeline|
-  sh.cmd("cat").call_with(_pipeline: pipeline)
-  sh.cmd("wc").call_with("-c", _pipeline: pipeline)
-end
-r.stdout_data # => "11\n"
-```
-
-
 ## Reference
 
 ### Special Kwargs
 
-* `_in_data`:
-  * use: Specifies an argument for the process to use as its standard input data.
-  * default value: `nil`
-* `_in`:
-  * use: Specifies an argument for the process to use as its standard input.
-  * default value: `nil`
-* `_out`:
-  * use: Where to redirect STDOUT to.
-  * default value: `nil`
-* `_err`:
-  * use: Where to redirect STDERR to.
-  * default value: `nil`
-* `_err_to_out`:
-  * use: If true, duplicate the file descriptor bound to the process’s STDOUT also to STDERR.
-  * default value: `false`
-* `_capture`:
-  * use: Iterates over STDOUT/STDERR.
-  * default value: `nil`
-* `_bg`:
-  * use: Runs a command in the background. The command will return immediately, and you will have to run RunningCommand#wait on it to ensure it terminates.
-  * default value: `false`
-* `_timeout`:
-  * use: How much time, in seconds, we should give the process to complete. If the process does not finish within the timeout, it will be terminated.
-  * default value: `nil`
-* `_env`:
-  * use: A dictionary defining the only environment variables that will be made accessible to the process. If not specified, the calling process’s environment variables are used.
-  * default value: `nil`
-* `_cwd`:
-  * use: Current working directory of the process.
-  * default value: `nil`
-* `_ok_code`:
-  * use: Some misbehaved programs use exit codes other than 0 to indicate success. Set to treats as success.
-  * default value: `[0]`
-* `_no_out`:
-  * use: Disables STDOUT being internally stored. This is useful for commands that produce huge amounts of output that you don’t need, that would otherwise be hogging memory if stored internally by Rubsh.
-  * default value: `false`
-* `_no_err`:
-  * use: Disables STDERR being internally stored. This is useful for commands that produce huge amounts of output that you don’t need, that would otherwise be hogging memory if stored internally by Rubsh.
-  * default value: `false`
-* `_out_bufsize`:
-  * use: The STDOUT buffer size. nil for unbuffered, 0 for line buffered, anything else for a buffer of that amount.
-  * default value: `0`
-* `_err_bufsize`:
-  * use: The STDERR buffer size. nil for unbuffered, 0 for line buffered, anything else for a buffer of that amount.
-  * default value: `0`
-* `_long_sep`:
-  * use: This is the character(s) that separate a program’s long argument’s key from the value.
-  * default value: `"="`
-* `_long_prefix`:
-  * use: This is the character(s) that prefix a long argument for the program being run. Some programs use single dashes, for example, and do not understand double dashes.
-  * default value: `"--"`
-* `_pipeline`:
-  * use: Specifies the :pipeline.
-  * default value: `nil`
-
+- `_in_data`:
+  - use: Specifies an argument for the process to use as its standard input data.
+  - default value: `nil`
+- `_in`:
+  - use: Specifies an argument for the process to use as its standard input.
+  - default value: `nil`
+- `_out`:
+  - use: Where to redirect STDOUT to.
+  - default value: `nil`
+- `_err`:
+  - use: Where to redirect STDERR to.
+  - default value: `nil`
+- `_err_to_out`:
+  - use: If true, duplicate the file descriptor bound to the process’s STDOUT also to STDERR.
+  - default value: `false`
+- `_capture`:
+  - use: Iterates over STDOUT/STDERR.
+  - default value: `nil`
+- `_bg`:
+  - use: Runs a command in the background. The command will return immediately, and you will have to run RunningCommand#wait on it to ensure it terminates.
+  - default value: `false`
+- `_timeout`:
+  - use: How much time, in seconds, we should give the process to complete. If the process does not finish within the timeout, it will be terminated.
+  - default value: `nil`
+- `_env`:
+  - use: A dictionary defining the only environment variables that will be made accessible to the process. If not specified, the calling process’s environment variables are used.
+  - default value: `nil`
+- `_cwd`:
+  - use: Current working directory of the process.
+  - default value: `nil`
+- `_ok_code`:
+  - use: Some misbehaved programs use exit codes other than 0 to indicate success. Set to treats as success.
+  - default value: `[0]`
+- `_no_out`:
+  - use: Disables STDOUT being internally stored. This is useful for commands that produce huge amounts of output that you don’t need, that would otherwise be hogging memory if stored internally by Rubsh.
+  - default value: `false`
+- `_no_err`:
+  - use: Disables STDERR being internally stored. This is useful for commands that produce huge amounts of output that you don’t need, that would otherwise be hogging memory if stored internally by Rubsh.
+  - default value: `false`
+- `_out_bufsize`:
+  - use: The STDOUT buffer size. nil for unbuffered, 0 for line buffered, anything else for a buffer of that amount.
+  - default value: `0`
+- `_err_bufsize`:
+  - use: The STDERR buffer size. nil for unbuffered, 0 for line buffered, anything else for a buffer of that amount.
+  - default value: `0`
+- `_long_sep`:
+  - use: This is the character(s) that separate a program’s long argument’s key from the value.
+  - default value: `"="`
+- `_long_prefix`:
+  - use: This is the character(s) that prefix a long argument for the program being run. Some programs use single dashes, for example, and do not understand double dashes.
+  - default value: `"--"`
 
 ## FAQ
 
@@ -311,9 +271,8 @@ Glob expansion is a feature of a shell, like Bash, and is performed by the shell
 ### How do I execute a bash builtin?
 
 ```ruby
-sh = Rubsh::Shell.new
-rawsh = sh.cmd('bash').bake('-c')
-print(rawsh.call_with('echo Hello').stdout_data) # => "Hello\n"
+rawsh = Rubsh.cmd('bash').bake('-c')
+print(rawsh.call('echo Hello').stdout_data) # => "Hello\n"
 ```
 
 ### How do I call a program that isn’t in $PATH?
@@ -321,16 +280,7 @@ print(rawsh.call_with('echo Hello').stdout_data) # => "Hello\n"
 Use absolute binpath
 
 ```ruby
-sh = Rubsh::Shell.new
-sh.cmd('/path/to/command').call()
-```
-
-OR Use `Rubsh::Shell::Env#path`
-
-```ruby
-sh = Rubsh::Shell.new
-sh.env.path << "/dir/to/command/"
-sh.cmd('command').call()
+Rubsh.cmd('/path/to/command').call()
 ```
 
 ### How do I run a command and connect it to stdout and stdin?
@@ -348,36 +298,29 @@ my-command --arg1=val1 arg2 --arg3=val3
 Use:
 
 ```ruby
-sh = Rubsh::Shell.new
-sh.cmd('my-command').call_with({ arg1: "val1" }, "args2", { arg3: "val3" })
+Rubsh.cmd('my-command').call({ arg1: "val1" }, "args2", { arg3: "val3" })
 ```
 
-
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/rspec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
-
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/souk4711/rubsh. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/souk4711/rubsh/blob/main/CODE_OF_CONDUCT.md).
 
-
 ## Acknowledgements
 
-* Special thanks to [python-sh].
-
+- Special thanks to [python-sh].
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
-
 ## Code of Conduct
 
 Everyone interacting in the Rubsh project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/souk4711/rubsh/blob/main/CODE_OF_CONDUCT.md).
 
-
-[python-sh]:https://github.com/amoffat/sh
+[python-sh]: https://github.com/amoffat/sh

data/Rakefile

@@ -1,12 +1,11 @@
 # frozen_string_literal: true
 
 require "bundler/gem_tasks"
-require "rspec/core/rake_task"
-
-RSpec::Core::RakeTask.new(:spec)
 
 require "rubocop/rake_task"
-
 RuboCop::RakeTask.new
 
-task default: %i[spec rubocop]
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new(:spec)
+
+task default: %i[rubocop spec]

data/lib/rubsh/command.rb

@@ -6,8 +6,7 @@ module Rubsh
   # When a Command object is called, the result that is returned is a RunningCommand
   # object, which represents the Command put into an execution state.
   class Command
-    def initialize(sh, prog)
-      @sh = sh
+    def initialize(prog)
       @prog = prog.to_s
       @progpath = resolve_progpath(@prog)
       @baked_opts = []
@@ -18,8 +17,7 @@ module Rubsh
     # @return [RunningCommand] An new instance of RunningCommand with execution state.
     # @example
     #
-    #   sh = Rubsh::Shell.new
-    #   git = Rubsh::Command.new(sh, "git")
+    #   git = Rubsh::Command.new("git")
     #   git.call()                                  # => ["git"]
     #   git.call("")                                # => ["git", ""]
     #   git.call("status")                          # => ["git", "status"]
@@ -30,24 +28,23 @@ module Rubsh
     #   git.call(:status, { v: proc{ true }, short: true }, "--", ".")  # => ["git", "status", "-v", "--short=true", "--", "."]
     #   git.call(:status, { untracked_files: "normal" }, "--", ".")     # => ["git", "status", "--untracked-files=normal", "--", "."]
     def call(*args, **kwargs)
-      rcmd = RunningCommand.new(@sh, @prog, @progpath, *@baked_opts, *args, **kwargs)
+      rcmd = RunningCommand.new(@prog, @progpath, *@baked_opts, *args, **kwargs)
       rcmd.__run
       rcmd
     end
-    alias_method :call_with, :call
 
     # @param args [String, Symbol, #to_s, Hash]
     # @param kwargs [Hash]
     # @return [Command] a new instance of Command with baked options.
     def bake(*args, **kwargs)
-      cmd = Command.new(@sh, @prog)
+      cmd = Command.new(@prog)
       cmd.__bake!(*@baked_opts, *args, **kwargs)
       cmd
     end
 
     # @return [String]
-    def inspect
-      format("#<Rubsh::Command '%s'>", @progpath)
+    def to_s
+      @progpath
     end
 
     # @!visibility private
@@ -70,7 +67,7 @@ module Rubsh
           progpath = prog
         end
       else
-        @sh.env.path.each do |path|
+        ::ENV["PATH"].split(::File::PATH_SEPARATOR).each do |path|
           filepath = ::File.join(path, prog)
           if ::File.executable?(filepath) && ::File.file?(filepath)
             progpath = filepath