open4ssh 0.1.1 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: 64411bd7946581982389a29fa49974703aaac6a4
4
- data.tar.gz: 7dae3d9662aa2373ffd4246a3a2f4b76b7e3531b
3
+ metadata.gz: 26bd3a93e22a85fff7203c396a7f9a63c9370b2d
4
+ data.tar.gz: 4ef5d35b8d5770e9d67c32da55e06f04552478af
5
5
  SHA512:
6
- metadata.gz: 412afd60971d813b4febfbcea213f10965f25163a7ed3486c6b1b85b219d9701c3cfc7c5af91934caadd12fd7432ebe24afabc7535326732c235846ee96f9bef
7
- data.tar.gz: d50cd2d1c3f7bf6bbfa42b6941aa6ad2f7471b3785bbc0a93c057aae5d3550477d70b4b6225f47502072030a01cfa88b433471fd2089a2351e88598a53c4978c
6
+ metadata.gz: 2913a4e37a357677c7865581f6108ed91c9633e6d3f5b0160654b4a94cc51217fd8775354c3d42f45ff888ac8b9d655e1f4827ac765eac975cb148f3255f7bce
7
+ data.tar.gz: a384c9dd93d1964c060be4bf1aedf3994f0530d926152db775169a552fa299b9c18f4db0277322db0f4a36063b14887c11d20e2e03eb614af62f28cbca7e035e
data/CHANGELOG.md CHANGED
@@ -1,15 +1,20 @@
1
1
  # Changelog
2
2
 
3
+ ## Version 0.1.2
4
+
5
+ - Added <code>success(), stdout(), stderr(), console()</code> functions.
6
+ - Optimized documentation.
7
+
3
8
  ## Version 0.1.1
4
9
 
5
10
  Warning, this update is not backward compatible.
6
11
 
7
- - renamed exec to capture function (better alignment to Open3)
8
- - renamed exec3 to capture3 function (better alignment to Open3)
12
+ - Renamed <code>exec</code> to <code>capture</code> function (better alignment to Open3)
13
+ - Renamed <code>exec4</code> to <code>capture4</code> function (better alignment to Open3)
9
14
 
10
15
  ## Version 0.1.0
11
16
 
12
17
  Initial release.
13
18
 
14
- - exec function
15
- - exec3 function
19
+ - Introduced <code>exec</code> function.
20
+ - Introduced <code>exec4</code> function.
data/README.md CHANGED
@@ -15,6 +15,10 @@ sequence of commands and returns their exit codes, standard out and standard err
15
15
 
16
16
  Open4ssh is most useful in remote automation scenarios which are triggered from Ruby environments.
17
17
 
