xcodeproj 0.1.0 → 0.2.0.rc1

data/ext/xcodeproj/extconf.h

@@ -0,0 +1,8 @@
+#ifndef EXTCONF_H
+#define EXTCONF_H
+#define HAVE_FRAMEWORK_COREFOUNDATION 1
+#define HAVE_COREFOUNDATION_COREFOUNDATION_H 1
+#define HAVE_COREFOUNDATION_CFSTREAM_H 1
+#define HAVE_COREFOUNDATION_CFPROPERTYLIST_H 1
+#define HAVE_RUBY_ST_H 1
+#endif

data/ext/xcodeproj/extconf.rb

@@ -37,6 +37,7 @@ end
 have_header 'CoreFoundation/CoreFoundation.h'
 have_header 'CoreFoundation/CFStream.h'
 have_header 'CoreFoundation/CFPropertyList.h'
+have_header 'ruby/st.h'
 
 create_header
 create_makefile 'xcodeproj_ext'

data/ext/xcodeproj/xcodeproj_ext.c

@@ -4,7 +4,10 @@
 #include "extconf.h"
 
 #include "ruby.h"
+#if HAVE_RUBY_ST_H
 #include "ruby/st.h"
+#endif
+
 #include "CoreFoundation/CoreFoundation.h"
 #include "CoreFoundation/CFStream.h"
 #include "CoreFoundation/CFPropertyList.h"
@@ -29,7 +32,14 @@ str_to_cfstr(VALUE str) {
   return CFStringCreateWithCString(NULL, RSTRING_PTR(rb_String(str)), kCFStringEncodingUTF8);
 }
 
