bubble-wrap 0.4.0 → 1.0.0.pre

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+## 1.0.0
+
+* Improved the integration with RubyMotion build system.
+* Improved test suite.
+* Added better documentation, including on how to work on the internals.
+* Added a KVO DSL to observe objects.
+* Renamed `Device.screen.widthForOrientation` to Device.screen.width_for_orientation` and `Device.screen.heightForOrientation` to `Device.screen.height_for_orientation`.
+* The `HTTP` wrapper now encodes arrays in params in a way that's compatible with Rails.
+
 ## 0.4.0
 
 * Refactored the code and test suite to be more modular and to handle

data/GEM.md

@@ -0,0 +1,104 @@
+# Creating a RubyMotion gem with BubbleWrap
+
+Let's say we want to develop a simple library gem that lists the
+people in a user's addressbook.
+
+Let's start by initializing an empty gem directory:
+
+```
+$ gem install bundler
+$ bundle gem bw-addressbook
+```
+
+Add BubbleWrap and Rake to your gem's dependencies in `bw-addressbook.gemspec`:
+
+```ruby
+Gem::Specification.new do |gem|
+  gem.add_dependency 'bubble-wrap'
+  gem.add_development_dependency 'rake'
+end
+```
+
+Then run `bundler`:
+```
+$ bundle
+Fetching gem metadata from https://rubygems.org/..
+Using rake (0.9.2.2) 
+Installing bubble-wrap (0.4.0) 
+Using bw-addressbook (0.0.1) from source at /Users/jnh/Dev/tmp/bw-addressbook 
+Using bundler (1.1.4) 
+Your bundle is complete! Use `bundle show [gemname]` to see where a bundled gem is installed.
+```
+
+Modify your `lib/bw-addressbook.rb` to include:
+
+```ruby
+require 'bw-addressbook/version'
+BW.require 'motion/address_book.rb'
+```
+
+Edit your project's `Rakefile` to include:
+
+```ruby
+#!/usr/bin/env rake
+$:.unshift("/Library/RubyMotion/lib")
+require 'motion/project'
+require "bundler/gem_tasks"
+Bundler.setup
+Bundler.require
+require 'bubble-wrap/test'
+```
+
+At this point we should have a working RubyMotion environment able to
+compile our code as we write it.
+
+Let's start by creating a spec for our address book gem in `spec/address_book_spec.rb`:
+
+```ruby
+describe AddressBook do
+  describe '.list' do
+    it 'returns an Enumerable' do
+      AddressBook.list.is_a?(Enumerable).should == true
+    end
+  end
+end
+```
+
+Now if you run `rake spec` you can watch the spec fail:
+
+```
+2012-06-07 11:19:35.506 Untitled[14987:f803] *** Terminating app due to uncaught exception 'NameError', reason: 'uninitialized constant AddressBook (NameError)'
+*** First throw call stack:
+(0x8f6022 0x286cd6 0x140054 0x291f 0x2645 0x1)
+terminate called throwing an exception
+```
+
+Let's go and define ourselves an `AddressBook` class in `motion/address_book.rb`:
+
+```ruby
+class AddressBook
+end
+```
+
+You'll now get a spec failure:
+
+```
+NoMethodError: undefined method `list' for AddressBook:Class
+	spec.rb:156:in `block in run_spec_block': .list - returns an Enumerable
+	 4:in `execute_block'
+	spec.rb:156:in `run_spec_block'
+	spec.rb:171:in `run'
+```
+
+Well, we'd better go and define it then, eh?
+
+```
+class AddressBook
+  def self.list
+    []
+  end
+end
+```
+
+I'm going to leave it here for now, but you're welcome to take a look at the 
+fully working demonstration project on [Github](http://github.com/jamesotron/bw-addressbook-demo).

data/HACKING.md

@@ -0,0 +1,101 @@
+# Hacking on BubbleWrap
+
+## A library in two parts
+
+RubyMotion forces a certain background-radiation of schitzophrenia
+due to the fact that it's build tools run using the system ruby
+via Rake.  BubbleWrap manipulates the build environment in order
+to make it possible to include itself (and other code) into the
+build process from outsite the project heirarchy.
+
+### Part the first: `lib/`
+
+This is where [RubyGems](http://rubygems.org) goes looking for
+code when you call
+
+```ruby
+require 'bubble-wrap'
+```
+
+When `bubble-wrap` is required it immediately requires `bubble-wrap/loader` which sets up the infrastructure needed to manipulate the `Rakefile` build process.  Once that is done we can freely call
+
+```ruby
+BubbleWrap.require 'motion/core**/*.rb'
+```
+
+`BubbleWrap.require` (or simply `BW.require`) is used to include
+library code into the Rake build process used by RubyMotion. 
+`BW.require` is similar to ruby's standard `require` method with
+two major changes:
+
+  - it can take a file pattern as used by [`Dir.glob`](http://ruby-doc.org/core-1.9.3/Dir.html#method-c-glob).
+  - it can be passed a block to manipulate dependencies.
+
+If a block is passed to `BW.require` it is evaluated in the context
+of `BW::Requirement` and thus has access to all it's class methods.
+The most common use cases are setting file dependencies:
+
+```ruby
+BW.require('motion/core**/*.rb') do
+  file('motion/core/device/screen.rb').depends_on 'motion/core/device.rb'
+end
+```
+
+and specifying frameworks that need to be included at build time:
+
+```ruby
+BW.require('motion/**/*.rb') do
+  file('motion/address_book.rb').uses_framework 'Addressbook'
+end
+```
+
+### Part the second: `motion/`
+
+Inside the `motion` directory you'll see the actual implementation code
+which is compiled into RubyMotion projects that are using BubbleWrap.
+
+  - `motion/core` contains "core" extension, things that the developers
+    reasonably think should be included in every BubbleWrap using project.
+    Careful consideration should be taken when making changes to the 
+    contents and test coverage (in `spec/core`) must be updated to match.
+    This can be included in your project by requiring `bubble-wrap` or 
+    `bubble-wrap/core` in your project `Rakefile`.
+  - `motion/http` contains the "http" extension.  This can be included
+    by requiring `bubble-wrap/http` in your project `Rakefile`.
+  - `motion/test_suite_delegate` contains a simple `AppDelegate` which
+    can be used to enable the `rake spec` to run when developing a
+    BubbleWrap gem.  Using `require 'bubble-wrap/test'` will include
+    it in the build process and also configure the app delegate to point
+    to `TestSuiteDelegate`. See the [BubbleWrap gem guide](gem.html) for
+    more information.
+
+#### Your project here
+
+If you think that your project would be of interest to the large number 
+of RubyMotion users that use BubbleWrap in their daily development then
+feel free to fork [the repository on GitHub](https://github.com/mattetti/BubbleWrap)
+and send us a pull request.
+
+You should place your implemenation files in a subdirectory of `motion`
+(eg `motion/my_awesome_project`), your tests in a subdirectory of `spec`
+(eg `spec/my_awesome_project`) and you can create a require file in
+`lib/bubble-wrap` for example `lib/bubble-wrap/my_awesome_project.rb`:
+
+```ruby
+require 'bubble-wrap/loader'
+BW.require 'motion/my_awesome_project.rb'
+```
+
+People will then be able to use it by adding:
+
+```ruby
+require 'bubble-wrap/my_awesome_project'
+```
+
+to their project's `Rakefile`
+
+## Go forth and conquer!
+
+The developers wish to thank you so much for taking the time
+to improve BubbleWrap and by extension the RubyMotion
+ecosystem. You're awesome!

data/README.md

@@ -3,6 +3,7 @@
 A collection of (tested) helpers and wrappers used to wrap CocoaTouch code and provide more Ruby like APIs.
 
 [BubbleWrap website](http://bubblewrap.io)
+[BubbleWrap mailing list](https://groups.google.com/forum/#!forum/bubblewrap)
 
 ## Installation
 
@@ -43,7 +44,7 @@ Make sure to append onto the array or use `+=`.
 ```ruby
 class AppDelegate
   def application(application, didFinishLaunchingWithOptions:launchOptions)
-    puts "#{App.name} (#{documents_path})"
+    puts "#{App.name} (#{App.documents_path})"
     true
   end
 end
@@ -112,9 +113,9 @@ Examples:
 # 320
 > Device.screen.height
 # 480
-> Device.screen.widthForOrientation(:landscape_left)
+> Device.screen.width_for_orientation(:landscape_left)
 # 480
-> Device.screen.heightForOrientation(:landscape_left)
+> Device.screen.height_for_orientation(:landscape_left)
 # 320
 ```
 
@@ -163,7 +164,7 @@ def viewWillAppear(animated)
     loadAndRefresh
   end
   
-  @reload_observer notification_center.observe ReloadNotification do |notification|
+  @reload_observer = notification_center.observe ReloadNotification do |notification|
     loadAndRefresh
   end
 end
@@ -196,6 +197,33 @@ simple interface:
 # ['TF1', 'France 2', 'France 3']
 ```
 
+### Observers
+**Since: > version 0.4**
+
+You can observe for object's changes and trigger blocks:
+
+``` ruby
+class ExampleViewController < UIViewController
+  include BW::KVO
+
+  def viewDidLoad
+    @label = "Initial state"
+
+    observe(@label, "text") do |old_value, new_value|
+      puts "Hello from viewDidLoad!"
+    end
+  end
+
+  def viewDidAppear(animated)
+    observe(@label, "text") do |old_value, new_value|
+      puts "Hello from viewDidAppear!"
+    end
+  end
+
+end
+```
+
+
 ### String
 
 The Ruby `String` class was extended to add `#camelize` and

data/Rakefile

@@ -1,19 +1,18 @@
 require "bundler/gem_tasks"
 $:.unshift("/Library/RubyMotion/lib")
 require 'motion/project'
-require File.expand_path '../lib/bubble-wrap', __FILE__
-require File.expand_path '../lib/bubble-wrap/http', __FILE__
+Bundler.setup
+Bundler.require
 
-task :rspec do
-  sh "rspec lib_spec/"
+require 'bubble-wrap/test'
+
+task :lib_spec do
+  sh "bacon #{Dir.glob("lib_spec/**/*_spec.rb").join(' ')}"
 end
 
+task :test => [ :lib_spec, :spec ]
+
 Motion::Project::App.setup do |app|
   app.name = 'testSuite'
   app.identifier = 'io.bubblewrap.testSuite'
-  
-  app.development do
-    app.files << './lib/tests/test_suite_delegate.rb'
-    app.delegate_class = 'TestSuiteDelegate'
-  end
 end

data/bubble-wrap.gemspec

@@ -16,6 +16,7 @@ Gem::Specification.new do |gem|
 
   gem.extra_rdoc_files = gem.files.grep(%r{motion})
 
-  gem.add_development_dependency 'rspec'
+  gem.add_development_dependency 'bacon'
+  gem.add_development_dependency 'mocha-on-bacon'
   gem.add_development_dependency 'rake'
 end

data/lib/bubble-wrap/core.rb

@@ -1,4 +1,4 @@
-require File.expand_path('../loader.rb', __FILE__)
+require 'bubble-wrap/loader'
 BubbleWrap.require('motion/core.rb')
 BubbleWrap.require('motion/core/**/*.rb') do 
   file('motion/core/device/screen.rb').depends_on 'motion/core/device.rb'

data/lib/bubble-wrap/ext.rb

@@ -1,2 +1,2 @@
-require File.expand_path('../ext/motion_project_config', __FILE__)
-require File.expand_path('../ext/motion_project_app', __FILE__)
+require 'bubble-wrap/ext/motion_project_config'
+require 'bubble-wrap/ext/motion_project_app'

data/lib/bubble-wrap/ext/motion_project_app.rb

@@ -6,10 +6,10 @@ module BubbleWrap
         base.instance_eval do
           def setup_with_bubblewrap(&block)
             bw_config = proc do |app|
-              app.files = ::BubbleWrap::Requirement.files + Dir.glob('./app/**/*.rb')
+              app.files = (::BubbleWrap::Requirement.files + (app.files||[])).uniq
               app.files_dependencies ::BubbleWrap::Requirement.files_dependencies
-              app.frameworks = ::BubbleWrap::Requirement.frameworks
-              block.call(app)
+              app.frameworks = (::BubbleWrap::Requirement.frameworks + (app.frameworks||[])).uniq
+              block.call(app) unless block.nil?
             end
             configs.each_value &bw_config
             config.validate

data/lib/bubble-wrap/ext/motion_project_config.rb

@@ -1,6 +1,7 @@
 module Motion
   module Project
     class Config
+
       # HACK NEEDED since RubyMotion doesn't support full path
       # dependencies.
       def files_dependencies(deps_hash)

data/lib/bubble-wrap/http.rb

@@ -1,2 +1,2 @@
-require File.expand_path('../loader.rb', __FILE__)
+require 'bubble-wrap/loader'
 BubbleWrap.require('motion/http.rb')

data/lib/bubble-wrap/loader.rb

@@ -2,9 +2,9 @@ unless defined?(Motion::Project::Config)
   raise "This file must be required within a RubyMotion project Rakefile."
 end
 
-require File.expand_path('../version', __FILE__) unless defined?(BubbleWrap::VERSION)
-require File.expand_path('../ext', __FILE__)
-require File.expand_path('../requirement', __FILE__)
+require 'bubble-wrap/version'
+require 'bubble-wrap/ext'
+require 'bubble-wrap/requirement'
 
 module BubbleWrap
 

data/lib/bubble-wrap/requirement.rb

@@ -1,4 +1,4 @@
-require File.expand_path "../requirement/path_manipulation", __FILE__
+require 'bubble-wrap/requirement/path_manipulation'
 
 module BubbleWrap
   class Requirement

data/lib/bubble-wrap/test.rb

@@ -0,0 +1,8 @@
+require 'bubble-wrap/loader'
+BW.require 'motion/test_suite_delegate.rb'
+
+Motion::Project::App.setup do |app|
+  app.development do
+    app.delegate_class = 'TestSuiteDelegate'
+  end
+end

data/lib/bubble-wrap/version.rb

@@ -1,3 +1,3 @@
 module BubbleWrap
-  VERSION = '0.4.0'
+  VERSION = '1.0.0.pre'
 end

data/lib_spec/bubble-wrap/ext/motion_project_app_spec.rb

@@ -0,0 +1,138 @@
+require 'mocha-on-bacon'
+require File.expand_path('../../../motion_stub', __FILE__)
+require 'bubble-wrap'
+
+describe BubbleWrap::Ext::BuildTask do
+
+  before do
+    @subject = Class.new do
+      def self.setup; end
+      def self.configs
+        @configs ||= { :development => Object.new }
+      end
+    end
+    @subject.extend BubbleWrap::Ext::BuildTask
+  end
+
+  describe '.extended' do
+    it 'responds to :setup_with_bubblewrap' do
+      @subject.respond_to?(:setup_with_bubblewrap).should == true
+    end
+
+    it 'responds to :setup_without_bubblewrap' do
+      @subject.respond_to?(:setup_without_bubblewrap).should == true
+    end
+
+    it 'replaces :setup with :setup_with_bubblewrap' do
+      @subject.method(:setup).should == @subject.method(:setup_with_bubblewrap)
+    end
+  end
+
+  describe '.setup_with_bubblewrap' do
+    before do
+      @config = @subject.configs[:development]
+      @config.stubs(:files=)
+      @config.stubs(:files)
+      @config.stubs(:files_dependencies)
+      @config.stubs(:frameworks)
+      @config.stubs(:frameworks=)
+      @subject.stubs(:config).returns(mock())
+      @subject.config.stubs(:validate)
+    end
+
+    it 'calls the passed-in block' do
+      block = proc { }
+      block.expects(:call).with(@config)
+      @subject.setup &block
+    end
+
+    describe 'when app.files is nil' do
+      it 'sets app.files' do
+        @config.stubs(:files).returns(nil)
+        files = BubbleWrap::Requirement.files
+        @config.expects(:files=).with(files)
+        @subject.setup
+      end
+    end
+
+    describe 'when app.files is empty' do
+      it 'sets app.files' do
+        @config.stubs(:files).returns([])
+        files = BubbleWrap::Requirement.files
+        @config.expects(:files=).with(files)
+        @subject.setup
+      end
+    end
+
+    describe 'when app.files has contents' do
+      it 'sets app.files' do
+        mock_files = ['a', 'b', 'c']
+        @config.stubs(:files).returns(mock_files)
+        files = BubbleWrap::Requirement.files + mock_files
+        @config.expects(:files=).with(files)
+        @subject.setup
+      end
+    end
+
+    it 'removes duplicates from app.files' do
+      files = ['a', 'a', 'b', 'b', 'c', 'c']
+      @config.stubs(:files).returns(files)
+      @config.expects(:files=).with(BubbleWrap::Requirement.files + files.uniq)
+      @subject.setup
+    end
+
+    it 'adds BW dependencies' do
+      @config.expects(:files_dependencies).with(BubbleWrap::Requirement.files_dependencies)
+      @subject.setup
+    end
+
+    describe 'when app.frameworks is empty' do
+      it 'sets the default frameworks' do
+        defaults = ['CoreGraphics', 'Foundation', 'UIKit']
+        @config.stubs(:frameworks).returns(nil)
+        @config.expects(:frameworks=).with(defaults)
+        @subject.setup
+      end
+    end
+
+    describe 'when app.frameworks is empty' do
+      it 'sets the default frameworks' do
+        defaults = ['CoreGraphics', 'Foundation', 'UIKit']
+        @config.stubs(:frameworks).returns([])
+        @config.expects(:frameworks=).with(defaults)
+        @subject.setup
+      end
+    end
+
+    describe 'when app.frameworks contains defaults' do
+      it 'sets the default frameworks' do
+        defaults = ['CoreGraphics', 'Foundation', 'UIKit']
+        @config.stubs(:frameworks).returns(defaults)
+        @config.expects(:frameworks=).with(defaults)
+        @subject.setup
+      end
+    end
+
+    describe 'when app.frameworks contains non-defaults' do
+      it 'sets the default frameworks and the contents' do
+        defaults = ['CoreGraphics', 'Foundation', 'UIKit']
+        @config.stubs(:frameworks).returns(['Addressbook'])
+        @config.expects(:frameworks=).with(defaults + ['Addressbook'])
+        @subject.setup
+      end
+    end
+
+    describe 'when BW::Requirement.frameworks has contents' do
+      it 'sets the default frameworks and the contents' do
+        defaults = ['CoreGraphics', 'Foundation', 'UIKit']
+        BW.require('motion/core.rb') do
+          file('motion/core.rb').uses_framework('Addressbook')
+        end
+        @config.stubs(:frameworks).returns(nil)
+        @config.expects(:frameworks=).with(['Addressbook'] + defaults)
+        @subject.setup
+      end
+    end
+  end
+
+end