tty-command 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 1fc9ae4bb4984bdcf9fdc7a49fd6b9b912ff60a2
+  data.tar.gz: d47f52018f538b780aac9eba1abafcf696d1ebd7
+SHA512:
+  metadata.gz: 6b4b96a1351485b1b4fa436a58adc71d08f91f21e81f2f4cdeea78b10773bce7d5681e6340add08d963a57e17183b65799c17fc2d74ec32c48c5b325950994e6
+  data.tar.gz: ba6f5e69a2588cdf37f33bea99e10147ccc0b0d0b5f3f91dd6d0b24ec44cac7b24627184644ac07627557d91de950f42012c6cfdebab5eea644f900a72e8d598

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--color
+--warnings

data/.travis.yml

@@ -0,0 +1,25 @@
+---
+language: ruby
+sudo: false
+cache: bundler
+script: "bundle exec rake ci"
+rvm:
+  - 1.9.3
+  - 2.0
+  - 2.1
+  - 2.2
+  - 2.3.0
+  - ruby-head
+  - jruby
+  - jruby-9000
+  - rbx-2
+matrix:
+  allow_failures:
+    - rvm: ruby-head
+    - rvm: jruby
+    - rvm: jruby-9000
+  fast_finish: true
+branches:
+  only: master
+notifications:
+  email: false

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Change log
+
+## [v0.1.0] - 2016-05-29
+
+* Initial implementation and release
+
+[v0.1.0]: https://github.com/piotrmurach/tty-command/compare/v0.1.0

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,49 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, and in the interest of
+fostering an open and welcoming community, we pledge to respect all people who
+contribute through reporting issues, posting feature requests, updating
+documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free
+experience for everyone, regardless of level of experience, gender, gender
+identity and expression, sexual orientation, disability, personal appearance,
+body size, race, ethnicity, age, religion, or nationality.
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery
+* Personal attacks
+* Trolling or insulting/derogatory comments
+* Public or private harassment
+* Publishing other's private information, such as physical or electronic
+  addresses, without explicit permission
+* Other unethical or unprofessional conduct
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+By adopting this Code of Conduct, project maintainers commit themselves to
+fairly and consistently applying these principles to every aspect of managing
+this project. Project maintainers who do not follow or enforce the Code of
+Conduct may be permanently removed from the project team.
+
+This code of conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting a project maintainer at [email]. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. Maintainers are
+obligated to maintain confidentiality with regard to the reporter of an
+incident.
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 1.3.0, available at
+[http://contributor-covenant.org/version/1/3/0/][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/3/0/

data/Gemfile

@@ -0,0 +1,8 @@
+source 'https://rubygems.org'
+
+gemspec
+
+group :test do
+  gem 'simplecov', '~> 0.10.0'
+  gem 'coveralls', '~> 0.8.2'
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Piotr Murach
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,392 @@
+# TTY::Command [![Gitter](https://badges.gitter.im/Join%20Chat.svg)][gitter]
+[![Gem Version](https://badge.fury.io/rb/tty-command.svg)][gem]
+[![Build Status](https://secure.travis-ci.org/piotrmurach/tty-command.svg?branch=master)][travis]
+[![Code Climate](https://codeclimate.com/github/piotrmurach/tty-command/badges/gpa.svg)][codeclimate]
+[![Coverage Status](https://coveralls.io/repos/github/piotrmurach/tty-command/badge.svg)][coverage]
+[![Inline docs](http://inch-ci.org/github/piotrmurach/tty-command.svg?branch=master)][inchpages]
+
+[gitter]: https://gitter.im/piotrmurach/tty
+[gem]: http://badge.fury.io/rb/tty-command
+[travis]: http://travis-ci.org/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.
+
+**TTY::Command** provides independent command execution component for [TTY](https://github.com/piotrmurach/tty) toolkit.
+
+## Motivation
+
+Complex software projects aren't just a single app. These projects usually spawn dozens or hundreds of supplementary standalone scripts which are just as important as the app itself. Examples include - data validation, deployment, monitoring, database maintenance, backup & restore, configuration management, crawling, ETL, analytics, log file processing, custom reports, etc. One of the contributors to **TTY::Command** counted 222 scripts in the `bin` directory for his startup.
+
+Why should we be handcuffed to `sh` or `bash` for these scripts when we could be using Ruby? Ruby is easier to write and more fun, and we gain a lot by using a better language. It's nice for everyone to just use Ruby everywhere.
+
+**TTY::Command** tries to add value in other ways. It'll halt automatically if a command fails. It's easy to get verbose or quiet output as appropriate, or even capture output and parse it with Ruby. Escaping arguments is a breeze. These are all areas where traditional shell scripts tend to fall flat.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'tty-command'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install tty-command
+
+## Contents
+
+* [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)
+* [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. Timeout](#323-timeout)
+    * [3.2.4. User](#324-user)
+    * [3.2.5. Group](#325-group)
+    * [3.2.6. Umask](#326-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.4. Custom printer](#34-custom-printer)
+* [4. Example](#4-example)
+
+## 1. Usage
+
+Create a command instance and then run some commands:
+
+```ruby
+cmd = TTY::Command.new
+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')
+```
+
+Instead of using a plain old string, you can break up the arguments and they'll get escaped if necessary:
+
+```ruby
+path = "hello world"
+FileUtils.touch(path)
+cmd.run("sum #{path}")  # this will fail due to bad escaping
+cmd.run("sum", path)    # this gets escaped automatically
+```
+
+## 2. Interface
+
+### 2.1 Run
+
+Run starts the specified command and waits for it to complete.
+
+The argument signature of `run` is as follows:
+
+`run([env], command, [argv1, ...], [options])`
+
+The `env`, `command` and `options` arguments are described in the following sections.
+
+For example, to display file contents:
+
+```ruby
+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')
+puts "The date is #{out}"
+# => "The date is Tue 10 May 2016 22:30:15 BST\n"
+```
+
+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
+  * stderr bytes
+
+If the error output is very long, the stderr may contain only a prefix, number of omitted bytes and suffix.
+
+### 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')
+end
+```
+
+### 2.3 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.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
+* `:quiet` - only output actual command stdout and stderr
+
+like so:
+
+```ruby
+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')
+cmd = TTY::Command.new(output: output)
+```
+
+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
+
+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')
+# => [123abc] (dry run) rm all_my_files
+```
+
+To check what mode the command is in use the `dry_run?` query helper:
+
+```ruby
+cmd.dry_run? # => true
+```
+
+## 3. Advanced Interface
+
+### 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')
+```
+
+or as an option with `:env` key:
+
+```ruby
+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})
+```
+
+### 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
+
+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
+
+The streams can be redirected using hash keys `:in`, `:out`, `:err`, a fixnum, an IO and array. The keys specify a given file descriptor for the child process.
+
+You can specify a filename for redirection as a hash value:
+
+```ruby
+cmd.run(:ls, :in => "/dev/null")   # read mode
+cmd.run(:ls, :out => "/dev/null")  # write mode
+cmd.run(:ls, :err => "log")        # write mode
+cmd.run(:ls, [:out, :err] => "/dev/null") # write mode
+cmd.run(:ls, 3 => "/dev/null")     # read mode
+```
+
+You can also provide actual file descriptor for redirection:
+
+```ruby
+cmd.run(:cat, :in => open('/etc/passwd'))
+```
+
+For example, to merge stderr into stdout you would do:
+
+```ruby
+cmd.run(:ls, '-la', :stderr => :stdout)
+cmd.run(:ls, '-la', 2 => 1)
+```
+
+#### 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)
+```
+
+Please run `examples/timeout.rb` to see timeout in action.
+
+#### 3.2.4 User
+
+To run command as a given user do:
+
+```ruby
+cmd.run(:echo, 'hello', user: 'piotr')
+```
+
+#### 3.2.5 Group
+
+To run command as part of group do:
+
+```ruby
+cmd.run(:echo, 'hello', group: 'devs')
+```
+
+#### 3.2.6 Umask
+
+To run command with umask do:
+
+```ruby
+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')
+```
+
+However, if you want to you can defer reading:
+
+```ruby
+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.success? # => true
+```
+
+#### 3.3.2 failure?
+
+To check if command exited unsuccessfully use `failure?` or `failed?`:
+
+```ruby
+result = cmd.run(:echo, 'Hello')
+result.failure?  # => false
+result.failed?   # => false
+```
+
+#### 3.3.3 exited?
+
+To check if command run to complition use `exited?` or `complete?`:
+
+```ruby
+result = cmd.run(:echo, 'Hello')
+result.exited?    # => true
+result.complete?  # => true
+```
+
+### 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:
+
+```ruby
+CustomPrinter < TTY::Command::Printers::Abstract
+  def write(message)
+    puts message
+  end
+end
+
+printer = CustomPrinter
+
+cmd = TTY::Command.new(printer: printer)
+```
+
+## 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.
+
+```ruby
+cmd = TTY::Command.new
+
+# dependencies
+cmd.run "apt-get -y install build-essential checkinstall"
+
+# fetch ruby if necessary
+if !File.exists?("ruby-2.3.0.tar.gz")
+  puts "Downloading..."
+  cmd.run "wget http://ftp.ruby-lang.org/pub/ruby/2.3/ruby-2.3.0.tar.gz"
+  cmd.run "tar xvzf ruby-2.3.0.tar.gz"
+end
+
+# now install
+Dir.chdir("ruby-2.3.0") do
+  puts "Building..."
+  cmd.run "./configure --prefix=/usr/local"
+  cmd.run "make"
+end
+```
+
+## 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.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/piotrmurach/tty-command. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+
+## Copyright
+
+Copyright (c) 2016 Piotr Murach. See LICENSE for further details.