Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 180 lines (133 sloc) 5.524 kb
ac47b6f Gabe Berke-Williams 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 Jon Yurek 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 Jon Yurek Adds a feedback section to the README
jyurek authored
6
464d2ab Jon Yurek README and LICENSE
jyurek authored
7 ## Usage
8
06898a2 Mike Burns Spruce up the README
mike-burns authored
9 The basic, normal stuff:
464d2ab Jon Yurek README and LICENSE
jyurek authored
10
0f60aee John Bachir 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 John Bachir pretty syntax highlighting
jjb authored
15 ```
464d2ab Jon Yurek README and LICENSE
jyurek authored
16
06898a2 Mike Burns Spruce up the README
mike-burns authored
17 Interpolated arguments:
464d2ab Jon Yurek README and LICENSE
jyurek authored
18
0f60aee John Bachir 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 John Bachir pretty syntax highlighting
jjb authored
25 ```
464d2ab Jon Yurek README and LICENSE
jyurek authored
26
f96add7 Gabe Berke-Williams Let's use colons in the README.
gabebw authored
27 It prevents attempts at being bad:
464d2ab Jon Yurek README and LICENSE
jyurek authored
28
0f60aee John Bachir 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 Jon Yurek 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 John Bachir pretty syntax highlighting
jjb authored
35 ```
464d2ab Jon Yurek README and LICENSE
jyurek authored
36
f96add7 Gabe Berke-Williams Let's use colons in the README.
gabebw authored
37 You can ignore the result:
464d2ab Jon Yurek README and LICENSE
jyurek authored
38
0f60aee John Bachir 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 Jon Yurek README and LICENSE
jyurek authored
42
0f60aee John Bachir pretty syntax highlighting
jjb authored
43 # ... and on Windows...
44 line.command # => "noisy --extra-verbose 2>NUL"
45 ```
464d2ab Jon Yurek README and LICENSE
jyurek authored
46
f96add7 Gabe Berke-Williams Let's use colons in the README.
gabebw authored
47 If your command errors, you get an exception:
464d2ab Jon Yurek README and LICENSE
jyurek authored
48
0f60aee John Bachir 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 Jon Yurek 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 Gabe Berke-Williams Let's use colons in the README.
gabebw authored
69 You don't have the command? You get an exception:
464d2ab Jon Yurek README and LICENSE
jyurek authored
70
0f60aee John Bachir 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 Jon Yurek README and LICENSE
jyurek authored
79
f96add7 Gabe Berke-Williams Let's use colons in the README.
gabebw authored
80 But don't fear, you can specify where to look for the command:
464d2ab Jon Yurek README and LICENSE
jyurek authored
81
0f60aee John Bachir pretty syntax highlighting
jjb authored
82 ```ruby
83 Cocaine::CommandLine.path = "/opt/bin"
84 line = Cocaine::CommandLine.new("lolwut")
6fb2bf1 Jon Yurek Update the README
jyurek authored
85 line.command # => "lolwut", but it looks in /opt/bin for it.
86 ```
87
f96add7 Gabe Berke-Williams Let's use colons in the README.
gabebw authored
88 You can even give it a bunch of places to look:
6fb2bf1 Jon Yurek Update the README
jyurek authored
89
90 ```ruby
f96add7 Gabe Berke-Williams 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 Gabe Berke-Williams 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 John Bachir pretty syntax highlighting
jjb authored
96 ```
464d2ab Jon Yurek README and LICENSE
jyurek authored
97
f96add7 Gabe Berke-Williams Let's use colons in the README.
gabebw authored
98 Or just put it in the command:
464d2ab Jon Yurek README and LICENSE
jyurek authored
99
0f60aee John Bachir pretty syntax highlighting
jjb authored
100 ```ruby
101 line = Cocaine::CommandLine.new("/opt/bin/lolwut")
102 line.command # => "/opt/bin/lolwut"
103 ```
464d2ab Jon Yurek README and LICENSE
jyurek authored
104
6fb2bf1 Jon Yurek 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 Jon Yurek Update the README
jyurek authored
110 ```
111
06898a2 Mike Burns Spruce up the README
mike-burns authored
112 Or log every command:
6fb2bf1 Jon Yurek 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 Brian Durand 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 Jon Yurek 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
6073cd0 Jon Yurek Remove official support for REE
jyurek authored
152 ## REE
153
154 So, here's the thing about REE: The specs that involve timeouts don't work
155 there. Not because the logic is unsound, but because the command runs really
156 slowly. The test passes -- eventually. This was verified using an external
157 debugger: the process that REE kicks off in the tests reads and writes
158 surprisingly slowly. For this reason, we cannot recommend using Cocaine with
159 REE anymore.
160
161 It's not something we like, so if anyone has any insight into this problem,
162 we'd love to hear about it. But, for the time being, we'll consider it more
163 appropriate to just not use it anymore. Upgrade to 1.9.3, people.
164
06898a2 Mike Burns Spruce up the README
mike-burns authored
165 ## Feedback
166
167 *Security* concerns must be privately emailed to
168 [security@thoughtbot.com](security@thoughtbot.com).
169
170 Question? Idea? Problem? Bug? Comment? Concern? Like using question marks?
171
172 [GitHub Issues For All!](https://github.com/thoughtbot/cocaine/issues)
6fb2bf1 Jon Yurek Update the README
jyurek authored
173
464d2ab Jon Yurek README and LICENSE
jyurek authored
174 ## License
175
06835ec Adarsh Pandit Update Copyright years in LICENSE and README.md
adarsh authored
176 Copyright 2011-2012 Jon Yurek and thoughtbot, inc. This is free software, and
06898a2 Mike Burns Spruce up the README
mike-burns authored
177 may be redistributed under the terms specified in the
178 [LICENSE](https://github.com/thoughtbot/cocaine/blob/master/LICENSE)
179 file.
Something went wrong with that request. Please try again.