cfbundle 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 34fbdac8d95981c1ee22c2cb3b57a5f80d1cd975
+  data.tar.gz: 85f292ed9c14e869a69b2d01c3238765fe29f5ae
+SHA512:
+  metadata.gz: d162902ed081d3c2cc34d108e0d881846333eec364c9daa34208477c3c66f0f4e1f08389e008272dea1487570f60562ce71f6a515218ccaa4169e5953d59c104
+  data.tar.gz: b8fbc74c34d59c06bf626f744517c74419773c4732fe01b49e9d5e44a8569bfb7219380e7d42c8fb414bd0f87762546d62940b96e9298b100923a1135e0ac143

data/lib/cfbundle/bundle.rb

@@ -0,0 +1,255 @@
+require 'cfbundle/constants'
+require 'cfbundle/localization'
+require 'cfbundle/path_utils'
+require 'cfbundle/plist'
+require 'cfbundle/resource'
+require 'cfbundle/storage_detection'
+
+module CFBundle
+  # A Bundle is an abstraction of a bundle accessible by the program.
+  class Bundle
+    # Opens a bundle.
+    #
+    # With no associated block, {open} is a synonym for {initialize new}. If the
+    # optional code block is given, it will be passed the opened bundle as an
+    # argument and the Bundle object will automatically be closed when the block
+    # terminates. The value of the block will be returned from the method.
+    #
+    # @param file [Object] The file to open. See {initialize} for a description
+    #                      of the supported values.
+    # @yieldparam bundle [Bundle] The opened bundle. It is automatically closed
+    #                              when the block terminates.
+    # @return [Object] The return value of the block when a block if given.
+    # @return [Bundle] The opened bundle when no block is given.
+    def self.open(file)
+      bundle = new(file)
+      return bundle unless block_given?
+      begin
+        yield bundle
+      ensure
+        bundle.close
+      end
+    end
+
+    # Opens the bundle and returns a new Bundle object.
+    #
+    # A new {storage} is automatically created from the +file+ parameter:
+    # * If the file is a path to a bundle directory, a new {Storage::FileSystem}
+    #   is created that references the bundle at the path.
+    # * If the file is an +IO+ or a path to a ZIP archive, a new {Storage::Zip}
+    #   is created that references the bundle within the archive.
+    #   The +rubyzip+ gem must be loaded and the archive is expected to contain
+    #   a single bundle at its root (or inside a +Payload+ directory for +.ipa+
+    #   archives).
+    # * If the file is a {Storage::Base}, it is used as the bundle's storage.
+    #
+    # You should send +#close+ when the bundle is no longer needed.
+    #
+    # Note that storages created from an exisiting +IO+ do not automatically
+    # close the file when the bundle is closed.
+    #
+    # @param file [Object] The file to open.
+    # @raise [ArgumentError] If the file cannot be opened.
+    def initialize(file)
+      @storage = StorageDetection.open(file)
+    end
+
+    # Closes the bundle and its underlying storage.
+    # @return [void]
+    def close
+      @storage.close
+    end
+
+    # The abstract storage used by the bundle.
+    #
+    # The storage implements the methods that are used by Bundle to read the
+    # bundle from the underlying storage (ZIP archive or file system).
+    #
+    # @return [Storage::Base]
+    # @see Storage::FileSystem
+    # @see Storage::Zip
+    attr_reader :storage
+
+    # Returns the bundle's information property list hash.
+    # @return [Hash]
+    def info
+      @info ||= Plist.load_info_plist(self)
+    end
+
+    # Returns the bundle identifier from the bundle's information property list.
+    # @return [String, nil]
+    # @see INFO_KEY_BUNDLE_IDENTIFIER
+    def identifier
+      info_string(CFBundle::INFO_KEY_BUNDLE_IDENTIFIER)
+    end
+
+    # Returns the bundle's build version number.
+    # @return [String, nil]
+    # @see INFO_KEY_BUNDLE_VERSION
+    def build_version
+      info_string(CFBundle::INFO_KEY_BUNDLE_VERSION)
+    end
+
+    # Returns the bundle's release version number.
+    # @return [String, nil]
+    # @see INFO_KEY_BUNDLE_SHORT_VERSION_STRING
+    def release_version
+      info_string(CFBundle::INFO_KEY_BUNDLE_SHORT_VERSION_STRING)
+    end
+
+    # Returns the bundle's OS Type code.
+    #
+    # The value for this key consists of a four-letter code.
+    # @return [String, nil]
+    # @see INFO_KEY_BUNDLE_PACKAGE_TYPE
+    # @see PACKAGE_TYPE_APPLICATION
+    # @see PACKAGE_TYPE_BUNDLE
+    # @see PACKAGE_TYPE_FRAMEWORK
+    def package_type
+      info_string(CFBundle::INFO_KEY_BUNDLE_PACKAGE_TYPE)
+    end
+
+    # Returns the short name of the bundle.
+    # @return [String, nil]
+    # @see INFO_KEY_BUNDLE_NAME
+    def name
+      info_string(CFBundle::INFO_KEY_BUNDLE_NAME)
+    end
+
+    # Returns the user-visible name of the bundle.
+    # @return [String, nil]
+    # @see INFO_KEY_BUNDLE_DISPLAY_NAME
+    def display_name
+      info_string(CFBundle::INFO_KEY_BUNDLE_DISPLAY_NAME)
+    end
+
+    # Returns the name of the development language of the bundle.
+    # @return [String, nil]
+    # @see INFO_KEY_BUNDLE_DEVELOPMENT_REGION
+    def development_localization
+      info_string(CFBundle::INFO_KEY_BUNDLE_DEVELOPMENT_REGION)
+    end
+
+    # Returns the name of the bundle's executable file.
+    # @return [String, nil]
+    # @see INFO_KEY_BUNDLE_EXECUTABLE
+    def executable_name
+      info_string(CFBundle::INFO_KEY_BUNDLE_EXECUTABLE)
+    end
+
+    # Returns the path of the bundle's executable file.
+    #
+    # The executable's path is relative to the bundle's path.
+    # @return [String, nil]
+    # @see INFO_KEY_BUNDLE_EXECUTABLE
+    def executable_path
+      @executable_path ||=
+        executable_name && lookup_executable_path(executable_name)
+    end
+
+    # Returns the path of the bundle's subdirectory that contains its resources.
+    #
+    # The path is relative to the bundle's path. For iOS application bundles,
+    # as the resources directory is the bundle, this method returns a single dot
+    # (+.+).
+    # @return [String]
+    # @see Resource
+    def resources_directory
+      case layout_version
+      when 0 then 'Resources'
+      when 2 then 'Contents/Resources'
+      when 3 then '.'
+      end
+    end
+
+    # Returns a list of all the localizations contained in the bundle.
+    # @return [Array]
+    def localizations
+      @localizations ||= Localization.localizations_in(self)
+    end
+
+    # Returns an ordered list of preferred localizations contained in the
+    # bundle.
+    # @param preferred_languages [Array] An array of strings (or symbols)
+    #        corresponding to a user's preferred languages.
+    # @return [Array]
+    def preferred_localizations(preferred_languages)
+      Localization.preferred_localizations(localizations, preferred_languages)
+    end
+
+    # Returns the first {Resource} object that matches the specified parameters.
+    #
+    # @param name [String?] The name to match or +nil+ to match any name.
+    # @param extension [String?] The extension to match or +nil+ to match any
+    #        extension.
+    # @param subdirectory [String?] The name of the bundle subdirectory
+    #        search.
+    # @param localization [String?, Symbol?] A language identifier to restrict
+    #        the search to a specific localization.
+    # @param preferred_languages [Array] An array of strings (or symbols)
+    #        corresponding to a user's preferred languages.
+    # @param product [String?] The product to match or +nil+ to match any
+    #        product.
+    # @return [Resource?]
+    # @see Resource.foreach
+    def find_resource(name, extension: nil, subdirectory: nil,
+                      localization: nil, preferred_languages: [], product: nil)
+      Resource.foreach(
+        self, name,
+        extension: extension, subdirectory: subdirectory,
+        localization: localization, preferred_languages: preferred_languages,
+        product: product
+      ).first
+    end
+
+    # Returns all the {Resource} objects that matches the specified parameters.
+    #
+    # @param name [String?] The name to match or +nil+ to match any name.
+    # @param extension [String?] The extension to match or +nil+ to match any
+    #        extension.
+    # @param subdirectory [String?] The name of the bundle subdirectory to
+    #        search.
+    # @param localization [String?, Array] The language identifier for the
+    #        localization.
+    # @param preferred_languages [Array] An array of strings (or symbols)
+    #        corresponding to a user's preferred languages.
+    # @param product [String?] The product to match or +nil+ to match any
+    #        product.
+    # @return [Array] An array of {Resource} objects.
+    # @see Resource.foreach
+    def find_resources(name, extension: nil, subdirectory: nil,
+                       localization: nil, preferred_languages: [], product: nil)
+      Resource.foreach(
+        self, name,
+        extension: extension, subdirectory: subdirectory,
+        localization: localization, preferred_languages: preferred_languages,
+        product: product
+      ).to_a
+    end
+
+    private
+
+    def layout_version
+      @layout_version ||= detect_layout_version
+    end
+
+    def detect_layout_version
+      return 2 if storage.directory? 'Contents'
+      return 0 if storage.directory? 'Resources'
+      3
+    end
+
+    def info_string(key)
+      value = info[key.to_s]
+      value.to_s unless value.nil?
+    end
+
+    def lookup_executable_path(name)
+      root = layout_version == 2 ? 'Contents' : '.'
+      path = PathUtils.join(root, 'MacOS', name)
+      return path if storage.file? path
+      path = PathUtils.join(root, name)
+      return path if storage.file? path
+    end
+  end
+end

