rutty 2.1.1 → 2.1.2

data/README.md

@@ -1,23 +1,79 @@
 RuTTY
 =====
 
-RuTTY is a DSH implementation in Ruby.
+RuTTY is a DSH implementation in Ruby. You can use it to execute shell commands on multiple remote
+servers simultaneously using a tagging system to target just the servers you want.
+
+Also supports SCP uploads to multiple remote servers using the same tagging system.
 
 Requirements
 ------------
 
 * Ruby >= 1.8.7 (Not tested on 1.9.x)
 * Rubygems >= 1.3.7
+
+###Development Requirements###
+
 * Bundler >= 1.0.0
 
 Installation
 ------------
 
-	$ sudo gem install bundler
-	$ git clone git://github.com/jlindsey/rutty.git
-	$ cd rutty
-	$ bundle install
-	$ ./rutty --help
+	$ sudo gem install rutty
+	$ rutty init
+	$ rutty help
+
+Usage
+-----
+
+###Init###
+
+You must first initialize the RuTTY configuration and data directory with the `rutty init` command. This
+command takes an optional argument to specify the directory to install into. If omitted, it will install
+into `~/.rutty/`. Note that if you install into a directory other than the default, you will have to supply
+the config to all the other commands with the `-c` option.
+
+	$ rutty init
+	         create  /Users/jlindsey/.rutty
+	         create  /Users/jlindsey/.rutty/defaults.yaml
+	         create  /Users/jlindsey/.rutty/nodes.yaml
+	
+
+###Adding Nodes###
+
+After initialization, you must add nodes to the RuTTY config. This is done with the `rutty add_node` command.
+Invoking `rutty help add_node` will give you a list of all the options to pass into it. Any options you don't pass
+will be filled in from the defaults at `$RUTTY_HOME/defaults.yaml`.
+
+	$ rutty add_node example.com -u root -k /Users/jlindsey/.ssh/id_rsa --tags example,test
+	
+The above will add a node to the RuTTY config that looks like this (in YAML):
+
+	---
+	host: example.com
+	user: root
+	keypath: /Users/jlindsey/.ssh/id_rsa
+	tags:
+		- example
+		- test
+	port: 22
+	
+Note that the `port: 22` line was filled in from the defaults because it was not specified.
+
+###Running Commands###
+
+Now that we have a node, we can run commands on it. The default RuTTY command is the `dsh` action, so it
+can be omitted. That is to say, the following two commands are identical:
+
+	$ rutty dsh -a uptime
+	$ rutty -a uptime
+
+The `dsh` action can accept either a list of tags passed via `--tags` or the `-a` flag, which will run the command
+on all defined nodes regardless of tags.
+
+Note that any command that has any whitespace in it must be enclosed in quotes.
+
+	$ rutty -a "free -m"
 
 TODO
 ----
@@ -28,7 +84,6 @@ TODO
 * Implement delete_node command
 * Make better printouts
 * Documentation
-* Tests
 
 Copyright
 ---------

data/VERSION

@@ -1 +1 @@
-2.1.1
+2.1.2

data/lib/rutty.rb

@@ -7,7 +7,19 @@ require 'rutty/helpers'
 require 'rutty/node'
 require 'rutty/nodes'
 
+##
+# The RuTTY top-level module. Everything in the RuTTY gem is contained in this module.
+#
+# @author Josh Lindsey
+# @since 2.0.0
 module Rutty
+  
+  ##
+  # The Rutty::Runner class includes mixins from the other modules. All end-user interaction
+  # should be done through this class.
+  #
+  # @author Josh Lindsey
+  # @since 2.0.0 
   class Runner
     attr_writer :config_dir
   
@@ -15,18 +27,37 @@ module Rutty
     include Rutty::Helpers
     include Rutty::Actions
   
+    ##
+    # Initialize a new {Rutty::Runner} instance
+    #
+    # @param config_dir [String] Optional parameter specifying the directory RuTTY has been init'd into
     def initialize config_dir = nil
       self.config_dir = config_dir
     end
   
+    ##
+    # Lazy-load the {Rutty::Config} object for this instance, based on the config_dir param
+    # passed to {#initialize}.
+    #
+    # @return [Rutty::Config]
     def config
       @config ||= Rutty::Config.load_config self.config_dir
     end
   
