zerg_xcode 0.1

data/CHANGELOG

@@ -0,0 +1 @@
+v0.1. Initial release. Knows help, irb, ls, retarget.

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2008 Victor Costan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/Manifest

@@ -0,0 +1,44 @@
+bin/zerg-xcode
+CHANGELOG
+lib/zerg_xcode/file_format/archiver.rb
+lib/zerg_xcode/file_format/encoder.rb
+lib/zerg_xcode/file_format/lexer.rb
+lib/zerg_xcode/file_format/parser.rb
+lib/zerg_xcode/file_format/paths.rb
+lib/zerg_xcode/objects/pbx_build_file.rb
+lib/zerg_xcode/objects/pbx_native_target.rb
+lib/zerg_xcode/objects/pbx_project.rb
+lib/zerg_xcode/objects/xcode_object.rb
+lib/zerg_xcode/plugins/core/core.rb
+lib/zerg_xcode/plugins/help.rb
+lib/zerg_xcode/plugins/import.rb
+lib/zerg_xcode/plugins/irb.rb
+lib/zerg_xcode/plugins/ls.rb
+lib/zerg_xcode/plugins/retarget.rb
+lib/zerg_xcode/shortcuts.rb
+lib/zerg_xcode.rb
+LICENSE
+Manifest
+Rakefile
+README.textile
+RUBYFORGE
+test/file_format/archiver_test.rb
+test/file_format/encoder_test.rb
+test/file_format/lexer_test.rb
+test/file_format/parser_test.rb
+test/file_format/path_test.rb
+test/objects/pbx_build_file_test.rb
+test/objects/pbx_native_target_test.rb
+test/objects/pbx_project_test.rb
+test/objects/xcode_object_test.rb
+test/plugins/core/core_test.rb
+test/plugins/import_test.rb
+test/plugins/irb_test.rb
+test/plugins/ls_test.rb
+test/plugins/retarget_test.rb
+test/plugins/test_helper.rb
+test/shortcuts_test.rb
+testdata/project.pbxproj
+testdata/project.pbxproj.compat
+testdata/TestApp/TestApp.xcodeproj/project.pbxproj
+testdata/ZergSupport.xcodeproj/project.pbxproj

data/README.textile

