Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 143 lines (105 sloc) 4.007 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
20 line = Cocaine::CommandLine.new("convert", ":in -scale :resolution :out",
21 :in => "omg.jpg",
22 :resolution => "32x32",
904a17f @citrus added missing quotation mark to dynamic argument example
citrus authored
23 :out => "omg_thumb.jpg")
0f60aee @jjb pretty syntax highlighting
jjb authored
24 line.command # => "convert 'omg.jpg' -scale '32x32' 'omg_thumb.jpg'"
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
30 line = Cocaine::CommandLine.new("cat", ":file", :file => "haha`rm -rf /`.txt")
31 line.command # => "cat 'haha`rm -rf /`.txt'"
464d2ab @jyurek README and LICENSE
jyurek authored
32
0f60aee @jjb pretty syntax highlighting
jjb authored
33 line = Cocaine::CommandLine.new("cat", ":file", :file => "ohyeah?'`rm -rf /`.ha!")
34 line.command # => "cat 'ohyeah?'\\''`rm -rf /`.ha!'"
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
108 line = Cocaine::CommandLine.new("echo", ":var", :var => "LOL!", :logger => Logger.new(STDOUT))
109 line.run # => Logs this with #info -> Command :: echo 'LOL!'
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
128 ## Feedback
129
130 *Security* concerns must be privately emailed to
131 [security@thoughtbot.com](security@thoughtbot.com).
132
133 Question? Idea? Problem? Bug? Comment? Concern? Like using question marks?
134
135 [GitHub Issues For All!](https://github.com/thoughtbot/cocaine/issues)
6fb2bf1 @jyurek Update the README
jyurek authored
136
464d2ab @jyurek README and LICENSE
jyurek authored
137 ## License
138
06835ec Update Copyright years in LICENSE and README.md
Adarsh Pandit authored
139 Copyright 2011-2012 Jon Yurek and thoughtbot, inc. This is free software, and
06898a2 @mike-burns Spruce up the README
mike-burns authored
140 may be redistributed under the terms specified in the
141 [LICENSE](https://github.com/thoughtbot/cocaine/blob/master/LICENSE)
142 file.
Something went wrong with that request. Please try again.