open4ssh 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 26bd3a93e22a85fff7203c396a7f9a63c9370b2d
-  data.tar.gz: 4ef5d35b8d5770e9d67c32da55e06f04552478af
+  metadata.gz: 8c596e78cb2d1cb9e2928862634b22b0f727645f
+  data.tar.gz: 143940e4d7e01d4d1f86200247787469c7384b08
 SHA512:
-  metadata.gz: 2913a4e37a357677c7865581f6108ed91c9633e6d3f5b0160654b4a94cc51217fd8775354c3d42f45ff888ac8b9d655e1f4827ac765eac975cb148f3255f7bce
-  data.tar.gz: a384c9dd93d1964c060be4bf1aedf3994f0530d926152db775169a552fa299b9c18f4db0277322db0f4a36063b14887c11d20e2e03eb614af62f28cbca7e035e
+  metadata.gz: ef404db109f30939eacf686b5a7b2814259e17f8ea9225fb59fd9631856f2c90c1dfd1603846ab16dad4024877de65d5ab5f584fb4c4813468cea7b3f7bf97a3
+  data.tar.gz: c5e152ec8690b969c647e61844b0b17f3eef4f602e849dfcd3ad8b5c247f897a8aa7ebfdb2898adc09dfbb8895566b0eb93bb0a98621ff873f6afac86c4ab7c4

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## Version 0.1.3
+
+- Added unit tests.
+- Added <code>capture3()</code> function.
+- Optimized documentation.
+
 ## Version 0.1.2
 
 - Added <code>success(), stdout(), stderr(), console()</code> functions.

data/Rakefile

@@ -1,8 +1,14 @@
 require "bundler/gem_tasks"
 require 'yard'
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/test_*.rb']
+  t.verbose = true
+end
 
 YARD::Rake::YardocTask.new do |t|
-  t.files   = ['lib/**/*.rb', '-', 'README.md', 'LICENSE.txt', 'CHANGELOG.md']
-  # t.options = ['--any', '--extra', '--opts']
+  t.files   = ['lib/**/*.rb', 'test/**/*.rb', '-', 'README.md', 'LICENSE.txt', 'CHANGELOG.md']
   t.stats_options = ['--list-undoc']
 end

data/lib/open4ssh/version.rb

@@ -1,3 +1,6 @@
 module Open4ssh
-  VERSION = "0.1.2"
+
+  # Version of Open4ssh according to {http://semver.org semantic versioning}
+  #
+  VERSION = "0.1.3"
 end

data/lib/open4ssh.rb

@@ -1,6 +1,30 @@
 require "open4ssh/version"
 require "net/ssh"
 
+# Open4ssh is a small convenience wrapper for {https://rubygems.org/gems/net-ssh net-ssh}.
+# Its intended and primary purpose is to provide pragmatic
+# execution of shell commands on a remote host via SSH.
+#
+# It provides the following functions:
+#
+# - {capture} to execute one command on a remote host via SSH and get the console output back.
+# - {capture3} to execute one command on a remote host via SSH and get the exit code, standard out, standard error of the command back.
+# - {capture4} to execute a sequence of commands on a remote host via SSH and get all return values (exit code, standard out, standard error, command) back.
+# - {success} to evaluate whether a sequence of commands was successful.
+# - {stdout} to get all standard out messages of a sequence of commands.
+# - {stderr} to get all standard error messages of a sequence of commands.
+# - {console} to get all console output (union of standard out and standard error messages) of a sequence of commands.
+#
+# @author Nane Kratzke
+# @example
+#   console = Open4ssh.capture(
+#       host: 'remote.host.io',
+#       user: 'nane',
+#       pwd: 'secret',
+#       cmd: 'ls -la'
+#   )
+#   puts console
+#
 module Open4ssh
 
   # Executes a shell command on a remote host via SSH and captures the console output.
@@ -27,14 +51,41 @@ module Open4ssh
     stdout = ""
     keys = [key]
 
-    Net::SSH.start(host, user, port: 22, password: pwd, keys: keys) do |ssh|
-      result = ssh.exec!(cmd)
-      stdout = result
+    Net::SSH.start(host, user, port: port, password: pwd, keys: keys) do |ssh|
+      stdout = ssh.exec!(cmd)
     end
 
     return stdout
   end
 
+  # Executes one shell command on a remote host via SSH and captures it exit code, stdout and stderr.
+  #
+  # @param host [String] DNS name or IP address of the remote host (required)
+  # @param port [Integer] Port (defaults to 22)
+  # @param user [String] User name (required)
+  # @param key [Path] Path to a key file (.pem) if user logs in via keyfile (not required if password is provided)
+  # @param pwd [String] Password of user (not required if key is provided)
+  # @param cmd [String] shell command string to be executed on host (required)
+  # @param verbose [Bool] console outputs are plotted to stdout/stderr if set (defaults to false)
+  #
+  # @return [exit_code, std_out, std_err] exit_code, stdout, stderr of executed command
+  #
+  # @example
+  #   exit_code, std_err, std_out = Open4ssh.capture3(
+  #     host: 'remote.host.io',
+  #     user: 'nane',
+  #     pwd: 'secret',
+  #     cmd: 'ls -la'
+  #   )
+  #
+  def self.capture3(host: '', user: '', port: 22, key: '', pwd: '', cmd: '', verbose: false)
+    returns = self.capture4(host: host, user: user, port: port, key: key, pwd: pwd, cmd: [cmd], verbose: verbose)
+    exit_code = returns.last[0]
+    std_out = returns.last[1]
+    std_err = returns.last[2]
+    return exit_code, std_out, std_err
+  end
+
   # Executes a list of shell commands on a remote host via SSH and captures their exit codes, stdouts and stderrs.
   # The commands are executed sequentially until a command terminates with an exit code not equal 0 (no success).
   #

data/open4ssh.gemspec

@@ -30,6 +30,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "bundler", "~> 1.10"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "yard", "~> 0.8"
+  spec.add_development_dependency "test-unit", "~> 3.2"
 
   spec.add_runtime_dependency "net-ssh", "~> 3.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: open4ssh
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Nane Kratzke
@@ -52,6 +52,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: test-unit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
 - !ruby/object:Gem::Dependency
   name: net-ssh
   requirement: !ruby/object:Gem::Requirement