xcoder 0.1.4 → 0.1.6

data/lib/xcode/file_reference.rb

@@ -1,15 +1,30 @@
 module Xcode
   
   #
-  # Within the project file the PBXFileReference represents the object 
-  # representation to the file on the file sytem. This is usually your source
-  # files within your project.
+  # Within the project file the FileReference represents a large number of objects
+  # related to files like source files, resources, frameworks, and system libraries.
+  # 
+  # A FileReference is used as input to add to the various Build Phases.
+  # 
+  # @see BuildPhase 
+  # @see BuildFile
   # 
   module FileReference
     
     # This is the group for which this file is contained within.
+    # @return [Group] the group that contains this file.
     attr_accessor :supergroup
     
+    #
+    # Generate the properties for a file. A name and a path option need to
+    # be specified in the properties.
+    # 
+    # @note a 'name' and 'path' key need to be specified in the framework for
+    #   the framework to be added correctly.
+    # 
+    # @param [Hash] properties to override or merge with the base properties.
+    # @return [Hash] properties of a file
+    #
     def self.file(properties)
       default_properties = { 'isa' => 'PBXFileReference', 
         'path' => nil,
@@ -49,7 +64,8 @@ module Xcode
     # @param [String] name of the system framework which can be specified with or
     #   without the ".framework" suffix / extension.
     # @param [Hash] properties the parameters to override for the system framework
-    #
+    # @return [Hash] system framework properties
+    # 
     def self.system_framework(name,properties = {})
 
       name = name[/(.+)(?:\.framework)?$/,1]
@@ -73,7 +89,8 @@ module Xcode
     # @param [String] name of the system library, which can be found by default
     #   in the /usr/lib folder.
     # @param [Types] properties the parameters to override for the system library
-    #
+    # @return [Hash] system library properties
+    # 
     def self.system_library(name,properties = {})
       default_properties = { 'isa' => 'PBXFileReference',
         'lastKnownFileType' => 'compiled.mach-o.dylib', 
@@ -94,6 +111,9 @@ module Xcode
     #       path = newtarget.app; 
     #       sourceTree = BUILT_PRODUCTS_DIR; };
     # 
+    # @param [String] name name of the app product
+    # @return [Hash] app product properties
+    # 
     def self.app_product(name)
       { 'isa' => 'PBXFileReference',
         'explicitFileType' => 'wrapper.application',

data/lib/xcode/group.rb

@@ -26,6 +26,7 @@ module Xcode
     # Return the hash that maps to the properties for a logical group
     # 
     # @param [String] name of the logical group
+    # @return [Hash] the properties for a Group
     # 
     def self.logical_group(name)
       { 'isa' => 'PBXGroup', 
@@ -68,7 +69,9 @@ module Xcode
     
     #
     # Find all the non-group objects within the group and return them
-    # @return [Array] the children of the group, excluding the groups
+    # 
+    # @return [Array<Resource>] the children of the group, excluding the 
+    #   groups, which is usually composed of FileReferences
     # 
     def files
       children.reject {|child| child.is_a?(Group) }
@@ -86,11 +89,18 @@ module Xcode
     end
     
     #
-    # Check whether a file or group is contained within this group.
-    #
+    # Check whether a file or group is contained within this group that has a name
+    # that matches the one specified
+    # 
+    # @param [String] name of the group attempting to be found.
+    # 
+    # @return [Array<Resource>] resource with the name that matches; empty array 
+    #   if no matches were found.
+    # 
     def exists?(name)
       children.find_all {|child| child.name == name }
     end
+    
     #
     # Adds a group as a child to current group with the given name. 
     # 
@@ -99,7 +109,9 @@ module Xcode
     # 
     # @param [String] name of the group that you want to add as a child group of
     #   the specified group.
-    #
+    # 
+    # @return [Group] the created group
+    # 
     def create_group(name)
       new_group = create_child_object Group.logical_group(name)
       new_group.supergroup = self
@@ -120,7 +132,9 @@ module Xcode
     # 
     # @param [String,Hash] path to the file that is being added or a hash that 
     #   contains the values would be merged with the default values.
-    #
+    # 
+    # @return [FileReference] the file created.
+    # 
     def create_file(file_properties)
       # This allows both support for the string value or the hash as the parameter
       file_properties = { 'path' => file_properties } if file_properties.is_a? String
@@ -151,6 +165,8 @@ module Xcode
     # @param [Hash] framework_properties the properties to merge with the default
     #   properties.
     #
+    # @return [FileReference] the framework created.
+    # 
     def create_framework(framework_properties)
       find_or_create_child_object FileReference.framework(framework_properties)
     end
@@ -164,7 +180,8 @@ module Xcode
     #     project.frameworks_group.create_system_framework "Foundation"
     #
     # @param [String] name the name of the System framework to add to this group.
-    #
+    # @return [FileReference] the system framework created.
+    # 
     def create_system_framework(name)
       find_or_create_child_object FileReference.system_framework(name)
     end
@@ -177,7 +194,8 @@ module Xcode
     #     project.frameworks_group.create_system_library "libz.dylib"
     #
     # @param [String] name the name of the System Library to add to this group.
-    #
+    # @return [FileReference] the system library created.
+    # 
     def create_system_library(name)
       find_or_create_child_object FileReference.system_library(name)
     end
@@ -189,7 +207,8 @@ module Xcode
     #   properties.
     # 
     # @see VariantGroup#info_plist
-    #
+    # @return [VariantGroup] the infoplist created
+    # 
     def create_infoplist(infoplist_properties)
       create_child_object VariantGroup.info_plist(infoplist_properties)
     end
@@ -203,6 +222,7 @@ module Xcode
     # @see Target#create_product_reference
     # 
     # @param [String] name the name of the product to generate
+    # @return [FileReference] the app product created.
     # 
     def create_product_reference(name)
       create_child_object FileReference.app_product(name)

data/lib/xcode/project.rb

@@ -1,20 +1,40 @@
-require 'plist'
 require 'xcode/parsers/plutil_project_parser'
 require 'xcode/resource'
-require 'xcode/target'
-require 'xcode/configuration'
-require 'xcode/scheme'
-require 'xcode/group'
-require 'xcode/file_reference'
 require 'xcode/registry'
-require 'xcode/build_phase'
-require 'xcode/variant_group'
-require 'xcode/configuration_list'
 
 module Xcode
+  
+  #
+  # The project is the representation of an Xcode Project folder, the `*.xcodeproj`,
+  # folder that contains a number of workspace files and project files like
+  # `project.pbxproj`. 
+  # 
+  # The Project represents the top-most element within the structure. It contains 
+  # most of the methods that allow you to traverse through the targets and
+  # configurations that it is composed.
+  # 
   class Project 
     
-    attr_reader :name, :sdk, :path, :schemes, :registry
+    # @return [String] the name of the project; This value is deteremined from the 
+    #   first part of the Xcode project folder name (e.g. "TestProject.xcodeproj" 
+    #   name is "TestProject")
+    attr_reader :name
+    
+    # @return [String] the sdks for the project. This is specified during the project
+    #   initialization. If none are provided this currently defaults to "iphoneos"
+    attr_reader :sdk
+    
+    # @return [String] the expanded file path for the project. This is expanded from the
+    #   file path specified during initialization.
+    attr_reader :path
+    
+    # @return [Array<Scheme>] the schemes that are found within the project path.
+    attr_reader :schemes
+    
+    # @return [Registry] the data that is parsed from the project.pbxproj, it is
+    #   in most part a Hash with additional methods included to provide core
+    #   functionality.
+    attr_reader :registry
     
     #
     # Initialized with a specific path and sdk.
@@ -61,7 +81,7 @@ module Xcode
     #
     # Returns the main group of the project where all the files reside.
     # 
-    # @todo this really could use a better name then groups as it is the mainGroup
+    # @todo this really could use a better name then groups as it is the main group
     #   but it should likely be something like main_group, root or something
     #   else that conveys that this is the project root for files, and such.
     # 
@@ -78,20 +98,22 @@ module Xcode
     # the path the group is created. Also paths can be specified to make the 
     # traversing of the groups easier.
     # 
-    # @example a group path that contains a traversal to sub-groups
+    # @note this will attempt to find the paths specified, if it fails to find them
+    #   it will create one and then continue traversing.
+    #
+    # @example Traverse a path through the various sub-groups.
     # 
     #     project.group('Vendor/MyCode/Support Files')
-    #     # is equivalent to...
+    #     # is equivalent to ...
     #     project.group('Vendor').first.group('MyCode').first.group('Supporting Files')
     # 
     # @note this path functionality current is only exercised from the project level
     #   all groups will treat the path division `/` as simply a character.
     # 
-    # @note this will attempt to find the paths specified, if it fails to find them
-    #   it will create one and then continue traversing.
-    #
     # @param [String] name the group name to find/create
     # 
+    # @return [Group] the group with the specified name.
+    # 
     def group(name,options = {},&block)
       # By default create missing groups along the way
       options = { :create => true }.merge(options)
@@ -222,7 +244,7 @@ module Xcode
     #
     # All the targets specified within the project.
     # 
-    # @return [Array<PBXNativeTarget>] an array of all the available targets for
+    # @return [Array<Target>] an array of all the available targets for
     #   the specific project.
     # 
     def targets
@@ -239,7 +261,7 @@ module Xcode
     # @note if two targets match names, the first matching target is returned.
     # 
     # @param [String] name of the specific target
-    # @return [PBXNativeTarget] the specific target that matches the name specified
+    # @return [Target] the specific target that matches the name specified
     #
     def target(name)
       target = targets.select {|t| t.name == name.to_s}.first
@@ -264,6 +286,8 @@ module Xcode
     # @param [String] name the name to provide to the target. This will also
     #   be the value that other defaults will be based on.
     #
+    # @return [Target] the target created.
+    # 
     def create_target(name,type=:ios)
       
       target = @registry.add_object Target.send(type)
@@ -294,16 +318,17 @@ module Xcode
     # @param [String] name the name of the target to remove from the Xcode
     #   project.
     #
+    # @return [Target] the target that has been removed.
+    # 
     def remove_target(name)
       found_target = targets.find {|target| target.name == name }
       if found_target
         @project.properties['targets'].delete found_target.identifier
         @registry.remove_object found_target.identifier
       end
+      found_target
     end
     
-    
-    
     # 
     # Prints to STDOUT a description of this project's targets, configuration and schemes.  
     #
@@ -330,6 +355,9 @@ module Xcode
     # the schemes will load the shared ones and then the current acting user's
     # schemes.
     # 
+    # @return [Array<Scheme>] the shared schemes and user specific schemes found
+    #   within the projet at the path defined for schemes.
+    # 
     def parse_schemes
       shared_schemes = Dir["#{@path}/xcshareddata/xcschemes/*.xcscheme"]
       user_specific_schemes = Dir["#{@path}/xcuserdata/#{ENV['USER']}.xcuserdatad/xcschemes/*.xcscheme"]
@@ -341,16 +369,12 @@ module Xcode
   
     #
     # Using the sytem tool plutil, the specified project file is parsed and 
-    # converted to JSON, which is then converted to a hash object.
-    # 
-    # This content contains all the data within the project file and is used
-    # to create the Registry.
-    # 
-    # @return [Resource] a resource mapped to the root resource within the project
-    #   this is generally the project file which contains details about the main
-    #   group, targets, etc.
+    # converted to JSON, which is then converted to a hash object. This content 
+    # contains all the data within the project file and is used to create the 
+    # Registry.
     # 
-    # @see Registry
+    # @return [Registry] the representation of the project, this is a Hash with
+    #   additional methods to provide easier functionality.
     # 
     def parse_pbxproj
       registry = Xcode::PLUTILProjectParser.parse "#{@path}/project.pbxproj"

data/lib/xcode/registry.rb

@@ -1,17 +1,33 @@
+require 'xcode/build_file'
+require 'xcode/build_phase'
+require 'xcode/configuration'
+require 'xcode/configuration_list'
+require 'xcode/file_reference'
+require 'xcode/group'
+require 'xcode/resource'
+require 'xcode/scheme'
 require 'xcode/simple_identifier_generator'
+require 'xcode/target'
+require 'xcode/variant_group'
 
 module Xcode
   
   #
-  # The Registry represents the parsed data from the Xcode Project file. Namely
-  # the registry is a Hash that provides additional functionality to allow the 
+  # The Registry represents the parsed data from the Xcode Project file. The 
+  # registry is a Hash that provides additional functionality to allow the 
   # the ability to query, add, and remove resources from the object hash.
   # 
   # Opening the Xcode project file in a text-editor you'll notice that it is a
-  # big hash/plist with a file core keys. The most important key is the 'objects'
-  # dictionary which maintains the master-list of Identifiers to properties. All 
-  # objects are represented here and all other resources use the reference
-  # to make the connection to the objects.
+  # big hash/plist. The registry represents this structure and provides access
+  # to the top-level items: 'rootObject'; 'objectVersion'; 'archiveVersion' and 
+  # 'objects'. The registry provides a number of methods to access these items.
+  # 
+  # The most important key is the 'objects' dictionary which maintains the 
+  # master-list of Identifiers to properties. The registry provides additional
+  # methods get, add, remove, and update the objects stored within it. The 
+  # registry returns {Resource} objects which is a wrapper class around the 
+  # properties hash that would normally be returned. Providing additional 
+  # functionality to make it easier to traverse the project.
   # 
   # @see Project
   # 
@@ -21,18 +37,31 @@ module Xcode
     # This method is used internally to determine if the value that is being 
     # retrieved is an identifier.
     # 
+    # @see Resource#define_property
+    # 
     # @param [String] value is the specified value in the form of an identifier
-    #
+    # @return [TrueClass,FalseClass] true if the value specified is a valid 
+    #   identifier; false if it is not.
+    # 
     def self.is_identifier? value
       value =~ /^[0-9A-F]{24}$/
     end
 
     #
-    # Objects within the registry contain an `isa` property, which translates
-    # to modules which can be mixed in to provide additional functionality.
+    # All object parameters contain an `isa` property, which represents the class
+    # within Xcode. Here the `isa` string value is translated into a Ruby module.
+    # 
+    # Initially the `isa` values were mapped directly to Ruby modules but that
+    # was changed to this model to make it easy to repair if Xcode were to 
+    # change their `isa` values and also provide the ability to mixin different
+    # functionality as needed.
+    # 
+    # @see Resource#initialize
     # 
     # @param [String] isa the type of the object.
-    #
+    # @return [Module] the module name mapped to the parameter. If the parameter
+    #   matches no module then a nil is returned.
+    # 
     def self.isa_to_module isa
 
       { 'XCBuildConfiguration' => Configuration,
@@ -53,6 +82,8 @@ module Xcode
     # This is the root object of the project. This is generally an identifier
     # pointing to a project.
     # 
+    # @return [Resource] this is traditionally the root, project object.
+    # 
     def root
       self['rootObject']
     end
@@ -108,8 +139,6 @@ module Xcode
       objects[identifier]
     end
     
-    MAX_IDENTIFIER_GENERATION_ATTEMPTS = 10
-    
     #
     # Provides a method to generically add objects to the registry. This will
     # create a unqiue identifier and add the specified parameters to the 
@@ -124,28 +153,7 @@ module Xcode
     #   that are known for the particular item.
     # 
     def add_object(object_properties)
-      
-      new_identifier = SimpleIdentifierGenerator.generate
-      
-      # Ensure that the identifier generated is unique
-      
-      identifier_generation_count = 0
-      
-      while objects.key?(new_identifier)
-        
-        new_identifier = SimpleIdentifierGenerator.generate
-        
-        # Increment our identifier generation count and if we reach our max raise
-        # an exception as something has gone horribly wrong.
-
-        identifier_generation_count += 1
-        if identifier_generation_count > MAX_IDENTIFIER_GENERATION_ATTEMPTS
-          raise "Unable to generate a unique identifier for object: #{object_properties}"
-        end
-      end
-      
-      new_identifier = SimpleIdentifierGenerator.generate if objects.key?(new_identifier)
-      
+      new_identifier = SimpleIdentifierGenerator.generate :existing_keys => objects.keys
       
       objects[new_identifier] = object_properties
       

data/lib/xcode/resource.rb

@@ -1,82 +1,111 @@
 require 'xcode/core_ext/string'
+require 'xcode/registry'
 
 module Xcode
   
   #
   # Resources are not represented as a true entity within an Xcode project.
-  # When traversing through groups, targets, configurations, etc. you will find
-  # yourself interacting with these objects. As they represent a class that
-  # acts as a shim around the hash data is parsed from the project.
+  # However when traversing through groups, targets, configurations, etc. you will 
+  # find yourself interacting with these objects. As they represent a class that
+  # acts as a shim around their hash data.
   # 
-  # A resource do some things that should be explained:
+  # The goal of the {Resource} is to aid in the navigation through the project
+  # and provide a flexible system to allow for Xcoder to adapt to changes to 
+  # the Xcode project format.
   # 
-  # When a resource is created it requires an identifier and an instance of
-  # of the Registry. It finds the properties hash of that given identifier 
-  # within the registry and creates a bunch of read-only methods that allow for 
-  # easy access to those elements. This is not unlike an OpenStruct.
-  # 
-  # @example of accessing the contents of a file reference
+  # A Resource requires an identifier and an instance of the {Registry}. Based
+  # on the supplied identifier, it peforms a look up of it's properties or hash
+  # of data. With that hash it then proceeds to create methods that allow for
+  # easy read/write access to those property elements. This is similar to Ruby's
+  # OpenStruct.
+  #
+  # @example Accessing the contents of a file reference
   # 
-  #     file_resource.properties # => 
+  #     file = project.file('IOSApp/IOSAppDelegate.m').properties # => 
   # 
   #     { 'isa' => 'PBXFileReference',
   #       'lastKnownFileType' => 'sourcecode.c.h',
   #       'path' => IOSAppDelegate.h', 
   #       'sourceTree' => "<group>" }
   # 
-  #     file_resource.isa # => 'PBXFileReference'
-  #     file_resource.sourceTree # => "<group>"
+  #     file.isa # => 'PBXFileReference'
+  #     file.last_known_file_type # => 'sourcecode.c.h'
+  #     file.path # => 'IOSAppDelegate.m'
+  #     file.path = "NewIOSAppDelegate.m" # => 'NewIOSAppDeleget.m'
+  #     file.source_tree # => "<group>"
   #
+  # In the above example, you can still gain access to the internal properties
+  # through the {#properties} method. However, the {Resource} provides for you
+  # additional ruby friendly methods to access the properties.
   # 
   # To provide additional convenience when traversing through the
-  # various objects, the read-only method will check to see if the value
+  # various objects, the getter methods will check to see if the value
   # being returned matches that of a unique identifier. If it does, instead of
-  # providing that identifier as a result and then having additional code to
-  # perform the look up, it does it automatically.
+  # providing that identifier, it will instead look in the {Registry} for the 
+  # object that matches and return a new Resource automatically.
+  # 
+  # @example Magically accessing resources through resources
   # 
-  # @example of how this would have to been done without this indirection
+  #     group = project.groups
+  #     group.properties # =>
   # 
-  #     project = Xcode.project('MyProject')
-  #     main_group = project.groups
-  #     child_identifier = group.children.first
-  #     subgroup = project.registry['objects'][child_identifier]
-  #     
-  # @example of hot this works currently because of this indirection
+  #     { "children"=>["7165D45A146B4EA100DE2F0E", 
+  #                    "7165D472146B4EA100DE2F0E", 
+  #                    "7165D453146B4EA100DE2F0E", 
+  #                    "7165D451146B4EA100DE2F0E"], 
+  #       "isa"=>"PBXGroup", 
+  #       "sourceTree"=>"<group>"}
   # 
-  #     group = Xcode.project('MyProject.xcodeproj').mainGroup
-  #     subgroup = group.group('Models')
+  #     group.children.first # => 
   # 
+  #     PBXGroup 7165D45A146B4EA100DE2F0E {"children"=>["7165D463146B4EA100DE2F0E", 
+  #                                                     "7165D464146B4EA100DE2F0E", 
+  #                                                     "7165D45B146B4EA100DE2F0E"], 
+  #                                        "isa"=>"PBXGroup", 
+  #                                        "path"=>"TestProject", 
+  #                                        "sourceTree"=>"<group>"} 
   # 
-  # Next, as most every one of these objects is a Hash that contain the properties
-  # instead of objects it would likely be better to encapsulate these resources
-  # within specific classes that provide additional functionality. So that when 
-  # a group resource or a file resource is returned you can perform unique 
-  # functionality with it automatically.
+  # In this example when accessing the first element of children instead of an
+  # identifier string being returned the child resource is returned. This
+  # functionality is in place to allow Xcoder to flexibly conform to new relationships 
+  # that may exist or come to exist.
   # 
-  # This is done by using the 'isa' property field which contains the type of
-  # content object. Instead of creating an object and encapsulating if a module
-  # that matches the name of the 'isa', that module of functionality is 
-  # automatically mixed-in to provide that functionality.
+  # Lastly, a {Resource} is simply not enough to describe most of the objects
+  # within an Xcode project as each object has unique functionality that needs 
+  # to be able to perform. So each resource when it is created will query the
+  # {Registry#isa_to_module} hash to determine the functionality that it needs
+  # to additionally extend into the Resource.
+  # 
+  # This `isa` property mapped to Ruby modules allows for the easy expansion of
+  # new objects or for changes to be made to existing ones as needed.
   # 
   class Resource
     
-    # The unique identifier for this resource
+    # @return [String] the unique identifier for this resource
     attr_accessor :identifier
     
-    # The properties hash that is known about the resource
+    # The raw properties hash that is known about the resource. This is the best
+    # way to manipulate the raw values of the resource.
+    # 
+    # @return [Hash] the raw properties hash for the object
     attr_accessor :properties
     
     # The registry of all objects within the project file which all resources
     # have a reference to so that they can retrieve any items they may own that
-    # are simply referenced by identifiers.
-    attr_accessor :registry
+    # are simply referenced by identifiers. This registry is used to convert
+    # identifier keys to resource objects. It is also passed to any resources
+    # that are created.
+    # 
+    # @return [Registry] the registry for the entire project.
+    attr_reader :registry
     
     #
     # Definiing a property allows the creation of an alias to the actual value.
     # This level of indirection allows for the replacement of values which are
     # identifiers with a resource representation of it.
     # 
-    # @note This is used internally by the resource when it is created.
+    # @note This is used internally by the resource when it is created to create
+    #   the getter/setter methods.
     # 
     # @param [String] name of the property
     # @param [String] value of the property
@@ -128,6 +157,8 @@ module Xcode
 
       end
       
+      # Generate a setter method for this property based on the given name.
+      
       self.class.send :define_method, "#{name.underscore}=" do |new_value|
         @properties[name] = new_value
       end
@@ -136,22 +167,25 @@ module Xcode
     end
 
     #
-    # Within the code, a single resource is created and that is with the root
-    # projet object. All other resources are created through the indirecation of
-    # the above property methods.
+    # A Resource is created during {Project#initialize}, when the project is
+    # first parsed. Afterwards each Resource is usually generated through the 
+    # special getter method defined through {#define_property}.
+    # 
+    # @see Project#initialize
+    # @see #defined_property
     # 
     # @param [String] identifier the unique identifier for this resource.
-    # @param [Types] details Description
+    # @param [Registry] registry the core registry for the system. 
     #
-    def initialize identifier, details
-      @registry = details
+    def initialize identifier, registry
+      @registry = registry
       @properties = {}
       @identifier = identifier
       
       # Create property methods for all of the key-value pairs found in the
       # registry for specified identifier.
       
-      Array(details.properties(@identifier)).each do |key,value| 
+      Array(registry.properties(@identifier)).each do |key,value| 
         send :define_property, key, value
       end
       
@@ -171,6 +205,13 @@ module Xcode
     # Saves the current resource back to the registry. This is necessary as
     # any changes made are not automatically saved back into the registry.
     # 
+    # @example group adding a files and then saving itself
+    # 
+    #     group = project.groups
+    #     group.create_file 'name' => 'AppDelegate.m', 'path' => 'AppDelegate.m'
+    #     group.save!
+    # 
+    # @return [Resource] the object that is being saved.
     def save!
       @registry.set_object(self)
       self
@@ -194,7 +235,6 @@ module Xcode
     def to_xcplist
       %{
         #{@identifier} = { #{ @properties.map {|k,v| "#{k} = \"#{v.to_xcplist}\"" }.join("; ") } }
-        
       }
     end