open4ssh 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 64411bd7946581982389a29fa49974703aaac6a4
-  data.tar.gz: 7dae3d9662aa2373ffd4246a3a2f4b76b7e3531b
+  metadata.gz: 26bd3a93e22a85fff7203c396a7f9a63c9370b2d
+  data.tar.gz: 4ef5d35b8d5770e9d67c32da55e06f04552478af
 SHA512:
-  metadata.gz: 412afd60971d813b4febfbcea213f10965f25163a7ed3486c6b1b85b219d9701c3cfc7c5af91934caadd12fd7432ebe24afabc7535326732c235846ee96f9bef
-  data.tar.gz: d50cd2d1c3f7bf6bbfa42b6941aa6ad2f7471b3785bbc0a93c057aae5d3550477d70b4b6225f47502072030a01cfa88b433471fd2089a2351e88598a53c4978c
+  metadata.gz: 2913a4e37a357677c7865581f6108ed91c9633e6d3f5b0160654b4a94cc51217fd8775354c3d42f45ff888ac8b9d655e1f4827ac765eac975cb148f3255f7bce
+  data.tar.gz: a384c9dd93d1964c060be4bf1aedf3994f0530d926152db775169a552fa299b9c18f4db0277322db0f4a36063b14887c11d20e2e03eb614af62f28cbca7e035e

data/CHANGELOG.md

@@ -1,15 +1,20 @@
 # Changelog
 
+## Version 0.1.2
+
+- Added <code>success(), stdout(), stderr(), console()</code> functions.
+- Optimized documentation. 
+
 ## Version 0.1.1
 
 Warning, this update is not backward compatible.
 
-- renamed exec to capture function (better alignment to Open3)
-- renamed exec3 to capture3 function (better alignment to Open3)
+- Renamed <code>exec</code> to <code>capture</code> function (better alignment to Open3)
+- Renamed <code>exec4</code> to <code>capture4</code> function (better alignment to Open3)
 
 ## Version 0.1.0
 
 Initial release.
 
-- exec function
-- exec3 function
+- Introduced <code>exec</code> function.
+- Introduced <code>exec4</code> function.

data/README.md

@@ -15,6 +15,10 @@ sequence of commands and returns their exit codes, standard out and standard err
 
 Open4ssh is most useful in remote automation scenarios which are triggered from Ruby environments.
 
