README.md in tty-command-0.4.0 vs README.md in tty-command-0.5.0
- old
+ new
@@ -44,24 +44,28 @@
* [1. Usage](#1-usage)
* [2. Interface](#2-interface)
* [2.1. Run](#21-run)
* [2.2. Run!](#22-run)
- * [2.3. Test](#23-test)
- * [2.4. Logging](#24-logging)
- * [2.5. Dry run](#25-dry-run)
- * [2.6. Ruby interpreter](#26-ruby-interpreter)
+ * [2.3. Logging](#23-logging)
+ * [2.3.1. Color](#231-color)
+ * [2.3.2. UUID](#232-uuid)
+ * [2.4. Dry run](#24-dry-run)
+ * [2.5. Wait](#25-wait)
+ * [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.5. User](#324-user)
- * [3.2.6. Group](#325-group)
- * [3.2.7. Umask](#326-umask)
+ * [3.2.3. Handling input](#323-handling-input)
+ * [3.2.4. Timeout](#324-timeout)
+ * [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.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)
@@ -119,10 +123,19 @@
out, err = cmd.run('date')
puts "The date is #{out}"
# => "The date is Tue 10 May 2016 22:30:15 BST\n"
```
+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|
+ output << out if out
+ errors << err if err
+end
+```
+
If the command fails (with a non-zero exit code), a `TTY::Command::ExitError` is raised. The `ExitError` message will include:
* the name of command executed
* the exit status
* stdout bytes
@@ -138,25 +151,12 @@
if cmd.run!('which xyzzy').failure?
cmd.run('brew install xyzzy')
end
```
-### 2.3 Test
+### 2.3 Logging
-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'
- puts "Sweet..."
-else
- puts "Ohh no! Where is it?"
- exit 1
-end
-```
-
-### 2.4 Logging
-
By default, when a command is run, the command and the output are printed to `stdout` using the `:pretty` printer. If you wish to change printer you can do so by passing a `:printer` option:
* `:null` - no output
* `:pretty` - colorful output
* `:progress` - minimal output with green dot for success and F for failure
@@ -170,21 +170,35 @@
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')
-cmd = TTY::Command.new(output: output)
+cmd = TTY::Command.new(output: logger)
```
You can force the printer to always in print in color by passing the `:color` option:
```ruby
cmd = TTY::Command.new(color: true)
```
-### 2.5 Dry run
+#### 2.3.1 Color
+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 each log entry is prefixed by specific command run uuid number. This number can be switched off using `uuid` option:
+
+```ruby
+cmd = TTY::Command.new uuid: false
+cmd.run('rm -R all_my_files')
+# => rm -r all_my_files
+```
+
+### 2.4 Dry run
+
Sometimes it can be useful to put your script into a "dry run" mode that prints commands without actually running them. To simulate execution of the command use the `:dry_run` option:
```ruby
cmd = TTY::Command.new(dry_run: true)
cmd.run(:rm, 'all_my_files')
@@ -195,12 +209,33 @@
```ruby
cmd.dry_run? # => true
```
-### 2.6 Ruby interpreter
+### 2.5 Wait
+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/
+```
+
+### 2.6 Test
+
+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'
+ puts "Sweet..."
+else
+ puts "Ohh no! Where is it?"
+ exit 1
+end
+```
+
+### 2.7 Ruby interpreter
+
In order to run a command with Ruby interpreter do:
```ruby
cmd.ruby %q{-e "puts 'Hello world'"}
```
@@ -272,21 +307,35 @@
cmd.run(:ls, '-la', 2 => 1)
```
#### 3.2.3 Handling Input
-You can pass input via the :in option, by passing a StringIO Object. This object might have more than one line, if the executed command reads more than once from STDIN.
+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
+puts "Your name: #{name}"
+```
+
+In order to execute `cli` with name input do:
+
+```ruby
+cmd.run('cli', input: "Piotr\n")
+# => Your name: Piotr
+```
+
+Alternatively, you can pass input via the :in option, by passing a `StringIO` Object. This object might have more than one line, if the executed command reads more than once from STDIN.
+
Assume you have run a program, that first asks for your email address and then for a password:
```ruby
in_stream = StringIO.new
in_stream.puts "username@example.com"
in_stream.puts "password"
in_stream.rewind
-TTY::Command.new.run("my_cli_program", "login", in: in_stream).out
+cmd.run("my_cli_program", "login", in: in_stream).out
```
#### 3.2.4 Timeout
You can timeout command execuation by providing the `:timeout` option in seconds:
@@ -295,26 +344,34 @@
cmd.run("while test 1; sleep 1; done", timeout: 5)
```
Please run `examples/timeout.rb` to see timeout in action.
-#### 3.2.5 User
+#### 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
+
To run command as a given user do:
```ruby
cmd.run(:echo, 'hello', user: 'piotr')
```
-#### 3.2.6 Group
+#### 3.2.7 Group
To run command as part of group do:
```ruby
cmd.run(:echo, 'hello', group: 'devs')
```
-#### 3.2.7 Umask
+#### 3.2.8 Umask
To run command with umask do:
```ruby
cmd.run(:echo, 'hello', umask: '007')