plist4r 0.2.2 → 1.0.0

data/lib/plist4r/plist_cache.rb

@@ -1,77 +1,76 @@
 
 require 'plist4r/backend'
+require 'plist4r/mixin/ruby_stdlib'
+
 module Plist4r
   class PlistCache
     def initialize plist, *args, &blk
+      @checksum = {}
       @plist = plist
       @backend = Backend.new plist, *args, &blk
     end
   
-    def checksum
-      @plist.to_hash.hash
-    end
-  
-    def last_checksum
-      @checksum
-    end
+    def from_string
+      if @from_string == @plist.from_string
+        unless @from_string_plist_type == @plist.plist_type
+          @from_string_plist_type = @plist.detect_plist_type
+        end
+        unless @from_string_file_format == @plist.file_format
+          @plist.file_format @from_string_file_format
+        end
+      else
+        @backend.call :from_string
+        @from_string = @plist.from_string
+        @from_string_file_format = @plist.file_format
 
-    def update_checksum
-      @checksum = @plist.to_hash.hash
+        @plist.detect_plist_type
+        unless @from_string_plist_type == @plist.plist_type
+          @from_string_plist_type = @plist.plist_type
+        end
+      end
+      @plist
     end
 
-    def needs_update
-      checksum != last_checksum
+    def update_checksum_for fmt
+      @checksum[fmt] = @plist.to_hash.hash
     end
 
-    def from_string
-      @backend.call :from_string
-      update_checksum
-      @plist.detect_plist_type
-      @plist
+    def needs_update_for fmt
+      @checksum[fmt] != @plist.to_hash.hash
     end
 
     def to_xml
-      if needs_update || @xml.nil?
-        puts "needs update"
-        update_checksum
+      if needs_update_for(:xml) || @xml.nil?
         @xml = @backend.call :to_xml
-      else
-        @xml
+        update_checksum_for(:xml)
       end
+      @xml
     end
-  
+
     def to_binary
-      if needs_update || @binary.nil?
-        update_checksum
+      if needs_update_for(:binary) || @binary.nil?
         @binary = @backend.call :to_binary
-      else
-        @binary
+        update_checksum_for(:binary)
       end
+      @binary
     end
 
-    def to_next_step
-      if needs_update || @next_step.nil?
-        update_checksum
-        @next_step = @backend.call :to_next_step
-      else
-        @next_step
+    def to_gnustep
+      if needs_update_for(:gnustep) || @gnustep.nil?
+        @gnustep = @backend.call :to_gnustep
+        update_checksum_for(:gnustep)
       end
+      @gnustep
     end
-  
+
     def open
       @backend.call :open
-      update_checksum
-      @plist.detect_plist_type
       @plist
     end
-  
+
     def save
-      if needs_update
-        update_checksum
-        @backend.call :save
-      else
-        true
-      end
+      @backend.call :save
+      @plist.filename_path
     end
   end
-end
+end

data/lib/plist4r/plist_type.rb

@@ -1,15 +1,22 @@
 
 require 'plist4r/mixin/data_methods'
+require 'plist4r/mixin/array_dict'
 
 module Plist4r
   class PlistType
     include ::Plist4r::DataMethods
 
+    ValidKeys = {}
+
+    # @param [Plist4r::Plist] plist A pointer referencing back to the plist object
     def initialize plist, *args, &blk
       @plist = plist
       @hash = @orig = plist.to_hash
     end
     
+    # Set or return the plist's raw data object
+    # @param [Plist4r::OrderedHash] hash Set the hash if not nil
+    # @return [Plist4r::OrderedHash] @hash
     def hash hash=nil
       case hash
       when ::Plist4r::OrderedHash
@@ -21,95 +28,45 @@ module Plist4r
       end
     end
 
-    def self.valid_keys
-      raise "Method not implemented #{method_name.to_sym.inspect}, for class #{self.inspect}"
-    end
-
-    # A Hash Array of the supported plist keys for this type. These are only those plist keys 
-    # recognized as belonging to a specific plist datatype. Used in validation, part of DataMethods.
-    # We usually overload this method in subclasses of {Plist4r::PlistType}.
+    # Compare a list of foreign keys to the valid keys for this known PlistType.
+    # Generate statistics about how many keys (what proportion) match the the key names
+    # match this particular PlistType.
+    # @param [Array] plist_keys The list of keys to compare to this PlistType
+    # @return [Hash] A hash of the match statistics
+    # @see Plist4r::Plist#detect_plist_type
     # @example
