Merge pull request #250 from willpragnell/acknowledgements

Acknowledgements plist and markdown generation

CHANGELOG.md

@@ -75,6 +75,54 @@ See [#149](https://github.com/CocoaPods/CocoaPods/issues/149) and
 [#151](https://github.com/CocoaPods/CocoaPods/issues/151) for more info.
 
 
+### Licenses & Documentation
+
+CocoaPods will now generate two 'Acknowledgements' files for each target specified
+in your Podfile which contain the License details for each Pod used in that target
+(assuming details have been specified in the Pod spec).
+
+There is a markdown file, for general consumption, as well as a property list file
+that can be added to a settings bundle for an iOS application.
+
+You don't need to do anything for this to happen, it should just work.
+
+If you're not happy with the default boilerplate text generated for the title, header
+and footnotes in the files, it's possible to customise these by overriding the methods
+that generate the text in your `Podfile` like this:
+
+```ruby
+class ::Pod::Generator::Acknowledgements
+  def header_text
+    "My custom header text"
+  end
+end
+```
+
+You can even go one step further and customise the text on a per target basis by 
+checking against the target name, like this:
+
+```ruby
+class ::Pod::Generator::Acknowledgements
+  def header_text
+    if @target_definition.label.end_with?("MyTargetName")
+      "Custom header text for MyTargetName"
+    else
+      "Custom header text for other targets"
+    end
+  end
+end
+```
+
+Finally, here's a list of the methods that are available to override:
+
+```ruby
+header_title
+header_text
+footnote_title
+footnote_text
+```
+
+
 ### Introduced two new classes: LocalPod and Sandbox.
 
 The Sandbox represents the entire contents of the `POD_ROOT` (normally

lib/cocoapods.rb

@@ -34,6 +34,9 @@ module Pod
     autoload :BridgeSupport,        'cocoapods/generator/bridge_support'
     autoload :CopyResourcesScript,  'cocoapods/generator/copy_resources_script'
     autoload :Documentation,        'cocoapods/generator/documentation'
+    autoload :Acknowledgements,     'cocoapods/generator/acknowledgements'
+    autoload :Plist,                'cocoapods/generator/acknowledgements/plist'
+    autoload :Markdown,             'cocoapods/generator/acknowledgements/markdown'
     autoload :DummySource,          'cocoapods/generator/dummy_source'
   end
 end

lib/cocoapods/generator/acknowledgements.rb

+module Pod
+  module Generator
+
+    class Acknowledgements
+
+      def self.generators
+        [Plist, Markdown]
+      end
+
+      def initialize(target_definition, pods)
+        @target_definition, @pods = target_definition, pods
+      end
+
+      def save_as(path)
+        Acknowledgements.generators.each do |generator|
+          generator.new(@target_definition, @pods).save_as(path)
+        end
+      end
+
+      def header_title
+        "Acknowledgements"
+      end
+
+      def header_text
+        "This application makes use of the following third party libraries:"
+      end
+
+      def footnote_title
+        ""
+      end
+
+      def footnote_text
+        "Generated by CocoaPods - http://cocoapods.org"
+      end
+    end
+  end
+end

lib/cocoapods/generator/acknowledgements/markdown.rb

+module Pod
+  module Generator
+
+    class Markdown < Acknowledgements
+
+      def save_as(path)
+        if (path.extname != ".markdown")
+          path = Pathname.new(path.dirname + "#{path.basename.to_s}.markdown")
+        end
+        file = File.new(path, "w")
+        file.write(licenses)
+        file.close
+      end
+
+      def title_from_string(string)
+        if !string.empty?
+          "#{string}\n" + '-' * string.length + "\n"
+        end
+      end
+ 
+      def string_for_pod(pod)
+        if (license_text = pod.license_text)
+          title_from_string(pod.name) + license_text + "\n"
+        end
+      end
+
+      def licenses
+        licenses_string = "#{title_from_string(header_title)}#{header_text}\n"
+        @pods.each do |pod|
+          if (license = string_for_pod(pod))
+            licenses_string += license
+          end
+        end
+        licenses_string += "#{title_from_string(footnote_title)}#{footnote_text}\n"
+      end
+    end
+  end
+end

lib/cocoapods/generator/acknowledgements/plist.rb

+module Pod
+  module Generator
+
+    class Plist < Acknowledgements
+      require "xcodeproj/xcodeproj_ext"
+
+      def save_as(path)
+        if (path.extname != ".plist")
+          path = Pathname.new(path.dirname + "#{path.basename.to_s}.plist")
+        end
+        Xcodeproj.write_plist(plist, path)
+      end
+
+      def plist
+        {
+          :Title => plist_title,
+          :StringsTable => plist_title,
+          :PreferenceSpecifiers => licenses
+        }
+      end
+ 
+      def plist_title
+        "Acknowledgements"
+      end
+
+      def licenses
+        licences_array = [header_hash]
+        @pods.each do |pod|
+          if (hash = hash_for_pod(pod))
+            licences_array << hash
+          end
+        end
+        licences_array << footnote_hash
+      end
+
+      def hash_for_pod(pod)
+        if (license = pod.license_text)
+          {
+            :Type => "PSGroupSpecifier",
+            :Title => pod.name,
+            :FooterText => license
+          }
+        end
+      end
+
+      def header_hash
+        {
+          :Type => "PSGroupSpecifier",
+          :Title => header_title,
+          :FooterText => header_text
+        }
+      end
+
+      def footnote_hash
+        {
+          :Type => "PSGroupSpecifier",
+          :Title => footnote_title,
+          :FooterText => footnote_text
+        }
+      end
+    end
+  end
+end

lib/cocoapods/installer.rb

@@ -87,6 +87,9 @@ module Pod
       target_installers.each do |target_installer|
         pods_for_target = pods_by_target[target_installer.target_definition]
         target_installer.install!(pods_for_target, @sandbox)
+        acknowledgements_path = target_installer.target_definition.acknowledgements_path
+        Generator::Acknowledgements.new(target_installer.target_definition,
+                                        pods_for_target).save_as(acknowledgements_path)
       end
 
       generate_lock_file!(specifications)

lib/cocoapods/local_pod.rb

@@ -118,6 +118,16 @@ module Pod
     def header_files
       source_files.select { |f| f.extname == '.h' }
     end
+    
+    def license_text
+      if (license_hash = specification.license)
+        if (result = license_hash[:text])
+          result
+        elsif (filename = license_hash[:file])
+          result = IO.read(root + filename)
+        end
+      end
+    end
 
     def xcconfig
       specifications.map { |s| s.xcconfig }.reduce(:merge)

lib/cocoapods/podfile.rb

@@ -92,6 +92,10 @@ module Pod
         end
       end
 
+      def acknowledgements_path
+        config.project_pods_root + "#{label}-Acknowledgements"
+      end
+
       # Returns a path, which is relative to the project_root, relative to the
       # `$(SRCROOT)` of the user's project.
       def relative_to_srcroot(path)

spec/unit/generator/acknowledgements/markdown_spec.rb

+require File.expand_path("../../../../spec_helper", __FILE__)
+
+describe Pod::Generator::Markdown do
+  before do
+    @sandbox = temporary_sandbox
+    @target_definition = mock
+    @pods = [mock]
+    @pods[0].expects(:license_text).returns("LICENSE_TEXT").at_least_once
+    @pods[0].expects(:name).returns("POD_NAME").at_least_once
+    @markdown = Pod::Generator::Markdown.new(@target_definition, @pods)
+  end
+
+  it "returns a correctly formatted title string" do
+    @pods[0].unstub(:license_text)
+    @pods[0].unstub(:name)
+    @markdown.title_from_string("A Title").should.equal "A Title\n-------\n"
+  end
+
+  it "returns a correctly formatted license string for each pod" do
+    @markdown.string_for_pod(@pods[0]).should.equal "POD_NAME\n--------\nLICENSE_TEXT\n"
+  end
+
+  it "returns a correctly formatted markdown string for the target" do
+    @markdown.stubs(:header_title).returns("HEADER_TITLE")
+    @markdown.stubs(:header_text).returns("HEADER_TEXT")
+    @markdown.stubs(:footnote_title).returns("") # Test that extra \n isn't added for empty strings
+    @markdown.stubs(:footnote_text).returns("FOOTNOTE_TEXT")
+    @markdown.licenses.should.equal "HEADER_TITLE\n------------\nHEADER_TEXT\nPOD_NAME\n--------\nLICENSE_TEXT\nFOOTNOTE_TEXT\n"
+  end
+
+  it "writes a markdown file to disk" do
+    given_path = @sandbox.root + "Pods-Acknowledgements"
+    expected_path = @sandbox.root + "Pods-Acknowledgements.markdown"
+    mockFile = mock
+    mockFile.expects(:write).with(equals(@markdown.licenses))
+    mockFile.expects(:close)
+    File.expects(:new).with(equals(expected_path), equals("w")).returns(mockFile)
+    @markdown.save_as(given_path)
+  end
+end

spec/unit/generator/acknowledgements/plist_spec.rb

+require File.expand_path("../../../../spec_helper", __FILE__)
+
+describe Pod::Generator::Plist do
+  before do
+    @sandbox = temporary_sandbox
+    @target_definition = mock
+    @pods = [mock]
+    @pods[0].expects(:license_text).returns("LICENSE_TEXT").at_least_once
+    @pods[0].expects(:name).returns("POD_NAME").at_least_once
+    @plist = Pod::Generator::Plist.new(@target_definition, @pods)
+  end
+
+  it "returns the correct number of licenses (including header and footnote)" do
+    @plist.licenses.count.should == 3
+  end
+
+  it "returns a string for the plist title" do
+    @pods[0].unstub(:license_text)
+    @pods[0].unstub(:name)
+    @plist.plist_title.should.be.kind_of(String)
+  end
+
+  it "returns a correctly formed license hash for each pod" do
+    @plist.hash_for_pod(@pods[0]).should == {
+      :Type => "PSGroupSpecifier",
+      :Title => "POD_NAME",
+      :FooterText => "LICENSE_TEXT"
+    }
+  end
+
+  it "returns nil for a pod with no license text" do
+    @pods[0].unstub(:license_text)
+    @pods[0].unstub(:name)
+    @pods[0].expects(:license_text).returns(nil)
+    @plist.hash_for_pod(@pods[0]).should.be.nil
+  end
+
+  it "returns a plist containg the licenses" do
+    @plist.plist.should == {
+      :Title => "Acknowledgements",
+      :StringsTable => "Acknowledgements",
+      :PreferenceSpecifiers => @plist.licenses
+    }
+  end
+
+  it "writes a plist to disk at the given path" do
+    given_path = @sandbox.root + "Pods-Acknowledgements"
+    expected_path = @sandbox.root + "Pods-Acknowledgements.plist"
+    Xcodeproj.expects(:write_plist).with(equals(@plist.plist), equals(expected_path))
+    @plist.save_as(given_path)
+  end
+end

spec/unit/generator/acknowledgements_spec.rb

+require File.expand_path("../../../spec_helper", __FILE__)
+
+describe Pod::Generator::Acknowledgements do
+  before do
+    @sandbox = temporary_sandbox
+    @target_definition = mock
+    @pods = [mock]
+    @acknowledgements = Pod::Generator::Acknowledgements.new(@target_definition, @pods)
+  end
+
+  it "calls save_as on both a Plist and a Markdown generator" do
+    path = @sandbox.root + "Pods-Acknowledgements.plist"
+    Pod::Generator::Plist.any_instance.expects(:save_as).with(equals(path))
+    Pod::Generator::Markdown.any_instance.expects(:save_as).with(equals(path))
+    @acknowledgements.save_as(path)
+  end
+
+  it "returns a string for each header and footnote text method" do
+    @acknowledgements.header_title.should.be.kind_of(String)
+    @acknowledgements.header_text.should.be.kind_of(String)
+    @acknowledgements.footnote_title.should.be.kind_of(String)
+    @acknowledgements.footnote_text.should.be.kind_of(String)
+  end
+end

spec/unit/specification_spec.rb

@@ -136,13 +136,11 @@ describe "A Pod::Specification, in general," do
     @spec.license = {
       :type => 'MIT',
       :file => 'LICENSE',
-      :range => 1..15,
       :text => 'Permission is hereby granted ...'
     }
     @spec.license.should == {
       :type => 'MIT',
       :file => 'LICENSE',
-      :range => 1..15,
       :text => 'Permission is hereby granted ...'
     }
   end