@@ -0,0 +1,124 @@
+h1. ZergXcode
+
+ZergXcode is a tool and library for performing automated modifications to Xcode
+project files. It can be used to work around Xcode's limitations, such as
+* the cumbersome UI for assigning files to the main target vs the test target
+* the impossibility to easily drop other people's code in your project
+* a problem that annoys you enough to learn the API and write a ruby script   
+
+h2. User Instructions
+
+If you're on OSX Leopard, you already have most of the infrastructure in place.
+Install the gem by typing the following in Terminal.
+
+<pre>sudo gem install zerg_xcode</pre>
+
+Stay in Terminal and take a look at the available commands.
+<pre>zerg-xcode help</pre>
+
+Then start playing with your code project.
+<pre>
+zerg-xcode help
+zerg-xcode help ls
+zerg-xcode ls ProjectName
+</pre>
+
+h2. Developer Notes
+
+The rest of the file is useful if you're considering tweaking the code. Here are
+a few reasons to use this library:
+* ruby and rubygems come pre-installed on every Mac
+* full test coverage, so it's high quality and easy to refactor
+* MIT license, so your boss will not hate you
+* all commands are plug-ins, so all the infrastructure is in place
+
+h3. Getting started.
+
+It's recommended to start by playing with the API in
+<code>lib/zerg_xcode/shortcuts.rb</code>
+
+<pre>
+moonstone:ZergSupport victor$ zerg-xcode irb ZergSupport
+>> $p
+*snip*
+>> $p.attrs   # shows the names of all the attributes of the Xcode object
+=> ["isa", "buildConfigurationList", "hasScannedForEncodings", "targets", "projectDirPath", "compatibilityVersion", "projectRoot", "mainGroup"]
+>> $p['targets'].first.attrs   # navigates a list 
+=> ["name", "isa", "productType", "buildConfigurationList", "productReference", "productName", "buildRules", "dependencies", "buildPhases"]
+>> $p['targets'].first['name']   # inspects attributes
+=> "ZergSupport"
+>> $p['targets'].map { |target| target['name'] }  # more attribute inspection
+=> ["ZergSupport", "ZergTestSupport", "ZergSupportTests"]
+>> $p.all_files.length  # call method in PBXProject 
+=> 116
+</pre>
+
+You can up load your favorite Xcode project in irb, and understand the object
+graph. Once you feel you have a decent grasp, you can start experimenting with
+changing the graph, as shown below.
+
+<pre>
+moonstone:ZergSupport victor$ zerg-xcode irb ZergSupport
+>> $p['targets'][2]['name'] 
+=> "ZergSupportTests"
+>> $p['targets'][2]['name'] = 'ZergSupportTestz'
+=> "ZergSupportTestz"
+>> $p.save!  # the project remembers where it was loaded from
+=> 54809
+>> quit  # now load the project in Xcode and see the change
+</pre>
+
+h3. Plug-ins Extend the Command Set
+
+The set of commands accepted by the <code>zerg-xcode</code> tool can be extended
+by adding a plug-in, which is nothing but a ruby file that exists in
+<code>lib/zerg_xcode/plugins</code>. An easy example to get you started can be
+found at <code>lib/zerg_xcode/plugins/ls.rb</code>. The code in there should
+help you if you want to write your own command-line tool as well.
+
+Plug-ins must implement the methods <code>run(args)</code> (called when the
+command is executed) and <code>help</code> (called when the user needs help on
+your plug-in), which must return a Hash with the keys <code>:short</code> and
+<code>:long</code>.
+
+If you write a plug-in that seems even remotely useful, please don't be shy and
+send a Pull Request on Github.
+
+h3. Encoding and Decoding Files
+
+The code is in <code>lib/zerg_xcode/file_format</code>. You can safely ignore it
+unless you're handling a new file format, or you want to make the decoding
+better.
+
+A .pbxproj file is decoded by the chain Lexer -> Parser -> Archiver.unarchive
+into an object graph. An object graph is encoded back into a .pbxproj by the
+chain Archiver.archive -> Encoder.
+
+The decoding process discards comments and the order of objects in the graph, so
+an encoded .pbxproj will not be the same as the original. However, Xcode will
+happily open an encoded file, and that's all that matters.
+
+h3. Xcode Object Graph
+
+Objects in the Xcode object graph are represented by XcodeObject instances. The
+code for XcodeObject is in <code>lib/zerg_xcode/objects/xcode_object.rb</code>.
+Xcode objects use the 'isa' attribute to indicate their class. 
+<code>XcodeObject.new</code> implements isa-based polymorphism as follows: if
+<code>ZergXcode::Objects</code> has a class with the same name as the 'isa'
+property, that class is instantiated instead of <code>XcodeObject.new</code>.
+
+So, you can add magic methods to Xcode objects by implementing them in 
+XcodeObject subclasses contained in the <code>ZergXcode::Objects</code> module.
+By convention, these classes are implemented in
+<code>lib/zerg_xcode/objects</code>. 
+ 
+XcodeObject stores the attributes of the original object, and also keeps track
+of subtle meta-data from the original objects, such as the object version and
+archive identifier. This is done so modified Xcode files resemble the originals
+as much as possible.
+
+h3. Testing
+
+The <code>test</code> directory contains a parallel tree to
+<code>lib/zerg_xcode</code>. Coverage must remain excellent, because this is a
+tool that deals with people's work.

data/RUBYFORGE

@@ -0,0 +1,40 @@
+Quickstart for Rubyforge:
+
+1) Checkout the zergxcode code
+git clone git@github.com:costan/zerg_xcode.git
+
+2) Install the rubyforge gem
+gem install rubyforge
+
+3) Save your rubyforge.org login information
+rubyforge setup
+
+4) Get a login cookie
+rubyforge login
+
+5) Get project configuration from rubyforge
+rubyforge config zerglings
+
+6) Create a package to release under
+rubyforge create_package zerglings zerg_xcode
+
+7) Install the echoe gem (required for building this gem)
+gem install echoe
+
+8) Release the gem (finally!)
+rake release
+
+Releasing a new gemspec to Github
+
+1) Build the gem
+rake package
+
+2) Copy the spec
+cp pkg/zerg_xcode-0.1/zerg_xcode.gemspec .
+
+3) Commit the spec
+git add zerg_xcode.gemspec
+git commit -m "New gemspec, for Github distribution."
+
+4) Push to Github
+git push

data/Rakefile

