Giter VIP home page Giter VIP logo

cheetah's Introduction

Cheetah

Cheetah is a simple library for executing external commands safely and conveniently.

Examples

# Run a command and capture its output
files = Cheetah.run("ls", "-la", :stdout => :capture)

# Run a command and handle errors
begin
  Cheetah.run("rm", "/etc/passwd")
rescue Cheetah::ExecutionFailed => e
  puts e.message
  puts "Standard output: #{e.stdout}"
  puts "Error ouptut:    #{e.stderr}"
end

Features

  • Easy passing of command input
  • Easy capturing of command output (standard, error, or both)
  • 100% secure (shell expansion is impossible by design)
  • Raises exceptions on errors (no more manual status code checks)
  • Optional logging for easy debugging

Non-features

  • Handling of interactive commands

Installation

$ gem install cheetah

Usage

First, require the library:

require "cheetah"

You can now use the Cheetah.run method to run commands, pass them an input and capture their output:

# Run a command with arguments
Cheetah.run("tar", "xzf", "foo.tar.gz")

# Pass an input (as a string)
Cheetah.run("python", :stdin => source_code)

# Pass an input (as a stream)
File.open("huge_program.py") do |stdin|
  Cheetah.run("python", :stdin => stdin)
end

# Capture standard output
files = Cheetah.run("ls", "-la", :stdout => :capture)

# Capture both standard and error output
results, errors = Cheetah.run("grep", "-r", "User", ".", :stdout => :capture, :stderr => :capture)

# Capture standard output into a stream
File.open("files.txt") do |stdout|
  Cheetah.run("ls", "-la", :stdout => stdout)
end

If the command can't be executed for some reason or returns a non-zero exit status, the method raises an exception with detailed information about the failure:

# Run a command and handle errors
begin
  Cheetah.run("rm", "/etc/passwd")
rescue Cheetah::ExecutionFailed => e
  puts e.message
  puts "Standard output: #{e.stdout}"
  puts "Error ouptut:    #{e.stderr}"
end

For debugging purposes, you can also use a logger. Cheetah will log the command, its status, input and both outputs to it. By default, the Logger::INFO level will be used for normal messages and the Logger::ERROR level for messages about errors (non-zero exit status or non-empty error output), but this can be changed if needed:

# Log the execution
Cheetah.run("ls -l", :logger => logger)

# Change levels of logged messages
Cheetah.run("ls -l",
  :logger             => logger,
  :logger_level_info  => Logger::DEBUG,
  :logger_level_error => Logger::WARN
)

To avoid repetition, you can set global default value of any option passed too Cheetah.run:

# If you're tired of passing the :logger option all the time...
Cheetah.default_options = { :logger = my_logger }
Cheetah.run("./configure")
Cheetah.run("make")
Cheetah.run("make", "install")
Cheetah.default_options = {}

For more information, see the API documentation.

Compatibility

Cheetah should run well on any Unix system with Ruby 1.8.7 or 1.9.3. Non-Unix systems and different Ruby implementations/versions may work too but they were not tested.

cheetah's People

Contributors

dmajda avatar jreidinger avatar

Stargazers

 avatar

Watchers

 avatar  avatar

Forkers

teclator

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.