README.md in tty-command-0.9.0 vs README.md in tty-command-0.10.0
- old
+ new
@@ -1,7 +1,7 @@
<div align="center">
- <a href="https://piotrmurach.github.io/tty" target="_blank"><img width="130" src="https://cdn.rawgit.com/piotrmurach/tty/master/images/tty.png" alt="tty logo" /></a>
+ <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]
[][gem]
@@ -34,11 +34,11 @@
## Installation
Add this line to your application's Gemfile:
```ruby
-gem 'tty-command'
+gem "tty-command"
```
And then execute:
$ bundle
@@ -86,23 +86,23 @@
## 1. Usage
Create a command instance and then run some commands:
```ruby
-require 'tty-command'
+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.
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:
```ruby
@@ -125,25 +125,25 @@
The `env`, `command` and `options` arguments are described in the following sections.
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"
```
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
```
@@ -159,12 +159,12 @@
### 2.2 Run!
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
```
### 2.3 Logging
@@ -182,11 +182,11 @@
```
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)
```
You can force the printer to always in print in color by passing the `:color` option:
@@ -204,11 +204,11 @@
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')
+cmd.run("rm -R all_my_files")
# =>
# Running rm -r all_my_files
# ...
# Finished in 6 seconds with exit status 0 (successful)
```
@@ -228,31 +228,31 @@
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
-cmd.run('non_failing_command', only_output_on_error: true)
+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')
+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)
+cmd.run("failing_command", only_output_on_error: true)
```
either:
```ruby
-cmd.run('failing_command')
+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.*
@@ -269,11 +269,11 @@
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')
+cmd.run(:rm, "all_my_files")
# => [123abc] (dry run) rm all_my_files
```
To check what mode the command is in use the `dry_run?` query helper:
@@ -284,19 +284,19 @@
### 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/
+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'
+if cmd.test "-e /etc/passwd"
puts "Sweet..."
else
puts "Ohh no! Where is it?"
exit 1
end
@@ -315,23 +315,23 @@
### 3.1 Environment variables
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 zero or more fd redirects for the child process.
@@ -365,31 +365,31 @@
The hash key and value specify a file descriptor in the child process (stderr & stdout in the examples).
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
You can provide input to stdin stream using the `:input` key. For instance, given the following executable called `cli` that expects name from `stdin`:
@@ -400,11 +400,11 @@
```
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
```
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.
@@ -494,88 +494,88 @@
#### 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
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
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
To run command with umask do:
```ruby
-cmd.run(:echo, 'hello', umask: '007')
+cmd.run(:echo, "hello", umask: "007")
```
### 3.3 Result
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
```
#### 3.3.1 success?
To check if command exited successfully use `success?`:
```ruby
-result = cmd.run(:echo, 'Hello')
+result = cmd.run(:echo, "Hello")
result.success? # => true
```
#### 3.3.2 failure?
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
```
#### 3.3.3 exited?
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
```
#### 3.3.4 each
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
# CODE_OF_CONDUCT.md
# Gemfile
@@ -594,10 +594,10 @@
```
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. A printer is a regular Ruby class that can be registered through `:printer` option to receive notifications about received command data.