+    ##
+    # Lazy-load the {Rutty::Nodes} object containing the user-defined nodes' connection info.
+    # Loads from the config_dir param passed to {#initialize}
+    #
+    # @return [Rutty::Nodes]
     def nodes
       @nodes ||= Rutty::Nodes.load_config self.config_dir
     end
     
+    ##
+    # If @config_dir is nil, returns {Rutty::Consts::CONF_DIR}. Otherwise return @config_dir.
+    #
+    # @see Rutty::Consts::CONF_DIR
+    # @return [String] The user-specified config directory, falling back to the default on nil
     def config_dir
       (@config_dir.nil? && Rutty::Consts::CONF_DIR) || @config_dir
     end

data/lib/rutty/actions.rb

@@ -1,7 +1,20 @@
 require 'rutty/consts'
 
 module Rutty
+  
+  ##
+  # The primary mixin module containing the code executed by the rutty bin's actions.
+  #
+  # @author Josh Lindsey
+  # @since 2.0.0
   module Actions
+    ##
+    # Initialize the Rutty config file structure in the specified directory, or
+    # report that the files already exist there.
+    #
+    # @see Rutty::Runner#config_dir
+    # @param [String] dir The directory to install into. {Rutty::Runner#config_dir} ensures
+    #   that this falls back to {Rutty::Consts::CONF_DIR} if not passed in by the user.
     def init dir
       general_file = File.join(dir, Rutty::Consts::GENERAL_CONF_FILE)
       nodes_file = File.join(dir, Rutty::Consts::NODES_CONF_FILE)
@@ -40,6 +53,12 @@ module Rutty
       end
     end
 