@@ -0,0 +1,27 @@
+require 'rubygems'
+require 'echoe'
+
+Echoe.new('zerg_xcode') do |p|
+  p.project = 'zerglings' # rubyforge project
+  
+  p.author = 'Victor Costan'
+  p.email = 'victor@zergling.net'
+  p.summary = 'Automated modifications for Xcode project files'
+  p.url = 'http://www.zergling.net/'
+  p.runtime_dependencies = []
+  p.dependencies = []
+  # remove echoe, because it becomes a runtime dependency for rubygems < 1.2
+  p.development_dependencies = []
+  p.eval = proc do |p|
+    p.default_executable = 'bin/zerg-xcode'
+  end
+  
+  p.need_tar_gz = true
+  p.need_zip = true
+  p.rdoc_pattern = /^(lib|bin|tasks|ext)|^BUILD|^README|^CHANGELOG|^LICENSE$/  
+end
+
+if $0 == __FILE__
+  Rake.application = Rake::Application.new
+  Rake.application.run
+end

data/bin/zerg-xcode

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+require 'rubygems'
+require 'zerg_xcode'
+
+plugin = ARGV.shift
+plugin = 'help' unless ZergXcode::Plugins.all.include? plugin
+ZergXcode::Plugins.run(plugin, ARGV)

data/lib/zerg_xcode/file_format/archiver.rb

@@ -0,0 +1,87 @@
+module ZergXcode::Archiver
+  # Unarchives an Xcode object graph from the contents of a file.
+  def self.unarchive(string)
+    proj_hash = ZergXcode::Parser.parse string
+    unarchive_hash proj_hash
+  end
+  
+  # Archives an Xcode object graph to a string to be written to a .pbxproj file.
+  def self.archive(project)
+    proj_hash = archive_to_hash project
+    ZergXcode::Encoder.encode proj_hash
+  end    
+  
+  # Unarchives an Xcode object graph serialized to a hash.
+  def self.unarchive_hash(hash)
+    raise 'Uknown archive version' unless hash['archiveVersion'] == '1'
+    raise 'Classes not implemented' unless hash['classes'] = {}
+    version = hash['objectVersion'].to_i
+    
+    objects = {}
+    hash['objects'].each do |archive_id, object_hash|
+      object = ZergXcode::XcodeObject.from object_hash
+      object.version, object.archive_id = version, archive_id
+      objects[archive_id] = object
+    end
+    objects.each do |object_id, object|
+      object.visit do |object, parent, key, value|
+        parent[key] = objects[value] if objects.has_key? value
+        next true
+      end
+    end
+    return objects[hash['rootObject']]
+  end
+  
+  def self.archive_to_hash(root_object)
+    archived = ZergXcode::XcodeObject.from root_object
+    id_generator = IdGenerator.new
+    visited = Set.new([archived])
+    
+    archived.visit do |object, parent, key, value|
+      next true unless value.kind_of? ZergXcode::XcodeObject
+      
+      if visited.include? value
+        parent[key] = value.archive_id
+        next false
+      else
+        visited << value
+        value.archive_id = id_generator.id_for(value)
+        parent[key] = value.archive_id
+        next true
+      end      
+    end
+    root_object_id = archived.archive_id
+  
+    objects = {}
+    visited.each { |object| objects[object.archive_id] = object._attr_hash }
+    return { 'archiveVersion' => '1',
+             'objectVersion' => root_object.version.to_s,
+             'classes' => Hash.new, 'rootObject' => root_object_id,
+             'objects' => objects }
+  end
+  
+  # Generates archive IDs for objects.
+  class IdGenerator
+    def initialize
+      @assigned_ids = Set.new
+    end
+    
+    def new_id
+      loop do
+        id = (0...24).map { '%02X' % rand(256) }.join
+        next if @assigned_ids.include? id
+        @assigned_ids << id
+        return id
+      end
+    end
+  
+    def id_for(object)
+      if object.archive_id && !@assigned_ids.include?(object.archive_id)
+        @assigned_ids << object.archive_id 
+        return object.archive_id 
+      else
+        return new_id
+      end
+    end
+  end
+end

data/lib/zerg_xcode/file_format/encoder.rb

