BlueAdmiral 0.0.1 → 0.0.2

data/BlueAdmiral.gemspec

@@ -5,15 +5,15 @@
 
 Gem::Specification.new do |s|
   s.name = %q{BlueAdmiral}
-  s.version = "0.0.1"
+  s.version = "0.0.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["David Love"]
   s.date = %q{2011-05-03}
-  s.default_executable = %q{bootstrap}
+  s.default_executable = %q{mercury}
   s.description = %q{Prepares hosts/networks/etc to become part of a stated Mercury environment}
   s.email = %q{david@homeunix.org.uk}
-  s.executables = ["bootstrap"]
+  s.executables = ["mercury"]
   s.extra_rdoc_files = [
     "LICENSE",
     "README.rdoc"
@@ -29,12 +29,13 @@ Gem::Specification.new do |s|
     "README.rdoc",
     "Rakefile",
     "VERSION",
-    "bin/bootstrap",
+    "bin/mercury",
     "lib/LICENSE",
     "lib/mercury.rb",
     "lib/mercury/cli.rb",
     "lib/mercury/cli/base.rb",
     "lib/mercury/cli/commands.rb",
+    "lib/mercury/cli/commands/bootstrap.rb",
     "lib/mercury/cli/commands/help.rb",
     "lib/mercury/cli/commands/show.rb",
     "lib/mercury/cli/logger.rb",

data/VERSION

@@ -1 +1 @@
-0.0.1
+0.0.2

data/lib/mercury/cli/base.rb

@@ -1,22 +1,48 @@
-### Copyright (c) 2009 Denis Defreyne, 2010-2011 David Love
-###
-### Permission to use, copy, modify, and/or distribute this software for 
-### any purpose with or without fee is hereby granted, provided that the 
-### above copyright notice and this permission notice appear in all copies.
-###
-### THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 
-### WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 
-### MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 
-### ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 
-### WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 
-### ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 
-### OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
-###
+# Copyright (c) 2009 Denis Defreyne, 2010-2011 David Love
+#
+# Permission to use, copy, modify, and/or distribute this software for 
+# any purpose with or without fee is hereby granted, provided that the 
+# above copyright notice and this permission notice appear in all copies.
+#
+# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+#
 
+# @author Denis Defreyne
+# @author David Love
+#
+# The +CLI+ module acts as the gathering place for all the gloabl options
+# and the sub-commands which the +mercury+ command can deal with. 
+# Sub-commands are themselves defined in the {Mercury::CLI::Commands} 
+# module 
 module Mercury::CLI
 
+  # @author Denis Defreyne
+  # @author David Love
+  #
+  # Details the global options applicable to all commands, and the code necessary
+  # to process those options. Each sub-command also needs to be registered with 
+  # this class for it to work: strange things will happen if the sub-command is
+  # not set-up here!
+  #
+  # When creating a new sub-command, the constructor for that sub-command needs
+  # to be added to the {Base#initialize} function of *this* class as well. Be sure to 
+  # also add the path to the file where the sub-command is defined to the file 
+  # +lib/mercury/cli/commands.rb+, otherwise you will get warnings of unknown
+  # classes.
   class Base < Cri::Base
 
+    # Instantiates the sub-commands by creating a single reference to each
+    # known sub-command.
+    # 
+    # @note This means that if your sub-command is not in this constructor
+    #   it *will not* be found, and *will not* appear as a valid sub-command.
+    #   If something is missing from the 'help' command, check this method! 
     def initialize
       super('mercury')
 
@@ -25,6 +51,7 @@ module Mercury::CLI
       add_command(self.help_command)
 
       # Add other commands
+      add_command(Mercury::CLI::Commands::Bootstrap.new)
       add_command(Mercury::CLI::Commands::Show.new)
     end
 
@@ -50,6 +77,7 @@ module Mercury::CLI
       ]
     end
 
+    # Process the global options, and set/change the application state from them
     def handle_option(option)
       # Handle version option
       if option == :version

data/lib/mercury/cli/commands/bootstrap.rb

