sshkit-custom-dsl 0.0.7 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2fd766977dc760e757d032aeb5afba4a8ecca796
-  data.tar.gz: 244879dd93b7ff53dea9070b59facd6726ef2ab8
+  metadata.gz: d69e7d1a549d382002bb5f7b61505554d86cbea7
+  data.tar.gz: 06927a065efea837d41444920c747f56da9fe253
 SHA512:
-  metadata.gz: ed3e7881c9e5aa5d64165dd2643135b9082701a66b9abbe09e32520b6141a1dcada72a954e658086843958053a9f2b0f02412b882bcb491c52920d88d1b00251
-  data.tar.gz: 0b2e4323dc19009e77c73bdf7693c67dbfc85e34506abffdd442308ea59404bdf556d853a379d6c0ddd3aed68453520405ae0ed3be8ee0a8371f2fecab5bb288
+  metadata.gz: f49e9f43033421eba935a4db6b7b483af95262154a290da5199c9ab6d84828f15bcbe52f5d179d9a700045a129b2ba3ac77bf45b2790d61d942646f3366ab5dd
+  data.tar.gz: ac897cae0d3eb20962659992632d74986ef4f58686e0a468502e68f629465f29b91cbef1a30125159bd6de7d4dad0b42bf94a0de2adc6a39e60fd41de7b23a30

data/.yardopts

@@ -0,0 +1,8 @@
+--tag dsl:"DSL"
+--no-private
+--public
+--api public
+--verbose
+--debug
+--markup-provider=redcarpet
+--markup=markdown

data/Gemfile

@@ -6,5 +6,8 @@ gemspec
 gem 'simplecov', require:  false, group: :test
 gem 'coveralls', require: false
 gem 'rubocop', require: false
+gem 'yard', require: false
+gem 'redcarpet', require: false
+gem 'github-markup', require: false
 
 

data/Rakefile

@@ -1,10 +1,15 @@
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 require 'rubocop/rake_task'
+require 'yard'
 
 RSpec::Core::RakeTask.new(:spec)
 RuboCop::RakeTask.new
 
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ['lib/**/*.rb']   # optional
+end
+
 task default: :spec
 
 desc 'Run RSpec with code coverage'

data/lib/core_ext/sshkit/backend/abstract.rb

@@ -1,5 +1,6 @@
 module SSHKit
   module Backend
+    # Extend (monkeypatch)the original class with some accessors.
     class Abstract
       attr_writer :pwd, :env, :host, :user, :group
 

data/lib/sshkit/custom/config/store.rb

@@ -4,44 +4,63 @@ module SSHKit
       module Store
         module_function
 
+        # @api private
         def scope_storage
           ScopedStorage::ThreadLocalStorage
         end
 
+        # @api private
         def config_scope
           @config_scope ||= ScopedStorage::Scope.new('sshkit_dsl_config', scope_storage)
         end
 
+        # Creates a new runner
+        # @option opts [Symbol] :in Chooses the runner to be used
+        #   :parallel => Parallel
+        #   :sequence => Sequential
+        #   :groups => Group
+        # @option opts [Integer] :wait Amount of seconds to sleep between executions for Sequential and Parallel Runner
+        # @option opts [Integer] :limit Amount of hosts to use in one Batch for Group Runner
+        #
         def create_runner(opts)
           @runner = Runner::Abstract.create_runner opts
         end
 
+        # The actual runner object
         def runner
           @runner.tap { |r| r.backends = backends }
         end
 
+        # Sets the actual backends
         def backends=(hosts)
           @backends = hosts.map { |host| SSHKit.config.backend.new(host) }
         end
 
+        # Get the actual backends
         def backends
           @backends ||= []
         end
 
+        # Set the working directory for the current backend.
+        # @param directory [String] The new working directory
         def add_pwd(directory)
           active_backend.pwd ||= []
           active_backend.pwd << directory
         end
 
+        # Set the working directory to the previous working directory for the current backend.
         def pop_pwd
           active_backend.pwd ||= []
           active_backend.pwd.pop
         end
 
+        # @api private
         def _envs
           config_scope[:_envs] ||= []
         end
 
+        # Set the environment for the current backend.
+        # @param env [Hash<String, String>] The new ENV-Vars to be used.
         def add_env(env)
           old_env =  active_backend.env.clone
           _envs << old_env
@@ -49,27 +68,34 @@ module SSHKit
           active_backend.env = env
         end
 
+        # Resets the environment variables to the previous one.
         def pop_env
           old_env = _envs.pop || {}
           active_backend.env = old_env
         end
 
+        # @api private
         def _user_groups
           config_scope[:_user_groups] ||= []
         end
 