-
+/* Generates a UUID. The original version is truncated, so this is not 100%
+ * guaranteed to be unique. However, the `PBXObject#generate_uuid` method
+ * checks that the UUID does not exist yet, in the project, before using it.
+ *
+ * @note Meant for internal use only.
+ *
+ * @return [String] A 24 characters long UUID.
+ */
 static VALUE
 generate_uuid(void) {
   CFUUIDRef uuid = CFUUIDCreate(NULL);
@@ -69,11 +79,22 @@ hash_set(const void *keyRef, const void *valueRef, void *hash) {
     value = rb_ary_new();
     CFIndex i, count = CFArrayGetCount(valueRef);
     for (i = 0; i < count; i++) {
-      CFStringRef x = CFArrayGetValueAtIndex(valueRef, i);
-      if (CFGetTypeID(x) == CFStringGetTypeID()) {
-        rb_ary_push(value, cfstr_to_str(x));
+      CFTypeRef elementRef = CFArrayGetValueAtIndex(valueRef, i);
+      CFTypeID elementType = CFGetTypeID(elementRef);
+      if (elementType == CFStringGetTypeID()) {
+        rb_ary_push(value, cfstr_to_str(elementRef));
+
+      } else if (elementType == CFDictionaryGetTypeID()) {
+        VALUE hashElement = rb_hash_new();
+        CFDictionaryApplyFunction(elementRef, hash_set, (void *)hashElement);
+        rb_ary_push(value, hashElement);
+
       } else {
-        rb_raise(rb_eTypeError, "Plist array value contains a object type unsupported by Xcodeproj.");
+        CFStringRef descriptionRef = CFCopyDescription(elementRef);
+        // obviously not optimial, but we're raising here, so it doesn't really matter
+        VALUE description = cfstr_to_str(descriptionRef);
+        rb_raise(rb_eTypeError, "Plist array value contains a object type unsupported by Xcodeproj. In: `%s'", RSTRING_PTR(description));
+        CFRelease(descriptionRef);
       }
     }
 
@@ -94,15 +115,26 @@ dictionary_set(st_data_t key, st_data_t value, CFMutableDictionaryRef dict) {
                                          0,
                                          &kCFTypeDictionaryKeyCallBacks,
                                          &kCFTypeDictionaryValueCallBacks);
-    st_foreach(RHASH_TBL(value), dictionary_set, (st_data_t)valueRef);
+    rb_hash_foreach(value, dictionary_set, (st_data_t)valueRef);
 
   } else if (TYPE(value) == T_ARRAY) {
     long i, count = RARRAY_LEN(value);
     valueRef = CFArrayCreateMutable(NULL, count, &kCFTypeArrayCallBacks);
     for (i = 0; i < count; i++) {
-      CFStringRef x = str_to_cfstr(RARRAY_PTR(value)[i]);
-      CFArrayAppendValue((CFMutableArrayRef)valueRef, x);
-      CFRelease(x);
+      VALUE element = RARRAY_PTR(value)[i];
+      CFTypeRef elementRef = NULL;
+      if (TYPE(element) == T_HASH) {
+        elementRef = CFDictionaryCreateMutable(NULL,
+                                               0,
+                                               &kCFTypeDictionaryKeyCallBacks,
+                                               &kCFTypeDictionaryValueCallBacks);
+        rb_hash_foreach(element, dictionary_set, (st_data_t)elementRef);
+      } else {
+        // otherwise coerce to string
+        elementRef = str_to_cfstr(element);
+      }
+      CFArrayAppendValue((CFMutableArrayRef)valueRef, elementRef);
+      CFRelease(elementRef);
     }
 
   } else {
@@ -130,7 +162,19 @@ str_to_url(VALUE path) {
 }
 
 
-// TODO handle errors
+/* @overload read_plist(path)
+ *
+ * Reads from the specified path and de-serializes the property list.
+ *
+ * @note This does not yet support all possible types that can exist in a valid property list.
+ *
+ * @note This currently only assumes to be given an Xcode project document.
+ *       This means that it only accepts dictionaries, arrays, and strings in
+ *       the document.
+ *
+ * @param [String] path  The path to the property list file.
+ * @return [Hash]        The dictionary contents of the document.
+ */
 static VALUE
 read_plist(VALUE self, VALUE path) {
   CFPropertyListRef dict;
@@ -159,6 +203,20 @@ read_plist(VALUE self, VALUE path) {
   return hash;
 }
 
+/* @overload write_plist(hash, path)
+ *
+ * Writes the serialized contents of a property list to the specified path.
+ *
+ * @note This does not yet support all possible types that can exist in a valid property list.
+ *
+ * @note This currently only assumes to be given an Xcode project document.
+ *       This means that it only accepts dictionaries, arrays, and strings in
+ *       the document.
+ *
+ * @param [Hash] hash     The property list to serialize.
+ * @param [String] path   The path to the property list file.
+ * @return [true, false]  Wether or not saving was successful.
+ */
 static VALUE
 write_plist(VALUE self, VALUE hash, VALUE path) {
   VALUE h = rb_check_convert_type(hash, T_HASH, "Hash", "to_hash");
@@ -171,7 +229,7 @@ write_plist(VALUE self, VALUE hash, VALUE path) {
                                                           &kCFTypeDictionaryKeyCallBacks,
                                                           &kCFTypeDictionaryValueCallBacks);
 
-  st_foreach(RHASH_TBL(h), dictionary_set, (st_data_t)dict);
+  rb_hash_foreach(h, dictionary_set, (st_data_t)dict);
 
   CFURLRef fileURL = str_to_url(path);
   CFWriteStreamRef stream = CFWriteStreamCreateWithFile(NULL, fileURL);

data/lib/xcodeproj.rb

@@ -1,5 +1,5 @@
 module Xcodeproj
-  VERSION = '0.1.0'
+  VERSION = '0.2.0.rc1'
   
   autoload :Config,    'xcodeproj/config'
   autoload :Project,   'xcodeproj/project'

data/lib/xcodeproj/config.rb

@@ -1,31 +1,163 @@
 module Xcodeproj
+  # This class holds the data for a Xcode build settings file (xcconfig) and
+  # serializes it.
   class Config
-    def initialize(xcconfig = {})
+    # Returns a new instance of Config
+    #
+    # @param [Hash, File, String] xcconfig_hash_or_file  Initial data.
+    require 'set'
+
+    attr_accessor :attributes, :frameworks ,:libraries
+
+    def initialize(xcconfig_hash_or_file = {})
       @attributes = {}
-      merge!(xcconfig)
+      @includes = []
+      @frameworks, @libraries = Set.new, Set.new
+      merge!(extract_hash(xcconfig_hash_or_file))
     end
 
+    # @return [Hash] The internal data.
     def to_hash
-      @attributes
+      hash = @attributes.dup
+      flags = hash['OTHER_LDFLAGS'] || ''
+      flags = flags.dup.strip
+      flags << libraries.to_a.sort.reduce('')  {| memo, l | memo << " -l#{l}" }
+      flags << frameworks.to_a.sort.reduce('') {| memo, f | memo << " -framework #{f}" }
+      hash['OTHER_LDFLAGS'] = flags.strip
+      hash.delete('OTHER_LDFLAGS') if flags.strip.empty?
+      hash
     end
 
+    def ==(other)
+      other.respond_to?(:to_hash) && other.to_hash == self.to_hash
+    end
+
+    # @return [Array] Config's include file list
+    # @example
+    #
+    # Consider following xcconfig file:
+    #
+    #   #include "SomeConfig"
+    #   Key1 = Value1
+    #   Key2 = Value2
+    #
+    #   config.includes # => [ "SomeConfig" ]
+    def includes
+      @includes
+    end
+
+    # Merges the given xcconfig hash or Config into the internal data.
+    #
+    # If a key in the given hash already exists, in the internal data, then its
+    # value is appended to the value in the internal data.
+    #
+    # @example
+    #
+    #   config = Config.new('PODS_ROOT' => '"$(SRCROOT)/Pods"', 'OTHER_LDFLAGS' => '-lxml2')
+    #   config.merge!('OTHER_LDFLAGS' => '-lz', 'HEADER_SEARCH_PATHS' => '"$(PODS_ROOT)/Headers"')
+    #   config.to_hash # => { 'PODS_ROOT' => '"$(SRCROOT)/Pods"', 'OTHER_LDFLAGS' => '-lxml2 -lz', 'HEADER_SEARCH_PATHS' => '"$(PODS_ROOT)/Headers"' }
+    #
+    # @param [Hash, Config] xcconfig  The data to merge into the internal data.
     def merge!(xcconfig)
-      xcconfig.to_hash.each do |key, value|
-        if existing_value = @attributes[key]
-          @attributes[key] = "#{existing_value} #{value}"
-        else
-          @attributes[key] = value
-        end
+      if xcconfig.is_a? Config
+        @attributes.merge!(xcconfig.attributes) { |key, v1, v2| "#{v1} #{v2}" }
+        @libraries.merge   xcconfig.libraries
+        @frameworks.merge  xcconfig.frameworks
+      else
+      @attributes.merge!(xcconfig.to_hash) { |key, v1, v2| "#{v1} #{v2}" }
+      # Parse frameworks and libraries. Then remove the from the linker flags
+      flags = @attributes['OTHER_LDFLAGS']
+      return unless flags
+
+      frameworks = flags.scan(/-framework\s+([^\s]+)/).map { |m| m[0] }
+      libraries  = flags.scan(/-l ?([^\s]+)/).map { |m| m[0] }
+      @frameworks.merge frameworks
+      @libraries.merge libraries
+
+      new_flags = flags.dup
+      frameworks.each {|f| new_flags.gsub!("-framework #{f}", "") }
+      libraries.each  {|l| new_flags.gsub!("-l#{l}", ""); new_flags.gsub!("-l #{l}", "") }
+      @attributes['OTHER_LDFLAGS'] = new_flags.gsub("\w*", ' ').strip
       end
     end
     alias_method :<<, :merge!
 
+    def merge(config)
+      self.dup.tap { |x|x.merge!(config) }
+    end
+
+    def dup
+      Xcodeproj::Config.new(self.to_hash.dup)
+    end
+
+    # Serializes the internal data in the xcconfig format.
+    #
+    # @example
+    #
+    #   config = Config.new('PODS_ROOT' => '"$(SRCROOT)/Pods"', 'OTHER_LDFLAGS' => '-lxml2')
+    #   config.to_s # => "PODS_ROOT = \"$(SRCROOT)/Pods\"\nOTHER_LDFLAGS = -lxml2"
+    #
+    # @return [String]  The serialized internal data.
     def to_s
-      @attributes.map { |key, value| "#{key} = #{value}" }.join("\n")
+      to_hash.map { |key, value| "#{key} = #{value}" }.join("\n")
+    end
+
+    def inspect
+      to_hash.inspect
     end
 
+    # Writes the serialized representation of the internal data to the given
+    # path.
+    #
+    # @param [Pathname] pathname  The file that the data should be written to.
     def save_as(pathname)
       pathname.open('w') { |file| file << to_s }
     end
+
+    private
+
+    def extract_hash(argument)
+      if argument.respond_to? :read
+        hash_from_file_content(argument.read)
+      elsif File.readable? argument.to_s
+        hash_from_file_content(File.read(argument))
+      else
+        argument
+      end
+    end
+
+    def hash_from_file_content(raw_string)
+      hash = {}
+      raw_string.split("\n").each do |line|
+        uncommented_line = strip_comment(line)
+        if include = extract_include(uncommented_line)
+          @includes.push include
+        else
+          key, value = extract_key_value(uncommented_line)
+          hash[key] = value if key
+        end
+      end
+      hash
+    end
+
+    def strip_comment(line)
+      line.partition('//').first
+    end
+
+    def extract_include(line)
+      regexp = /#include\s*"(.+)"/
+      match = line.match(regexp)
+      match[1] if match
+    end
+
+    def extract_key_value(line)
+      key, value = line.split('=', 2)
+      if key && value
+        [key.strip, value.strip]
+      else
+        []
+      end
+    end
+
   end
 end

data/lib/xcodeproj/inflector.rb

@@ -189,7 +189,7 @@ module Xcodeproj
         if first_letter_in_uppercase
           lower_case_and_underscored_word.to_s.gsub(/\/(.?)/) { "::#{$1.upcase}" }.gsub(/(?:^|_)(.)/) { $1.upcase }
         else
-          lower_case_and_underscored_word.first.downcase + camelize(lower_case_and_underscored_word)[1..-1]
+          lower_case_and_underscored_word[0,1].downcase + camelize(lower_case_and_underscored_word)[1..-1]
         end
       end
 

data/lib/xcodeproj/project.rb

@@ -1,555 +1,37 @@
 require 'fileutils'
-require 'xcodeproj/inflector'
+require 'pathname'
 require 'xcodeproj/xcodeproj_ext'
 
+require 'xcodeproj/project/object'
+
 module Xcodeproj
+  # This class represents a Xcode project document.
+  #
+  # It can be used to manipulate existing documents or even create new ones
+  # from scratch.
+  #
+  # The Project API returns instances of AbstractPBXObject which wrap the objects
+  # described in the Xcode project document.
   class Project
-    class PBXObject
-      class AssociationReflection
-        def initialize(name, options)
-          @name, @options = name.to_s, options
-        end
-
-        attr_reader :name, :options
-
-        def klass
-          @options[:class] ||= begin
-            name = "PBX#{@name.classify}"
-            name = "XC#{@name.classify}" unless Project.const_defined?(name)
-            Project.const_get(name)
-          end
-        end
-
-        def inverse
-          klass.reflection(@options[:inverse_of])
-        end
-
-        def inverse?
-          !!@options[:inverse_of]
-        end
-
-        def singular_name
-          @options[:singular_name] || @name.singularize
-        end
-
-        def singular_getter
-          singular_name
-        end
-
-        def singular_setter
-          "#{singular_name}="
-        end
-
-        def plural_name
-          @name.pluralize
-        end
-
-        def plural_getter
-          plural_name
-        end
-
-        def plural_setter
-          "#{plural_name}="
-        end
-
-        def uuid_attribute
-          @options[:uuid] || @name
-        end
-
-        def uuid_method_name
-          (@options[:uuid] || @options[:uuids] || "#{singular_name}Reference").to_s.singularize
-        end
-
-        def uuid_getter
-          uuid_method_name
-        end
-
-        def uuid_setter
-          "#{uuid_method_name}="
-        end
-
-        def uuids_method_name
-          uuid_method_name.pluralize
-        end
-
-        def uuids_getter
-          uuids_method_name
-        end
-
-        def uuids_setter
-          "#{uuids_method_name}="
-        end
-      end
-
-      def self.reflections
-        @reflections ||= []
-      end
-
-      def self.create_reflection(name, options)
-        (reflections << AssociationReflection.new(name, options)).last
-      end
-
-      def self.reflection(name)
-        reflections.find { |r| r.name.to_s == name.to_s }
-      end
-
-      def self.attribute(attribute_name, accessor_name = nil)
-        attribute_name = attribute_name.to_s
-        name = (accessor_name || attribute_name).to_s
-        define_method(name) { @attributes[attribute_name] }
-        define_method("#{name}=") { |value| @attributes[attribute_name] = value }
-      end
-
-      def self.attributes(*names)
-        names.each { |name| attribute(name) }
-      end
-
-      def self.has_many(plural_attr_name, options = {}, &block)
-        reflection = create_reflection(plural_attr_name, options)
-        if reflection.inverse?
-          define_method(reflection.name) do
-            scoped = @project.objects.select_by_class(reflection.klass).select do |object|
-              object.send(reflection.inverse.uuid_getter) == self.uuid
-            end
-            PBXObjectList.new(reflection.klass, @project, scoped) do |object|
-              object.send(reflection.inverse.uuid_setter, self.uuid)
-            end
-          end
-        else
-          attribute(reflection.name, reflection.uuids_getter)
-          define_method(reflection.name) do
-            uuids = send(reflection.uuids_getter)
-            if block
-              # Evaluate the block, which was specified at the class level, in
-              # the instance’s context.
-              list_by_class(uuids, reflection.klass) do |object|
-                instance_exec(object, &block)
-              end
-            else
-              list_by_class(uuids, reflection.klass)
-            end
-          end
-          define_method(reflection.plural_setter) do |objects|
-            send(reflection.uuids_setter, objects.map(&:uuid))
-          end
-        end
-      end
-
-      def self.has_one(singular_attr_name, options = {})
-        reflection = create_reflection(singular_attr_name, options)
-        if reflection.inverse?
-          define_method(reflection.name) do
-            # Loop over all objects of the class and find the one that includes
-            # this object in the specified uuid list.
-            @project.objects.select_by_class(reflection.klass).find do |object|
-              object.send(reflection.inverse.uuids_getter).include?(self.uuid)
-            end
-          end
-          define_method(reflection.singular_setter) do |object|
-            # Remove this object from the uuid list of the target
-            # that this object was associated to.
-            if previous = send(reflection.name)
-              previous.send(reflection.inverse.uuids_getter).delete(self.uuid)
-            end
-            # Now assign this object to the new object
-            object.send(reflection.inverse.uuids_getter) << self.uuid if object
-          end
-        else
-          attribute(reflection.uuid_attribute, reflection.uuid_getter)
-          define_method(reflection.name) do
-            @project.objects[send(reflection.uuid_getter)]
-          end
-          define_method(reflection.singular_setter) do |object|
-            send(reflection.uuid_setter, object.uuid)
-          end
-        end
-      end
-
-      def self.isa
-        @isa ||= name.split('::').last
-      end
-
-      attr_reader :uuid, :attributes
-      attributes :isa, :name
-
-      def initialize(project, uuid, attributes)
-        @project, @attributes = project, attributes
-        unless uuid
-          # Add new objects to the main hash with a unique UUID
-          begin; uuid = generate_uuid; end while @project.objects_hash.has_key?(uuid)
-          @project.objects_hash[uuid] = @attributes
-        end
-        @uuid = uuid
-        self.isa ||= self.class.isa
-      end
-
-      def ==(other)
-        other.is_a?(PBXObject) && self.uuid == other.uuid
-      end
-
-      def inspect
-        "#<#{isa} UUID: `#{uuid}', name: `#{name}'>"
-      end
-
-      private
-
-      def generate_uuid
-        Xcodeproj.generate_uuid
-      end
-
-      def list_by_class(uuids, klass, scoped = nil, &block)
-        unless scoped
-          scoped = uuids.map { |uuid| @project.objects[uuid] }.select { |o| o.is_a?(klass) }
-        end
-        if block
-          PBXObjectList.new(klass, @project, scoped, &block)
-        else
-          PBXObjectList.new(klass, @project, scoped) do |object|
-            # Add the uuid of a newly created object to the uuids list
-            uuids << object.uuid
-          end
-        end
-      end
-    end
-
-    # Missing constants that begin with either `PBX' or `XC' are assumed to be
-    # valid classes in a Xcode project. A new PBXObject subclass is created
-    # for the constant and returned.
-    def self.const_missing(name)
-      if name.to_s =~ /^(PBX|XC)/
-        klass = Class.new(PBXObject)
-        const_set(name, klass)
-        klass
-      else
-        super
-      end
-    end
-
-    class PBXFileReference < PBXObject
-      attributes :path, :sourceTree, :explicitFileType, :lastKnownFileType, :includeInIndex
-      has_many :buildFiles, :inverse_of => :file
-      has_one :group, :inverse_of => :children
-
-      def self.new_static_library(project, productName)
-        new(project, nil, {
-          "path"             => "lib#{productName}.a",
-          "includeInIndex"   => "0", # no idea what this is
-          "sourceTree"       => "BUILT_PRODUCTS_DIR",
-        })
-      end
-
-      def initialize(project, uuid, attributes)
-        is_new = uuid.nil?
-        super
-        self.path = path if path # sets default name
-        self.sourceTree ||= 'SOURCE_ROOT'
-        if is_new
-          @project.main_group.children << self
-        end
-        set_default_file_type!
-      end
-
-      alias_method :_path=, :path=
-      def path=(path)
-        self._path = path
-        self.name ||= pathname.basename.to_s
-        path
-      end
-
-      def pathname
-        Pathname.new(path)
-      end
-      
-      def set_default_file_type!
-        return if explicitFileType || lastKnownFileType
-        case path
-        when /\.a$/
-          self.explicitFileType = 'archive.ar'
-        when /\.framework$/
-          self.lastKnownFileType = 'wrapper.framework'
-        when /\.xcconfig$/
-          self.lastKnownFileType = 'text.xcconfig'
-        end
-      end
-    end
-
-    class PBXGroup < PBXObject
-      attributes :sourceTree
-
-      has_many :children, :class => PBXFileReference do |object|
-        if object.is_a?(Xcodeproj::Project::PBXFileReference)
-          # Associating the file to this group through the inverse
-          # association will also remove it from the group it was in.
-          object.group = self
-        else
-          # TODO What objects can actually be in a group and don't they
-          # all need the above treatment.
-          childReferences << object.uuid
-        end
-      end
-
-      def initialize(*)
-        super
-        self.sourceTree ||= '<group>'
-        self.childReferences ||= []
-      end
-
-      def files
-        list_by_class(childReferences, Xcodeproj::Project::PBXFileReference) do |file|
-          file.group = self
-        end
-      end
-
-      def source_files
-        files = self.files.reject { |file| file.buildFiles.empty? }
-        list_by_class(childReferences, Xcodeproj::Project::PBXFileReference, files) do |file|
-          file.group = self
-        end
-      end
-
-      def groups
-        list_by_class(childReferences, Xcodeproj::Project::PBXGroup)
-      end
-
-      def <<(child)
-        children << child
-      end
-    end
-
-    class PBXBuildFile < PBXObject
-      attributes :settings
-      has_one :file, :uuid => :fileRef
-    end
-
-    class PBXBuildPhase < PBXObject
-      # TODO rename this to buildFiles and add a files :through => :buildFiles shortcut
-      has_many :files, :class => PBXBuildFile
-
-      attributes :buildActionMask, :runOnlyForDeploymentPostprocessing
-
-      def initialize(*)
-        super
-        self.fileReferences ||= []
-        # These are always the same, no idea what they are.
-        self.buildActionMask ||= "2147483647"
-        self.runOnlyForDeploymentPostprocessing ||= "0"
+    module Object
+      class PBXProject < AbstractPBXObject
+        has_many :targets, :class => PBXNativeTarget
+        has_one :products_group, :uuid => :product_ref_group, :class => PBXGroup
+        has_one :build_configuration_list, :class => XCConfigurationList
       end
     end
 
-    class PBXCopyFilesBuildPhase < PBXBuildPhase
-      attributes :dstPath, :dstSubfolderSpec
-
-      def initialize(*)
-        super
-        self.dstSubfolderSpec ||= "16"
-      end
-    end
-
-    class PBXSourcesBuildPhase < PBXBuildPhase;     end
-    class PBXFrameworksBuildPhase < PBXBuildPhase;  end
-    class PBXShellScriptBuildPhase < PBXBuildPhase
-      attribute :shellScript
-    end
-
-    class PBXNativeTarget < PBXObject
-      STATIC_LIBRARY = 'com.apple.product-type.library.static'
-
-      attributes :productName, :productType
-
-      has_many :buildPhases
-      has_many :dependencies # TODO :class => ?
-      has_many :buildRules # TODO :class => ?
-      has_one :buildConfigurationList
-      has_one :product, :uuid => :productReference
-
-      def self.new_static_library(project, productName)
-        # TODO should probably switch the uuid and attributes argument
-        target = new(project, nil, 'productType' => STATIC_LIBRARY, 'productName' => productName)
-        target.product = project.files.new_static_library(productName)
-        products = project.groups.find { |g| g.name == 'Products' }
-        products ||= project.groups.new({ 'name' => 'Products'})
-        products.children << target.product
-        target.buildPhases.add(PBXSourcesBuildPhase)
-
-        buildPhase = target.buildPhases.add(PBXFrameworksBuildPhase)
-        frameworks = project.groups.find { |g| g.name == 'Frameworks' }
-        frameworks ||= project.groups.new({ 'name' => 'Frameworks'})
-        frameworks.files.each do |framework|
-          buildPhase.files << framework.buildFiles.new
-        end
-
-        target.buildPhases.add(PBXCopyFilesBuildPhase, 'dstPath' => '$(PRODUCT_NAME)')
-        target
-      end
-
-      # You need to specify a product. For a static library you can use
-      # PBXFileReference.new_static_library.
-      def initialize(project, *)
-        super
-        self.name ||= productName
-        self.buildRuleReferences  ||= []
-        self.dependencyReferences ||= []
-        self.buildPhaseReferences ||= []
-
-        unless buildConfigurationList
-          self.buildConfigurationList = project.objects.add(XCConfigurationList)
-          # TODO or should this happen in buildConfigurationList?
-          buildConfigurationList.buildConfigurations.new('name' => 'Debug')
-          buildConfigurationList.buildConfigurations.new('name' => 'Release')
-        end
-      end
-
-      alias_method :_product=, :product=
-      def product=(product)
-        self._product = product
-        product.group = @project.products
-      end
-
-      def buildConfigurations
-        buildConfigurationList.buildConfigurations
-      end
-
-      def source_build_phases
-        buildPhases.select_by_class(PBXSourcesBuildPhase)
-      end
-
-      def copy_files_build_phases
-        buildPhases.select_by_class(PBXCopyFilesBuildPhase)
-      end
-
-      def frameworks_build_phases
-        buildPhases.select_by_class(PBXFrameworksBuildPhase)
-      end
-
-      # Finds an existing file reference or creates a new one.
-      def add_source_file(path, copy_header_phase = nil, compiler_flags = nil)
-        file = @project.files.find { |file| file.path == path.to_s } || @project.files.new('path' => path.to_s)
-        buildFile = file.buildFiles.new
-        if path.extname == '.h'
-          buildFile.settings = { 'ATTRIBUTES' => ["Public"] }
-          # Working around a bug in Xcode 4.2 betas, remove this once the Xcode bug is fixed:
-          # https://github.com/alloy/cocoapods/issues/13
-          #phase = copy_header_phase || headers_build_phases.first
-          phase = copy_header_phase || copy_files_build_phases.first
-          phase.files << buildFile
-        else
-          buildFile.settings = { 'COMPILER_FLAGS' => compiler_flags } if compiler_flags
-          source_build_phases.first.files << buildFile
-        end
-        file
-      end
-    end
-
-    class XCBuildConfiguration < PBXObject
-      attribute :buildSettings
-      has_one :baseConfiguration, :uuid => :baseConfigurationReference
-
-      def initialize(*)
-        super
-        # TODO These are from an iOS static library, need to check if it works for any product type
-        self.buildSettings = {
-          'DSTROOT'                      => '/tmp/xcodeproj.dst',
-          'GCC_PRECOMPILE_PREFIX_HEADER' => 'YES',
-          'GCC_VERSION'                  => 'com.apple.compilers.llvm.clang.1_0',
-          'PRODUCT_NAME'                 => '$(TARGET_NAME)',
-          'SKIP_INSTALL'                 => 'YES',
-        }.merge(buildSettings || {})
-      end
-    end
-
-    class XCConfigurationList < PBXObject
-      has_many :buildConfigurations
-
-      def initialize(*)
-        super
-        self.buildConfigurationReferences ||= []
-      end
-    end
-
-    class PBXProject < PBXObject
-      has_many :targets, :class => PBXNativeTarget
-      has_one :products, :singular_name => :products, :uuid => :productRefGroup, :class => PBXGroup
-    end
-
-    class PBXObjectList
-      include Enumerable
-
-      def initialize(represented_class, project, scoped, &new_object_callback)
-        @represented_class = represented_class
-        @project           = project
-        @scoped_hash       = scoped.is_a?(Array) ? scoped.inject({}) { |h, o| h[o.uuid] = o.attributes; h } : scoped
-        @callback          = new_object_callback
-      end
-
-      def empty?
-        @scoped_hash.empty?
-      end
-
-      def [](uuid)
-        if hash = @scoped_hash[uuid]
-          Project.const_get(hash['isa']).new(@project, uuid, hash)
-        end
-      end
-
-      def add(klass, hash = {})
-        object = klass.new(@project, nil, hash)
-        @callback.call(object) if @callback
-        object
-      end
-
-      def new(hash = {})
-        add(@represented_class, hash)
-      end
-
-      def <<(object)
-        @callback.call(object) if @callback
-      end
-
-      def each
-        @scoped_hash.keys.each do |uuid|
-          yield self[uuid]
-        end
-      end
-
-      def ==(other)
-        self.to_a == other.to_a
-      end
-
-      def first
-        to_a.first
-      end
-
-      def last
-        to_a.last
-      end
-
-      def inspect
-        "<PBXObjectList: #{map(&:inspect)}>"
-      end
-
-      # Only makes sense on lists that contain mixed classes.
-      def select_by_class(klass)
-        scoped = Hash[*@scoped_hash.select { |_, attr| attr['isa'] == klass.isa }.flatten]
-        PBXObjectList.new(klass, @project, scoped) do |object|
-          # Objects added to the subselection should still use the same
-          # callback as this list.
-          self << object
-        end
-      end
-
-      def method_missing(name, *args, &block)
-        if @represented_class.respond_to?(name)
-          object = @represented_class.send(name, @project, *args)
-          # The callbacks are only for PBXObject instances instantiated
-          # from the class method that we forwarded the message to.
-          @callback.call(object) if object.is_a?(PBXObject)
-          object
-        else
-          super
-        end
-      end
-    end
+    include Object
 
+    # Opens a Xcode project document if a path to one is given, otherwise a new
+    # Project is created.
+    #
+    # @param [Pathname, String] xcodeproj  The path to the Xcode project
+    #                                      document (xcodeproj).
+    #
+    # @return [Project]                    A new Project instance or one with
+    #                                      the data of an existing Xcode
+    #                                      document.
     def initialize(xcodeproj = nil)
       if xcodeproj
         file = File.join(xcodeproj, 'project.pbxproj')
@@ -561,86 +43,180 @@ module Xcodeproj
           'objectVersion' => '46',
           'objects' => {}
         }
-        self.root_object = objects.add(Xcodeproj::Project::PBXProject, {
+        main_group = groups.new
+        self.root_object = objects.add(PBXProject, {
           'attributes' => { 'LastUpgradeCheck' => '0420' },
           'compatibilityVersion' => 'Xcode 3.2',
           'developmentRegion' => 'English',
           'hasScannedForEncodings' => '0',
           'knownRegions' => ['en'],
-          'mainGroup' => groups.new.uuid,
+          'mainGroup' => main_group.uuid,
+          'productRefGroup' => main_group.groups.new('name' => 'Products').uuid,
           'projectDirPath' => '',
           'projectRoot' => '',
           'targets' => []
         })
+
+        config_list = objects.add(XCConfigurationList)
+        config_list.default_configuration_name = 'Release'
+        config_list.default_configuration_is_visible = '0'
+        config_list.build_configurations.new('name' => 'Debug')
+        config_list.build_configurations.new('name' => 'Release')
+        self.root_object.build_configuration_list = config_list
+
+        # TODO make this work
+        #self.root_object.product_reference = groups.new('name' => 'Products').uuid
       end
     end
 
+    # @return [Hash]  The internal data.
     def to_hash
       @plist
     end
 
+    def ==(other)
+      other.respond_to?(:to_hash) && @plist == other.to_hash
+    end
+
+    # This gives access to the objects part of the internal data hash. It is,
+    # however, **not** recommended to use this to add a hash for an object, for
+    # that see `add_object_hash`.
+    #
+    # @return [Hash]  The `objects` part of the internal data.
     def objects_hash
       @plist['objects']
     end
 
-    def objects
-      @objects ||= PBXObjectList.new(PBXObject, self, objects_hash)
+    # This is the preferred way to add an object attributes hash to the objects
+    # hash, as it validates the data before inserting it.
+    #
+    # @param [String] uuid        The UUID of the object.
+    # @param [Hash]   attributes  The attributes of the object.
+    #
+    # @raise [ArgumentError]      Raised if the value of the `isa` key is equal
+    #                             to `AbstractPBXObject`.
+    #
+    # @todo Ideally we would do more validation here, but I don't think we know
+    #       of all classes that can exist yet.
+    def add_object_hash(uuid, attributes)
+      if attributes['isa'] !~ /^(PBX|XC)/
+        raise ArgumentError, "Attempted to insert a `#{attributes['isa']}' instance into the objects hash, which is not allowed."
+      end
+      objects_hash[uuid] = attributes
     end
 
+    # @return [PBXProject]  The root object of the project.
     def root_object
       objects[@plist['rootObject']]
     end
 
+    # @param [PBXProject] object  The object to assign as the root object.
     def root_object=(object)
       @plist['rootObject'] = object.uuid
     end
 
+    # @return [PBXObjectList<AbstractPBXObject>]  A list of all the objects in the
+    #                                     project.
+    def objects
+      PBXObjectList.new(AbstractPBXObject, self) do |list|
+        list.let(:uuid_scope) { objects_hash.keys }
+      end
+    end
+
+    # @return [PBXObjectList<PBXGroup>]  A list of all the groups in the
+    #                                    project.
     def groups
-      objects.select_by_class(PBXGroup)
+      objects.list_by_class(PBXGroup)
     end
-    
+
+    # Tries to find a group with the given name.
+    #
+    # @param [String] name     The name of the group to find.
+    # @return [PBXGroup, nil]  The PBXgroup, if found.
+    def group(name)
+      groups.object_named(name)
+    end
+
+    # @return [PBXGroup]  The main top-level group.
     def main_group
       objects[root_object.attributes['mainGroup']]
     end
 
+    # @return [PBXObjectList<PBXFileReference>]  A list of all the files in the
+    #                                            project.
     def files
-      objects.select_by_class(PBXFileReference)
-    end
-
+      objects.list_by_class(PBXFileReference)
+    end
+
+    # Adds a file reference for a system framework to the project.
+    #
+    # The file reference can then be added to the buildFiles of a
+    # PBXFrameworksBuildPhase.
+    #
+    # @example
+    #
+    #     framework = project.add_system_framework('QuartzCore')
+    #
+    #     target = project.targets.first
+    #     build_phase = target.frameworks_build_phases.first
+    #     build_phase.files << framework.buildFiles.new
+    #
+    # @todo Make it possible to do: `build_phase << framework`
+    #
+    # @param [String] name        The name of a framework in the SDK System
+    #                             directory.
+    # @return [PBXFileReference]  The file reference object.
     def add_system_framework(name)
-      files.new({
+      group = groups.where('name' => 'Frameworks') || groups.new('name' => 'Frameworks')
+      group.files.new({
         'name' => "#{name}.framework",
         'path' => "System/Library/Frameworks/#{name}.framework",
         'sourceTree' => 'SDKROOT'
       })
     end
-    
-    def add_shell_script_build_phase(name, script_path)
-      objects.add(Xcodeproj::Project::PBXShellScriptBuildPhase, {
-        'name' => name,
-        'files' => [],
-        'inputPaths' => [],
-        'outputPaths' => [],
-        'shellPath' => '/bin/sh',
-        'shellScript' => script_path
-      })
+
+    # @return [PBXObjectList<XCBuildConfiguration]  A list of project wide
+    #                                               build configurations.
+    def build_configurations
+      root_object.build_configuration_list.build_configurations
     end
 
-    def build_files
-      objects.select_by_class(PBXBuildFile)
+    # @param [String] name  The name of a project wide build configuration.
+    #
+    # @return [Hash]        The build settings of the project wide build
+    #                       configuration with the given name.
+    def build_settings(name)
+      root_object.build_configuration_list.build_settings(name)
     end
 
+    # @todo There are probably other target types too. E.g. an aggregate.
+    #
+    # @return [PBXObjectList<PBXNativeTarget>]  A list of all the targets in
+    #                                           the project.
     def targets
       # Better to check the project object for targets to ensure they are
       # actually there so the project will work
       root_object.targets
     end
 
+    # @return [PBXGroup]  The group which holds the product file references.
+    def products_group
+      root_object.products_group
+    end
+
+    # @return [PBXObjectList<PBXFileReference>]  A list of the product file
+    #                                            references.
     def products
-      root_object.products
+      products_group.children
     end
 
+    # @private
     IGNORE_GROUPS = ['Frameworks', 'Products', 'Supporting Files']
+
+    # @todo I think this is here because of easier testing in CocoaPods. Move
+    #       this extension to the CocoaPods specs.
+    #
+    # @return [Hash]  A list of all the groups and their source files.
     def source_files
       source_files = {}
       groups.each do |group|
@@ -650,6 +226,18 @@ module Xcodeproj
       source_files
     end
 
+    # Serializes the internal data as a property list and stores it on disk at
+    # the given path.
+    #
+    # @example
+    #
+    #     project.save_as("path/to/Project.xcodeproj") # => true
+    #
+    # @param [String, Pathname] projpath  The path where the data should be
+    #                                     stored.
+    #
+    # @return [true, false]               Returns whether or not saving was
+    #                                     successful.
     def save_as(projpath)
       projpath = projpath.to_s
       FileUtils.mkdir_p(projpath)