@@ -0,0 +1,87 @@
+# Copyright (c) 2009 Denis Defreyne, 2010-2011 David Love
+#
+# Permission to use, copy, modify, and/or distribute this software for 
+# any purpose with or without fee is hereby granted, provided that the 
+# above copyright notice and this permission notice appear in all copies.
+#
+# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+
+module Mercury::CLI::Commands
+
+  # @author David Love
+  #
+  # The +bootstrap+ command prepared the basic Mercury realms (if 
+  # needed), and then links the current host to those realms. The basic
+  # realms consists of
+  #
+  # +Realm 0+: *Namespace*. All the named realms stored in this domain.
+  # 
+  # +Realm 1+: *Realm Handlers*. The basic gateways needed to create/store/update
+  # other realms.
+  # 
+  # +Realm 5+: *Realm Code*. Libraries and other code which the realm handlers
+  # should use by preference when conducting operations on the realms.
+  #
+  # If the IP address of a server (or a server name) is given to as an argument
+  # to this command, then we will use that IP address (name) for as the Mercury
+  # realm server to contact. Otherwise we will look for the same data from the file
+  # +/etc/mercury.conf+: aborting if the file cannot be found.
+  #
+  # Once we have made contact with the server, we look at the basic realms listed
+  # above, and attempt to ensure they can be found. If not, an attempt is made to
+  # create the basic realms: aborting if this attempt fails.
+  #
+  # Finally, once everything has been set-up, we upload the core realm code (or 
+  # update the existing code)
+  class Bootstrap < Cri::Command
+
+    # The name of the sub-command (as it appears in the command line app)
+    def name
+      'bootstrap'
+    end
+
+    # The aliases this sub-command is known by
+    def aliases
+      []
+    end
+
+    # A short help text describing the purpose of this command
+    def short_desc
+      'Create a link between this host and the mercury servers.'
+    end
+
+    # A longer description, detailing both the purpose and the
+    # use of this command
+    def long_desc
+      'Look for the specified server, adding the data required to link the ' +
+      'current host to that server. If the found server has not been set-up ' +
+      'then this command also performs the setup of the base realms as well. '
+    end
+
+    # Show the user the basic syntax of this command
+    def usage
+      "mercury bootstrap [-s server]"
+    end
+    
+    # Define the options for this command
+    def option_definitions
+      [
+        { :short => 's', :long => 'server', :argument => :optional }
+      ]
+    end
+
+    # Execute the command
+    def run(options, arguments)
+      return
+    end
+
+  end
+
+end

data/lib/mercury/cli/commands/help.rb

@@ -15,32 +15,54 @@
 
 module Mercury::CLI::Commands
 
+  # @author Denis Defreyne
+  # @author David Love
+  #
+  # The +help+ command show the user a brief summary of the available
+  # sub-commands, and the short description of each of those commands.
+  #
+  # Further help is available to the user, if one of the sub-commands
+  # is named as an argument to this command. In that case, the longer
+  # help for the command is displayed.
+  #
+  # @note This class is merely a helper class: the actual text, options
+  #   and other details are drawn directly from the source code of those
+  #   commands. In the execution of this command, we rely on the +cri+
+  #   and +cli+ libraries to do the hard work of actually processing the
+  #   sub-commands.
   class Help < Cri::Command
 
+    # The name of the sub-command (as it appears in the command line app)
     def name
       'help'
     end
 
+    # The aliases this sub-command is known by
     def aliases
       []
     end
 
+    # A short help text describing the purpose of this command
     def short_desc
       'Show help for a command'
     end
 
+    # A longer description, detailing both the purpose and the
+    # use of this command
     def long_desc
       'Show help for the given command, or show general help. When no ' +
       'command is given, a list of available commands is displayed, as ' +
-      'well as a list of global commandline options. When a command is ' +
+      'well as a list of global command-line options. When a command is ' +
       'given, a command description as well as command-specific ' +
-      'commandline options are shown.'
+      'command-line options are shown.'
     end
 
+    # Show the user the basic syntax of this command
     def usage
       "mercury help [command]"
     end
 
+    # Execute the command
     def run(options, arguments)
       # Check arguments
       if arguments.size > 1
@@ -53,7 +75,7 @@ module Mercury::CLI::Commands
         text = ''
 
         # Add title
-        text << "A Mercury Server client written in Ruby.\n"
+        text << "A command-line tool for managing Mercury realms.\n"
 
         # Add available commands
         text << "\n"

data/lib/mercury/cli/commands/show.rb