+        # Set the user and group for the current backend.
+        # @param user [String] The new username
+        # @param group [String, nil] The new group
         def add_user_group(user, group)
           _user_groups << { user: active_backend.user, group:  active_backend.group }
           active_backend.user = user
           active_backend.group = group
         end
 
+        # Resets user and group to the previous one.
         def pop_user_group
           old_user_group = _user_groups.pop || {}
           active_backend.user = old_user_group[:user]
           active_backend.group = old_user_group[:group]
         end
 
+        # Returns the active backend in the current thread
         def active_backend
           SSHKit::Custom::Runner::Abstract.active_backend
         end

data/lib/sshkit/custom/dsl/config_statements.rb

@@ -2,6 +2,21 @@ module SSHKit
   module Custom
     module DSL
       module ConfigStatements
+        # Starts the action to be done for named hosts
+        #
+        # @param hosts [Array<String>] the DNS of the hosts to execute the following blocks
+        # @option options [Symbol] :in Chooses the runner to be used
+        #
+        #   * :parallel => Parallel
+        #   * :sequence => Sequential
+        #   * :groups => Group
+        #
+        # @option options [Integer] :wait Amount of seconds to sleep between executions for Sequential and Parallel Runner
+        # @option options [Integer] :limit Amount of hosts to use in one Batch for Group Runner
+        # For a block {|host| ... }
+        # @yield Host for further DSL execution
+        # @dsl
+        # @see SSHKit::Custom::Config::Store#create_runner
         def on(hosts, options = {}, &block)
           hosts = Array(hosts).map { |rh| Host(rh) }.uniq
 
@@ -10,6 +25,13 @@ module SSHKit
           _runner.apply_block_to_bcks(&block) if block_given?
         end
 
+        # Executes all following statements within the named directory.
+        # Multiple call's will stack the directories together. After the block
+        # is executed the working directory is set back.
+        #
+        # @param directory [String] The directory within the statements are executed
+        # @yield Host for further DSL execution
+        # @dsl
         def within(directory)
           _guard_dir!(File.join(_config_store.active_backend.pwd + [directory]))
 
@@ -20,6 +42,13 @@ module SSHKit
           _config_store.pop_pwd
         end
 
+        # Executes all following statements with provided environment variables.
+        # Multiple call's will the environment variables. After the block
+        # is executed the working environment variables are set back.
+        #
+        # @param environment [Hash<String, String>] Environment variables to be set
+        # @yield Host for further DSL execution
+        # @dsl
         def with(environment)
           _config_store.add_env environment
           yield if block_given?
@@ -27,6 +56,13 @@ module SSHKit
           _config_store.pop_env
         end
 
+        # Executes all following statements as the provided user and group (sudo).
+        # After the block is executed the user and group is set back.
+        #
+        # @param who [String, Hash<String, String>] User and group to be set.
+        # Possible Hash keys are :user and :group
+        # @yield Host for further DSL execution
+        # @dsl
         def as(who)
           if who.respond_to? :fetch
             user = who.fetch(:user) { who.fetch('user') }
@@ -46,11 +82,13 @@ module SSHKit
           _config_store.pop_user_group
         end
 
+        # @api private
         def _setup_runner(hosts, options)
           _config_store.backends = hosts
           _config_store.create_runner options
         end
 
+        # @api private
         def _runner
           _config_store.runner
         end

data/lib/sshkit/custom/dsl/exec_statements.rb

@@ -4,12 +4,27 @@ module SSHKit
       module ExecStatements
         EXEC_STATEMENTS = [:execute, :make, :rake, :test, :capture, :upload!, :download!].freeze
 
-        EXEC_STATEMENTS.each do |method|
+        # @api private
+        # @!macro [attach] dsl.create_delegator
+        #   @!method $1(*args, &block)
+        #   @api public
+        #   @ dsl
+        #   Delegates $1 to the runner
+        def self.create_delegator(method)
           define_method method do |*args, &block|
             _config_store.runner.send_cmd method, *args, &block
           end
         end
 
+        create_delegator :execute
+        create_delegator :make
+        create_delegator :rake
+        create_delegator :test
+        create_delegator :capture
+        create_delegator :upload!
+        create_delegator :download!
+
+        # @api private
         def _guard_sudo_user!(user)
           execute <<-EOTEST, verbosity: Logger::DEBUG
             if ! sudo -u #{user} whoami > /dev/null
@@ -19,6 +34,7 @@ module SSHKit
           EOTEST
         end
 
+        # @api private
         def _guard_sudo_group!(user, group)
           execute <<-EOTEST, verbosity: Logger::DEBUG if group
             if ! sudo -u #{user} -g #{group} whoami > /dev/null