@@ -0,0 +1,40 @@
+module ZergXcode::Encoder  
+  def self.encode(project)
+    "// !$*UTF8*$!\n" + encode_hash(project, 0) + "\n"
+  end
+
+  def self.encode_hash(hash, indentation)
+    "{\n" + hash.map { |key, value|
+      encode_indentation(indentation + 1) + 
+      encode_value(key, indentation + 1) + " = " +
+      encode_object(value, indentation + 1) + ";\n"
+    }.join + encode_indentation(indentation) + "}"
+  end
+  
+  def self.encode_object(object, indentation)
+    case object
+    when Hash
+      encode_hash object, indentation
+    when Array
+      encode_array object, indentation
+    when String
+      encode_value object, indentation
+    end
+  end
+
+  def self.encode_array(array, indentation)
+    "(\n" + array.map { |value|
+      encode_indentation(indentation + 1) +
+      encode_object(value, indentation + 1) + ",\n"
+    }.join + encode_indentation(indentation) + ")"
+  end
+  
+  def self.encode_value(value, indentation)
+    # This escapes what needs to be escaped.
+    value.to_s.inspect
+  end
+  
+  def self.encode_indentation(indentation)
+    "\t" * indentation
+  end
+end

data/lib/zerg_xcode/file_format/lexer.rb

@@ -0,0 +1,60 @@
+module ZergXcode::Lexer
+  def self.tokenize(string)
+    
+    encoding_match = string.match /^\/\/ \!\$\*(.*?)\*\$\!/
+    raise "No encoding - #{string[0, 20]}" unless encoding_match
+    
+    i = encoding_match[0].length
+    tokens = [[:encoding, encoding_match[1]]]
+    while i < string.length
+      # skip comments
+      if string[i, 2] == '/*'
+        i += 2
+        i += 1 while string[i, 2] != '*/'
+        i += 2
+        next
+      end
+      
+      case string[i, 1]
+      when /\s/
+        i += 1
+      when '(', ')', '{', '}', '=', ';', ','
+        tokens << {'(' => :begin_array, ')' => :end_array,
+                   '{' => :begin_hash, '}' => :end_hash,
+                   '=' => :assign, ';' => :stop, ',' => :comma}[string[i, 1]]
+        i += 1
+      when '"'
+        # string
+        i += 1
+        token = ''
+        while string[i, 1] != '"'
+          if string[i, 1] == '\\'
+            i += 1
+            case string[i, 1]            
+            when 'n', 'r', 't'
+              token << { 'n' => "\n", 't' => "\t", 'r' => "\r" }[string[i, 1]]
+              i += 1 
+            when '"', "'", '\\'
+              token << string[i]
+              i += 1
+            else
+              raise "Uknown escape sequence \\#{string[i, 20]}"
+            end
+          else
+            token << string[i]
+            i += 1
+          end
+        end
+        tokens << [:string, token]
+        i += 1
+      else
+        # something
+        len = 0
+        len += 1 while /[^\s\t\r\n\f(){}=;,]/ =~ string[i + len, 1]
+        tokens << [:symbol, string[i, len]]
+        i += len
+      end
+    end
+    return tokens
+  end
+end

data/lib/zerg_xcode/file_format/parser.rb

@@ -0,0 +1,46 @@
+module ZergXcode::Parser
+  def self.parse(project_string)
+    tokens = ZergXcode::Lexer.tokenize project_string
+    
+    context = [[]]
+    last_token = nil
+    tokens.each do |token|
+      case token
+      when :begin_array
+        context << Array.new
+      when :begin_hash
+        context << Hash.new
+      when :end_array, :end_hash
+        last_object = context.pop
+        if context.last.kind_of? Array
+          context.last << last_object
+        elsif context.last.kind_of? String
+          hash_key = context.pop
+          context.last[hash_key] = last_object
+        end
+      when :assign, :stop, :comma
+        
+      when Array
+        case token.first
+        when :encoding
+        when :string, :symbol
+          token_string = token.last
+          if context.last.kind_of? Hash
+            context << token_string
+          elsif context.last.kind_of? Array
+            context.last << token_string
+          elsif context.last.kind_of? String
+            key = context.pop
+            context.last[key] = token_string
+          else
+            p context
+            raise 'WTFed'
+          end
+        end        
+      else
+        raise "Unknown token #{token}"
+      end
+    end
+    return context[0][0]
+  end  
+end

data/lib/zerg_xcode/file_format/paths.rb