data/lib/cfbundle/constants.rb

@@ -0,0 +1,14 @@
+module CFBundle
+  INFO_KEY_BUNDLE_DEVELOPMENT_REGION    = 'CFBundleDevelopmentRegion'.freeze
+  INFO_KEY_BUNDLE_DISPLAY_NAME          = 'CFBundleDisplayName'.freeze
+  INFO_KEY_BUNDLE_EXECUTABLE            = 'CFBundleExecutable'.freeze
+  INFO_KEY_BUNDLE_IDENTIFIER            = 'CFBundleIdentifier'.freeze
+  INFO_KEY_BUNDLE_NAME                  = 'CFBundleName'.freeze
+  INFO_KEY_BUNDLE_PACKAGE_TYPE          = 'CFBundlePackageType'.freeze
+  INFO_KEY_BUNDLE_SHORT_VERSION_STRING  = 'CFBundleShortVersionString'.freeze
+  INFO_KEY_BUNDLE_VERSION               = 'CFBundleVersion'.freeze
+
+  PACKAGE_TYPE_APPLICATION              = 'APPL'.freeze
+  PACKAGE_TYPE_BUNDLE                   = 'BNDL'.freeze
+  PACKAGE_TYPE_FRAMEWORK                = 'FMWK'.freeze
+end