+- [RubyGems](https://rubygems.org/gems/open4ssh)
+- [CHANGELOG](file.CHANGELOG.html)
+- [LICENSE](file.LICENSE.html)
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -33,9 +37,9 @@ Or install it yourself as:
 
 ## Usage
 
-### Remote execution of a single command via SSH
+### Remote execution of a single command via SSH using <code>capture()</code>
 
-All parameters of the _capture_ command are explained [here](Open4ssh.html#capture-class_method).
+All parameters of the <code>capture()</code> command are explained [here](Open4ssh.html#capture-class_method).
 
 However, the following snippets explain how to use Open4ssh. 
 To execute simply one single command on a remote host, we can do the following:
@@ -69,9 +73,9 @@ stdout = Open4ssh.capture(
 puts stdout
 ```
 
-### Remote execution of a sequence of commands via SSH
+### Remote execution of a sequence of commands via SSH using <code>capture4()</code>
 
-All parameters of the _capture4_ command are explained [here](Open4ssh.html#capture4-class_method).
+All parameters of the <code>capture4()</code> function are explained [here](Open4ssh.html#capture4-class_method).
 The following snippets will explain how to use Open4ssh to execute a (sequence) of commands.
 
 This snippet here will execute five shell commands sequentially
@@ -108,7 +112,7 @@ So, for each command a list of return values is returned.
 1. exit code of the executed command
 2. standard out message (might be empty)
 3. standard error message (might be empty)
-4. executed command (as passed by the _cmd_ parameter in _exec4_ call.
+4. executed command (as passed by the _cmd_ parameter)
 
 However, if we launch a sequence of commands exiting with exit codes not equal 0, this sequence is only executed as long as 
 each command could be successfully processed (exit code 0). So this snippet here
@@ -140,13 +144,13 @@ would produce the following output
      
 and the last two commands would not been executed on the remote host, because the third command failed.
 
-### How to check whether a sequence of commands was successful?
+### How to check whether a sequence of commands was successful? Use <code>success()</code>
 
 Because Open4ssh only executes commands as long as they are returning a exit code of 0, we can check 
 pragmatically whether all commands of a sequence have been executed successfully:
 
 ```ruby
-exit_code, stderr, stdout, command = Open4ssh.capture4(
+returns = Open4ssh.capture4(
      host: 'remote.host.io',
      user: 'nane',
      key: '/path/to/your/sshkey.pem',
@@ -157,59 +161,77 @@ exit_code, stderr, stdout, command = Open4ssh.capture4(
        "cat helloworld.txt",
        "rm helloworld.txt"
      ]
-).last
+)
 
-if (exit_code == 0 && command == "rm helloworld.txt")
+if Open4ssh.success(returns)
     puts "Everything worked fine"
 end
 ```
 
-### What is this good for?
+### Verbose mode
 
-Just a small example. Assuming your remote host is a Ubuntu 14.04 system we could do something like that:
+If you want to know what is happening there you can turn on the verbose mode (mostly useful for debugging).
 
 ```ruby
-exit_code, stdout, stderr, command = Open4ssh.capture4(
+returns = Open4ssh.capture4(
      host: 'remote.host.io',
      user: 'nane',
      key: '/path/to/your/sshkey.pem',
      cmd: [
        "curl -fsSL https://test.docker.com/ | sh",
        "sudo docker swarm init"
-     ]
-).last
+     ],
+     verbose: true
+)
 
-if (command == "sudo docker swarm init" && exit_code == 0)
+if Open4ssh.success(returns)
     puts "You started successfully a new Docker Swarm cluster."
 end
 ```
 
-This would fire up an initial master for a [Docker Swarm cluster](https://docs.docker.com/engine/swarm/) 
-in a few lines of Ruby code. Be patient. This can take several minutes. 
-Of course, you can do any other tasks as well. This was only one example ;-)
+This will perform the same install like above but will print all messages of the Docker install script on your console.
 
-### Verbose mode
+### How to get stdout and stderr outputs? Use <code>stdout(), stderr(), console()</code>
 
-If you want to know what is happening there you can turn on the verbose mode (mostly useful for debugging).
+It is possible to print all standard output and error messages of
+sequentially executed commands by calling <code>stdout()</code>, <code>stderr()</code> or <code>console()</code>
+with the return of a <code>capture4()</code> call.
 
 ```ruby
-exit_code, stdout, stderr, command = Open4ssh.capture4(
+# This will print all standard output messages of all executed commands.
+puts Open4ssh.stdout(returns)
+
+# This will print all standard error messages of all executed commands.
+puts Open4ssh.stderr(returns)
+
+# This will print all console output messages of all executed commands 
+# (which includes standard out and standard err messages).
+puts Open4ssh.console(returns) 
+```
+
+### What is this good for?
+
+Just a small example. Assuming your remote host is a Ubuntu 14.04 system we could do something like that:
+
+```ruby
+returns = Open4ssh.capture4(
      host: 'remote.host.io',
      user: 'nane',
      key: '/path/to/your/sshkey.pem',
      cmd: [
        "curl -fsSL https://test.docker.com/ | sh",
        "sudo docker swarm init"
-     ],
-     verbose: true
-).last
+     ]
+)
 
-if (command == "sudo docker swarm init" && exit_code == 0)
+if Open4ssh.success(returns)
     puts "You started successfully a new Docker Swarm cluster."
 end
 ```
 
-This will perform the same install like above but will print all messages of the Docker install script on your console.
+This would fire up an initial master for a [Docker Swarm cluster](https://docs.docker.com/engine/swarm/) 
+in a few lines of Ruby code. Be patient. This can take several minutes. 
+Of course, you can do any other tasks as well. This was only one example ;-)
 
 ## Development
 
@@ -221,8 +243,13 @@ push git commits and tags, and push the `.gem` file to [rubygems.org](https://ru
 
 ## Contributing
 
-Bug reports and pull requests are welcome on Github at https://github.com/nkratzke/open4ssh.
+All kind of 
+
+- bug reports,
+- feature requests, 
+- and pull requests 
 
+are welcome on Github at https://github.com/nkratzke/open4ssh.
 
 ## License
 

data/lib/open4ssh/version.rb

@@ -1,3 +1,3 @@
 module Open4ssh
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

data/lib/open4ssh.rb

@@ -46,7 +46,7 @@ module Open4ssh
   # @param cmd [Array<String>] List of valid shell command strings to be executed on host (required)
   # @param verbose [Bool] console outputs are plotted to stdout/stderr if set (defaults to false)
   #
-  # @return [Array<exit_code, stdout, stderr, command>] List of exit_code, stdout, stderr and executed commands
+  # @return [Array<exit_code, std_out, std_err, command>] List of exit_code, stdout, stderr and executed commands
   #
   # @example
   #   exit_code, stderr, stdout, command = Open4ssh.capture4(
@@ -101,4 +101,122 @@ module Open4ssh
 
     return results
   end
+
+  # Determines whether a list of shell commands has been executed successfully.
+  #
+  # @param results [Array<exit_code, std_out, std_err, command>] List of returns by executed commands as returned by capture4
+  #
+  # @return [Bool] true, if all exit codes are 0;
+  # @return [Bool] false, otherwise
+  #
+  # @example
+  #   ecodes = Open4ssh.capture4(
+  #     host: 'remote.host.io',
+  #     user: 'nane',
+  #     key: '/path/to/your/sshkey.pem',
+  #     cmd: [
+  #       "touch helloworld.txt",
+  #       "cat helloworld.txt",
+  #       "echo 'Hello World' >> helloworld.txt",
+  #       "cat helloworld.txt",
+  #       "rm helloworld.txt"
+  #   ])
+  #
+  #   if Open4ssh.success(ecodes)
+  #      puts "Success:"
+  #      puts Open4ssh.console(ecodes) # Print collected console outputs of all executed commands
+  #   end
+  #
+  def self.success(results)
+    results.select { |result| result[0] != 0 }
+        .empty?
+  end
+
+  # Collects all stdout messages of a list of executed shell commands.
+  #
+  # @param results [Array<exit_code, std_out, std_err, command>] List of returns by executed commands as returned by capture4
+  #
+  # @return [String] All stdout messages (separated by line feed \n)
+  #
+  # @example
+  #   ecodes = Open4ssh.capture4(
+  #     host: 'remote.host.io',
+  #     user: 'nane',
+  #     key: '/path/to/your/sshkey.pem',
+  #     cmd: [
+  #       "touch helloworld.txt",
+  #       "cat helloworld.txt",
+  #       "echo 'Hello World' >> helloworld.txt",
+  #       "cat helloworld.txt",
+  #       "rm helloworld.txt"
+  #   ])
+  #
+  #   if Open4ssh.success(ecodes)
+  #      puts "Success:"
+  #      puts Open4ssh.stdout(ecodes) # Print collected stdout messages of all executed commands
+  #   end
+  #
+  def self.stdout(results)
+    output = results.map { |result| result[1] }
+                 .select {  |stdout| not stdout.strip.empty? } * "\n"
+    output.strip
+  end
+
+  # Collects all stderr messages of a list of executed shell commands.
+  #
+  # @param results [Array<exit_code, std_out, std_err, command>] List of returns by executed commands as returned by capture4
+  #
+  # @return [String] All stderr messages (separated by line feed \n)
+  #
+  # @example
+  #   ecodes = Open4ssh.capture4(
+  #     host: 'remote.host.io',
+  #     user: 'nane',
+  #     key: '/path/to/your/sshkey.pem',
+  #     cmd: [
+  #       "touch helloworld.txt",
+  #       "cat helloworld.txt",
+  #       "this will fail",
+  #       "cat helloworld.txt",
+  #       "rm helloworld.txt"
+  #   ])
+  #
+  #   unless Open4ssh.success(ecodes)
+  #      puts "Failure:"
+  #      puts Open4ssh.stderr(ecodes) # Print collected stderr messages of all executed commands
+  #   end
+  #
+  def self.stderr(results)
+    output = results.map { |result| result[2] }
+                 .select { |stderr| not stderr.strip.empty? } * "\n"
+    output.strip
+  end
+
+  # Collects all console messages (stdout + stderr) of a list of executed shell commands.
+  #
+  # @param results [Array<exit_code, std_out, std_err, command>] List of returns by executed commands as returned by capture4
+  #
+  # @return [String] All console messages (separated by line feed \n)
+  #
+  # @example
+  #   ecodes = Open4ssh.capture4(
+  #     host: 'remote.host.io',
+  #     user: 'nane',
+  #     key: '/path/to/your/sshkey.pem',
+  #     cmd: [
+  #       "touch helloworld.txt",
+  #       "cat helloworld.txt",
+  #       "echo 'Hello World' >> helloworld.txt",
+  #       "cat helloworld.txt",
+  #       "rm helloworld.txt"
+  #   ])
+  #
+  #   puts Open4ssh.console(ecodes) # Print collected console messages of all executed commands
+  #
+  def self.console(results)
+    output = results.map { |result| "#{result[1]}\n#{result[2]}" }
+                 .select { |console| not console.strip.empty? } * "\n"
+    output.strip
+  end
+
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: open4ssh
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Nane Kratzke
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-07-02 00:00:00.000000000 Z
+date: 2016-07-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler