https://github.com/fetlife/scallop

Ergonomic shell wrapper for Ruby.
https://github.com/fetlife/scallop

gem ruby shell

Last synced: 3 months ago
JSON representation

Ergonomic shell wrapper for Ruby.

• Host: GitHub
• URL: https://github.com/fetlife/scallop
• Owner: fetlife
• License: mit
• Created: 2019-06-18T14:18:16.000Z (over 5 years ago)
• Default Branch: master
• Last Pushed: 2022-02-22T04:56:56.000Z (over 2 years ago)
• Last Synced: 2024-07-24T12:29:00.964Z (4 months ago)
• Topics: gem, ruby, shell
• Language: Ruby
• Homepage:
• Size: 52.7 KB
• Stars: 148
• Watchers: 20
• Forks: 6
• Open Issues: 2
• Metadata Files:
  • Readme: README.md
  • License: LICENSE.txt
  • Code of conduct: CODE_OF_CONDUCT.md

Awesome Lists containing this project

README

        
[![Gem Version](https://badge.fury.io/rb/scallop.svg)](https://badge.fury.io/rb/scallop)

[![CircleCI](https://circleci.com/gh/fetlife/scallop.svg?style=svg)](https://circleci.com/gh/fetlife/scallop)

[![Maintainability](https://api.codeclimate.com/v1/badges/b7d9660aa51c7205fbac/maintainability)](https://codeclimate.com/github/fetlife/scallop/maintainability)

[![Test Coverage](https://api.codeclimate.com/v1/badges/b7d9660aa51c7205fbac/test_coverage)](https://codeclimate.com/github/fetlife/scallop/test_coverage)

# Scallop

![](./scallop.png)

Ergonomic shell wrapper.

Features:

* Easy access to command's output (stdout & stderr)

* Failure handling

* Parameterization

* Measuring execution time

* Built-in string escaping

* No dependencies

## Installation

Add this line to your application's Gemfile:

```ruby

gem 'scallop'

```

And then execute:

    $ bundle

Or install it yourself as:

    $ gem install scallop

## Usage

To run `sudo -u chuck grep -R /home/chuck`

```ruby

result = Scallop.sudo(:chuck).cmd(:grep, '-R', '/home/chuck').run

```

You can then check whether command succeeded

```ruby

result.success?

```

See its output

```ruby

result.stdout

result.stderr

result.output # STDOUT and STDERR combined

```

You can also access information about command execution time

```ruby

result.timing.real # Elapsed real time

result.timing.stime # System CPU time

result.timing.utime # User CPU time

result.timing.total # Total time, that is utime + stime + cutime + cstime

```

### Handling failures with exceptions

If you replace `run` with `run!`, exception will be raised in case command fails

```ruby

begin

  Scallop.cmd(some_command).run!

rescue Scallop::Errors::CommandFailed => error

  # you can access result right on the error itself

  error.result.stderr

end

```

### Piping

To run `cat /some/file | grep something`

```ruby

command = Scallop.cmd(:cat, '/some/file') | Scallop.cmd(:grep, 'something')

command.run

```

### Parameterization

```ruby

stored_command = Scallop.cmd(:rm, '-rf', Scallop::Param[:path])

stored_command.set(path: '/foo').run # rm -rf /foo

stored_command.set(path: '/bar').run # rm -rf /bar

```

--------

You can also [check specs](./spec/scallop_spec.rb) for examples.