teaminsight/scmd — pull request #1 by kellyredding (2012-08-17 16:43:57+00:00)
Title: First pass at basic usage API and design

## Usage

Create a command object:

```ruby
cmd = Scmd.new("echo hi")

cmd.to_s #=> "echo hi"
cmd.inspect #=>

cmd.pid #=> nil
cmd.exitcode #=> nil
cmd.stdout #=> ''
cmd.stderr #=> ''
```

Run it:

```ruby
cmd.run
```

Run it with some input:

```ruby
# executed with `some_input` as `stdin`
cmd.run("hi there")
```

Results:

```ruby
# written to the cmd instance
cmd.pid #=> 12345
cmd.exitcode #=> 0
cmd.stdout #=> 'hi'
cmd.stderr #=> ''

# the cmd instance is returned by `run` for chaining as well
cmd.run.stdout #=> 'hi'
```

Some helpers:

```ruby
puts cmd.stderr if !cmd.success?
```

Raise an exception if not successful with `run!`:

```ruby
Scmd.new("cd /path/that/does/not/exist").run! #=> Scmd::CommandFailure
```

Log cmd execution:

```ruby
Scmd.new("echo hi", :logger => a_logger)
```

Pretend to run the command (for testing or other non-production uses):

```ruby
cmd = Scmd.new("echo hi", :logger => a_logger).pretend

# just logs what it would have done and sets `exitcode` to zero (success)
cmd.pid #=> nil
cmd.exitcode #=> 0
cmd.stdout #=> ''
cmd.stderr #=> ''
```