@@ -0,0 +1,44 @@
+module ZergXcode::Paths
+  # The most likely project file name for the given path. 
+  def self.project_file_at(base_path)
+    return base_path if File.exist?(base_path) and File.file?(base_path)
+    pbxfile = 'project.pbxproj'
+    
+    # naively assume the user gave the right name
+    path = base_path
+    path = path[0...-1] if path[-1, 1] == '/' || path[-1, 1] == '\\'
+    path = path + '.xcodeproj' unless /\.xcodeproj$/ =~ path
+    if File.exist? path
+      file = File.join(path, pbxfile)
+      return file
+    end
+    
+    # didn't work, perhaps user gave us a path into their root
+    entries = Dir.entries(base_path).sort_by do |entry|
+      File.file?(File.join(base_path, entry)) ? 0 : 1
+    end
+    
+    entries.each do |entry|
+      next if entry == '..'
+      path = File.join(base_path, entry)      
+      case entry
+      when /\.pbxproj$/
+        return path
+      when /\.xcodeproj$/
+        return File.join(path, pbxfile)
+      else
+        if File.directory?(path) && File.exist?(File.join(path, pbxfile))
+          return File.join(path, pbxfile)
+        end
+      end
+    end
+    
+    raise "Could not find Xcode project at #{base_path}"
+  end
+  
+  # The most likely project root dir for the given path.
+  def self.project_root_at(base_path)
+    file = project_file_at base_path
+    File.dirname File.dirname(file)
+  end
+end

data/lib/zerg_xcode/objects/pbx_build_file.rb

@@ -0,0 +1,27 @@
+# A file used for building. Points to a PBXFileRef.
+class ZergXcode::Objects::PBXBuildFile < ZergXcode::XcodeObject
+  # The name of the referenced file.
+  def filename
+    self['fileRef']['path']
+  end
+  
+  # The type of the referenced file.
+  def file_type
+    self['fileRef']['explicitFileType'] || self['fileRef']['lastKnownFileType']
+  end
+  
+  # Guesses the type of the build phase that this file should belong to.
+  # This can be useful when figuring out which build phase to add a file to.
+  def guessed_build_phase_type
+    case file_type
+    when /\.h$/
+      return 'PBXHeadersBuildPhase'
+    when /^sourcecode/
+      return 'PBXSourcesBuildPhase'
+    when /\.framework$/, /\.ar$/
+      return 'PBXFrameworksBuildPhase'
+    else
+      return 'PBXResourcesBuildPhase'
+    end
+  end
+end

data/lib/zerg_xcode/objects/pbx_native_target.rb

@@ -0,0 +1,19 @@
+# An Xcode target.
+class ZergXcode::Objects::PBXNativeTarget < ZergXcode::XcodeObject
+  # All the files referenced by this target.
+  # Returns:
+  #   an array containing a hash for each file with
+  #     :phase - the build phase referencing the file
+  #     :build_object - the build object referencing the file
+  #     :object - the file object
+  def all_files
+    files = []
+    self['buildPhases'].each do |phase|
+      phase['files'].each do |build_file|
+        files << { :phase => phase, :build_object => build_file,
+                   :object => build_file['fileRef'] }
+      end
+    end
+    files
+  end
+end

data/lib/zerg_xcode/objects/pbx_project.rb

@@ -0,0 +1,60 @@
+# The root object in the Xcode object graph.
+class ZergXcode::Objects::PBXProject < ZergXcode::XcodeObject
+  # Used to implement save!
+  attr_accessor :source_filename
+  
+  # Saves a project that was loaded by ZergXcode.load
+  def save!
+    raise 'Project not loaded by ZergXcode.load' unless @source_filename
+    ZergXcode.dump self, @source_filename
+  end
+  
+  # All the files referenced by the project.
+  def all_files
+    files = []
+    project_root = self['projectRoot'].empty? ? '.' : self['projectRoot']
+    FileVisitor.visit self['mainGroup'], project_root, files
+    files
+  end
+
+  # Container for the visitor that lists all files in a project.
+  module FileVisitor
+    def self.visit(object, root_path, files)
+      case object.isa
+      when :PBXGroup
+        visit_group(object, root_path, files)
+      when :PBXFileReference
+        visit_file(object, root_path, files)
+      end
+    end
+    
+    def self.visit_group(group, root_path, files)
+      path = merge_path(root_path, group['sourceTree'], group)
+      
+      group['children'].each do |child|
+        visit child, path, files
+      end
+    end
+    
+    def self.visit_file(file, root_path, files)
+      path = merge_path(root_path, file['sourceTree'], file)
+      
+      files << { :path => path, :object => file } 
+    end
+    
+    def self.merge_path(old_path, source_tree, object)
+      case source_tree
+      when '<group>'
+        base_path = old_path
+      else
+        base_path = source_tree
+      end
+      if object['path']
+        path = File.join(base_path, object['path'])
+      else
+        path = old_path
+      end
+      return path
+    end
+  end
+end