-    #  class Plist4r::PlistType::MyPlistType < PlistType
-    #      def self.valid_keys
-    #     {
-    #        :string => %w[PlistKeyS1 PlistKeyS2 ...],
-    #        :bool => %w[PlistKeyB1 PlistKeyB2 ...],
-    #        :integer => %w[PlistKeyI1 PlistKeyI2 ...],
-    #        :method_defined => %w[CustomPlistKey1 CustomPlistKey2 ...]
-    #      }
-    #    end
-    #  end
-    #
-    #  plist.plist_type :my_plist_type
-    #  plist.plist_key_s1 "some string"
-    #  plist.plist_key_b1 true
-    #  plist.plist_key_i1 08
-    #  plist.custom_plist_key1 MyClass.new(opts)
-    # 
-    def valid_keys
-      self.class.valid_keys
-    end
-
+    #  Plist4r::PlistType::Launchd.match_stat ["ProgramArguments","Sockets","SomeArbitraryKeyName"]
+    #  # => { :matches => 2, :ratio => 0.0465116279069767 }
     def self.match_stat plist_keys
-      type_keys = valid_keys.values.flatten
+      type_keys = self::ValidKeys.values.flatten
       matches = plist_keys & type_keys
       include_ratio = matches.size.to_f / type_keys.size
       return :matches => matches.size, :ratio => include_ratio
     end
 
+    # @return The shortform string, in snake case, a unique name
+    # @example
+    #  pt = Plist4r::PlistType::Launchd.new
+    #  pt.to_s
+    #  # => "launchd"
     def to_s
       return @string ||= self.class.to_s.gsub(/.*:/,"").snake_case
     end
 
+    # @return A symbol representation the shortform string, in snake case, a unique name
+    # @example
+    #  pt = Plist4r::PlistType::Launchd.new
+    #  pt.to_sym
+    #  # => :launchd
     def to_sym
       return @sym ||= to_s.to_sym
     end
-  end
-
-  class ArrayDict
-    include ::Plist4r::DataMethods
-
-    def initialize orig, index=nil, &blk
-      @orig = orig
-      if index
-        @enclosing_block = self.class.to_s.snake_case + "[#{index}]"
-        @orig = @orig[index]
-      else
-        @enclosing_block = self.class.to_s.snake_case
-      end
-      # puts "@orig = #{@orig.inspect}"
-      # puts "@enclosing_block = #{@enclosing_block}"
-
-      @block = blk
-      @hash = ::Plist4r::OrderedHash.new
-      # puts "@hash = #{@hash}"
-
-      instance_eval(&@block) if @block
-      # puts "@hash = #{@hash}"
-    end
-
-    def hash
-      @hash
-    end
-
-    def select *keys
-      keys.each do |k|
-        @hash[k] = @orig[k]
-      end
-    end
-
-    def unselect *keys
-      keys.each do |k|
-        @hash.delete k
-      end
-    end
-
-    def unselect_all
-      @hash = ::Plist4r::OrderedHash.new
-    end
 
-    def select_all
-      @hash = @orig
+    def array_dict method_sym, *args
+      a = ArrayDict.new @hash
+      result = eval "a.#{method_sym} *args"
+      @hash = @orig = a.hash
+      @plist.import_hash a.hash
     end
   end
 end

data/lib/plist4r/plist_type/info.rb

@@ -2,12 +2,166 @@
 require 'plist4r/plist_type'
 
 module Plist4r
+  # For documentation on the Info.plist keys, and their values, see:
+  # http://developer.apple.com/mac/library/documentation/General/Reference/InfoPlistKeyReference
   class PlistType::Info < PlistType
