README.md in tty-command-0.6.0 vs README.md in tty-command-0.7.0
- old
+ new
@@ -1,15 +1,18 @@
# TTY::Command [][gitter]
+
[][gem]
[][travis]
+[][appveyor]
[][codeclimate]
[][coverage]
[][inchpages]
[gitter]: https://gitter.im/piotrmurach/tty
[gem]: http://badge.fury.io/rb/tty-command
[travis]: http://travis-ci.org/piotrmurach/tty-command
+[appveyor]: https://ci.appveyor.com/project/piotrmurach/tty-command
[codeclimate]: https://codeclimate.com/github/piotrmurach/tty-command
[coverage]: https://coveralls.io/github/piotrmurach/tty-command
[inchpages]: http://inch-ci.org/github/piotrmurach/tty-command
> Run external commands with pretty output logging and capture stdout, stderr and exit status. Redirect stdin, stdout and stderr of each command to a file or a string.
@@ -54,18 +57,20 @@
* [2.6. Test](#26-test)
* [2.7. Ruby interpreter](#27-ruby-interpreter)
* [3. Advanced Interface](#3-advanced-interface)
* [3.1. Environment variables](#31-environment-variables)
* [3.2. Options](#32-options)
- * [3.2.1. Current directory](#321-current-directory)
- * [3.2.2. Redirection](#322-redirection)
- * [3.2.3. Handling input](#323-handling-input)
- * [3.2.4. Timeout](#324-timeout)
+ * [3.2.1. Redirection](#321-redirection)
+ * [3.2.2. Handling input](#322-handling-input)
+ * [3.2.3. Timeout](#323-timeout)
+ * [3.2.4. Binary mode](#324-binary-mode)
* [3.2.5. Signal](#325-signal)
- * [3.2.6. User](#326-user)
- * [3.2.7. Group](#327-group)
- * [3.2.8. Umask](#328-umask)
+ * [3.2.6. PTY(pseudo-terminal)](#326-ptypseudo-terminal)
+ * [3.2.7. Current directory](#327-current-directory)
+ * [3.2.8. User](#328-user)
+ * [3.2.9. Group](#329-group)
+ * [3.2.10. Umask](#3210-umask)
* [3.3. Result](#33-result)
* [3.3.1. success?](#331-success)
* [3.3.2. failure?](#332-failure)
* [3.3.3. exited?](#333-exited)
* [3.3.4. each](#334-each)
@@ -264,20 +269,12 @@
### 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.
-#### 3.2.1 Current directory
+#### 3.2.1 Redirection
-To change directory in which the command is run pass the `:chidir` option:
-
-```ruby
-cmd.run(:echo, 'hello', chdir: '/var/tmp')
-```
-
-#### 3.2.2 Redirection
-
There are few ways you can redirect commands output.
You can directly use shell redirection like so:
```ruby
@@ -326,11 +323,11 @@
```ruby
cmd.run("cat", :in => "Gemfile", :out => 'gemfile.log')
```
-#### 3.2.3 Handling Input
+#### 3.2.2 Handling Input
You can provide input to stdin stream using the `:input` key. For instance, given the following executable called `cli` that expects name from `stdin`:
```ruby
name = $stdin.gets
@@ -355,44 +352,104 @@
in_stream.rewind
cmd.run("my_cli_program", "login", in: in_stream).out
```
-#### 3.2.4 Timeout
+#### 3.2.3 Timeout
You can timeout command execuation by providing the `:timeout` option in seconds:
```ruby
cmd.run("while test 1; sleep 1; done", timeout: 5)
```
+And to set it for all commands do:
+
+```ruby
+cmd = TTY::Command.new(timeout: 5)
+```
+
Please run `examples/timeout.rb` to see timeout in action.
+#### 3.2.4 Binary mode
+
+By default the standard input, output and error are non-binary. However, you can change to read and write in binary mode by using the `:binmode` option like so:
+
+```ruby
+cmd.run("echo 'hello'", binmode: true)
+```
+
+To set all commands to be run in binary mode do:
+
+```ruby
+cmd = TTY::Command.new(binmode: true)
+```
+
#### 3.2.5 Signal
You can specify process termination signal other than the defaut `SIGTERM`:
```ruby
cmd.run("whilte test1; sleep1; done", timeout: 5, signal: :KILL)
```
-#### 3.2.6 User
+#### 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.
+
+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:
+
+```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`:
+
+```ruby
+out, _ = cmd.run("echo 'hello'")
+out # => "hello\n"
+```
+
+and with `:pty` option:
+
+```ruby
+out, _ = cmd.run("echo 'hello'", pty: true)
+out # => "hello\r\n"
+```
+
+In addition, any input to command may be echoed to the standard output.
+
+#### 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')
+```
+
+#### 3.2.8 User
+
To run command as a given user do:
```ruby
cmd.run(:echo, 'hello', user: 'piotr')
```
-#### 3.2.7 Group
+#### 3.2.9 Group
To run command as part of group do:
```ruby
cmd.run(:echo, 'hello', group: 'devs')
```
-#### 3.2.8 Umask
+#### 3.2.10 Umask
To run command with umask do:
```ruby
cmd.run(:echo, 'hello', umask: '007')