data/lib/cfbundle/localization.rb

@@ -0,0 +1,66 @@
+module CFBundle
+  # @private
+  #
+  # Utility methods to perform localization.
+  module Localization
+    # The file extension of localization directories.
+    FILE_EXTENSION = '.lproj'.freeze
+
+    class << self
+      # Returns all the localizations contained in a bundle.
+      # @param bundle [Bundle] The bundle to search.
+      # @return [Array]
+      def localizations_in(bundle)
+        return [] unless bundle.storage.directory?(bundle.resources_directory)
+        bundle.storage
+              .foreach(bundle.resources_directory)
+              .select { |path| File.extname(path) == FILE_EXTENSION }
+              .map { |path| File.basename(path, FILE_EXTENSION) }
+      end
+
+      # Returns an ordered list of preferred localizations contained in a
+      # bundle.
+      # @param localizations [Array] An array of localization identifiers.
+      # @param preferred_languages [Array] An array of strings (or symbols)
+      #        corresponding to a user's preferred languages.
+      # @return [Array]
+      # @see Bundle#localizations
+      def preferred_localizations(localizations, preferred_languages)
+        preferred_languages.each do |language|
+          result = matching_localizations(localizations, language)
+          return result unless result.empty?
+          result = alternate_regional_localizations(localizations, language)
+          return result unless result.empty?
+        end
+        []
+      end
+
+      private
+
+      def matching_localizations(localizations, language)
+        result = []
+        loop do
+          if localizations.include?(language.to_s) ||
+             localizations.include?(language.to_sym)
+            result << language
+          end
+          language = language.to_s.rpartition('-').first
+          break if language.empty?
+        end
+        result
+      end
+
+      def alternate_regional_localizations(localizations, language)
+        loop do
+          language = language.to_s.rpartition('-').first
+          return [] if language.empty?
+          prefix = language + '-'
+          match = localizations.find do |localization|
+            localization.start_with?(prefix)
+          end
+          return [match.to_s] if match
+        end
+      end
+    end
+  end
+end