-    def self.valid_keys
-      {}
-    end
+
+    ValidKeysCoreFoundation =
+    {
+      :string => %w[
+        CFAppleHelpAnchor
+        CFBundleDevelopmentRegion
+        CFBundleDisplayName
+        CFBundleExecutable
+        CFBundleGetInfoString
+        CFBundleHelpBookFolder
+        CFBundleHelpBookName
+        CFBundleIconFile
+        CFBundleIdentifier
+        CFBundleInfoDictionaryVersion
+        CFBundleName
+        CFBundlePackageType
+        CFBundleShortVersionString
+        CFBundleSignature
+        CFBundleVersion
+        CFPlugInDynamicRegistration
+        CFPlugInDynamicRegisterFunction
+        CFPlugInUnloadFunction
+        ],
+      :bool => %w[
+        CFBundleAllowMixedLocalizations
+        ],
+      :array_of_strings => %w[
+        CFBundleIconFiles
+        CFBundleLocalizations
+        ],
+      :array_of_hashes => %w[
+        CFBundleDocumentTypes
+        ],
+      :array => %w[
+        CFBundleDocumentTypes
+        CFBundleURLTypes
+        ],
+      :hash_of_strings => %w[
+        CFPlugInFactories
+        ],
+      :hash_of_arrays_of_strings => %w[
+        CFPlugInTypes
+        ],
+    }
+
+    ValidKeysLaunchServices =
+    {
+      :string => %w[
+        LSMinimumSystemVersion
+        LSUIElement
+        LSVisibleInClassic
+        MinimumOSVersion
+        ],
+      :bool => %w[
+        LSBackgroundOnly
+        LSFileQuarantineEnabled
+        LSGetAppDiedEvents
+        LSMultipleInstancesProhibited
+        LSRequiresIPhoneOS
+        LSRequiresNativeExecution
+        ],
+      :integer => %w[
+        LSUIPresentationMode
+        ],
+      :array_of_strings => %w[
+        LSArchitecturePriority
+        LSFileQuarantineExcludedPathPatterns
+        ],
+      :hash_of_strings => %w[
+        LSEnvironment
+        LSMinimumSystemVersionByArchitecture
+        ],
+    }
+
+    ValidKeysCocoa =
+    {
+      :string => %w[
+        NSDockTilePlugIn
+        NSHumanReadableCopyright
+        NSJavaRoot
+        NSMainNibFile
+        NSPersistentStoreTypeKey
+        NSPrefPaneIconFile
+        NSPrefPaneIconLabel
+        NSPrincipalClass
+        ],
+      :bool => %w[
+        NSSupportsSuddenTermination
+        ],
+      :bool_or_string => %w[
+        NSAppleScriptEnabled
+        NSJavaNeeded
+        ],
+      :array_of_strings => %w[
+        NSJavaPath
+        ],
+      :array_of_hashes => %w[
+        NSServices
+        UTExportedTypeDeclarations
+        UTImportedTypeDeclarations
+        ],
+    }
+
+    ValidKeysMacOsx =
+    {
+      :string => %w[ APInstallerURL ATSApplicationFontsPath ],
+      :bool => %w[ CSResourcesFileMapped QuartzGLEnable ],
+      :array_of_strings => %w[ APFiles ]
+    }
+
+    ValidKeysUiKit =
+    {
+      :string => %w[
+        UIInterfaceOrientation
+        UILaunchImageFile
+        UIStatusBarStyle
+        ],
+      :bool => %w[
+        UIApplicationExitsOnSuspend
+        UIFileSharingEnabled
+        UIPrerenderedIcon
+        UIRequiresPersistentWiFi
+        UIStatusBarHidden
+        UIViewEdgeAntialiasing
+        UIViewGroupOpacity
+        ],
+      :array_of_strings => %w[
+        UIAppFonts
+        UIBackgroundModes
+        UISupportedExternalAccessoryProtocols
+        UISupportedInterfaceOrientations
+        ],
+      :array_or_integer => %w[
+        UIDeviceFamily
+        ],
+      :array_or_hash => %w[
+        UIRequiredDeviceCapabilities
+        ],
+    }
+
+
+    # A Hash Array of the supported plist keys for this type. These are plist keys which belong to the
+    # PlistType for Info plists. Each CamelCased key name has a corresponding set_or_return method call.
+    # For example "CFBundleIdentifier" => c_f_bundle_identifier(value). For more information please see {file:PlistKeyNames}
+    # @see Plist4r::DataMethods
+    ValidKeys = {}.merge_array_of_hashes_of_arrays [
+      ValidKeysCoreFoundation,
+      ValidKeysLaunchServices,
+      ValidKeysCocoa,
+      ValidKeysMacOsx,
+      ValidKeysUiKit
+      ]
+
   end
 end
 
 
 
+
+

data/lib/plist4r/plist_type/launchd.rb

@@ -2,22 +2,31 @@
 require 'plist4r/plist_type'
 
 module Plist4r
+  # @author Dreamcat4 (dreamcat4@gmail.com)
   class PlistType::Launchd < PlistType
 