+    ##
+    # Add a new user-defined node to the datastore file.
+    #
+    # @see http://visionmedia.github.com/commander/
+    # @param [Array] args ARGV passed by the bin
+    # @param [Object] options The parsed options object as passed by the bin
     def add_node args, options
       raise Rutty::BadUsage.new "Must supply a hostname or IP address. 
       See `rutty help add_node' for usage" if args.empty?
@@ -54,12 +73,23 @@ module Rutty
       self.nodes.write_config self.config_dir
     end
 
+    ##
+    # List all the user-defined nodes currently stored in the datastore file.
+    #
+    # @see (see #add_node)
+    # @param (see #add_node)
     def list_nodes args, options
       require 'pp'
 
       pp self.nodes.filter(options)
     end
 
+    ##
+    # Cycle through all the user-defined nodes, filtered by the options, connect to them
+    # and run the specified command on them.
+    #
+    # @see (see #add_node)
+    # @param (see #add_node)
     def dsh args, options
       # TODO: Clean this up, it's pretty hard to read and follow
 
@@ -138,6 +168,12 @@ module Rutty
       pp @returns
     end
 
+    ##
+    # Cycle through all the user-defined nodes, filtered by the options, connect to them
+    # and upload the specified file(s).
+    #
+    # @see (see #add_node)
+    # @param (see #add_node)
     def scp args, options
       check_installed!
       raise Rutty::BadUsage.new "Must supply a local path and a remote path" unless args.length == 2

data/lib/rutty/config.rb

@@ -1,7 +1,29 @@
-# http://mjijackson.com/2010/02/flexible-ruby-config-objects
 module Rutty
+  
+  ##
+  # Flexible config class able to use both hash accessors and object accessors. Nested
+  # attributes are also instances of this class, allowing for object (dot) style accessor
+  # chaining.
+  #
+  # @see http://mjijackson.com/2010/02/flexible-ruby-config-objects
+  # 
+  # @example
+  #   config = Config.new :foo => "bar", :test => "baz", :widget => { :another => "string" }
+  #
+  #   config.foo            # => "bar"
+  #   config.widget.another # => "string"
+  #
+  # @author Michael Jackson
+  # @author Josh Lindsey
+  # @since 2.0.0
   class Config
     class << self
+      ##
+      # Loads the default config data from the yaml file in the specified config dir.
+      #
+      # @see Rutty::Consts::GENERAL_CONF_FILE
+      # @param [String] dir The directory to look in for the file specified by {Rutty::Consts::GENERAL_CONF_FILE}
+      # @return [Rutty::Config] The populated {Config} instance
       def load_config dir
         require 'yaml'
         
@@ -10,21 +32,41 @@ module Rutty
       end
     end
     
+    ##
+    # Returns a new {Config} populated with the specified data hash.
+    #
+    # @see #update!
+    # @param (see #update!)
     def initialize(data={})
       @data = {}
       update!(data)
     end
 
+    ##
+    # Updates this instance's @data attribute with the specified data hash.
+    #
+    # @param [Hash] data Data hash to iterate over
+    # @see #[]=
     def update!(data)
       data.each do |key, value|
         self[key] = value
       end
     end
 
+    ##
+    # Retrieve the specified key via Hash accessor syntax.
+    #
+    # @param [Symbol, String] key The key to lookup
+    # @return [Object] The object corresponding to the key
     def [](key)
       @data[key.to_sym]
     end
 
+    ##
+    # Set the specified key as the specified value via Hash accessor syntax.
+    #
+    # @param [Symbol, String] key The key to set
+    # @param [Object] value The value to set into the key
     def []=(key, value)
       if value.class == Hash
         @data[key.to_sym] = Config.new(value)
@@ -33,10 +75,20 @@ module Rutty
       end
     end
 
+    ##
+    # Simply returns this instance's @data attribute, which is internally stored as a hash.
+    # 
+    # @return [Hash] The @data attribute
     def to_hash
       @data
     end
     
+    ##
+    # Allows for object accessor (dot) syntax to access the stored data.
+    # If the missing method ends with an equals, calls {#[]=}, otherwise calls {#[]}
+    #
+    # @param [Symbol] sym The method symbol
+    # @param [*Array] args The splatted array of method arguments
     def method_missing(sym, *args)
       if sym.to_s =~ /(.+)=$/
         self[$1] = args.first

data/lib/rutty/consts.rb

@@ -1,10 +1,20 @@
 module Rutty
+  ##
+  # Simple container module for constants.
+  #
+  # @author Josh Lindsey
+  # @since 2.0.0
   module Consts
+    ## Name of the general (defaults) config file
     GENERAL_CONF_FILE = 'defaults.yaml'
+    ## Name of the datastore file for user-defined nodes
     NODES_CONF_FILE = 'nodes.yaml'
     
+    ## Default configuaration storage directory
     CONF_DIR = File.join(ENV['HOME'], '.rutty')
+    ## Default general (defaults) config file location
     GENERAL_CONF = File.join(CONF_DIR, GENERAL_CONF_FILE)
+    ## Default nodes datastore file location
     NODES_CONF = File.join(CONF_DIR, NODES_CONF_FILE)
   end
 end

data/lib/rutty/errors.rb

@@ -1,5 +1,15 @@
 module Rutty
+  ##
+  # Raised by {Rutty::Helpers#check_installed!} if the check fails.
+  #
+  # @author Josh Lindsey
+  # @since 2.0.0
   class NotInstalledError < StandardError; end
   
+  ##
+  # Raised by various {Rutty::Actions} methods on invalid options, etc.
+  #
+  # @author Josh Lindsey
+  # @since 2.0.0
   class BadUsage < StandardError; end
 end

data/lib/rutty/helpers.rb

@@ -1,9 +1,19 @@
 require 'rutty/errors'
-require 'rutty/consts'
 require 'rutty/version'
 
 module Rutty
+  
+  ##
+  # Simple mixin module for miscellaneous methods that don't fit in elsewhere.
+  #
+  # @author Josh Lindsey
+  # @since 2.0.0
   module Helpers
+    ##
+    # Check to ensure the config dir exists. Method expects this module to be included in a
+    # class or module where self.config_dir is meaningful, such as {Rutty::Runner}.
+    #
+    # @raise [Rutty::NotInstalledError] If file cannot be found
     def check_installed!
       unless File.exists? self.config_dir
         raise Rutty::NotInstalledError.new %Q(Can't find conf directory at #{self.config_dir}.
@@ -11,6 +21,11 @@ module Rutty
       end
     end
     
+    ##
+    # Returns the version string contained in {Rutty::Version::STRING}. Used by the rutty bin.
+    #
+    # @see (see Rutty::Version)
+    # @return [String] The version string
     def self.get_version
       Rutty::Version::STRING
     end

data/lib/rutty/node.rb

@@ -1,21 +1,51 @@
 require 'rutty/config'
-require 'rutty/consts'
 
 module Rutty
-  class Node < Config    
+  
+  ##
+  # A wrapper class representing an individual node. Normally contained by {Rutty::Nodes}.
+  #
+  # @see Rutty::Config
+  # @author Josh Lindsey
+  # @since 2.0.0
+  class Node < Config
+    ##
+    # Initialize a new {Rutty::Node} instance by merging the user-provided data with
+    # the configured defaults.
+    #
+    # @see Rutty::Config#initialize
+    # @param [Hash] data The data provided by the user
+    # @param [Hash] defaults The defaults data provided by the {Rutty::Config} class
     def initialize data, defaults = {}
       merged_data = defaults.merge data
       super merged_data
     end
     
+    ##
+    # Whether this object's tags array includes the specified tag.
+    #
+    # @param [String] tag The tag string to check for
     def has_tag? tag
       self.tags.include? tag
     end
     
+    ##
+    # Relation of this {Rutty::Node} to another {Rutty::Node}. Used for sorting.
+    # Compares the host property of the nodes, as it's the only property guaranteed to be
+    # set and unique.
+    #
+    # @see http://ruby-doc.org/core/classes/String.html#M000763
+    # @param [Rutty::Node] other The other {Rutty::Node} to compare to
+    # @return [Integer] Relation of self to other: -1 for less-than, 0 for equal-to, 1 for greater-than
     def <=> other
       self.host <=> other.host
     end
     
+    ##
+    # Checks for object eqality. Checks each property of this {Node} against the other.
+    #
+    # @param (see Rutty::Node#<=>)
+    # @return [Boolean]
     def == other
       self.host == other.host and
       self.port == other.port and

data/lib/rutty/nodes.rb

@@ -2,14 +2,36 @@ require 'rutty/node'
 require 'rutty/consts'
 
 module Rutty
+  
+  ##
+  # Simple container class for {Rutty::Node} instances. Contains methods to load node data from file,
+  # write data back to the file, and filter nodes based on user-supplied criteria.
+  #
+  # @author Josh Lindsey
+  # @since 2.1.0
   class Nodes < Array
     class << self
+      ##
+      # Loads the users's node data from the yaml file contained in the specified dir.
+      #
+      # @param [String] dir The directory to look in for the filename specified by {Rutty::Consts::NODES_CONF_FILE}
+      # @return [Rutty::Nodes] The filled instance of {Rutty::Node} objects
+      # @see Rutty::Consts::NODES_CONF_FILE
       def load_config dir
         require 'yaml'
         Rutty::Nodes.new YAML.load(File.open(File.join(dir, Rutty::Consts::NODES_CONF_FILE)).read)
       end
     end
     
+    ##
+    # Filters out the {Rutty::Node} objects contained in this instance based on user-defined criteria.
+    #
+    # @param [Hash, #[]] opts The filter criteria
+    # @option opts [String] :keypath (nil) The path to the private key
+    # @option opts [String] :user (nil) The user to login as
+    # @option opts [Integer] :port (nil) The port to connect to
+    # @option opts [Array<String>] :tags (nil) The tags to filter by
+    # @return [Array] An Array containing the {Rutty::Node} objects after filtering
     def filter opts = {}
       return self if opts[:all]
       
@@ -23,6 +45,11 @@ module Rutty
       ary
     end
     
+    ##
+    # Writes the updated nodes config back into the nodes.yaml file in the specified dir.
+    #
+    # @param (see Rutty::Nodes.load_config)
+    # @see (see Rutty::Nodes.load_config)
     def write_config dir
       File.open(File.join(dir, Rutty::Consts::NODES_CONF_FILE), 'w') do |f|
         YAML.dump(self, f)

data/lib/rutty/version.rb

@@ -1,8 +1,15 @@
 module Rutty
+  
+  ##
+  # The current version of the gem, expressed in Ruby code so it can
+  # be accessed programmatically.
+  #
+  # @author Josh Lindsey
+  # @see http://semver.org
   module Version
     MAJOR = 2
     MINOR = 1
-    PATCH = 1
+    PATCH = 2
     BUILD = nil
 
     STRING = [MAJOR, MINOR, PATCH, BUILD].compact.join('.')

data/rutty.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{rutty}
-  s.version = "2.1.1"
+  s.version = "2.1.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Josh Lindsey"]

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: rutty
 version: !ruby/object:Gem::Version 
-  hash: 9
+  hash: 15
   prerelease: false
   segments: 
   - 2
   - 1
-  - 1
-  version: 2.1.1
+  - 2
+  version: 2.1.2
 platform: ruby
 authors: 
 - Josh Lindsey