data/lib/cfbundle/path_utils.rb

@@ -0,0 +1,70 @@
+module CFBundle
+  # @private
+  #
+  # Utility methods for manipulating paths
+  module PathUtils
+    class << self
+      # Returns a new path formed by joining the strings using
+      # +File::SEPARATOR+.
+      #
+      # The methods also makes sure to remove any trailing separator along with
+      # path components that are empty, nil or a single dot (+.+) in order to
+      # generate a canonical path.
+      #
+      # @param args [Array] An array of strings.
+      # @return [String]
+      def join(*args)
+        args.compact!
+        args.map! { |arg| arg.split(File::SEPARATOR) }
+        args.flatten!
+        args.reject! { |arg| arg == '.' }
+        return '.' if args.empty?
+        absolute = args.first == ''
+        args.reject! { |arg| arg == '' }
+        args.unshift('/') if absolute
+        File.join(args)
+      end
+
+      # Splits the resource path into four components.
+      #
+      # The components are the resource's directory, name, product and
+      # extension. The product is either empty or starts with a tilde. The
+      # extension is either empty or starts with a dot.
+      # @param path [String] The path to the resource.
+      # @return [Array]
+      # @see join_resource
+      def split_resource(path)
+        directory = File.dirname(path)
+        extension = File.extname(path)
+        basename = File.basename(path, extension)
+        name, product = split_resource_name_and_product(basename)
+        [directory, name, product, extension]
+      end
+
+      # Returns a new path formed by joining the resource components.
+      # @param directory [String] The resource's directory.
+      # @param name [String] The resource's name.
+      # @param product [String] The resource's product. It should be empty or
+      #                         start with a tilde.
+      # @param extension [String] The resource's extension. It should be empty
+      #                           or start with a dot.
+      # @return [String]
+      # @see split_resource
+      def join_resource(directory, name, product, extension)
+        filename = [name, product, extension].join
+        join(directory, filename)
+      end
+
+      private
+
+      def split_resource_name_and_product(basename)
+        name, _, product = basename.rpartition('~')
+        if name.empty? || product.empty?
+          [basename, '']
+        else
+          [name, '~' + product]
+        end
+      end
+    end
+  end
+end

data/lib/cfbundle/plist.rb

@@ -0,0 +1,37 @@
+require 'cfpropertylist'
+
+module CFBundle
+  # @private
+  #
+  # Utility methods for manipulating Property list files.
+  module Plist
+    class << self
+      # Loads the +Info.plist+ file in a bundle.
+      # @param bundle [Bundle] The bundle to search.
+      # @return [Hash]
+      def load_info_plist(bundle)
+        load_plist(bundle, info_plist_path_in(bundle))
+      end
+
+      # Loads a Propery list file in a bundle.
+      # @param bundle [Bundle] The bundle to search.
+      # @param path [String] The path to the Property list file in the bundle.
+      # @return [Hash]
+      def load_plist(bundle, path)
+        data = bundle.storage.open(path, &:read)
+        plist = CFPropertyList::List.new(data: data)
+        CFPropertyList.native_types(plist.value)
+      end
+
+      private
+
+      def info_plist_path_in(bundle)
+        case bundle.send :layout_version
+        when 0 then 'Resources/Info.plist'
+        when 2 then 'Contents/Info.plist'
+        when 3 then 'Info.plist'
+        end
+      end
+    end
+  end
+end

data/lib/cfbundle/resource.rb

