tty-command 0.7.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: fb721a5620ec91bddc77643358783a38fb76631f
-  data.tar.gz: b0f3485e21f80e9172d1651eb661360fb3972d6f
+SHA256:
+  metadata.gz: efe5adcd3fe993ed0b35a1d640b77e50d42611e4c87efd296656c82680bbe19e
+  data.tar.gz: 91276213aee2b1a56b3b983e3779d47da9c2de4b2f16fd9fa1603173d12ec522
 SHA512:
-  metadata.gz: 3184987586dff4f957bbeee34cf0811f60c10db0f533fe48e957f171a3a1b22485f1e4970a7b4867466deb73ad95e9b3ae30c4194753724471756aece30446de
-  data.tar.gz: 1500b854c1a69a788e49226d28403f92ee28258b608939596e1da92296ff815623ef70885e0c54751e3a8769539fc5f6c8dfd973f69c43c87f112cbf575707ce
+  metadata.gz: 3d3159b1a53f1649a220c6cd41f00fe8c9621c26460715d2352c1ff010c84de2f8ced1a06ce4de998da16f43a9d254429b37f825a370059dad1828b820c28060
+  data.tar.gz: '094d9b3afbc63cb7b94888873e602badf0dc2dd6dee3c2a13c79d2865ee7c1270f52136df5472c9c080f1f157778808033ffe3a4989b72cba6dbcf5d83d57c3c'

data/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Change log
 
+## [v0.10.0] - 2020-10-22
+
+### Changed
+* Change :chdir option to escape directory location path
+* Change gemspec to add metadata and remove test artefacts
+* Change to update pastel dependency and restrict version to minor only
+* Remove bundler as a dev dependency and relax rspec's upper boundary
+
+### Fixed
+* Fix Ruby 2.7 keyword conversion errors
+* Fix error when environment variable contains % character
+
+## [v0.9.0] - 2019-09-28
+
+### Changed
+* Change gemspec to require Ruby >= 2.0.0
+
+## [v0.8.2] - 2018-08-07
+
+### Changed
+* Change gemspec to load only required files
+
+### Fixed
+* Fix issue with Ruby greater than 2.5.0 displaying thread error traceback by default
+
+## [v0.8.1] - 2018-05-20
+
+### Changed
+* Change ProcessRunner#write_stream to handle all writing logic
+
+## [v0.8.0] - 2018-04-22
+
+### Added
+* Add :output_only_on_error option by Iulian Onofrei(@revolter)
+* Add :verbose flag to toggle warnings
+
+### Changed
+* Change ProcessRunner to use waitpid2 api for direct status
+* Change ProcessRunner stdout & stderr reading to use IO.select and be non-blocking
+
+### Fixed
+* Fix :timeout to raise when long running without input or output
+* Fix ProcessRunner to ensure no zombie processes on timeouts
+
 ## [v0.7.0] - 2017-11-19
 
 ### Added
@@ -96,6 +140,11 @@
 
 * Initial implementation and release
 
