Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 216 lines (156 sloc) 6.552 kB
b0c3165 @gabebw Only show master branch Travis status in README
gabebw authored
1 # Cocaine [![Build Status](https://secure.travis-ci.org/thoughtbot/cocaine.png?branch=master)](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'")
e9edac9 @gabebw Whitespace
gabebw authored
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")
4ad2ab9 @jyurek Update README's examples to use 1.9 hashes
jyurek authored
21 line.command(in: "omg.jpg",
22 resolution: "32x32",
23 out: "omg_thumb.jpg")
d20966e @mike-burns Update README with new interpolation syntax
mike-burns authored
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")
4ad2ab9 @jyurek Update README's examples to use 1.9 hashes
jyurek authored
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")
4ad2ab9 @jyurek Update README's examples to use 1.9 hashes
jyurek authored
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
587edeb @Tanner Fix spelling of "arguments".
Tanner authored
37 NOTE: It only does that for arguments interpolated via `run`, NOT arguments
6f5cd32 @jyurek Caution in the README
jyurek authored
38 passed into `new` (see 'Security' below):
39
40 ```ruby
41 line = Cocaine::CommandLine.new("echo", "haha`whoami`")
42 line.command # => "echo haha`whoami`"
43 line.run # => "hahawebserver"
44 ```
45
f96add7 @gabebw Let's use colons in the README.
gabebw authored
46 You can ignore the result:
464d2ab @jyurek README and LICENSE
jyurek authored
47
0f60aee @jjb pretty syntax highlighting
jjb authored
48 ```ruby
4ad2ab9 @jyurek Update README's examples to use 1.9 hashes
jyurek authored
49 line = Cocaine::CommandLine.new("noisy", "--extra-verbose", swallow_stderr: true)
0f60aee @jjb pretty syntax highlighting
jjb authored
50 line.command # => "noisy --extra-verbose 2>/dev/null"
464d2ab @jyurek README and LICENSE
jyurek authored
51
0f60aee @jjb pretty syntax highlighting
jjb authored
52 # ... and on Windows...
53 line.command # => "noisy --extra-verbose 2>NUL"
54 ```
464d2ab @jyurek README and LICENSE
jyurek authored
55
f96add7 @gabebw Let's use colons in the README.
gabebw authored
56 If your command errors, you get an exception:
464d2ab @jyurek README and LICENSE
jyurek authored
57
0f60aee @jjb pretty syntax highlighting
jjb authored
58 ```ruby
59 line = Cocaine::CommandLine.new("git", "commit")
60 begin
61 line.run
62 rescue Cocaine::ExitStatusError => e
63 e.message # => "Command 'git commit' returned 1. Expected 0"
64 end
65 ```
464d2ab @jyurek README and LICENSE
jyurek authored
66
06898a2 @mike-burns Spruce up the README
mike-burns authored
67 If your command might return something non-zero, and you expect that, it's cool:
68
69 ```ruby
4ad2ab9 @jyurek Update README's examples to use 1.9 hashes
jyurek authored
70 line = Cocaine::CommandLine.new("/usr/bin/false", "", expected_outcodes: [0, 1])
06898a2 @mike-burns Spruce up the README
mike-burns authored
71 begin
72 line.run
73 rescue Cocaine::ExitStatusError => e
74 # => You never get here!
75 end
76 ```
77
f96add7 @gabebw Let's use colons in the README.
gabebw authored
78 You don't have the command? You get an exception:
464d2ab @jyurek README and LICENSE
jyurek authored
79
0f60aee @jjb pretty syntax highlighting
jjb authored
80 ```ruby
81 line = Cocaine::CommandLine.new("lolwut")
82 begin
83 line.run
84 rescue Cocaine::CommandNotFoundError => e
85 e # => the command isn't in the $PATH for this process.
86 end
87 ```
464d2ab @jyurek README and LICENSE
jyurek authored
88
f96add7 @gabebw Let's use colons in the README.
gabebw authored
89 But don't fear, you can specify where to look for the command:
464d2ab @jyurek README and LICENSE
jyurek authored
90
0f60aee @jjb pretty syntax highlighting
jjb authored
91 ```ruby
92 Cocaine::CommandLine.path = "/opt/bin"
93 line = Cocaine::CommandLine.new("lolwut")
6fb2bf1 @jyurek Update the README
jyurek authored
94 line.command # => "lolwut", but it looks in /opt/bin for it.
95 ```
96
f96add7 @gabebw Let's use colons in the README.
gabebw authored
97 You can even give it a bunch of places to look:
6fb2bf1 @jyurek Update the README
jyurek authored
98
99 ```ruby
f96add7 @gabebw Let's use colons in the README.
gabebw authored
100 FileUtils.rm("/opt/bin/lolwut")
06898a2 @mike-burns Spruce up the README
mike-burns authored
101 File.open('/usr/local/bin/lolwut') {|f| f.write('echo Hello') }
f96add7 @gabebw Let's use colons in the README.
gabebw authored
102 Cocaine::CommandLine.path = ["/opt/bin", "/usr/local/bin"]
103 line = Cocaine::CommandLine.new("lolwut")
104 line.run # => prints 'Hello', because it searches the path
0f60aee @jjb pretty syntax highlighting
jjb authored
105 ```
464d2ab @jyurek README and LICENSE
jyurek authored
106
f96add7 @gabebw Let's use colons in the README.
gabebw authored
107 Or just put it in the command:
464d2ab @jyurek README and LICENSE
jyurek authored
108
0f60aee @jjb pretty syntax highlighting
jjb authored
109 ```ruby
110 line = Cocaine::CommandLine.new("/opt/bin/lolwut")
111 line.command # => "/opt/bin/lolwut"
112 ```
464d2ab @jyurek README and LICENSE
jyurek authored
113
6fb2bf1 @jyurek Update the README
jyurek authored
114 You can see what's getting run. The 'Command' part it logs is in green for visibility!
115
116 ```ruby
4ad2ab9 @jyurek Update README's examples to use 1.9 hashes
jyurek authored
117 line = Cocaine::CommandLine.new("echo", ":var", logger: Logger.new(STDOUT))
118 line.run(var: "LOL!") # => Logs this with #info -> Command :: echo 'LOL!'
6fb2bf1 @jyurek Update the README
jyurek authored
119 ```
120
06898a2 @mike-burns Spruce up the README
mike-burns authored
121 Or log every command:
6fb2bf1 @jyurek Update the README
jyurek authored
122
123 ```ruby
124 Cocaine::CommandLine.logger = Logger.new(STDOUT)
125 Cocaine::CommandLine.new("date").run # => Logs this -> Command :: date
126 ```
06898a2 @mike-burns Spruce up the README
mike-burns authored
127
6f5cd32 @jyurek Caution in the README
jyurek authored
128 ## Security
129
130 Short version: Only pass user-generated data into the `run` method and NOT
131 `new`.
132
133 As shown in examples above, Cocaine will only shell-escape what is passed in as
134 interpolations to the `run` method. It WILL NOT escape what is passed in to the
135 second argument of `new`. Cocaine assumes that you will not be manually
136 passing user-generated data to that argument and will be using it as a template
137 for your command line's structure.
138
aa36e45 @bdurand Add hooks to use posix-spawn gem if available.
bdurand authored
139 ## POSIX Spawn
140
06898a2 @mike-burns Spruce up the README
mike-burns authored
141 You can potentially increase performance by installing [the posix-spawn
142 gem](https://rubygems.org/gems/posix-spawn). This gem can keep your
143 application's heap from being copied when forking command line
144 processes. For applications with large heaps the gain can be
145 significant. To include `posix-spawn`, simply add it to your `Gemfile` or,
146 if you don't use bundler, install the gem.
147
910fcce @jyurek Version 0.3.1
jyurek authored
148 ## Runners
149
150 Cocaine will attempt to choose from among 3 different ways of running commands.
151 The simplest is using backticks, and is the default in 1.8. In Ruby 1.9, it
152 will attempt to use `Process.spawn`. And, as mentioned above, if the
153 `posix-spawn` gem is installed, it will attempt to use that. If for some reason
154 one of the `.spawn` runners don't work for you, you can override them manually
155 by setting a new runner, like so:
156
157 ```ruby
86d9c64 @cthulhu666 BackticksRunner doc fix
cthulhu666 authored
158 Cocaine::CommandLine.runner = Cocaine::CommandLine::BackticksRunner.new
910fcce @jyurek Version 0.3.1
jyurek authored
159 ```
160
161 And if you really want to, you can define your own Runner, though I can't
162 imagine why you would.
163
9d30a12 @kirs Mention spawn problem on JRuby on README
kirs authored
164 ### JRuby issues
165
166 #### Caveat
910fcce @jyurek Version 0.3.1
jyurek authored
167
168 If you get `Error::ECHILD` errors and are using JRuby, there is a very good
169 chance that the error is actually in JRuby. This was brought to our attention
170 in https://github.com/thoughtbot/cocaine/issues/24 and probably fixed in
171 http://jira.codehaus.org/browse/JRUBY-6162. You *will* want to use the
172 `BackticksRunner` if you are unable to update JRuby.
173
9d30a12 @kirs Mention spawn problem on JRuby on README
kirs authored
174 #### Spawn warning
175
176 If you get `unsupported spawn option: out` warning (like in [issue 38](https://github.com/thoughtbot/cocaine/issues/38)),
177 try to use `PopenRunner`:
178
179 ```ruby
180 Cocaine::CommandLine.runner = Cocaine::CommandLine::PopenRunner.new
181 ```
182
e61a678 @jyurek Don't use ClimateControl when it's not necessary
jyurek authored
183 ## Thread Safety
184
185 Cocaine should be thread safe. As discussed [here, in this climate_control
186 thread](https://github.com/thoughtbot/climate_control/pull/11), climate_control,
187 which modifies the environment under which commands are run for the
188 BackticksRunner and PopenRunner, is thread-safe but not reentrant. Please let us
189 know if you find this is ever not the case.
9d30a12 @kirs Mention spawn problem on JRuby on README
kirs authored
190
06898a2 @mike-burns Spruce up the README
mike-burns authored
191 ## Feedback
192
193 *Security* concerns must be privately emailed to
194 [security@thoughtbot.com](security@thoughtbot.com).
195
196 Question? Idea? Problem? Bug? Comment? Concern? Like using question marks?
197
198 [GitHub Issues For All!](https://github.com/thoughtbot/cocaine/issues)
6fb2bf1 @jyurek Update the README
jyurek authored
199
5cfb85d [#42] Add Credits section
Adarsh Pandit authored
200 ## Credits
201
ee7b2bd Add shout-out to contributors
Adarsh Pandit authored
202 Thank you to all [the contributors](https://github.com/thoughtbot/cocaine/graphs/contributors)!
203
5cfb85d [#42] Add Credits section
Adarsh Pandit authored
204 ![thoughtbot](http://thoughtbot.com/logo.png)
205
56bd9e7 Fix embarassing repo name error
Adarsh Pandit authored
206 Cocaine is maintained and funded by [thoughtbot, inc](http://thoughtbot.com/community)
5cfb85d [#42] Add Credits section
Adarsh Pandit authored
207
208 The names and logos for thoughtbot are trademarks of thoughtbot, inc.
209
464d2ab @jyurek README and LICENSE
jyurek authored
210 ## License
211
4e3439b Update copyright to 2014
Adarsh Pandit authored
212 Copyright 2011-2014 Jon Yurek and thoughtbot, inc. This is free software, and
06898a2 @mike-burns Spruce up the README
mike-burns authored
213 may be redistributed under the terms specified in the
214 [LICENSE](https://github.com/thoughtbot/cocaine/blob/master/LICENSE)
215 file.
Something went wrong with that request. Please try again.