@@ -0,0 +1,202 @@
+require 'cfbundle/path_utils'
+
+module CFBundle
+  # A {Resource} is an abstraction of file contained within a {Bundle}.
+  class Resource
+    # Returns the resource's enclosing bundle.
+    # @return [Bundle]
+    attr_reader :bundle
+
+    # Returns the path to the resource within the bundle.
+    # @return [String]
+    attr_reader :path
+
+    # @param bundle [Bundle] The resource's enclosing bundle.
+    # @param path [String] The path of the resource within the bundle.
+    def initialize(bundle, path)
+      @bundle = bundle
+      @path = path
+      @directory, @name, @product, @extension = PathUtils.split_resource(path)
+    end
+
+    # Opens the resource for reading.
+    #
+    # With no associated block, the method returns an IO. If the optional block
+    # is given, it will be passed the opened file and the file will
+    # automatically be closed when the block terminates.
+    # @yieldparam file [IO] The opened file. It is automatically closed when the
+    #                       block terminates.
+    # @return [Object] The return value to the block when a block is given.
+    # @return [IO] The opened file. When no block is given.
+    def open(&block)
+      bundle.storage.open(path, &block)
+    end
+
+    # Enumerates the resources in a bundle that match the specified parameters.
+    #
+    # @param bundle [Bundle] The bundle that contains the resources.
+    # @param name [String?] The name to match or +nil+ to match any name.
+    # @param extension [String?] The extension to match or +nil+ to match any
+    #        extension.
+    # @param localization [String?, Symbol?] A language identifier to restrict
+    #        the search to a specific localization.
+    # @param preferred_languages [Array] An array of strings (or symbols)
+    #        corresponding to a user's preferred languages.
+    # @param product [String?] The product to match or +nil+ to match any
+    #        product.
+    # @yieldparam resource [Resource]
+    # @return [nil] When a block is given.
+    # @return [Enumerator] When no block is given.
+    def self.foreach(bundle, name, extension: nil, subdirectory: nil,
+                     localization: nil, preferred_languages: [], product: nil,
+                     &block)
+      enumerator = ::Enumerator.new do |y|
+        enumerator = Enumerator.new(bundle, subdirectory, localization,
+                                    preferred_languages)
+        predicate = Predicate.new(name, extension, product)
+        loop do
+          resource = enumerator.next
+          y << resource if resource.send(:match?, predicate)
+        end
+      end
+      enumerator.each(&block)
+    end
+
+    private
+
+    def match?(predicate)
+      return false unless name_match?(predicate) &&
+                          extension_match?(predicate) &&
+                          product_match?(predicate)
+      predicate.uniq?(@name, @extension)
+    end
+
+    def name_match?(predicate)
+      predicate.name.nil? || @name == predicate.name
+    end
+
+    def extension_match?(predicate)
+      predicate.extension.nil? || @extension == predicate.extension
+    end
+
+    def product_match?(predicate)
+      return true if @product == predicate.product
+      return false unless @product.empty?
+      !bundle.storage.exist?(path_with_product(predicate.product))
+    end
+
+    def path_with_product(product)
+      PathUtils.join_resource(@directory, @name, product, @extension)
+    end
+
+    # @private
+    #
+    # Performs the enumeration of a bundle's resources.
+    class Enumerator
+      # @param bundle [Bundle] The bundle that contains the resources.
+      # @param subdirectory [String?] The name of the bundle subdirectory to
+      #        search.
+      # @param localization [String?, Symbol?] A language identifier to restrict
+      #        the search to a specific localization.
+      # @param preferred_languages [Array] An array of strings (or symbols)
+      #        corresponding to a user's preferred languages.
+      def initialize(bundle, subdirectory, localization, preferred_languages)
+        @bundle = bundle
+        @directory = PathUtils.join(bundle.resources_directory, subdirectory)
+        @localizations = localizations_for(bundle, localization,
+                                           preferred_languages)
+        @enumerator = [].to_enum
+      end
+
+      # Returns the next resource in the bundle.
+      #
+      # @return [Resource]
+      # @raise [StopIteration]
+      def next
+        Resource.new(@bundle, @enumerator.next)
+      rescue StopIteration
+        @enumerator = next_enumerator
+        retry
+      end
+
+      private
+
+      def next_enumerator
+        loop do
+          break if @localizations.empty?
+          localization = @localizations.shift
+          directory = localized_directory_for(localization)
+          next unless @bundle.storage.directory?(directory)
+          return @bundle.storage.foreach(directory)
+        end
+        raise StopIteration
+      end
+
+      def localized_directory_for(localization)
+        return @directory unless localization
+        PathUtils.join(@directory, localization + '.lproj')
+      end
+
+      def localizations_for(bundle, localization, preferred_languages)
+        return [nil, localization.to_s] if localization
+        [
+          nil,
+          *bundle.preferred_localizations(preferred_languages || []),
+          bundle.development_localization
+        ].uniq
+      end
+    end
+
+    # @private
+    #
+    # Stores the parameters to select the matching resources while enumerating
+    # the resources of a bundle.
+    class Predicate
+      # Returns the name to match or +nil+ to match any name.
+      # @return [String?]
+      attr_reader :name
+
+      # Returns the extension to match or +nil+ to match any extension.
+      # @return [String?]
+      attr_reader :extension
+
+      # Returns the product to match.
+      # @return [String]
+      attr_reader :product
+
+      # @param name [String?] The name to match or +nil+ to match any name.
+      # @param extension [String?] The extension to match or +nil+ to match any
+      #                            extension.
+      # @param product [String?] The product to match.
+      def initialize(name, extension, product)
+        @name = name
+        @extension = extension_for(extension)
+        @product = product_for(product)
+        @keys = Set.new
+      end
+
+      # Ensures the given name and extension are unique during the enumeration.
+      #
+      # @param name [String] The resource name.
+      # @param extension [String] The resource extension.
+      def uniq?(name, extension)
+        key = [name, extension].join
+        return false if @keys.include?(key)
+        @keys << key
+        true
+      end
+
+      private
+
+      def extension_for(extension)
+        return extension if extension.nil? || extension.empty?
+        extension.start_with?('.') ? extension : '.' + extension
+      end
+
+      def product_for(product)
+        return '' if product.nil? || product.empty?
+        product.start_with?('~') ? product : '~' + product
+      end
+    end
+  end
+end

