MuranoCLI 2.0.0 → 2.1.0

data/lib/MrMurano/Solution-Services.rb

@@ -24,11 +24,6 @@ module MrMurano
       # :nocov:
     end
 
-    def list
-      ret = get()
-      ret[:items]
-    end
-
     def fetch(name)
       raise "Missing name!" if name.nil?
       raise "Empty name!" if name.empty?
@@ -55,7 +50,7 @@ module MrMurano
       # we assume these are small enough to slurp.
       script = local.read
 
-      pst = remote.merge ({
+      pst = remote.to_h.merge ({
         :solution_id => $cfg['solution.id'],
         :script => script,
         :alias=>mkalias(remote),
@@ -152,8 +147,20 @@ module MrMurano
     end
   end
 
-  # …/library
+  # Libraries or better known as Modules.
   class Library < ServiceBase
+    # Module Specific details on an Item
+    class LibraryItem < Item
+      # @return [String] Internal Alias name
+      attr_accessor :alias
+      # @return [String] Timestamp when this was updated.
+      attr_accessor :updated_at
+      # @return [String] Timestamp when this was created.
+      attr_accessor :created_at
+      # @return [String] The solution.id that this is in
+      attr_accessor :solution_id
+    end
+
     def initialize
       super
       @uriparts << 'library'
@@ -167,24 +174,30 @@ module MrMurano
     end
 
     def mkalias(remote)
-      if remote.has_key? :name then
+      unless remote.name.nil? then
         [$cfg['solution.id'], remote[:name]].join('_')
       else
-        raise "Missing parts! #{remote.to_json}"
+        raise "Missing parts! #{remote.to_h.to_json}"
       end
     end
 
     def mkname(remote)
-      if remote.has_key? :name then
+      unless remote.name.nil? then
         remote[:name]
       else
-        raise "Missing parts! #{remote.to_json}"
+        raise "Missing parts! #{remote.to_h.to_json}"
       end
     end
 
+    def list
+      ret = get()
+      return [] unless ret.has_key? :items
+      ret[:items].map{|i| LibraryItem.new(i)}
+    end
+
     def toRemoteItem(from, path)
       name = path.basename.to_s.sub(/\..*/, '')
-      {:name => name}
+      LibraryItem.new(:name => name)
     end
 
     def synckey(item)
@@ -193,8 +206,24 @@ module MrMurano
   end
   SyncRoot.add('modules', Library, 'M', %{Modules}, true)
 
-  # …/eventhandler
+  # Services aka EventHandlers
   class EventHandler < ServiceBase
+    # EventHandler Specific details on an Item
+    class EventHandlerItem < Item
+      # @return [String] Internal Alias name
+      attr_accessor :alias
+      # @return [String] Timestamp when this was updated.
+      attr_accessor :updated_at
+      # @return [String] Timestamp when this was created.
+      attr_accessor :created_at
+      # @return [String] The solution.id that this is in
+      attr_accessor :solution_id
+      # @return [String] Which service triggers this script
+      attr_accessor :service
+      # @return [String] Which event triggers this script
+      attr_accessor :event
+    end
+
     def initialize
       super
       @uriparts << 'eventhandler'
@@ -204,18 +233,18 @@ module MrMurano
     end
 
     def mkalias(remote)
-      if remote.has_key? :service and remote.has_key? :event then
-        [$cfg['solution.id'], remote[:service], remote[:event]].join('_')
+      if remote.service.nil? or remote.event.nil? then
+        raise "Missing parts! #{remote.to_h.to_json}"
       else
-        raise "Missing parts! #{remote.to_json}"
+        [$cfg['solution.id'], remote[:service], remote[:event]].join('_')
       end
     end
 
     def mkname(remote)
-      if remote.has_key? :service and remote.has_key? :event then
-        [remote[:service], remote[:event]].join('_')
+      if remote.service.nil? or remote.event.nil? then
+        raise "Missing parts! #{remote.to_h.to_json}"
       else
-        raise "Missing parts! #{remote.to_json}"
+        [remote[:service], remote[:event]].join('_')
       end
     end
 
@@ -229,7 +258,7 @@ module MrMurano
         ( skiplist.include? i[:service] or
           skiplist.include? "#{i[:service]}.#{i[:event]}"
         )
-      }
+      }.map{|i| EventHandlerItem.new(i)}
     end
 
     def fetch(name)
@@ -266,11 +295,11 @@ module MrMurano
         md = @match_header.match(line)
         if not md.nil? then
           # header line.
-          cur = {:service=>md[:service],
-                 :event=>md[:event],
-                 :local_path=>path,
-                 :line=>lineno,
-                 :script=>line}
+          cur = EventHandlerItem.new(:service=>md[:service],
+                                     :event=>md[:event],
+                                     :local_path=>path,
+                                     :line=>lineno,
+                                     :script=>line)
         elsif not cur.nil? and not cur[:script].nil? then
           cur[:script] << line
         end
@@ -287,12 +316,13 @@ module MrMurano
         unless service.nil? or event.nil? then
           warning "Event in #{spath} missing header, but has legacy support."
           warning "Please add the header \"--#EVENT #{service} #{event}\""
-          cur = {:service=>service,
-                 :event=>event,
-                 :local_path=>path,
-                 :line=>0,
-                 :line_end => lineno,
-                 :script=>path.read()} # FIXME: ick, fix this.
+          cur = EventHandlerItem.new(:service=>service,
+                                     :event=>event,
+                                     :local_path=>path,
+                                     :line=>0,
+                                     :line_end => lineno,
+                                     :script=>path.read() # FIXME: ick, fix this.
+                                    )
         end
       end
       cur

data/lib/MrMurano/SyncUpDown.rb

@@ -9,18 +9,19 @@ require 'MrMurano/hash'
 module MrMurano
   ## Track what things are syncable.
   class SyncRoot
+    # A thing that is syncable.
     Syncable = Struct.new(:name, :class, :type, :desc, :bydefault) do
     end
 
     ##
     # Add a new entry to syncable things
-    # +name+:: The name to use for the long option
-    # +klass+:: The class to instanciate from
-    # +type+:: Single letter for short option and status listing
-    # +desc+:: Summary of what this syncs.
-    # +bydefault+:: Is this part of the default sync group
+    # @param name [String] The name to use for the long option
+    # @param klass [Class] The class to instanciate from
+    # @param type [String] Single letter for short option and status listing
+    # @param desc [String] Summary of what this syncs.
+    # @param bydefault [Boolean] Is this part of the default sync group
     #
-    # returns nil
+    # @return [nil]
     def self.add(name, klass, type, desc, bydefault=false)
       @@syncset = [] unless defined?(@@syncset)
       @@syncset << Syncable.new(name.to_s, klass, type, desc, bydefault)
@@ -35,29 +36,29 @@ module MrMurano
 
     ##
     # Get the list of default syncables.
-    # returns array of names
+    # @return [Array<String>] array of names
     def self.bydefault
       @@syncset.select{|a| a.bydefault }.map{|a| a.name}
     end
 
     ##
     # Iterate over all syncables
-    # +block+:: code to run on each
+    # @param block code to run on each
     def self.each(&block)
       @@syncset.each{|a| yield a.name, a.type, a.class }
     end
 
     ##
     # Iterate over all syncables with option arguments.
-    # +block+:: code to run on each
+    # @param block code to run on each
     def self.each_option(&block)
       @@syncset.each{|a| yield "-#{a.type.downcase}", "--[no-]#{a.name}", a.desc}
     end
 
     ##
     # Iterate over just the selected syncables.
-    # +opt+:: Options hash of which to select from
-    # +block+:: code to run on each
+    # @param opt [Hash{Symbol=>Boolean}] Options hash of which to select from
+    # @param block code to run on each
     def self.each_filtered(opt, &block)
       self.checkSAME(opt)
       @@syncset.each do |a|
@@ -70,9 +71,9 @@ module MrMurano
     ## Adjust options based on all or none
     # If none are selected, select the bydefault ones.
     #
-    # +opt+:: Options hash of which to select from
+    # @param opt [Hash{Symbol=>Boolean}] Options hash of which to select from
     #
-    # returns nil
+    # @return [nil]
     def self.checkSAME(opt)
       if opt[:all] then
         @@syncset.each {|a| opt[a.name.to_sym] = true }
@@ -88,7 +89,139 @@ module MrMurano
     end
   end
 
+  ## The functionality of a Syncable thing.
+  #
+  # This provides the logic for computing what things have changed, and pushing and
+  # pulling those things.
+  #
   module SyncUpDown
+
+    # This is one item that can be synced
+    class Item
+      # @return [String] The name of this item
+      attr_accessor :name
+      # @return [Pathname] Where this item lives
+      attr_accessor :local_path
+      # ??? what is this?
+      attr_accessor :id
+      # @return [String] The lua code for this item. (not all items use this.)
+      attr_accessor :script
+      # @return [Integer] The line in #local_path where this #script starts
+      attr_accessor :line
+      # @return [Integer] The line in #local_path where this #script ends
+      attr_accessor :line_end
+      # @return [String] If requested, the diff output
+      attr_accessor :diff
+      # @return [Boolean] When filtering, did this item pass.
+      attr_accessor :selected
+      # ???? what is this?
+      attr_accessor :synckey
+
+      # Initialize a new Item with a few, or all, attributes.
+      # @param hsh [Hash{Symbol=>Object}, Item] Initial values
+      #
+      # @example Initializing with a Hash
+      #  Item.new(:name=>'Bob', :local_path => Pathname.new(…))
+      # @example Initializing with an Item
+      #  item = Item.new(:name => 'get')
+      #  Item.new(item)
+      def initialize(hsh={})
+        hsh.each_pair{|k,v| self[k] = v}
+      end
+
+      def as_inst(key)
+        return key if key.to_s[0] == '@'
+        return "@#{key}"
+      end
+      private :as_inst
+      def as_sym(key)
+        return key.to_sym if key.to_s[0] != '@'
+        return key.to_s[1..-1].to_sym
+      end
+      private :as_sym
+
+      # Get attribute as if this was a Hash
+      # @param key [String,Symbol] attribute name
+      # @return [Object] The value
+      def [](key)
+        public_send(key.to_sym)
+      end
+
+      # Set attribute as if this was a Hash
+      # @param key [String,Symbol] attribute name
+      # @param value [Object] value to set
+      def []=(key,value)
+        public_send("#{key}=", value)
+      end
+
+      # Delete a key
+      # @param key [String,Symbol] attribute name
+      # @return [Object] The value
+      def delete(key)
+        inst = as_inst(key)
+        remove_instance_variable(inst) if instance_variable_defined?(inst)
+      end
+
+      # @return [Hash{Symbol=>Object}] A hash that represents this Item
+      def to_h
+        Hash[ instance_variables.map{|k| [ as_sym(k), instance_variable_get(k)]} ]
+      end
+
+      # Adds the contents of item to self.
+      # @param item [Item,Hash] Stuff to merge
+      # @return [Item] ourself
+      def merge!(item)
+        item.each_pair{|k,v| self[k] = v}
+        self
+      end
+
+      # A new Item containing our plus items.
+      # @param item [Item,Hash] Stuff to merge
+      # @return [Item] New item with contents of both
+      def merge(item)
+        dup.merge!(item)
+      end
+
+      # Calls block once for each non-nil key
+      # @yieldparam key [Symbol] The name of the key
+      # @yieldparam value [Object] The value for that key
+      # @return [Item]
+      def each_pair(&block)
+        instance_variables.each do |key|
+          yield as_sym(key), instance_variable_get(key)
+        end
+        self
+      end
+
+      # Delete items in self that block returns true.
+      # @yieldparam key [Symbol] The name of the key
+      # @yieldparam value [Object] The value for that key
+      # @yieldreturn [Boolean] True to delete this key
+      # @return [Item] Ourself.
+      def reject!(&block)
+        instance_variables.each do |key|
+          drop = yield as_sym(key), instance_variable_get(key)
+          delete(key) if drop
+        end
+        self
+      end
+
+      # A new Item with keys deleted where block is true
+      # @yieldparam key [Symbol] The name of the key
+      # @yieldparam value [Object] The value for that key
+      # @yieldreturn [Boolean] True to delete this key
+      # @return [Item] New Item with keys deleted
+      def reject(&block)
+        dup.reject!(&block)
+      end
+
+      # For unit testing.
+      include Comparable
+      def <=>(anOther)
+        self.to_h <=> anOther.to_h
+      end
+    end
+
     #######################################################################
     # Methods that must be overridden
 
@@ -97,7 +230,7 @@ module MrMurano
     #
     # Children objects Must override this
     #
-    # @return Array: of Hashes of item details
+    # @return [Array] of Hashes of item details
     def list()
       []
     end
@@ -106,7 +239,7 @@ module MrMurano
     #
     # Children objects Must override this
     #
-    # @param itemkey String: The identifying key for this item
+    # @param itemkey [String] The identifying key for this item
     def remove(itemkey)
       # :nocov:
       raise "Forgotten implementation"
@@ -117,9 +250,9 @@ module MrMurano
     #
     # Children objects Must override this
     #
-    # @param src Pathname: Full path of where to upload from
-    # @param item Hash: The item details to upload
-    # @param modify Bool: True if item exists already and this is changing it
+    # @param src [Pathname] Full path of where to upload from
+    # @param item [Hash] The item details to upload
+    # @param modify [Bool] True if item exists already and this is changing it
     def upload(src, item, modify)
       # :nocov:
       raise "Forgotten implementation"
@@ -148,14 +281,14 @@ module MrMurano
     #
     # @param root [Pathname,String] Root path for this resource type from config files
     # @param path [Pathname,String] Path to local item
-    # @return [Hash] hash of the details for the remote item for this path
+    # @return [Item] hash of the details for the remote item for this path
     def toRemoteItem(root, path)
       # This mess brought to you by Windows short path names.
       path = Dir.glob(path.to_s).first
       root = Dir.glob(root.to_s).first
       path = Pathname.new(path)
       root = Pathname.new(root)
-      {:name => path.realpath.relative_path_from(root.realpath).to_s}
+      Item.new(:name => path.realpath.relative_path_from(root.realpath).to_s)
     end
 
     ##
@@ -163,8 +296,8 @@ module MrMurano
     #
     # Children objects should override this or #tolocalpath
     #
-    # @param item Hash: listing details for the item.
-    # @param itemkey Symbol: Key for look up.
+    # @param item [Item] listing details for the item.
+    # @param itemkey [Symbol] Key for look up.
     def tolocalname(item, itemkey)
       item[itemkey].to_s
     end
@@ -177,11 +310,11 @@ module MrMurano
     #
     # Children objects should override this or #tolocalname
     #
-    # @param into Pathname: Root path for this resource type from config files
-    # @param item Hash: listing details for the item.
-    # @return Pathname: path to save (or merge) remote item into
+    # @param into [Pathname] Root path for this resource type from config files
+    # @param item [Item] listing details for the item.
+    # @return [Pathname] path to save (or merge) remote item into
     def tolocalpath(into, item)
-      return item[:local_path] if item.has_key? :local_path
+      return item[:local_path] unless item.local_path.nil?
       itemkey = @itemkey.to_sym
       name = tolocalname(item, itemkey)
       raise "Bad key(#{itemkey}) for #{item}" if name.nil?
@@ -196,7 +329,9 @@ module MrMurano
     #
     # Check child specific patterns against item
     #
-    # @returns true or false
+    # @param item [Item] Item to be checked
+    # @param pattern [String] pattern to check with
+    # @return [Bool] true or false
     def match(item, pattern)
       false
     end
@@ -205,8 +340,8 @@ module MrMurano
     #
     # Children objects should override this if synckey is not @itemkey
     #
-    # @param item Hash: The item to get a key from
-    # @returns Object: The object to use a comparison key
+    # @param item [Item] The item to get a key from
+    # @return [Object] The object to use a comparison key
     def synckey(item)
       key = @itemkey.to_sym
       item[key]
@@ -216,13 +351,13 @@ module MrMurano
     #
     # Children objects should override this or implement #fetch()
     #
-    # @param local Pathname: Full path of where to download to
-    # @param item Hash: The item to download
+    # @param local [Pathname] Full path of where to download to
+    # @param item [Item] The item to download
     def download(local, item)
-      if item[:bundled] then
-        warning "Not downloading into bundled item #{synckey(item)}"
-        return
-      end
+#      if item[:bundled] then
+#        warning "Not downloading into bundled item #{synckey(item)}"
+#        return
+#      end
       local.dirname.mkpath
       id = item[@itemkey.to_sym]
       if id.nil? then
@@ -243,8 +378,8 @@ module MrMurano
     # Children objects should override this if move than just unlinking the local
     # item.
     #
-    # @param dest Pathname: Full path of item to be removed
-    # @param item Hash: Full details of item to be removed
+    # @param dest [Pathname] Full path of item to be removed
+    # @param item [Item] Full details of item to be removed
     def removelocal(dest, item)
       dest.unlink
     end
@@ -253,8 +388,7 @@ module MrMurano
     #######################################################################
 
 
-    ##
-    # So, for bundles this needs to look at all the places and build up the mered
+    # So, for bundles this needs to look at all the places and build up the merged
     # stack of local items.
     #
     # Which means it needs the from to be split into the base and the sub so we can
@@ -267,7 +401,7 @@ module MrMurano
     # #localitems
     #
     # This collects items in the project and all bundles.
-    # @return Array: of Hashes of items
+    # @return [Array<Item>] items found
     def locallist()
       # so. if @locationbase/bundles exists
       #  gather and merge: @locationbase/bundles/*/@location
@@ -303,6 +437,7 @@ module MrMurano
 
     ##
     # Get the full path for the local versions
+    # @return [Pathname] Location for local items
     def location
       raise "Missing @project_section" if @project_section.nil?
       Pathname.new($cfg['location.base']) + $project["#{@project_section}.location"]
@@ -310,12 +445,14 @@ module MrMurano
 
     ##
     # Returns array of globs to search for files
+    # @return [Array<String>] of Strings that are globs
     def searchFor
       raise "Missing @project_section" if @project_section.nil?
       $project["#{@project_section}.include"]
     end
 
     ## Returns array of globs of files to ignore
+    # @return [Array<String>] of Strings that are globs
     def ignoring
       raise "Missing @project_section" if @project_section.nil?
       $project["#{@project_section}.exclude"]
@@ -327,8 +464,8 @@ module MrMurano
     # Children rarely need to override this. Only when the locallist is not a set
     # of files in a directory will they need to override it.
     #
-    # @param from Pathname: Directory of items to scan
-    # @return Array: of Hashes of item details
+    # @param from [Pathname] Directory of items to scan
+    # @return [Array<Item>] Items found
     def localitems(from)
       # TODO: Profile this.
       debug "#{self.class.to_s}: Getting local items from: #{from}"
@@ -357,6 +494,8 @@ module MrMurano
     ##
     # Take a hash or something (a Commander::Command::Options) and return a hash
     #
+    # @param hsh [Hash, Commander::Command::Options] Thing we want to be a Hash
+    # @return [Hash] an actual Hash with default value of false
     def elevate_hash(hsh)
       # Commander::Command::Options stripped all of the methods from parent
       # objects. I have not nice thoughts about that.
@@ -374,6 +513,9 @@ module MrMurano
     #
     # This creates, uploads, and deletes things as needed up in Murano to match
     # what is in the local project directory.
+    #
+    # @param options [Hash, Commander::Command::Options] Options on opertation
+    # @param selected [Array<String>] Filters for _matcher
     def syncup(options={}, selected=[])
       options = elevate_hash(options)
       itemkey = @itemkey.to_sym
@@ -413,6 +555,9 @@ module MrMurano
     #
     # This creates, downloads, and deletes things as needed up in the local project
     # directory to match what is in Murano.
+    #
+    # @param options [Hash, Commander::Command::Options] Options on opertation
+    # @param selected [Array<String>] Filters for _matcher
     def syncdown(options={}, selected=[])
       options = elevate_hash(options)
       options[:asdown] = true
@@ -452,9 +597,11 @@ module MrMurano
     end
 
     ## Call external diff tool on item
+    #
     # WARNING: This will download the remote item to do the diff.
-    # @param item Hash: The item to get a diff of
-    # @return String: The diff output
+    #
+    # @param item [Item] The item to get a diff of
+    # @return [String] The diff output
     def dodiff(item)
       trmt = Tempfile.new([tolocalname(item, @itemkey)+'_remote_', '.lua'])
       tlcl = Tempfile.new([tolocalname(item, @itemkey)+'_local_', '.lua'])
@@ -487,6 +634,8 @@ module MrMurano
 
     ##
     # Check if an item matches a pattern.
+    # @param items [Array<Item>] Of items to filter
+    # @param patterns [Array<String>] Filters for _matcher
     def _matcher(items, patterns)
       items.map do |item|
         if patterns.empty? then
@@ -495,7 +644,7 @@ module MrMurano
           item[:selected] = patterns.any? do |pattern|
             if pattern.to_s[0] == '#' then
               match(item, pattern)
-            elsif not item.has_key? :local_path then
+            elsif item.local_path.nil? then
               false
             else
               item[:local_path].fnmatch(pattern)
@@ -508,22 +657,24 @@ module MrMurano
     private :_matcher
 
     ## Get status of things here verses there
+    #
+    # @param options [Hash, Commander::Command::Options] Options on opertation
+    # @param selected [Array<String>] Filters for _matcher
+    # @return [Hash{Symbol=>Array<Item>}] Items grouped by the action that should be taken
     def status(options={}, selected=[])
       options = elevate_hash(options)
       itemkey = @itemkey.to_sym
 
-      there = _matcher(list(), selected)
-      here = _matcher(locallist(), selected)
+      there = _matcher(list(), selected)     # Array<Item>
+      here = _matcher(locallist(), selected) # Array<Item>
 
       therebox = {}
       there.each do |item|
-        item = Hash.transform_keys_to_symbols(item)
         item[:synckey] = synckey(item)
         therebox[ item[:synckey] ] = item
       end
       herebox = {}
       here.each do |item|
-        item = Hash.transform_keys_to_symbols(item)
         item[:synckey] = synckey(item)
         herebox[ item[:synckey] ] = item
       end