@@ -1,48 +1,63 @@
-### Copyright (c) 2011 David Love
-###
-### Permission to use, copy, modify, and/or distribute this software for 
-### any purpose with or without fee is hereby granted, provided that the 
-### above copyright notice and this permission notice appear in all copies.
-###
-### THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 
-### WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 
-### MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 
-### ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 
-### WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 
-### ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 
-### OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
-###
+# Copyright (c) 2011 David Love
+#
+# Permission to use, copy, modify, and/or distribute this software for 
+# any purpose with or without fee is hereby granted, provided that the 
+# above copyright notice and this permission notice appear in all copies.
+#
+# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+#
+#
+# @author David Love
+#
 
 module Mercury::CLI::Commands
 
+  # @author David Love
+  #
+  # Displays a summary of the realm data found in the configured Mercury
+  # server.
   class Show < Cri::Command
-
+    
+    # The name of the sub-command (as it appears in the command line app)
     def name
       'show-status'
     end
 
+    # The aliases this sub-command is known by
     def aliases
       []
     end
 
+    # A short help text describing the purpose of this command
     def short_desc
       'Create or update information from the network'
     end
 
+    # A longer description, detailing both the purpose and the
+    # use of this command
     def long_desc
       "Displays the current state of the evironemnt " +
       "to update the host files (held in the 'hosts' directory). Existing " +
       "information will be updated, and missing information inserted.\n"
     end
-
+    
+    # Show the user the basic syntax of this command
     def usage
       "bootstrap show-status"
     end
 
+    # Define the options for this command
     def option_definitions
       []
     end
 
+    # Execute the command
     def run(options, arguments)
 
       # Load the list of groups

data/lib/mercury/cli/commands.rb

@@ -1,21 +1,29 @@
-### Copyright (c) 2009 Denis Defreyne, 2010-2011 David Love
-###
-### Permission to use, copy, modify, and/or distribute this software for 
-### any purpose with or without fee is hereby granted, provided that the 
-### above copyright notice and this permission notice appear in all copies.
-###
-### THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 
-### WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 
-### MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 
-### ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 
-### WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 
-### ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 
-### OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
-###
+# Copyright (c) 2009 Denis Defreyne, 2010-2011 David Love
+#
+# Permission to use, copy, modify, and/or distribute this software for 
+# any purpose with or without fee is hereby granted, provided that the 
+# above copyright notice and this permission notice appear in all copies.
+#
+# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 
+# @author David Love
+#
+# The +Commands+ module acts as the gathering place for all the sub-commands 
+# which the +mercury+ command can deal with. Each sub-command defines both 
+# the command action, options, and associated help text.
+#
+# All commands should live under +lib/mercury/cli/commands+, with the 
+# file-name named after the sub-command defined within it. 
 module Mercury::CLI::Commands
 end
 
 require 'mercury/cli/commands/help'
 
+require 'mercury/cli/commands/bootstrap'
 require 'mercury/cli/commands/show'

data/lib/mercury/cli/logger.rb

@@ -21,6 +21,8 @@ module Mercury::CLI
   # feedback in the terminal.
   class Logger
 
+    # ANSI console codes (escape sequences) for highlighting particular
+    # log outputs.
     ACTION_COLORS = {
       :create         => "\e[1m" + "\e[32m", # bold + green
       :update         => "\e[1m" + "\e[33m", # bold + yellow

metadata

@@ -2,7 +2,7 @@
 name: BlueAdmiral
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors: 
 - David Love
@@ -11,7 +11,7 @@ bindir: bin
 cert_chain: []
 
 date: 2011-05-03 00:00:00 +01:00
-default_executable: bootstrap
+default_executable: mercury
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: hiredis
@@ -137,7 +137,7 @@ dependencies:
 description: Prepares hosts/networks/etc to become part of a stated Mercury environment
 email: david@homeunix.org.uk
 executables: 
-- bootstrap
+- mercury
 extensions: []
 
 extra_rdoc_files: 
@@ -154,12 +154,13 @@ files:
 - README.rdoc
 - Rakefile
 - VERSION
-- bin/bootstrap
+- bin/mercury
 - lib/LICENSE
 - lib/mercury.rb
 - lib/mercury/cli.rb
 - lib/mercury/cli/base.rb
 - lib/mercury/cli/commands.rb
+- lib/mercury/cli/commands/bootstrap.rb
 - lib/mercury/cli/commands/help.rb
 - lib/mercury/cli/commands/show.rb
 - lib/mercury/cli/logger.rb
@@ -179,7 +180,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: -4315529852713499843
+      hash: -976333998919963703
       segments: 
       - 0
       version: "0"