Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 126 lines (92 sloc) 3.384 kB
464d2ab @jyurek README and LICENSE
jyurek authored
1 # Cocaine
2
3 A small library for doing (command) lines.
4
7f11075 @jyurek Adds a feedback section to the README
jyurek authored
5 ## Feedback
6
7 Question? Idea? Problem? Bug? Something else? Comment? Concern? Like use question marks?
8
9 [GitHub Issues For All!](https://github.com/thoughtbot/cocaine/issues)
10
464d2ab @jyurek README and LICENSE
jyurek authored
11 ## Usage
12
13 The basic, normal stuff.
14
0f60aee @jjb pretty syntax highlighting
jjb authored
15 ```ruby
16 line = Cocaine::CommandLine.run("command", "some 'crazy' options")
17 line.command # => "command some 'crazy' options"
18 output = line.run # => Get you some output!
19 ```
464d2ab @jyurek README and LICENSE
jyurek authored
20
21 Allowing arguments to be dynamic.
22
0f60aee @jjb pretty syntax highlighting
jjb authored
23 ```ruby
24 line = Cocaine::CommandLine.new("convert", ":in -scale :resolution :out",
25 :in => "omg.jpg",
26 :resolution => "32x32",
27 :out => omg_thumb.jpg")
28 line.command # => "convert 'omg.jpg' -scale '32x32' 'omg_thumb.jpg'"
29 ```
464d2ab @jyurek README and LICENSE
jyurek authored
30
31 It prevents attempts at being bad.
32
0f60aee @jjb pretty syntax highlighting
jjb authored
33 ```ruby
34 line = Cocaine::CommandLine.new("cat", ":file", :file => "haha`rm -rf /`.txt")
35 line.command # => "cat 'haha`rm -rf /`.txt'"
464d2ab @jyurek README and LICENSE
jyurek authored
36
0f60aee @jjb pretty syntax highlighting
jjb authored
37 line = Cocaine::CommandLine.new("cat", ":file", :file => "ohyeah?'`rm -rf /`.ha!")
38 line.command # => "cat 'ohyeah?'\\''`rm -rf /`.ha!'"
39 ```
464d2ab @jyurek README and LICENSE
jyurek authored
40
41 You can ignore the result.
42
0f60aee @jjb pretty syntax highlighting
jjb authored
43 ```ruby
44 line = Cocaine::CommandLine.new("noisy", "--extra-verbose", :swallow_stderr => true)
45 line.command # => "noisy --extra-verbose 2>/dev/null"
464d2ab @jyurek README and LICENSE
jyurek authored
46
0f60aee @jjb pretty syntax highlighting
jjb authored
47 # ... and on Windows...
48 line.command # => "noisy --extra-verbose 2>NUL"
49 ```
464d2ab @jyurek README and LICENSE
jyurek authored
50
51 If your command errors, you get an exception.
52
0f60aee @jjb pretty syntax highlighting
jjb authored
53 ```ruby
54 line = Cocaine::CommandLine.new("git", "commit")
55 begin
56 line.run
57 rescue Cocaine::ExitStatusError => e
58 e.message # => "Command 'git commit' returned 1. Expected 0"
59 end
60 ```
464d2ab @jyurek README and LICENSE
jyurek authored
61
62 You don't have the command? You get an exception.
63
0f60aee @jjb pretty syntax highlighting
jjb authored
64 ```ruby
65 line = Cocaine::CommandLine.new("lolwut")
66 begin
67 line.run
68 rescue Cocaine::CommandNotFoundError => e
69 e # => the command isn't in the $PATH for this process.
70 end
71 ```
464d2ab @jyurek README and LICENSE
jyurek authored
72
73 But don't fear, you can specify where to look for the command.
74
0f60aee @jjb pretty syntax highlighting
jjb authored
75 ```ruby
76 Cocaine::CommandLine.path = "/opt/bin"
77 line = Cocaine::CommandLine.new("lolwut")
6fb2bf1 @jyurek Update the README
jyurek authored
78 line.command # => "lolwut", but it looks in /opt/bin for it.
79 ```
80
81 You can even give it a bunch of places to look.
82
83 ```ruby
84 FileUtils.rm("/opt/bin/lolwut")
85 `echo 'echo Hello' > /usr/local/bin/lolwut`
86 Cocaine::CommandLine.path = ["/opt/bin", "/usr/local/bin"]
87 line = Cocaine::CommandLine.new("lolwut")
88 line.run # => prints 'Hello', because it searches the path
0f60aee @jjb pretty syntax highlighting
jjb authored
89 ```
464d2ab @jyurek README and LICENSE
jyurek authored
90
91 Or, just, you know, put it in the command.
92
0f60aee @jjb pretty syntax highlighting
jjb authored
93 ```ruby
94 line = Cocaine::CommandLine.new("/opt/bin/lolwut")
95 line.command # => "/opt/bin/lolwut"
96 ```
464d2ab @jyurek README and LICENSE
jyurek authored
97
98 If your command might return something non-zero, and you expect that, it's cool.
99
0f60aee @jjb pretty syntax highlighting
jjb authored
100 ```ruby
101 line = Cocaine::CommandLine.new("/usr/bin/false", "", :expected_outcodes => [0, 1])
102 begin
103 line.run
104 rescue Cocaine::ExitStatusError => e
105 # => You never get here!
106 end
107 ```
464d2ab @jyurek README and LICENSE
jyurek authored
108
6fb2bf1 @jyurek Update the README
jyurek authored
109 You can see what's getting run. The 'Command' part it logs is in green for visibility!
110
111 ```ruby
112 line = Cocaine::CommandLine.new("echo", ":var", :var => "LOL!", :logger => Logger.new(STDOUT))
113 line.run # => Logs this with #info -> Command :: echo 'LOL!'
114 ```
115
116 But you don't have to, as you saw above where it doesn't use this. But you CAN log every command!
117
118 ```ruby
119 Cocaine::CommandLine.logger = Logger.new(STDOUT)
120 Cocaine::CommandLine.new("date").run # => Logs this -> Command :: date
121 ```
122
464d2ab @jyurek README and LICENSE
jyurek authored
123 ## License
124
125 Copyright 2011 Jon Yurek and thoughtbot, inc. This is free software, and may be redistributed under the terms specified in the LICENSE file.
Something went wrong with that request. Please try again.