+[v0.10.0]: https://github.com/piotrmurach/tty-command/compare/v0.9.0...v0.10.0
+[v0.9.0]: https://github.com/piotrmurach/tty-command/compare/v0.8.2...v0.9.0
+[v0.8.2]: https://github.com/piotrmurach/tty-command/compare/v0.8.1...v0.8.2
+[v0.8.1]: https://github.com/piotrmurach/tty-command/compare/v0.8.0...v0.8.1
+[v0.8.0]: https://github.com/piotrmurach/tty-command/compare/v0.7.0...v0.8.0
 [v0.7.0]: https://github.com/piotrmurach/tty-command/compare/v0.6.0...v0.7.0
 [v0.6.0]: https://github.com/piotrmurach/tty-command/compare/v0.5.0...v0.6.0
 [v0.5.0]: https://github.com/piotrmurach/tty-command/compare/v0.4.0...v0.5.0

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2016 Piotr Murach
+Copyright (c) 2016 Piotr Murach (https://piotrmurach.com)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,3 +1,7 @@
+<div align="center">
+  <a href="https://ttytoolkit.org"><img width="130" src="https://github.com/piotrmurach/tty/blob/master/images/tty.png" alt="TTY Toolkit logo"/></a>
+</div>
+
 # TTY::Command [![Gitter](https://badges.gitter.im/Join%20Chat.svg)][gitter]
 
 [![Gem Version](https://badge.fury.io/rb/tty-command.svg)][gem]
@@ -32,7 +36,7 @@ Why should we be handcuffed to `sh` or `bash` for these scripts when we could be
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'tty-command'
+gem "tty-command"
 ```
 
 And then execute:
@@ -52,6 +56,8 @@ Or install it yourself as:
   * [2.3. Logging](#23-logging)
     * [2.3.1. Color](#231-color)
     * [2.3.2. UUID](#232-uuid)
+    * [2.3.3. Only output on error](#233-only-output-on-error)
+    * [2.3.4. Verbose](#234-verbose)
   * [2.4. Dry run](#24-dry-run)
   * [2.5. Wait](#25-wait)
   * [2.6. Test](#26-test)
@@ -82,9 +88,11 @@ Or install it yourself as:
 Create a command instance and then run some commands:
 
 ```ruby
+require "tty-command"
+
 cmd = TTY::Command.new
-cmd.run('ls -la')
-cmd.run('echo Hello!')
+cmd.run("ls -la")
+cmd.run("echo Hello!")
 ```
 
 Note that `run` will throw an exception if the command fails. This is already an improvement over ordinary shell scripts, which just keep on going when things go bad. That usually makes things worse.
@@ -92,7 +100,7 @@ Note that `run` will throw an exception if the command fails. This is already an
 You can use the return value to capture stdout and stderr:
 
 ```ruby
-out, err = cmd.run('cat ~/.bashrc | grep alias')
+out, err = cmd.run("cat ~/.bashrc | grep alias")
 ```
 
 Instead of using a plain old string, you can break up the arguments and they'll get escaped if necessary:
@@ -119,13 +127,13 @@ The `env`, `command` and `options` arguments are described in the following sect
 For example, to display file contents:
 
 ```ruby
-cmd.run('cat file.txt')
+cmd.run("cat file.txt")
 ```
 
 If the command succeeds, a `TTY::Command::Result` is returned that records stdout and stderr:
 
 ```ruby
-out, err = cmd.run('date')
+out, err = cmd.run("date")
 puts "The date is #{out}"
 # => "The date is Tue 10 May 2016 22:30:15 BST\n"
 ```
@@ -133,7 +141,7 @@ puts "The date is #{out}"
 You can also pass a block that gets invoked anytime stdout and/or stderr receive output:
 
 ```ruby
-cmd.run('long running script') do |out, err|
+cmd.run("long running script") do |out, err|
   output << out if out
   errors << err if err
 end
@@ -153,8 +161,8 @@ If the error output is very long, the stderr may contain only a prefix, number o
 If you expect a command to fail occasionally, use `run!` instead. Then you can detect failures and respond appropriately. For example:
 
 ```ruby
-if cmd.run!('which xyzzy').failure?
-  cmd.run('brew install xyzzy')
+if cmd.run!("which xyzzy").failure?
+  cmd.run("brew install xyzzy")
 end
 ```
 
@@ -176,7 +184,7 @@ cmd = TTY::Command.new(printer: :progress)
 By default the printers log to `stdout` but this can be changed by passing an object that responds to `<<` message:
 
 ```ruby
-logger = Logger.new('dev.log')
+logger = Logger.new("dev.log")
 cmd = TTY::Command.new(output: logger)
 ```
 
@@ -186,18 +194,75 @@ You can force the printer to always in print in color by passing the `:color` op
 cmd = TTY::Command.new(color: true)
 ```
 
+If the default printers don't meet your needs you can always create [a custom printer](#34-custom-printer)
+
 #### 2.3.1 Color
 
-When using printers you can switch off coloring by using `color` option set to `false`.
+When using printers you can switch off coloring by using `:color` option set to `false`.
+
+#### 2.3.2 UUID
+
+By default, when logging is enabled and `pretty` printer is used, each log entry is prefixed by specific command run uuid number. This number can be switched off using the `:uuid` option at initialization:
+
+```ruby
+cmd = TTY::Command.new(uuid: false)
+cmd.run("rm -R all_my_files")
+# =>
+#  Running rm -r all_my_files
+#  ...
+#  Finished in 6 seconds with exit status 0 (successful)
+```
+
+or individually per command run:
 
-#### 2.3.2 Uuid
+```rub
+cmd = TTY::Command.new
+cmd.run("echo hello", uuid: false)
+# =>
+#  Running echo hello
+#      hello
+#  Finished in 0.003 seconds with exit status 0 (successful)
+```
 
-By default when logging is enabled each log entry is prefixed by specific command run uuid number. This number can be switched off using `uuid` option:
+#### 2.3.3 Only output on error
+
+When using a command that can fail, setting `:only_output_on_error` option to `true` hides the output if the command succeeds:
 
 ```ruby
-cmd = TTY::Command.new uuid: false
-cmd.run('rm -R all_my_files')
-# => rm -r all_my_files
+cmd = TTY::Command.new
+cmd.run("non_failing_command", only_output_on_error: true)
+```
+
+This will only print the `Running` and `Finished` lines, while:
+
+```ruby
+cmd.run("non_failing_command")
+```
+
+will also print any output that the `non_failing_command` might generate.
+
+Running either:
+
+```ruby
+cmd.run("failing_command", only_output_on_error: true)
+```
+
+either:
+
+```ruby
+cmd.run("failing_command")
+```
+
+will also print the output.
+
+*Setting this option will cause the output to show at once, at the end of the command.*
+
+#### 2.3.4 Verbose
+
+By default commands will produce warnings when, for example `pty` option is not supported on a given platform. You can switch off such warnings with `:verbose` option set to `false`.
+
+```ruby
+cmd.run("echo '\e[32mColors!\e[0m'", pty: true, verbose: false)
 ```
 
 ### 2.4 Dry run
@@ -206,7 +271,7 @@ Sometimes it can be useful to put your script into a "dry run" mode that prints
 
 ```ruby
 cmd = TTY::Command.new(dry_run: true)
-cmd.run(:rm, 'all_my_files')
+cmd.run(:rm, "all_my_files")
 # => [123abc] (dry run) rm all_my_files
 ```
 
@@ -221,7 +286,7 @@ cmd.dry_run? # => true
 If you need to wait for a long running script and stop it when a given pattern has been matched use `wait` like so:
 
 ```ruby
-cmd.wait 'tail -f /var/log/production.log', /something happened/
+cmd.wait "tail -f /var/log/production.log", /something happened/
 ```
 
 ### 2.6 Test
@@ -229,7 +294,7 @@ cmd.wait 'tail -f /var/log/production.log', /something happened/
 To simulate classic bash test command you case use `test` method with expression to check as a first argument:
 
 ```ruby
-if cmd.test '-e /etc/passwd'
+if cmd.test "-e /etc/passwd"
   puts "Sweet..."
 else
   puts "Ohh no! Where is it?"
@@ -252,24 +317,24 @@ cmd.ruby %q{-e "puts 'Hello world'"}
 The environment variables need to be provided as hash entries, that can be set directly as a first argument:
 
 ```ruby
-cmd.run({'RAILS_ENV' => 'PRODUCTION'}, :rails, 'server')
+cmd.run({"RAILS_ENV" => "PRODUCTION"}, :rails, "server")
 ```
 
 or as an option with `:env` key:
 
 ```ruby
-cmd.run(:rails, 'server', env: {rails_env: :production})
+cmd.run(:rails, "server", env: {rails_env: :production})
 ```
 
 When a value in env is nil, the variable is unset in the child process:
 
 ```ruby
-cmd.run(:echo, 'hello', env: {foo: 'bar', baz: nil})
+cmd.run(:echo, "hello", env: {foo: "bar", baz: nil})
 ```
 
 ### 3.2 Options
 
-When a hash is given in the last argument (options), it allows to specify a current directory, umask, user, group and and zero or more fd redirects for the child process.
+When a hash is given in the last argument (options), it allows to specify a current directory, umask, user, group and zero or more fd redirects for the child process.
 
 #### 3.2.1 Redirection
 
@@ -302,27 +367,27 @@ The hash key and value specify a file descriptor in the child process (stderr &
 You can also redirect to a file:
 
 ```ruby
-cmd.run(:cat, :in => 'file')
-cmd.run(:cat, :in => open('/etc/passwd'))
-cmd.run(:ls, :out => 'log')
+cmd.run(:cat, :in => "file")
+cmd.run(:cat, :in => open("/etc/passwd"))
+cmd.run(:ls, :out => "log")
 cmd.run(:ls, :out => "/dev/null")
-cmd.run(:ls, :out => 'out.log', :err => "err.log")
+cmd.run(:ls, :out => "out.log", :err => "err.log")
 cmd.run(:ls, [:out, :err] => "log")
-cmd.run("ls 1>&2", :err => 'log')
+cmd.run("ls 1>&2", :err => "log")
 ```
 
 It is possible to specify flags and permissions of file creation explicitly by passing an array value:
 
 ```ruby
-cmd.run(:ls, :out => ['log', 'w']) # 0664 assumed
-cmd.run(:ls, :out => ['log', 'w', 0600])
-cmd.run(:ls, :out => ['log', File::WRONLY|File::EXCL|File::CREAT, 0600])
+cmd.run(:ls, :out => ["log", "w"]) # 0664 assumed
+cmd.run(:ls, :out => ["log", "w", 0600])
+cmd.run(:ls, :out => ["log", File::WRONLY|File::EXCL|File::CREAT, 0600])
 ```
 
 You can, for example, read data from one source and output to another:
 
 ```ruby
-cmd.run("cat", :in => "Gemfile", :out => 'gemfile.log')
+cmd.run("cat", :in => "Gemfile", :out => "gemfile.log")
 ```
 
 #### 3.2.2 Handling Input
@@ -337,7 +402,7 @@ puts "Your name: #{name}"
 In order to execute `cli` with name input do:
 
 ```ruby
-cmd.run('cli', input: "Piotr\n")
+cmd.run("cli", input: "Piotr\n")
 # => Your name: Piotr
 ```
 
@@ -356,7 +421,7 @@ cmd.run("my_cli_program", "login", in: in_stream).out
 
 #### 3.2.3 Timeout
 
-You can timeout command execuation by providing the `:timeout` option in seconds:
+You can timeout command execution by providing the `:timeout` option in seconds:
 
 ```ruby
 cmd.run("while test 1; sleep 1; done", timeout: 5)
@@ -386,7 +451,7 @@ cmd = TTY::Command.new(binmode: true)
 
 #### 3.2.5 Signal
 
-You can specify process termination signal other than the defaut `SIGTERM`:
+You can specify process termination signal other than the default `SIGTERM`:
 
 ```ruby
 cmd.run("whilte test1; sleep1; done", timeout: 5, signal: :KILL)
@@ -394,42 +459,44 @@ cmd.run("whilte test1; sleep1; done", timeout: 5, signal: :KILL)
 
 #### 3.2.6 PTY(pseudo terminal)
 
-The `:pty` configuration option causes the command to be executed in subprocess where each stream is a pseudo terminal. By default this options is set to `false`. However, some comamnds may require a terminal like device to work correctly. For example, a command may emit colored output only if it is running via terminal.
+The `:pty` configuration option causes the command to be executed in subprocess where each stream is a `pseudo terminal`. By default this options is set to `false`.
+
+If you require to interface with interactive subprocess then setting this option to `true` will enable a `pty` terminal device. For example, a command may emit colored output only if it is running via terminal device. You may also wish to run a program that waits for user input, and simulates typing in commands and reading responses.
+
+This option will only work on systems that support BSD pty devices such as Linux or OS X, and it will gracefully fallback to non-pty device on all the other.
 
-In order to run command in pseudo terminal, either set the flag globally for all commands:
+In order to run command in `pseudo terminal`, either set the flag globally for all commands:
 
 ```ruby
 cmd = TTY::Command.new(pty: true)
 ```
 
-or for each executed command individually:
+or individually for each executed command:
 
 ```ruby
 cmd.run("echo 'hello'", pty: true)
 ```
 
-Please note though, that setting `:pty` to `true` may change how the command behaves. For instance, on unix like systems the line feed character `\n` in output will be prefixed with carriage return `\r`:
+Please note that setting `:pty` to `true` may change how the command behaves. It's important to understand the difference between `interactive` and `non-interactive` modes. For example, executing `git log` to view the commit history in default `non-interactive` mode:
 
 ```ruby
-out, _ = cmd.run("echo 'hello'")
-out # => "hello\n"
+cmd.run("git log") # => finishes and produces full output
 ```
 
-and with `:pty` option:
+However, in `interactive` mode with `pty` flag on:
 
 ```ruby
-out, _ = cmd.run("echo 'hello'", pty: true)
-out # => "hello\r\n"
+cmd.run("git log", pty: true) # => uses pager and waits for user input (never returns)
 ```
 
-In addition, any input to command may be echoed to the standard output.
+In addition, when pty device is used, any input to command may be echoed to the standard output, as well as some redirects may not work.
 
 #### 3.2.7 Current directory
 
 To change directory in which the command is run pass the `:chdir` option:
 
 ```ruby
-cmd.run(:echo, 'hello', chdir: '/var/tmp')
+cmd.run(:echo, "hello", chdir: "/var/tmp")
 ```
 
 #### 3.2.8 User
@@ -437,7 +504,7 @@ cmd.run(:echo, 'hello', chdir: '/var/tmp')
 To run command as a given user do:
 
 ```ruby
-cmd.run(:echo, 'hello', user: 'piotr')
+cmd.run(:echo, "hello", user: "piotr")
 ```
 
 #### 3.2.9 Group
@@ -445,7 +512,7 @@ cmd.run(:echo, 'hello', user: 'piotr')
 To run command as part of group do:
 
 ```ruby
-cmd.run(:echo, 'hello', group: 'devs')
+cmd.run(:echo, "hello", group: "devs")
 ```
 
 #### 3.2.10 Umask
@@ -453,7 +520,7 @@ cmd.run(:echo, 'hello', group: 'devs')
 To run command with umask do:
 
 ```ruby
-cmd.run(:echo, 'hello', umask: '007')
+cmd.run(:echo, "hello", umask: "007")
 ```
 
 ### 3.3 Result
@@ -461,13 +528,13 @@ cmd.run(:echo, 'hello', umask: '007')
 Each time you run command the stdout and stderr are captured and return as result. The result can be examined directly by casting it to tuple:
 
 ```ruby
-out, err = cmd.run(:echo, 'Hello')
+out, err = cmd.run(:echo, "Hello")
 ```
 
 However, if you want to you can defer reading:
 
 ```ruby
-result = cmd.run(:echo, 'Hello')
+result = cmd.run(:echo, "Hello")
 result.out
 result.err
 ```
@@ -477,7 +544,7 @@ result.err
 To check if command exited successfully use `success?`:
 
 ```ruby
-result = cmd.run(:echo, 'Hello')
+result = cmd.run(:echo, "Hello")
 result.success? # => true
 ```
 
@@ -486,7 +553,7 @@ result.success? # => true
 To check if command exited unsuccessfully use `failure?` or `failed?`:
 
 ```ruby
-result = cmd.run(:echo, 'Hello')
+result = cmd.run(:echo, "Hello")
 result.failure?  # => false
 result.failed?   # => false
 ```
@@ -496,7 +563,7 @@ result.failed?   # => false
 To check if command ran to completion use `exited?` or `complete?`:
 
 ```ruby
-result = cmd.run(:echo, 'Hello')
+result = cmd.run(:echo, "Hello")
 result.exited?    # => true
 result.complete?  # => true
 ```
@@ -506,7 +573,7 @@ result.complete?  # => true
 The result itself is an enumerable and allows you to iterate over the stdout output:
 
 ```ruby
-result = cmd.run(:ls, '-1')
+result = cmd.run(:ls, "-1")
 result.each { |line| puts line }
 # =>
 #  CHANGELOG.md
@@ -529,26 +596,29 @@ TTY::Command.record_separator = "\n\r"
 or configured per `each` call by passing delimiter as an argument:
 
 ```ruby
-cmd.run(:ls, '-1').each("\t") { ... }
+cmd.run(:ls, "-1").each("\t") { ... }
 ```
 
 ### 3.4 Custom printer
 
-If the built-in printers do not meet your requirements you can create your own. At the very minimum you need to specify the `write` method that will be called during the lifecycle of command execution:
+If the built-in printers do not meet your requirements you can create your own. A printer is a regular Ruby class that can be registered through `:printer` option to receive notifications about received command data.
+
+As the command runs the custom printer will be notified when the command starts, when data is printed to stdout, when data is printed to stderr and when the command exits.
+
+Please see [lib/tty/command/printers/abstract.rb](https://github.com/piotrmurach/tty-command/blob/master/lib/tty/command/printers/abstract.rb) for a full set of methods that you can override.
+
+At the very minimum you need to specify the `write` method that will be called during the lifecycle of command execution. The `write` accepts two arguments, first the currently run command instance and second the message to be printed:
 
 ```ruby
 CustomPrinter < TTY::Command::Printers::Abstract
-  def write(message)
-    puts message
+  def write(cmd, message)
+    puts cmd.to_command + message
   end
 end
 
-printer = CustomPrinter
-
-cmd = TTY::Command.new(printer: printer)
+cmd = TTY::Command.new(printer: CustomPrinter)
 ```
 
-
 ## 4. Example
 
 Here's a slightly more elaborate example to illustrate how tty-command can improve on plain old shell scripts. This example installs a new version of Ruby on an Ubuntu machine.
@@ -588,4 +658,4 @@ The gem is available as open source under the terms of the [MIT License](http://
 
 ## Copyright
 
-Copyright (c) 2016-2017 Piotr Murach. See LICENSE for further details.
+Copyright (c) 2016 Piotr Murach. See LICENSE for further details.