@@ -28,6 +44,7 @@ module SSHKit
           EOTEST
         end
 
+        # @api private
         def _guard_dir!(dir_to_check)
           execute <<-EOTEST, verbosity: Logger::DEBUG
            if test ! -d #{dir_to_check}

data/lib/sshkit/custom/dsl/helper.rb

@@ -4,20 +4,41 @@ module SSHKit
       module Helper
         LOGGING_METHODS = [:log, :debug, :fatal, :error, :warn, :info, :debug].freeze
 
+        # @api private
+        # @!macro [attach] dsl_helper.create_backend_delegator
+        #   @!method $1(*args, &block)
+        #   @api public
+        #   @dsl
+        #   Delegates $1 to the active backend
+        def self.create_backend_delegator(method)
+          define_method method do |*args|
+            active_backend.send method, *args
+          end
+        end
+
+        # Returns the active backend in the current thread
+        # @dsl
+        # @see SSHKit::Custom::Config::Store#active_backend
         def active_backend
           SSHKit::Custom::Config::Store.active_backend
         end
 
+        # Return the host of the active backend
         def host
           active_backend.host
         end
 
-        LOGGING_METHODS.each do |method|
-          define_method method do |*args|
-            active_backend.send method, *args
-          end
-        end
+        create_backend_delegator :log
+        create_backend_delegator :debug
+        create_backend_delegator :fatal
+        create_backend_delegator :error
+        create_backend_delegator :warn
+        create_backend_delegator :info
+        create_backend_delegator :debug
 
+        # Conversion function. Converts a host name into a Host object.
+        # @param rh [String, SSHKit::Host] The hostname or a SSHKit::Host object
+        # @dsl
         def Host(rh)
           if rh.is_a?(SSHKit::Host)
             rh
@@ -26,6 +47,7 @@ module SSHKit
           end
         end
 
+        # @api private
         def _config_store
           @_config_store ||= SSHKit::Custom::Config::Store
         end

data/lib/sshkit/custom/dsl/version.rb

@@ -1,7 +1,7 @@
 module SSHKit
   module Custom
     module DSL
-      VERSION = '0.0.7'
+      VERSION = '0.0.8'
     end
   end
 end

data/lib/sshkit/custom/dsl.rb

@@ -12,6 +12,8 @@ require 'sshkit/custom/dsl/config_statements'
 require 'sshkit/custom/dsl/exec_statements'
 require 'sshkit/custom/dsl/helper'
 
+# @api public
+# @public
 module SSHKit
   module Custom
     module DSL

data/lib/sshkit/custom/runner/abstract.rb

@@ -1,13 +1,19 @@
 module SSHKit
   module Custom
+    # @api public
+    # @public
     module Runner
       ExecuteError = SSHKit::Runner::ExecuteError
 
+      # Base class for all runners
+      # @abstract Subclass and override {#apply_block_to_bcks} to implement
+      # @public
       class Abstract
         attr_accessor :backends
         attr_reader :options
         attr_writer :wait_interval
 
+        # Factory method to create a new runner.
         def self.create_runner(opts)
           opts_with_defaults = { in: :parallel }.merge(opts)
 
@@ -23,18 +29,22 @@ module SSHKit
           end.new(opts_with_defaults)
         end
 
+        # @api private
         def self.scope_storage
           ScopedStorage::ThreadLocalStorage
         end
 
+        # @api private
         def self.scope
           @scope ||= ScopedStorage::Scope.new('sshkit_runner', scope_storage)
         end
 
+        # @api private
         def self.active_backend
           scope[:active_backend] || fail(ArgumentError, 'Backend not set')
         end
 
+        # @api private
         def self.active_backend=(new_backend)
           scope[:active_backend] = new_backend
         end
@@ -43,14 +53,20 @@ module SSHKit
           @options = options || {}
         end
 
+        # @api private
         def active_backend
           self.class.active_backend
         end
 
+        # @api private
         def active_backend=(new_backend)
           self.class.active_backend = new_backend
         end
 
+        # Sends the given command to the backend.
+        # @param cmd [Symbol] A command that the sshkit backend supports
+        # @param args [Array] Arguments for the backend command
+        #
         def send_cmd(cmd, *args, &block)
           args = Array(block.call(active_backend.host)) if block
           active_backend.send(cmd, *args)
@@ -59,10 +75,12 @@ module SSHKit
           raise e2, "Exception while executing on host #{active_backend.host}: #{e.message}"
         end
 
+        # @abstract
         def apply_block_to_bcks(&_block)
           fail SSHKit::Backend::MethodUnavailableError
         end
 
+        # @api private
         def apply_to_bck(backend, &block)
           self.active_backend = backend
           block.call(backend.host)