-    # A Hash Array of the supported plist keys for this type. These are the plist keys are recognized to belong to a Launchd plist.
-    # Used in validation, categorized by the value's DataType.
+    # A Hash Array of the supported plist keys for this type. These are plist keys which belong to the
+    # PlistType for Launchd plists. Each CamelCased key name has a corresponding set_or_return method call.
+    # For example "UserName" => user_name(value). For more information please see {file:PlistKeyNames}
     # @see Plist4r::DataMethods
-    def self.valid_keys
-      {
-        :string => %w[Label UserName GroupName LimitLoadToSessionType Program RootDirectory WorkingDirectory StandardInPath StandardOutPath StandardErrorPath],
-        :bool => %w[Disabled EnableGlobbing EnableTransactions OnDemand RunAtLoad InitGroups StartOnMount Debug WaitForDebugger AbandonProcessGroup HopefullyExitsFirst HopefullyExitsLast LowPriorityIO LaunchOnlyOnce],
-        :integer => %w[Umask TimeOut ExitTimeOut ThrottleInterval StartInterval Nice],
-        :array_of_strings => %w[LimitLoadToHosts LimitLoadFromHosts ProgramArguments WatchPaths QueueDirectories],
-        :method_defined => %w[inetdCompatibility KeepAlive EnvironmentVariables StartCalendarInterval SoftResourceLimits, HardResourceLimits MachServices Sockets]
-      }
-    end
+    ValidKeys =
+    {
+      :string           => %w[ Label UserName GroupName LimitLoadToSessionType Program RootDirectory \
+                               WorkingDirectory StandardInPath StandardOutPath StandardErrorPath ],
+
+      :bool             => %w[ Disabled EnableGlobbing EnableTransactions OnDemand RunAtLoad InitGroups \
+                               StartOnMount Debug WaitForDebugger AbandonProcessGroup HopefullyExitsFirst \
+                               HopefullyExitsLast LowPriorityIO LaunchOnlyOnce ],
+
+      :integer          => %w[ Umask TimeOut ExitTimeOut ThrottleInterval StartInterval Nice ],
+
+      :array_of_strings => %w[ LimitLoadToHosts LimitLoadFromHosts ProgramArguments WatchPaths QueueDirectories ],
 
-    # Set or return the plist key "inetdCompatibility"
+      :method_defined   => %w[ inetdCompatibility KeepAlive EnvironmentVariables StartCalendarInterval 
+                               SoftResourceLimits, HardResourceLimits MachServices Sockets ]
+    }
+
+    # Set or return the plist key +inetdCompatibility+
     # @param [Hash <true,false>] value the 
     # The presence of this key specifies that the daemon expects to be run as if it were launched from inetd.
     # 
@@ -27,10 +36,10 @@ module Plist4r
     # 
     # @example
     # # set inetdCompatibility
-    # launchd_plist.inetdCompatibility({:wait => true})
+    # launchd_plist.inetd_compatibility({:wait => true})
     # 
     # # return inetdCompatibility
-    # launchd_plist.inetdCompatibility => hash or nil
+    # launchd_plist.inetd_compatibility => hash or nil
     #
     def inetd_compatibility value=nil
       key = "inetdCompatibility"
@@ -49,15 +58,14 @@ module Plist4r
     end
     
     class KeepAlive < ArrayDict
-      def valid_keys
-        {
-          :bool => %w[SuccessfulExit NetworkState],
-          :hash_of_bools => %w[PathState OtherJobEnabled]
-        }
-      end
+      ValidKeys =
+      {
+        :bool => %w[SuccessfulExit NetworkState],
+        :hash_of_bools => %w[PathState OtherJobEnabled]
+      }
     end
 
-    # Set or return the plist key "KeepAlive"
+    # Set or return the plist key +KeepAlive+
     #
     # @param [true, false, Hash] value 
     # This optional key is used to control whether your job is to be kept continuously running or to let demand and conditions control the invocation. The default is
@@ -121,7 +129,7 @@ module Plist4r
       end
     end
 
-    # Set or return the plist key "EnvironmentVariables"
+    # Set or return the plist key +EnvironmentVariables+
     #
     # @example
     #  # Set environment variables
@@ -153,12 +161,10 @@ module Plist4r
     end
 
     class StartCalendarInterval < ArrayDict
-      def valid_keys
-        { :integer => %w[Minute Hour Day Weekday Month] }
-      end
+      ValidKeys = { :integer => %w[ Minute Hour Day Weekday Month ] }
     end
 
-    # Set or return the plist key "StartCalendarInterval"
+    # Set or return the plist key +StartCalendarInterval+
     # 
     # This optional key causes the job to be started every calendar interval as specified. Missing arguments are considered to be wildcard. The semantics are much like
     # crontab(5).  Unlike cron which skips job invocations when the computer is asleep, launchd will start the job the next time the computer wakes up.  If multiple