data/lib/cfbundle/storage/base.rb

@@ -0,0 +1,69 @@
+module CFBundle
+  module Storage
+    # The {Storage::Base} class defines the methods required to access a
+    # bundle's underlying storage.
+    #
+    # Most of the time, you don't need to concern youself with storages as
+    # {CFBundle::Bundle.open} and {CFBundle::Bundle#initialize}
+    # automatically detect and instantiate the appropriate storage.
+    class Base
+      # Returns whether a given path exists within the storage.
+      #
+      # @param path [String] The path of a file or directory, relative to the
+      #                      storage.
+      def exist?(path)
+        # :nocov:
+        false
+        # :nocov:
+      end
+
+      # Returns whether a given file exists within the storage.
+      #
+      # @param path [String] The path of a file, relative to the storage.
+      def file?(path)
+        # :nocov:
+        false
+        # :nocov:
+      end
+
+      # Returns whether a given directory exists within the storage.
+      #
+      # @param path [String] The path of a directory, relative to the storage.
+      def directory?(path)
+        # :nocov:
+        false
+        # :nocov:
+      end
+
+      # Opens a file for reading in the storage.
+      #
+      # @param path [String] The path of the file to open.
+      # @yieldparam file [IO] The opened file. It is automatically closed when
+      #                       the block terminates.
+      # @return [Object] The return value of the block when a block if given.
+      # @return [IO] The opened file when no block is given.
+      def open(path, &block)
+        # :nocov:
+        raise(Errno::ENOENT, path)
+        # :nocov:
+      end
+
+      # Returns an enumerator that enumerates the files contained in a
+      # directory.
+      #
+      # @param path [String] The path to the directory to enumerate.
+      # @return [Enumerator]
+      def foreach(path)
+        # :nocov:
+        raise(Errno::ENOENT, path)
+        # :nocov:
+      end
+
+      # Invoked when the storage is no longer needed.
+      #
+      # The default implementation does nothing.
+      # @return [void]
+      def close; end
+    end
+  end
+end

data/lib/cfbundle/storage/file_system.rb