18
+ - [RubyGems](https://rubygems.org/gems/open4ssh)
19
+ - [CHANGELOG](file.CHANGELOG.html)
20
+ - [LICENSE](file.LICENSE.html)
21
+
18
22
  ## Installation
19
23
 
20
24
  Add this line to your application's Gemfile:
@@ -33,9 +37,9 @@ Or install it yourself as:
33
37
 
34
38
  ## Usage
35
39
 
36
- ### Remote execution of a single command via SSH
40
+ ### Remote execution of a single command via SSH using <code>capture()</code>
37
41
 
38
- All parameters of the _capture_ command are explained [here](Open4ssh.html#capture-class_method).
42
+ All parameters of the <code>capture()</code> command are explained [here](Open4ssh.html#capture-class_method).
39
43
 
40
44
  However, the following snippets explain how to use Open4ssh.
41
45
  To execute simply one single command on a remote host, we can do the following:
@@ -69,9 +73,9 @@ stdout = Open4ssh.capture(
69
73
  puts stdout
70
74
  ```
71
75
 
72
- ### Remote execution of a sequence of commands via SSH
76
+ ### Remote execution of a sequence of commands via SSH using <code>capture4()</code>
73
77
 
74
- All parameters of the _capture4_ command are explained [here](Open4ssh.html#capture4-class_method).
78
+ All parameters of the <code>capture4()</code> function are explained [here](Open4ssh.html#capture4-class_method).
75
79
  The following snippets will explain how to use Open4ssh to execute a (sequence) of commands.
76
80
 
77
81
  This snippet here will execute five shell commands sequentially
@@ -108,7 +112,7 @@ So, for each command a list of return values is returned.
108
112
  1. exit code of the executed command
109
113
  2. standard out message (might be empty)
110
114
  3. standard error message (might be empty)
111
- 4. executed command (as passed by the _cmd_ parameter in _exec4_ call.
115
+ 4. executed command (as passed by the _cmd_ parameter)
112
116
 
113
117
  However, if we launch a sequence of commands exiting with exit codes not equal 0, this sequence is only executed as long as
114
118
  each command could be successfully processed (exit code 0). So this snippet here
@@ -140,13 +144,13 @@ would produce the following output
140
144
 
141
145
  and the last two commands would not been executed on the remote host, because the third command failed.
142
146
 
143
- ### How to check whether a sequence of commands was successful?
147
+ ### How to check whether a sequence of commands was successful? Use <code>success()</code>
144
148
 
145
149
  Because Open4ssh only executes commands as long as they are returning a exit code of 0, we can check
146
150
  pragmatically whether all commands of a sequence have been executed successfully:
147
151
 
148
152
  ```ruby
149
- exit_code, stderr, stdout, command = Open4ssh.capture4(
153
+ returns = Open4ssh.capture4(
150
154
  host: 'remote.host.io',
151
155
  user: 'nane',
152
156
  key: '/path/to/your/sshkey.pem',
@@ -157,59 +161,77 @@ exit_code, stderr, stdout, command = Open4ssh.capture4(
157
161
  "cat helloworld.txt",
158
162
  "rm helloworld.txt"
159
163
  ]
160
- ).last
164
+ )
161
165
 
162
- if (exit_code == 0 && command == "rm helloworld.txt")
166
+ if Open4ssh.success(returns)
163
167
  puts "Everything worked fine"
164
168
  end
165
169
  ```
166
170
 
167
- ### What is this good for?
171
+ ### Verbose mode
168
172
 
169
- Just a small example. Assuming your remote host is a Ubuntu 14.04 system we could do something like that:
173
+ If you want to know what is happening there you can turn on the verbose mode (mostly useful for debugging).
170
174
 
171
175
  ```ruby
172
- exit_code, stdout, stderr, command = Open4ssh.capture4(
176
+ returns = Open4ssh.capture4(
173
177
  host: 'remote.host.io',
174
178
  user: 'nane',
175
179
  key: '/path/to/your/sshkey.pem',
176
180
  cmd: [
177
181
  "curl -fsSL https://test.docker.com/ | sh",
178
182
  "sudo docker swarm init"
179
- ]
180
- ).last
183
+ ],
184
+ verbose: true
185
+ )
181
186
 
182
- if (command == "sudo docker swarm init" && exit_code == 0)
187
+ if Open4ssh.success(returns)
183
188
  puts "You started successfully a new Docker Swarm cluster."
184
189
  end
185
190
  ```
186
191
 
187
- This would fire up an initial master for a [Docker Swarm cluster](https://docs.docker.com/engine/swarm/)
188
- in a few lines of Ruby code. Be patient. This can take several minutes.
189
- Of course, you can do any other tasks as well. This was only one example ;-)
192
+ This will perform the same install like above but will print all messages of the Docker install script on your console.
190
193
 
191
- ### Verbose mode
194
+ ### How to get stdout and stderr outputs? Use <code>stdout(), stderr(), console()</code>
192
195
 
193
- If you want to know what is happening there you can turn on the verbose mode (mostly useful for debugging).
196
+ It is possible to print all standard output and error messages of
197
+ sequentially executed commands by calling <code>stdout()</code>, <code>stderr()</code> or <code>console()</code>
198
+ with the return of a <code>capture4()</code> call.
194
199
 
195
200
  ```ruby
196
- exit_code, stdout, stderr, command = Open4ssh.capture4(
201
+ # This will print all standard output messages of all executed commands.
202
+ puts Open4ssh.stdout(returns)
203
+
204
+ # This will print all standard error messages of all executed commands.
205
+ puts Open4ssh.stderr(returns)
206
+
207
+ # This will print all console output messages of all executed commands
208
+ # (which includes standard out and standard err messages).
209
+ puts Open4ssh.console(returns)
210
+ ```
211
+
212
+ ### What is this good for?
213
+
214
+ Just a small example. Assuming your remote host is a Ubuntu 14.04 system we could do something like that:
215
+
216
+ ```ruby
217
+ returns = Open4ssh.capture4(
197
218
  host: 'remote.host.io',
198
219
  user: 'nane',
199
220
  key: '/path/to/your/sshkey.pem',
200
221
  cmd: [
201
222
  "curl -fsSL https://test.docker.com/ | sh",
202
223
  "sudo docker swarm init"
203
- ],
204
- verbose: true
205
- ).last
224
+ ]
225
+ )
206
226
 
207
- if (command == "sudo docker swarm init" && exit_code == 0)
227
+ if Open4ssh.success(returns)
208
228
  puts "You started successfully a new Docker Swarm cluster."
209
229
  end
210
230
  ```
211
231
 
212
- This will perform the same install like above but will print all messages of the Docker install script on your console.
232
+ This would fire up an initial master for a [Docker Swarm cluster](https://docs.docker.com/engine/swarm/)
233
+ in a few lines of Ruby code. Be patient. This can take several minutes.
234
+ Of course, you can do any other tasks as well. This was only one example ;-)
213
235
 
214
236
  ## Development
215
237
 
@@ -221,8 +243,13 @@ push git commits and tags, and push the `.gem` file to [rubygems.org](https://ru
221
243
 
222
244
  ## Contributing
223
245
 
224
- Bug reports and pull requests are welcome on Github at https://github.com/nkratzke/open4ssh.
246
+ All kind of
247
+
248
+ - bug reports,
249
+ - feature requests,
250
+ - and pull requests
225
251
 
252
+ are welcome on Github at https://github.com/nkratzke/open4ssh.
226
253
 
227
254
  ## License
228
255
 
@@ -1,3 +1,3 @@
1
1
  module Open4ssh
2
- VERSION = "0.1.1"
2
+ VERSION = "0.1.2"
3
3
  end
data/lib/open4ssh.rb CHANGED
@@ -46,7 +46,7 @@ module Open4ssh
46
46
  # @param cmd [Array<String>] List of valid shell command strings to be executed on host (required)
47
47
  # @param verbose [Bool] console outputs are plotted to stdout/stderr if set (defaults to false)
48
48
  #
49
- # @return [Array<exit_code, stdout, stderr, command>] List of exit_code, stdout, stderr and executed commands
49
+ # @return [Array<exit_code, std_out, std_err, command>] List of exit_code, stdout, stderr and executed commands
50
50
  #
51
51
  # @example
52
52
  # exit_code, stderr, stdout, command = Open4ssh.capture4(
@@ -101,4 +101,122 @@ module Open4ssh
101
101
 
102
102
  return results
103
103
  end
104
+
105
+ # Determines whether a list of shell commands has been executed successfully.
106
+ #
107
+ # @param results [Array<exit_code, std_out, std_err, command>] List of returns by executed commands as returned by capture4
108
+ #
109
+ # @return [Bool] true, if all exit codes are 0;
110
+ # @return [Bool] false, otherwise
111
+ #
112
+ # @example
113
+ # ecodes = Open4ssh.capture4(
114
+ # host: 'remote.host.io',
115
+ # user: 'nane',
116
+ # key: '/path/to/your/sshkey.pem',
117
+ # cmd: [
118
+ # "touch helloworld.txt",
119
+ # "cat helloworld.txt",
120
+ # "echo 'Hello World' >> helloworld.txt",
121
+ # "cat helloworld.txt",
122
+ # "rm helloworld.txt"
123
+ # ])
124
+ #
125
+ # if Open4ssh.success(ecodes)
126
+ # puts "Success:"
127
+ # puts Open4ssh.console(ecodes) # Print collected console outputs of all executed commands
128
+ # end
129
+ #
130
+ def self.success(results)
131
+ results.select { |result| result[0] != 0 }
132
+ .empty?
133
+ end
134
+
135
+ # Collects all stdout messages of a list of executed shell commands.
136
+ #
137
+ # @param results [Array<exit_code, std_out, std_err, command>] List of returns by executed commands as returned by capture4
138
+ #
139
+ # @return [String] All stdout messages (separated by line feed \n)
140
+ #
141
+ # @example
142
+ # ecodes = Open4ssh.capture4(
143
+ # host: 'remote.host.io',
144
+ # user: 'nane',
145
+ # key: '/path/to/your/sshkey.pem',
146
+ # cmd: [
147
+ # "touch helloworld.txt",
148
+ # "cat helloworld.txt",
149
+ # "echo 'Hello World' >> helloworld.txt",
150
+ # "cat helloworld.txt",
151
+ # "rm helloworld.txt"
152
+ # ])
153
+ #
154
+ # if Open4ssh.success(ecodes)
155
+ # puts "Success:"
156
+ # puts Open4ssh.stdout(ecodes) # Print collected stdout messages of all executed commands
157
+ # end
158
+ #
159
+ def self.stdout(results)
160
+ output = results.map { |result| result[1] }
161
+ .select { |stdout| not stdout.strip.empty? } * "\n"
162
+ output.strip
163
+ end
164
+
165
+ # Collects all stderr messages of a list of executed shell commands.
166
+ #
167
+ # @param results [Array<exit_code, std_out, std_err, command>] List of returns by executed commands as returned by capture4
168
+ #
169
+ # @return [String] All stderr messages (separated by line feed \n)
170
+ #
171
+ # @example
172
+ # ecodes = Open4ssh.capture4(
173
+ # host: 'remote.host.io',
174
+ # user: 'nane',
175
+ # key: '/path/to/your/sshkey.pem',
176
+ # cmd: [
177
+ # "touch helloworld.txt",
178
+ # "cat helloworld.txt",
179
+ # "this will fail",
180
+ # "cat helloworld.txt",
181
+ # "rm helloworld.txt"
182
+ # ])
183
+ #
184
+ # unless Open4ssh.success(ecodes)
185
+ # puts "Failure:"
186
+ # puts Open4ssh.stderr(ecodes) # Print collected stderr messages of all executed commands
187
+ # end
188
+ #
189
+ def self.stderr(results)
190
+ output = results.map { |result| result[2] }
191
+ .select { |stderr| not stderr.strip.empty? } * "\n"
192
+ output.strip
193
+ end
194
+
195
+ # Collects all console messages (stdout + stderr) of a list of executed shell commands.
196
+ #
197
+ # @param results [Array<exit_code, std_out, std_err, command>] List of returns by executed commands as returned by capture4
198
+ #
199
+ # @return [String] All console messages (separated by line feed \n)
200
+ #
201
+ # @example
202
+ # ecodes = Open4ssh.capture4(
203
+ # host: 'remote.host.io',
204
+ # user: 'nane',
205
+ # key: '/path/to/your/sshkey.pem',
206
+ # cmd: [
207
+ # "touch helloworld.txt",
208
+ # "cat helloworld.txt",
209
+ # "echo 'Hello World' >> helloworld.txt",
210
+ # "cat helloworld.txt",
211
+ # "rm helloworld.txt"
212
+ # ])
213
+ #
214
+ # puts Open4ssh.console(ecodes) # Print collected console messages of all executed commands
215
+ #
216
+ def self.console(results)
217
+ output = results.map { |result| "#{result[1]}\n#{result[2]}" }
218
+ .select { |console| not console.strip.empty? } * "\n"
219
+ output.strip
220
+ end
221
+
104
222
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: open4ssh
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.1
4
+ version: 0.1.2
5
5
  platform: ruby
6
6
  authors:
7
7
  - Nane Kratzke
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2016-07-02 00:00:00.000000000 Z
11
+ date: 2016-07-03 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: bundler