@@ -227,12 +233,11 @@ module Plist4r
     end
 
     class ResourceLimits < ArrayDict
-      def valid_keys
-        { :integer => %w[Core CPU Data FileSize MemoryLock NumberOfFiles NumberOfProcesses ResidentSetSize Stack] }
-      end
+      ValidKeys = { :integer => %w[ Core CPU Data FileSize MemoryLock NumberOfFiles \
+                                    NumberOfProcesses ResidentSetSize Stack ] }
     end
   
-    # Set or return the plist key "SoftResourceLimits"
+    # Set or return the plist key +SoftResourceLimits+
     # 
     # Resource limits to be imposed on the job. These adjust variables set with setrlimit(2).  The following keys apply:
     # 
@@ -297,7 +302,7 @@ module Plist4r
       end
     end
 
-    # Set or return the plist key "HardResourceLimits"
+    # Set or return the plist key +HardResourceLimits+
     # 
     # Resource limits to be imposed on the job. These adjust variables set with setrlimit(2).  The following keys apply:
     # 
@@ -364,15 +369,13 @@ module Plist4r
 
   	class MachServices < ArrayDict
     	class MachService < ArrayDict
-    	  def valid_keys
-          { :bool => %w[ResetAtClose HideUntilCheckIn] }
-        end
+    	  ValidKeys = { :bool => %w[ ResetAtClose HideUntilCheckIn ] }
       end
 
   	  def add service, value=nil, &blk
         if value
     	    @hash[service] = value
-          set_or_return :bool, service, value
+          set_or_return_of_type :bool, service, value
         elsif blk
           @hash[service] = ::Plist4r::OrderedHash.new
           @hash[service] = ::LaunchdPlistStructs::MachServices::MachService.new(@hash[service],&blk).hash
@@ -382,9 +385,9 @@ module Plist4r
       end    
     end
   
-    # Set or return the plist key "MachServices"
+    # Set or return the plist key +MachServices+
     #
-    # Structure: "A dictionary of booleans" or a "dictionary of dictionaries"
+    # Structure: +dictionary of booleans+ or +dictionary of dictionaries+
     # 
     # This optional key is used to specify Mach services to be registered with the Mach bootstrap sub-system.  Each key in this dictionary should be the name of service
     # to be advertised. The value of the key must be a boolean and set to true.  Alternatively, a dictionary can be used instead of a simple true value.
@@ -433,14 +436,17 @@ module Plist4r
 
     class Sockets < ArrayDict
       class Socket < ArrayDict
-        def valid_keys
-          {
-            :string => %w[SockType SockNodeName SockServiceName SockFamily SockProtocol SockPathName SecureSocketWithKey MulticastGroup],
-            :bool => %w[SockPassive],
-            :integer => %w[SockPathMode],
-            :bool_or_string_or_array_of_strings => %w[Bonjour]
-          }
-        end
+        ValidKeys =
+        {
+          :string  => %w[ SockType SockNodeName SockServiceName SockFamily SockProtocol \
+                          SockPathName SecureSocketWithKey MulticastGroup ],
+
+          :bool    => %w[ SockPassive ],
+
+          :integer => %w[ SockPathMode ],
+
+          :bool_or_string_or_array_of_strings => %w[ Bonjour ]
+        }
       end
 
       def add_socket_to_dictionary key, &blk
@@ -470,9 +476,9 @@ module Plist4r
       end
     end
 
-    # Set or return the plist key "Sockets"
+    # Set or return the plist key +Sockets+
     # 
-    # Structure: "dictionary of dictionaries... OR dictionary of array of dictionaries..."
+    # Structure: +dictionary of dictionaries+ or +dictionary of array+ +of+ +dictionaries+
     # 
     # Please see http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPSystemStartup/Articles/LaunchOnDemandDaemons.html
     # for more information about how to properly use the Sockets feature.
@@ -591,7 +597,7 @@ module Plist4r
     #     bonjour ['smb']
     #   end
     #  # => Result: Exception error is raise the second time because the "Listeners" key already 
-    #  # exists. We can forcefully overwrite this existing sockets key with `socket "Listeners" do`.
+    #  # exists. We can forcefully overwrite this existing sockets key with +socket "Listeners" do+.
     #  
     #  # scenario 3:
     #   socket "netbios-ssn" do