@@ -0,0 +1,58 @@
+require 'cfbundle/path_utils'
+require 'cfbundle/storage/base'
+
+module CFBundle
+  module Storage
+    # A bundle storage that reads from the file system.
+    class FileSystem < Base
+      # @param path [String] The path of the bundle on the file system.
+      def initialize(path)
+        @root = path
+      end
+
+      # (see Base#exist?)
+      def exist?(path)
+        find(path) != nil
+      end
+
+      # (see Base#file?)
+      def file?(path)
+        entry = find(path)
+        !entry.nil? && File.file?(entry)
+      end
+
+      # (see Base#directory?)
+      def directory?(path)
+        entry = find(path)
+        !entry.nil? && File.directory?(entry)
+      end
+
+      # (see Base#open)
+      def open(path, &block)
+        File.open find!(path), &block
+      end
+
+      # (see Base#foreach)
+      def foreach(path)
+        Enumerator.new do |y|
+          base = Dir.foreach find!(path)
+          loop do
+            entry = base.next
+            y << PathUtils.join(path, entry) unless ['.', '..'].include?(entry)
+          end
+        end
+      end
+
+      private
+
+      def find(path)
+        entry = PathUtils.join(@root, path)
+        entry if File.exist? entry
+      end
+
+      def find!(path)
+        find(path) || raise(Errno::ENOENT, path)
+      end
+    end
+  end
+end

data/lib/cfbundle/storage/zip.rb

@@ -0,0 +1,96 @@
+require 'cfbundle/path_utils'
+require 'cfbundle/storage/base'
+
+module CFBundle
+  module Storage
+    # A bundle storage that reads from a ZIP archive.
+    class Zip < Base
+      # @param zip [Zip::File] The Zip file containing the bundle.
+      # @param path [String] The path of the bundle within the Zip file.
+      # @param skip_close [Boolean] Whether the storage should skip closing
+      #                             the Zip file when receiving {#close}.
+      def initialize(zip, path, skip_close: false)
+        @zip = zip
+        @root = path
+        @skip_close = skip_close
+      end
+
+      # (see Base#exist?)
+      def exist?(path)
+        find(path) != nil
+      end
+
+      # (see Base#file?)
+      def file?(path)
+        entry = find(path)
+        !entry.nil? && entry.file?
+      end
+
+      # (see Base#directory?)
+      def directory?(path)
+        entry = find(path)
+        !entry.nil? && entry.directory?
+      end
+
+      # (see Base#open)
+      def open(path, &block)
+        find!(path).get_input_stream(&block)
+      end
+
+      # (see Base#foreach)
+      def foreach(path)
+        Enumerator.new do |y|
+          directory = find! path
+          base = @zip.entries.each
+          loop do
+            entry = base.next
+            next unless entry.parent_as_string == directory.name
+            y << PathUtils.join(path, File.basename(entry.name))
+          end
+        end
+      end
+
+      # Invoked when the storage is no longer needed.
+      #
+      # This method closes the underlying Zip file unless the storage was
+      # initialized with +skip_close: true+.
+      # @return [void]
+      def close
+        @zip.close unless @skip_close
+      end
+
+      private
+
+      def find(path, symlinks = Set.new)
+        name = PathUtils.join(@root, path)
+        entry = @zip.find_entry name
+        if entry.nil?
+          find_in_parent(path, symlinks)
+        elsif entry.symlink?
+          find_symlink(entry.get_input_stream(&:read), path, symlinks)
+        else
+          entry
+        end
+      end
+
+      def find!(path)
+        find(path) || raise(Errno::ENOENT, path)
+      end
+
+      def find_in_parent(path, symlinks)
+        directory, filename = File.split(path)
+        return if ['.', '/'].include? filename
+        entry = find(directory, symlinks)
+        return unless entry && entry.directory?
+        @zip.find_entry File.join(entry.name, filename)
+      end
+
+      def find_symlink(path, symlink, symlinks)
+        return if path.start_with?('/') || symlinks.include?(symlink)
+        symlinks << symlink
+        resolved_path = PathUtils.join(File.dirname(symlink), path)
+        find(resolved_path, symlinks)
+      end
+    end
+  end
+end

data/lib/cfbundle/storage_detection.rb