@@ -73,6 +91,7 @@ module SSHKit
           self.active_backend = nil
         end
 
+        # @api private
         def do_wait
           sleep wait_interval
         end

data/lib/sshkit/custom/runner/group.rb

@@ -1,9 +1,13 @@
 module SSHKit
   module Custom
     module Runner
+      # A runner which executes all commands in groups.
+      #
       class Group < Abstract
         attr_writer :group_size
 
+        # Executes all commands in batches of size :group_size
+        # @yields the actual host
         def apply_block_to_bcks(&block)
           backends.each_slice(group_size).map do |group_backends|
 
@@ -14,10 +18,12 @@ module SSHKit
           end.flatten
         end
 
+        # @api private
         def group_size
           @group_size ||= options[:limit] || 2
         end
 
+        # @api private
         def exec_parallel(group, &block)
           use_runner.call(options).tap do |runner|
             runner.backends = group
@@ -25,6 +31,7 @@ module SSHKit
           end
         end
 
+        # @api private
         def use_runner
           ->(options) { Parallel.new(options) }
         end

data/lib/sshkit/custom/runner/parallel.rb

@@ -3,20 +3,26 @@ module SSHKit
     module Runner
       require 'rake'
 
+      # A runner which executes all commands in prallel (different threads).
       class Parallel < Abstract
+        # @api private
         def thread_pool
           @thread_pool ||= Rake::ThreadPool.new(thread_count)
         end
 
+        # Executes all commands parallel
+        # @yields the actual host
         def apply_block_to_bcks(&block)
           futures = to_futures(&block)
           futures.each { |f| f.value }
         end
 
+        # @api private
         def thread_count
           @thread_count ||= options[:thread_count] || Rake.suggested_thread_count - 1
         end
 
+        # @api private
         def to_futures(&block)
           backends.map do |b|
             thread_pool.future(b) do |fb|

data/lib/sshkit/custom/runner/sequential.rb

@@ -1,7 +1,10 @@
 module SSHKit
   module Custom
     module Runner
+      # A runner which executes all commands in sequence.
       class Sequential < Abstract
+        # Executes all commands in sequence
+        # @yields the actual host
         def apply_block_to_bcks(&block)
           backends.each do |backend|
             apply_to_bck backend, &block

data/spec/spec_helper.rb

@@ -34,7 +34,6 @@ Dir[File.join(File.expand_path(__dir__), 'support/**/*.rb')].each { |f| require
 #
 # See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
 RSpec.configure do |config|
-  config.treat_symbols_as_metadata_keys_with_true_values = true
   config.run_all_when_everything_filtered = true
   config.filter_run :focus
 

data/sshkit-custom-dsl.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
   spec.email         = ['d.spaeth@faber.de']
   spec.summary       = %q(Exchanges original sshkit dsl against a custom dsl)
   spec.description   = %q(Exchanges original sshkit dsl against a custom dsl. This DSL does not change the scope of the blocks.)
-  spec.homepage      = ''
+  spec.homepage      = 'https://github.com/faber-lotto/sshkit-custom-dsl'
   spec.license       = 'MIT'
 
   spec.files         = `git ls-files -z`.split("\x0")
@@ -25,7 +25,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'bundler'
   spec.add_development_dependency 'rspec'
 
-  spec.add_development_dependency 'rspec', '2.99.0.rc1'
+  spec.add_development_dependency 'rspec', '3.0.0'
   # show nicely how many specs have to be run
   spec.add_development_dependency 'fuubar'
   # extended console

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sshkit-custom-dsl
 version: !ruby/object:Gem::Version
-  version: 0.0.7
+  version: 0.0.8
 platform: ruby
 authors:
 - Dieter Späth
@@ -86,14 +86,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 2.99.0.rc1
+        version: 3.0.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 2.99.0.rc1
+        version: 3.0.0
 - !ruby/object:Gem::Dependency
   name: fuubar
   requirement: !ruby/object:Gem::Requirement
@@ -151,6 +151,7 @@ files:
 - .rubocop_todo.yml
 - .travis.yml
 - .versions.conf
+- .yardopts
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -184,7 +185,7 @@ files:
 - spec/unit/sshkit/custom/runner/sequential_spec.rb
 - spec/unit_spec_helper.rb
 - sshkit-custom-dsl.gemspec
-homepage: ''
+homepage: https://github.com/faber-lotto/sshkit-custom-dsl
 licenses:
 - MIT
 metadata: {}
@@ -225,3 +226,4 @@ test_files:
 - spec/unit/sshkit/custom/runner/parallel_spec.rb
 - spec/unit/sshkit/custom/runner/sequential_spec.rb
 - spec/unit_spec_helper.rb
+has_rdoc: