Skip to content
Browse files

Spruce up the README

  • Loading branch information...
1 parent a5a4821 commit 06898a20fbea2866f61330d66f29330656b25dab @mike-burns mike-burns committed Aug 29, 2012
Showing with 39 additions and 25 deletions.
  1. +39 −25 README.md
View
64 README.md
@@ -2,23 +2,19 @@
A small library for doing (command) lines.
-## Feedback
-
-Question? Idea? Problem? Bug? Something else? Comment? Concern? Like use question marks?
-
-[GitHub Issues For All!](https://github.com/thoughtbot/cocaine/issues)
+[API reference](http://rubydoc.info/gems/cocaine/)
## Usage
-The basic, normal stuff.
+The basic, normal stuff:
```ruby
-line = Cocaine::CommandLine.new("command", "some 'crazy' options")
-line.command # => "command some 'crazy' options"
-output = line.run # => Get you some output!
+line = Cocaine::CommandLine.new("echo", "hello 'world'")
+line.command # => "echo hello 'world'"
+line.run # => "hello world\n"
```
-Allowing arguments to be dynamic:
+Interpolated arguments:
```ruby
line = Cocaine::CommandLine.new("convert", ":in -scale :resolution :out",
@@ -59,6 +55,17 @@ rescue Cocaine::ExitStatusError => e
end
```
+If your command might return something non-zero, and you expect that, it's cool:
+
+```ruby
+line = Cocaine::CommandLine.new("/usr/bin/false", "", :expected_outcodes => [0, 1])
+begin
+ line.run
+rescue Cocaine::ExitStatusError => e
+ # => You never get here!
+end
+```
+
You don't have the command? You get an exception:
```ruby
@@ -82,7 +89,7 @@ You can even give it a bunch of places to look:
```ruby
FileUtils.rm("/opt/bin/lolwut")
- `echo 'echo Hello' > /usr/local/bin/lolwut`
+ File.open('/usr/local/bin/lolwut') {|f| f.write('echo Hello') }
Cocaine::CommandLine.path = ["/opt/bin", "/usr/local/bin"]
line = Cocaine::CommandLine.new("lolwut")
line.run # => prints 'Hello', because it searches the path
@@ -95,34 +102,41 @@ line = Cocaine::CommandLine.new("/opt/bin/lolwut")
line.command # => "/opt/bin/lolwut"
```
-If your command might return something non-zero, and you expect that, it's cool:
-
-```ruby
-line = Cocaine::CommandLine.new("/usr/bin/false", "", :expected_outcodes => [0, 1])
-begin
- line.run
-rescue Cocaine::ExitStatusError => e
- # => You never get here!
-end
-```
-
You can see what's getting run. The 'Command' part it logs is in green for visibility!
```ruby
line = Cocaine::CommandLine.new("echo", ":var", :var => "LOL!", :logger => Logger.new(STDOUT))
line.run # => Logs this with #info -> Command :: echo 'LOL!'
```
-But you don't have to, as you saw above where it doesn't use this. But you CAN log every command!
+Or log every command:
```ruby
Cocaine::CommandLine.logger = Logger.new(STDOUT)
Cocaine::CommandLine.new("date").run # => Logs this -> Command :: date
```
+
## POSIX Spawn
-You can potentially increase performance by installing the posix-spawn gem (https://rubygems.org/gems/posix-spawn). This gem can keep your application's heap from being copied when forking command line processesG. For applications with large heaps the gain can be significant. To include posix-spawn, simply add it to your Gemfile or, if you don't use bundler, install the gem.
+You can potentially increase performance by installing [the posix-spawn
+gem](https://rubygems.org/gems/posix-spawn). This gem can keep your
+application's heap from being copied when forking command line
+processes. For applications with large heaps the gain can be
+significant. To include `posix-spawn`, simply add it to your `Gemfile` or,
+if you don't use bundler, install the gem.
+
+## Feedback
+
+*Security* concerns must be privately emailed to
+[security@thoughtbot.com](security@thoughtbot.com).
+
+Question? Idea? Problem? Bug? Comment? Concern? Like using question marks?
+
+[GitHub Issues For All!](https://github.com/thoughtbot/cocaine/issues)
## License
-Copyright 2011 Jon Yurek and thoughtbot, inc. This is free software, and may be redistributed under the terms specified in the LICENSE file.
+Copyright 2011 Jon Yurek and thoughtbot, inc. This is free software, and
+may be redistributed under the terms specified in the
+[LICENSE](https://github.com/thoughtbot/cocaine/blob/master/LICENSE)
+file.

0 comments on commit 06898a2

Please sign in to comment.
Something went wrong with that request. Please try again.