Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 167 lines (123 sloc) 4.908 kb
ac47b6f @gabebw Show correct Travis CI status.
gabebw authored
1 # Cocaine [![Build Status](https://secure.travis-ci.org/thoughtbot/cocaine.png)](http://travis-ci.org/thoughtbot/cocaine)
464d2ab @jyurek README and LICENSE
jyurek authored
2
3 A small library for doing (command) lines.
4
06898a2 @mike-burns Spruce up the README
mike-burns authored
5 [API reference](http://rubydoc.info/gems/cocaine/)
7f11075 @jyurek Adds a feedback section to the README
jyurek authored
6
464d2ab @jyurek README and LICENSE
jyurek authored
7 ## Usage
8
06898a2 @mike-burns Spruce up the README
mike-burns authored
9 The basic, normal stuff:
464d2ab @jyurek README and LICENSE
jyurek authored
10
0f60aee @jjb pretty syntax highlighting
jjb authored
11 ```ruby
06898a2 @mike-burns Spruce up the README
mike-burns authored
12 line = Cocaine::CommandLine.new("echo", "hello 'world'")
13 line.command # => "echo hello 'world'"
14 line.run # => "hello world\n"
0f60aee @jjb pretty syntax highlighting
jjb authored
15 ```
464d2ab @jyurek README and LICENSE
jyurek authored
16
06898a2 @mike-burns Spruce up the README
mike-burns authored
17 Interpolated arguments:
464d2ab @jyurek README and LICENSE
jyurek authored
18
0f60aee @jjb pretty syntax highlighting
jjb authored
19 ```ruby
d20966e @mike-burns Update README with new interpolation syntax
mike-burns authored
20 line = Cocaine::CommandLine.new("convert", ":in -scale :resolution :out")
21 line.command(:in => "omg.jpg",
22 :resolution => "32x32",
23 :out => "omg_thumb.jpg")
24 # => "convert 'omg.jpg' -scale '32x32' 'omg_thumb.jpg'"
0f60aee @jjb pretty syntax highlighting
jjb authored
25 ```
464d2ab @jyurek README and LICENSE
jyurek authored
26
f96add7 @gabebw Let's use colons in the README.
gabebw authored
27 It prevents attempts at being bad:
464d2ab @jyurek README and LICENSE
jyurek authored
28
0f60aee @jjb pretty syntax highlighting
jjb authored
29 ```ruby
d20966e @mike-burns Update README with new interpolation syntax
mike-burns authored
30 line = Cocaine::CommandLine.new("cat", ":file")
31 line.command(:file => "haha`rm -rf /`.txt") # => "cat 'haha`rm -rf /`.txt'"
464d2ab @jyurek README and LICENSE
jyurek authored
32
d20966e @mike-burns Update README with new interpolation syntax
mike-burns authored
33 line = Cocaine::CommandLine.new("cat", ":file")
34 line.command(:file => "ohyeah?'`rm -rf /`.ha!") # => "cat 'ohyeah?'\\''`rm -rf /`.ha!'"
0f60aee @jjb pretty syntax highlighting
jjb authored
35 ```
464d2ab @jyurek README and LICENSE
jyurek authored
36
f96add7 @gabebw Let's use colons in the README.
gabebw authored
37 You can ignore the result:
464d2ab @jyurek README and LICENSE
jyurek authored
38
0f60aee @jjb pretty syntax highlighting
jjb authored
39 ```ruby
40 line = Cocaine::CommandLine.new("noisy", "--extra-verbose", :swallow_stderr => true)
41 line.command # => "noisy --extra-verbose 2>/dev/null"
464d2ab @jyurek README and LICENSE
jyurek authored
42
0f60aee @jjb pretty syntax highlighting
jjb authored
43 # ... and on Windows...
44 line.command # => "noisy --extra-verbose 2>NUL"
45 ```
464d2ab @jyurek README and LICENSE
jyurek authored
46
f96add7 @gabebw Let's use colons in the README.
gabebw authored
47 If your command errors, you get an exception:
464d2ab @jyurek README and LICENSE
jyurek authored
48
0f60aee @jjb pretty syntax highlighting
jjb authored
49 ```ruby
50 line = Cocaine::CommandLine.new("git", "commit")
51 begin
52 line.run
53 rescue Cocaine::ExitStatusError => e
54 e.message # => "Command 'git commit' returned 1. Expected 0"
55 end
56 ```
464d2ab @jyurek README and LICENSE
jyurek authored
57
06898a2 @mike-burns Spruce up the README
mike-burns authored
58 If your command might return something non-zero, and you expect that, it's cool:
59
60 ```ruby
61 line = Cocaine::CommandLine.new("/usr/bin/false", "", :expected_outcodes => [0, 1])
62 begin
63 line.run
64 rescue Cocaine::ExitStatusError => e
65 # => You never get here!
66 end
67 ```
68
f96add7 @gabebw Let's use colons in the README.
gabebw authored
69 You don't have the command? You get an exception:
464d2ab @jyurek README and LICENSE
jyurek authored
70
0f60aee @jjb pretty syntax highlighting
jjb authored
71 ```ruby
72 line = Cocaine::CommandLine.new("lolwut")
73 begin
74 line.run
75 rescue Cocaine::CommandNotFoundError => e
76 e # => the command isn't in the $PATH for this process.
77 end
78 ```
464d2ab @jyurek README and LICENSE
jyurek authored
79
f96add7 @gabebw Let's use colons in the README.
gabebw authored
80 But don't fear, you can specify where to look for the command:
464d2ab @jyurek README and LICENSE
jyurek authored
81
0f60aee @jjb pretty syntax highlighting
jjb authored
82 ```ruby
83 Cocaine::CommandLine.path = "/opt/bin"
84 line = Cocaine::CommandLine.new("lolwut")
6fb2bf1 @jyurek Update the README
jyurek authored
85 line.command # => "lolwut", but it looks in /opt/bin for it.
86 ```
87
f96add7 @gabebw Let's use colons in the README.
gabebw authored
88 You can even give it a bunch of places to look:
6fb2bf1 @jyurek Update the README
jyurek authored
89
90 ```ruby
f96add7 @gabebw Let's use colons in the README.
gabebw authored
91 FileUtils.rm("/opt/bin/lolwut")
06898a2 @mike-burns Spruce up the README
mike-burns authored
92 File.open('/usr/local/bin/lolwut') {|f| f.write('echo Hello') }
f96add7 @gabebw Let's use colons in the README.
gabebw authored
93 Cocaine::CommandLine.path = ["/opt/bin", "/usr/local/bin"]
94 line = Cocaine::CommandLine.new("lolwut")
95 line.run # => prints 'Hello', because it searches the path
0f60aee @jjb pretty syntax highlighting
jjb authored
96 ```
464d2ab @jyurek README and LICENSE
jyurek authored
97
f96add7 @gabebw Let's use colons in the README.
gabebw authored
98 Or just put it in the command:
464d2ab @jyurek README and LICENSE
jyurek authored
99
0f60aee @jjb pretty syntax highlighting
jjb authored
100 ```ruby
101 line = Cocaine::CommandLine.new("/opt/bin/lolwut")
102 line.command # => "/opt/bin/lolwut"
103 ```
464d2ab @jyurek README and LICENSE
jyurek authored
104
6fb2bf1 @jyurek Update the README
jyurek authored
105 You can see what's getting run. The 'Command' part it logs is in green for visibility!
106
107 ```ruby
d20966e @mike-burns Update README with new interpolation syntax
mike-burns authored
108 line = Cocaine::CommandLine.new("echo", ":var", :logger => Logger.new(STDOUT))
109 line.run(:var => "LOL!") # => Logs this with #info -> Command :: echo 'LOL!'
6fb2bf1 @jyurek Update the README
jyurek authored
110 ```
111
06898a2 @mike-burns Spruce up the README
mike-burns authored
112 Or log every command:
6fb2bf1 @jyurek Update the README
jyurek authored
113
114 ```ruby
115 Cocaine::CommandLine.logger = Logger.new(STDOUT)
116 Cocaine::CommandLine.new("date").run # => Logs this -> Command :: date
117 ```
06898a2 @mike-burns Spruce up the README
mike-burns authored
118
aa36e45 @bdurand Add hooks to use posix-spawn gem if available.
bdurand authored
119 ## POSIX Spawn
120
06898a2 @mike-burns Spruce up the README
mike-burns authored
121 You can potentially increase performance by installing [the posix-spawn
122 gem](https://rubygems.org/gems/posix-spawn). This gem can keep your
123 application's heap from being copied when forking command line
124 processes. For applications with large heaps the gain can be
125 significant. To include `posix-spawn`, simply add it to your `Gemfile` or,
126 if you don't use bundler, install the gem.
127
910fcce @jyurek Version 0.3.1
jyurek authored
128 ## Runners
129
130 Cocaine will attempt to choose from among 3 different ways of running commands.
131 The simplest is using backticks, and is the default in 1.8. In Ruby 1.9, it
132 will attempt to use `Process.spawn`. And, as mentioned above, if the
133 `posix-spawn` gem is installed, it will attempt to use that. If for some reason
134 one of the `.spawn` runners don't work for you, you can override them manually
135 by setting a new runner, like so:
136
137 ```ruby
138 Cocaine::CommandLine.runner = Cocaine::BackticksRunner.new
139 ```
140
141 And if you really want to, you can define your own Runner, though I can't
142 imagine why you would.
143
144 ### JRuby Caveat
145
146 If you get `Error::ECHILD` errors and are using JRuby, there is a very good
147 chance that the error is actually in JRuby. This was brought to our attention
148 in https://github.com/thoughtbot/cocaine/issues/24 and probably fixed in
149 http://jira.codehaus.org/browse/JRUBY-6162. You *will* want to use the
150 `BackticksRunner` if you are unable to update JRuby.
151
06898a2 @mike-burns Spruce up the README
mike-burns authored
152 ## Feedback
153
154 *Security* concerns must be privately emailed to
155 [security@thoughtbot.com](security@thoughtbot.com).
156
157 Question? Idea? Problem? Bug? Comment? Concern? Like using question marks?
158
159 [GitHub Issues For All!](https://github.com/thoughtbot/cocaine/issues)
6fb2bf1 @jyurek Update the README
jyurek authored
160
464d2ab @jyurek README and LICENSE
jyurek authored
161 ## License
162
06835ec Update Copyright years in LICENSE and README.md
Adarsh Pandit authored
163 Copyright 2011-2012 Jon Yurek and thoughtbot, inc. This is free software, and
06898a2 @mike-burns Spruce up the README
mike-burns authored
164 may be redistributed under the terms specified in the
165 [LICENSE](https://github.com/thoughtbot/cocaine/blob/master/LICENSE)
166 file.
Something went wrong with that request. Please try again.