@@ -0,0 +1,86 @@
+require 'cfbundle/storage/base'
+require 'cfbundle/storage/file_system'
+require 'cfbundle/storage/zip'
+
+module CFBundle
+  # @private
+  #
+  # Utility methods required to detect and instantiate a bundle's storage.
+  module StorageDetection
+    class << self
+      # Opens a file and returns a bundle storage.
+      # @param file The file to open.
+      # @return [Storage]
+      def open(file)
+        storage = open_as_storage(file) ||
+                  open_as_io(file) ||
+                  open_as_path(file)
+        raise "#{file.inspect} is not a bundle" unless storage
+        storage
+      end
+
+      private
+
+      def path_for(file)
+        if file.is_a? String
+          file
+        elsif file.respond_to? :to_path
+          file.to_path
+        end
+      end
+
+      def open_as_storage(file)
+        file if file.is_a?(Storage::Base)
+      end
+
+      def open_as_path(file)
+        path = path_for(file) || return
+        ext = File.extname(path)
+        if File.directory?(path) && ext != ''
+          Storage::FileSystem.new(path)
+        elsif ['.ipa', '.zip'].include? ext
+          open_zip_path(path)
+        end
+      end
+
+      def open_as_io(file)
+        open_zip_io(file.to_io) if file.respond_to?(:to_io)
+      end
+
+      def open_zip_path(path)
+        open_zip_file(path, &:open)
+      end
+
+      def open_zip_io(io)
+        open_zip_file(io, &:open_buffer)
+      end
+
+      def open_zip_file(file, skip_close: false)
+        unless defined?(Zip)
+          raise "cannot open ZIP archive #{file.inspect} without Rubyzip"
+        end
+        zip = yield(Zip::File, file)
+        entry = matching_zip_entry(zip)
+        Storage::Zip.new(zip, entry.name, skip_close: skip_close)
+      end
+
+      def matching_zip_entry(zip)
+        entries = zip.entries.select { |entry| zip_entry_match?(entry) }
+        case entries.count
+        when 1
+          entries.first
+        when 0
+          raise "no bundle found in ZIP archive \"#{zip}\""
+        else
+          raise "several bundles found in ZIP archive \"#{zip}\""
+        end
+      end
+
+      def zip_entry_match?(entry)
+        entry.directory? &&
+          [nil, 'Payload/'].include?(entry.parent_as_string) &&
+          File.extname(entry.name) != ''
+      end
+    end
+  end
+end

data/lib/cfbundle/version.rb

@@ -0,0 +1,3 @@
+module CFBundle
+  VERSION = '0.1.0'.freeze
+end

data/lib/cfbundle.rb

@@ -0,0 +1,11 @@
+require 'cfbundle/bundle'
+require 'cfbundle/constants'
+require 'cfbundle/storage/file_system'
+require 'cfbundle/storage/zip'
+require 'cfbundle/version'
+
+# Module for reading macOS and iOS bundles.
+#
+# See {CFBundle::Bundle.open} for opening bundles.
+module CFBundle
+end

metadata

@@ -0,0 +1,132 @@
+--- !ruby/object:Gem::Specification
+name: cfbundle
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Nicolas Bachschmidt
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-11-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: CFPropertyList
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.3.5
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.3.5
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.7.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.7.0
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.51.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.51.0
+- !ruby/object:Gem::Dependency
+  name: rubyzip
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.2.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.2.1
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.15.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.15.1
+description: CFBundle is a module for reading macOS and iOS bundles (including zipped
+  bundles and .ipa files).
+email: nicolas@h2g.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/cfbundle.rb
+- lib/cfbundle/bundle.rb
+- lib/cfbundle/constants.rb
+- lib/cfbundle/localization.rb
+- lib/cfbundle/path_utils.rb
+- lib/cfbundle/plist.rb
+- lib/cfbundle/resource.rb
+- lib/cfbundle/storage/base.rb
+- lib/cfbundle/storage/file_system.rb
+- lib/cfbundle/storage/zip.rb
+- lib/cfbundle/storage_detection.rb
+- lib/cfbundle/version.rb
+homepage: 
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.11
+signing_key: 
+specification_version: 4
+summary: CFBundle
+test_files: []