sugarcube 0.20.25 → 1.0.0

data/Gemfile

@@ -1,5 +1,7 @@
 source 'https://rubygems.org'
 
-gem 'rake'
+group :test, :development do
+  gem 'rake'
+end
 
 gemspec

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    sugarcube (0.20.25)
+    sugarcube (1.0.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -1,7 +1,7 @@
 SugarCube
 =========
 
-Some sugar for your cocoa, or your [tea][sweettea].
+Some sugar for your [cocoa](http://rubymotion.com), or your [tea][sweettea].
 
 [![Build Status](https://travis-ci.org/rubymotion/sugarcube.png)](https://travis-ci.org/rubymotion/sugarcube)
 
@@ -9,15 +9,14 @@ About
 -----
 
 CocoaTouch/iOS is a *verbose* framework.  These extensions hope to make
-development in rubymotion more enjoyable by tacking "UI" methods onto the base
-classes (String, Fixnum, Numeric).  With SugarCube, you can create a color from an
-integer or symbol, or create a UIFont or UIImage from a string.
+development in rubymotion more enjoyable. With SugarCube, you can create a color
+from an integer or symbol, or create a UIFont or UIImage from a string.
 
-Some UI classes are opened up as well, like adding the '<<' operator to a UIView
-instance, instead of view.addSubview(subview), you can use the more idiomatic:
-view << subview.
+Some core classes are opened up as well, like adding the '<<' operator to a
+UIView instance, instead of view.addSubview(subview), you can use the more
+idiomatic: view << subview.
 
-The basic idea of SugarCube is to turn some operations on their head.  Insead of
+The basic idea of SugarCube is to turn operations on their head.  So instead of:
 
     UIApplication.sharedApplication.openURL(NSURL.URLWithString(url))
 
@@ -49,6 +48,7 @@ diligent about adding Yard documentation, which is available here:
 
 <http://rubydoc.info/gems/sugarcube/latest>
 
+[documentation]: http://rubydoc.info/gems/sugarcube/latest
 
 Installation
 ============
@@ -59,554 +59,353 @@ Installation
     require 'sugarcube'
 
     # or in Gemfile
-    gem 'sugarcube'
+    gem 'sugarcube', :require => 'sugarcube-classic'
+    # or for the bold:
+    # gem 'sugarcube', :require => 'sugarcube-all'
 
     # in terminal
     $ bundle install
 
-Examples
+Packages
 ========
 
-Array
--------
+SugarCube has grown over time to be a pretty massive collection of helpers.
+While some people choose to use the entire library, other people like to pick
+and choose the extensions they want to use.  With that in mind, SugarCube is
+written so that it does *not* pollute any classes by default.  So if all you do
+is `require "sugarcube"`, you are NOT going to get much mileage!
+
+In the installation code above, I show the example of using `:require => 'sugarcube-all'`
+to include *all* of SugarCube's extensions.  Usually you will require the
+packages you need from your Rakefile:
 
 ```ruby
-[1, 3].nsindexpath  # NSIndexPath.indexPathWithIndex(1).indexPathByAddingIndex(3)
-[160, 210, 242].uicolor  # => UIColor.colorWithRed(0.6274, green:0.8235, blue:0.9490, alpha:1.0)
-[160, 210, 242].uicolor(0.5)  # => UIColor.colorWithRed(0.6274, green:0.8235, blue:0.9490, alpha:0.5)
+$:.unshift('/Library/RubyMotion/lib')
+require 'motion/project/template/ios'
+require 'bundler'
+Bundler.require
+require './lib/sugarcube-uikit'
+require './lib/sugarcube-events'
+require './lib/sugarcube-gestures'
+require './lib/sugarcube-568'
+require './lib/sugarcube-attributedstring'
+# ...
 ```
 
-Hash => Object
---------
+You can require the packages in piecemeal like this, or you can require a group
+of packages: `classic, common, or all`.
 
-```ruby
-require 'sugarcube-attributedstring'
-```
+* `sugarcube-classic`: Excludes **568**, **attributedstring**, **gestures**, **repl**, **awesome**, **anonymous**, **unholy**, and **legacy**
+* `sugarcube-common`: Excludes **awesome**, **anonymous**, **unholy**, and **legacy**
+* `sugarcube-all`: Excludes **legacy**
 
-Convert `Hash`es into an "anonymous object".  Existing keys will be able to be
-accessed using method names.  Uses the `SugarCube::Anonymous` class to
-accomplish this, though the usual interface is via `Hash#to_object`.
+So without further ado,
 
-```ruby
-h = { foo: 'FOO', 'bar' => 'BAR' }.to_object
+SugarCube
+=========
 
-# You can use methods instead of keys.
-h.foo         # => h[:foo]
-h.bar         # => h['bar']
-h.foo = 'Foo' # => h[:foo] = 'Foo'
-h.bar = 'Bar' # => h['bar'] = 'Bar'
+Packages are sorted more-or-less by their usefulness.  The more esoteric ones
+are at the end.
 
-# only existing keys are accessed this way
-h.baz          # => NoMethodError
-h.baz = 'baz'  # => NoMethodError
-```
+REPL ([wiki][REPL Wiki])
+----
 
-Fixnum
---------
+If you install SugarCube and *only* use the REPL package, you will benefit from
+some of its greatest tools!
 
-```ruby
-# create a UIColor from a hex value
-0xffffff.uicolor # => UIColor.colorWithRed(1.0, green:1.0, blue:1.0, alpha:1.0)
-0xffffff.uicolor(0.5) # => UIColor.colorWithRed(1.0, green:1.0, blue:1.0, alpha:0.5)
+> `require 'sugarcube-repl'`
 
-# some number-to-string stuff
-1.nth  # => 'st'
-2.nth  # => 'nd'
-3.nth  # => 'rd'
-4.nth  # => 'th'
-11.nth  # => 'th'
-13.nth  # => 'th'
-21.nth  # => 'st'
-23.nth  # => 'rd'
+This package is useful during development because it adds methods to the REPL
+that make adjusting and introspecting views much easier.  You'll get a lot more
+done in the REPL with these additions.
 
-NSDate.new  # => 2013-01-03 11:42:24 -0700
-5.days.ago  # => 2012-12-29 11:42:24 -0700
-5.days.before(NSDate.new)  # => 2012-12-29 11:42:24 -0700
-5.days.hence  # => 2013-01-08 11:42:24 -0700
-5.days.after(NSDate.new)  # => 2013-01-08 11:42:24 -0700
-# don't confuse 'after' and 'later'
-# after => NSDate
-# later => NSTimer
-```
+To keep this document lean-and-mean, I've put most of the REPL documentation [in
+the wiki][REPL Wiki], but a
+quick overview:
 
-Numeric
----------
+* Use the `tree` commands to output your view hierarchy.  It can accept a UIView,
+  `UIViewController`, or `CALayer` object as the root object, or it defaults to
+  your application's `UIWindow` object.
 
-```ruby
-# create a percentage
-100.0.percent # => 1.00
-55.0.percent # => 0.55
+  ```
+  (main)> tree
+    0: . UIWindow(#6e1f950: [[0.0, 0.0], [320.0, 480.0]])
+    1: `-- UIView(#8b203b0: [[0.0, 20.0], [320.0, 460.0]])
+    2:     +-- UIButton(#d028de0: [[10.0, 10.0], [320.0, 463.400512695312]])
+  ```
+* The number can be passed to the `adjust` method, aliased to `a`, and that will
+  become the view or object you are adjusting.
 
-# convert to radians.  does this look weird?
-180.degrees # => Math::PI
+  ```
+  (main)> a 2
+  => UIButton(#d028de0: [[10.0, 10.0], [320.0, 463.400512695312]])
+  ```
 
-# convert multiples of pi
-2.pi   # => 2 * Math::PI
-0.5.pi # => 0.5 * Math::PI
+* Now you can modify that view, either by accessing it via `a` (with no
+  arguments it returns the object being adjusted) or by using an adjust method:
 
-# if you thought conversion from degrees to radians looks weird, you'll hate
-# conversion from meters to miles:
-distance = 1500  # this is in meters.  why?  because all the methods that return
-  # a "distance" return it in meters
-distance.miles  # => 0.932056427001953
+  ```
+  > up 1
+  > wider 15
+  # these have shorthands, too
+  > u 1
+  > w 15
+  ```
 
-# use NSNumberFormatter to easily format a number in the current locale
-10000.string_with_style  # => "10,000"
-10000.string_with_style(NSNumberFormatterCurrencyStyle)  # => "$10,000.00"
-10000.string_with_style(:currency)  # => "$10,000.00"
-```
+Be sure to read more in the [REPL Adjustments][REPL Wiki] Wiki page.
 
-NSAttributedString
----------
+[REPL Wiki]: https://github.com/rubymotion/sugarcube/wiki/REPL-Additions
 
-```ruby
-require 'sugarcube-attributedstring'
-```
+UIKit ([wiki][UIKit Wiki])
+-----
 
-These become pretty fun!  Check out `nsattributedstring_spec.rb` for all the
-supported attributes (in theory they are all supported, but there's weird
-issues with missing constants).
+A big package chock full of methods to make working in UIKit a joy.
 
-```ruby
-'test'.nsattributedstring({})  #=> NSAttributedString.alloc.initWithString('test', attributes:{})
-'test'.attrd  # => alias for `nsattributedstring`
-'test'.bold  # => NSAttributedString.alloc.initWithString('test', attributes:{NSFontAttributeName => :bold.uifont})
-'test'.italic  # => NSAttributedString.alloc.initWithString('test', attributes:{NSFontAttributeName => :italic.uifont})
-'test'.underline  # => NSAttributedString.alloc.initWithString('test', attributes:{NSUnderlineStyleAttributeName => NSUnderlineStyleSingle})
+> `require 'sugarcube-uikit'`
 
-# you can chain 'em, too.
-'test'.bold.underline
-# If you look up NSAttributedString Application Kit Additions, you can see all
-# the constants.  Each of those has a method on NSAttributedString.
+A few varieties of methods are in this package:
 
-# you can add 'em, but the FIRST one MUST be an NSAttributedString
-'test'.attrd + '-ing'.italic
+* Conversions: `'string-to'.uiimage`, `image.uiimageview`
+* Helpers: shorthands for common operations, like `a_view << a_subview`
+* Symbols: `:system.uifont(20)`, `:label.uifontsize`
 
-# And there's where it gets FUN:
-('This'.italic + ' is going to be ' + 'FUN'.bold).underline
-```
+There are too many methods to define here. Instead: a complete list of methods
+is available in the [documentation][], and the [wiki page][UIKit Wiki] is a
+great source as well.
 
-And you can easily turn this into a label!
+[UIKit Wiki]: https://github.com/rubymotion/sugarcube/wiki/UIKit
 
-```ruby
-view << (("We just met\n".attrd +
-          "and this is " + "CRAZY".italic + "\n"
-          "But here's my " + "id_rsa.pub".monospace + " file,\n" +
-          "so give me SSH access.").uilabel
-```
+Constants
+-----
 
-NSCoder
----------
+> `require 'sugarcube-constants'`
 
-Shorthands and hash-like access to the coder/decoder objects.
+There are lots and lots of constants in UIKit, so many that I wanted a way to
+write these as symbols instead of UILongConstantNames.  This package adds
+methods to `Symbol`s to convert them into a UIKit or Foundation constant.
 
 ```ruby
-# hash access is the handiest
-coder['key'] = self.value
-self.value = decoder['key']
-
-# but if you want to store booleans and such (in their C form,
-# which will take up less space I suppose):
-coder.set('sugarcube_is_neat', toBool:self.sugarcube_is_neat?)
-self.sugarcube_is_neat = decoder.bool('sugarcube_is_neat')
+:center.uialignment  # => UITextAlignmentCenter
+:upside_down.uiorientation  # => UIDeviceOrientationPortraitUpsideDown
+:rounded.uibuttontype  # => UIButtonTypeRoundedRect
+:highlighted.uicontrolstate  # => UIControlStateHighlighted
+:touch.uicontrolevent  # => UIControlEventTouchUpInside
+:change.uicontrolevent  # => UIControlEventValueChanged
+:all.uicontrolevent  # => UIControlEventAllEvents
 
-coder.set('number_of_things', toInt:self.number_of_things)
-self.number_of_things = decoder.int('number_of_things')
+# these are really handy for custom buttons - touch_start means the finger is
+# inside the button, touch_stop is outside the button or canceled
+:touch_start  # => UIControlEventTouchDown | UIControlEventTouchDragEnter
+:touch_stop   # => UIControlEventTouchUpInside | UIControlEventTouchCancel | UIControlEventTouchDragExit
 
-# the entire list:
-coder.set(key, toBool:value)
-coder.set(key, toDouble:value)
-coder.set(key, toFloat:value)
-coder.set(key, toInt:value)
-coder.set(key, toPoint:value)
-coder.set(key, toRect:value)
-coder.set(key, toSize:value)
+:large.uiactivityindicatorstyle  # :large, :white, :gray
+:bar.uisegmentedstyle   # :plain, :bordered, :bar, :bezeled
 
-decoder.bool(key)
-decoder.double(key)
-decoder.float(key)
-decoder.int(key)
-decoder.point(key)
-decoder.rect(key)
-decoder.size(key)
+# UITableView and UITableViewCell have LOTS of associated constants... I'm
+# adding them as I come across them.
+:automatic.uitablerowanimation   # or .uitableviewrowanimation
+:default.uitablecellstyle        # or .uitableviewcellstyle
+:disclosure.uitablecellaccessory  # or .uitableviewcellaccessorytype
+:blue.uitablecellselectionstyle  # or .uitableviewcellselectionstyle
 ```
 
-NSData
-------
+See the complete list by browsing the [documentation][], or open up [symbol.rb][].
 
-Going to and from `NSData` is really useful when doing HTTP posts.
+[symbol.rb]: https://github.com/rubymotion/sugarcube/blob/master/lib/sugarcube-constants/symbol.rb
 
-```ruby
-string_data = 'String'.nsdata  # => default encoding is UTF8.
-image = 'an image'.uiimage
-image_data = image.nsdata  # PNG data representation
+Timer
+-----
 
-string_data.nsstring  # => 'String'
-image_data.nsimage  # => whatever 'an image' was
-```
+> `require 'sugarcube-timer'`
 
-NSDate
---------
-
-`NSDate` objects are converted to `Time` objects automatically by rubymotion.
-That's the good news.
-The bad news?  That still doesn't help a lot with some of
-the everyday date & time crap we have to deal with. (I hate dates, especially
-recurring events)
-##### NSDate
-
-1. Adds the following methods to get date and time components: `date_array, time_array, datetime_array`.
-   These methods return arrays.  Comparing dates, times, or both become
-   simple `date1.date_array == date2.date_array`.
-2. While I would love to support `date + 1.month` and have that support "smart"
-   calendar math (e.g. "2/13/2013" + 1.month => "3/13/2013"), I can't fudge with
-   the return value of `1.month` (=> `Fixnum`), and I won't make the terrible
-   assumption that "30 days of seconds is *about* one month".  So instead, a new
-   method that accepts date components as options is introduced:  `date.delta(months:1)`
-3. Checking whether two dates are the same, ignoring the time components, is often required
-`start_of_day` and `end_of_day` methods help
-   you here.  They are akin to `floor` and `ceil`; if you consider the time to
-   be the "floating" component, and the date to be the nearest "integer".
-4. Formatting is made easier with `NSDate#string_with_style(NSDateStyleConstant or Symbol for date, time)`
-   and `NSDate#string_with_format(format_string)`.  See
-   <http://www.unicode.org/reports/tr35/tr35-25.html#Date_Format_Patterns> for
-   the formatters, they take getting used to, coming from `strftime`, but they
-   are much more powerful and locale-aware.
-5. Miscellaneous other helpers.  I'll go over these first.
-
-###### Helpers
+Methods get added to the Fixnum class, and are available as methods on
+`NSTimer`, *and* can be called via the SugarCube::Timer module.
 
 ```ruby
-(main)> now = NSDate.new  # Time.new is the same thing
-=> 2012-09-13 09:19:06 -0600
-
-# NSDate##from_components
-(main)> feb_1_2013 = NSDate.from_components(year: 2013, month: 2, day:1)
-=> 2013-02-01 00:00:00 -0700
-(main)> feb_1_2013_sometime_later = NSDate.from_components(year: 2013, month: 2, day:1, hour:13, minute: 59, second:30)
-=> 2013-02-01 13:59:30 -0700
-(main)> feb_1_2012 = NSDate.from_components(year: 2012, month: 2, day:1)
-=> 2012-02-01 00:00:00 -0700
-
-
-(main)> feb_1_2013.timezone.name
-=> "America/Denver"
-(main)> feb_1_2013.era
-=> 1  # no, I don't know what this is :-/
-(main)> feb_1_2013.today?
-=> false  # actually, at the time I am WRITING this, it IS true, but by the time
-          # you read it, not so much ;-)
-(main)> NSDate.new.today?
-=> true
-(main)> feb_1_2013.same_day?(NSDate.new)
-=> false
-(main)> feb_1_2013.same_day?(feb_1_2013_sometime_later)
-# even though the time is different!?
-=> true
-(main)> feb_1_2013.utc_offset
-=> -25200
-(main)> feb_1_2013.leap_year?
-=> false
-(main)> NSDate.from_components(year: 2012).leap_year?
-=> true
-(main)> feb_1_2013.start_of_day
-=> 2013-02-01 00:00:00 -0700
-(main)> feb_1_2013.end_of_day
-# NOTE! end_of_day is the NEXT DAY.  this is not an accident, it makes comparisons cleaner.  deal with it.
-=> 2013-02-02 00:00:00 -0700
-(main)> feb_1_2013.start_of_week  # in the USA, start of week is Sunday
-=> 2013-01-27 00:00:00 -0700
-=> 2013-01-28 00:00:00 -0700  # in most other countries you will get Monday
-(main)> feb_1_2013.start_of_week(:monday)  # or you can specify it!
-=> 2013-01-28 00:00:00 -0700
-(main)> feb_1_2013.end_of_week  # Just like end_of_day, end_of_week returns midnight of the *next day*
-=> 2013-02-03 00:00:00 -0700
-(main)> feb_1_2013.end_of_week(:monday)
-=> 2013-02-04 00:00:00 -0700
-(main)> feb_1_2013.days_in_month
-=> 28
-(main)> feb_1_2013.days_in_year
-=> 365
-(main)> feb_1_2012.days_in_month
-=> 29
-(main)> feb_1_2012.days_in_year
-=> 366
-
-(main)> now.date_array
-=> [2012, 9, 13]
-(main)> now.time_array
-=> [9, 19, 6]
-(main)> now.datetime_array
-=> [2012, 9, 13, 9, 19, 6]
-```
-
-Use `NSDate#string_with_style` to generate date and/or time strings.
+# once
+1.second.later do
+  @view.shake
+end
+# repeating
+1.second.every do
+  @view.shake
+end
 
-```ruby
-(main)> now.string_with_style
-=> "January 29, 2013"
-(main)> now.string_with_style(NSDateFormatterShortStyle)
-=> "1/29/13"
-(main)> now.string_with_style(:short)
-=> "1/29/13"
-(main)> now.string_with_style(NSDateFormatterMediumStyle, NSDateFormatterShortStyle)
-=> "Jan 29, 2013, 9:19 AM"
-(main)> now.string_with_style(:short, :medium)
-=> "1/29/13, 9:19:06 AM"
-(main)> now.string_with_style(:none, :long)
-=> "9:19:06 AM GMT+01:00"
-```
+# you can assign the return value (an NSTimer)
+timer = 1.second.every do
+  @view.shake
+end
+# and invalidate it
+timer.invalidate
 
-It is easy to add seconds to the date using the time-related methods added to
-`Numeric`, though the `NSDate#delta` method is MUCH more capable.
+# the `every` method is available in the SugarCube::Timer module,
+# which you might find more readable
+include SugarCube::Timer
 
-```ruby
-(main)> now + 5
-=> 2012-09-13 09:19:11 -0600
-(main)> now - 5
-=> 2012-09-13 09:19:01 -0600
-(main)> now + 5.minutes
-=> 2012-09-13 09:24:06 -0600
-(main)> now + 5.days
-=> 2012-09-18 09:19:06 -0600
-```
+every 1.minute do
+  puts "tick"
+end
 
-Time zone objects are available, but the `Time#utc_offset` method is a little
-more useful.  It returns the offset *in seconds*, so divide by `1.0.hour` to get
-the offset in hours.  `utc_offset` is built into `Time`, not added by SugarCube,
-but it is added to the `NSDate` class in case you get one of those instead.
+# might as well make an alias for 'later', too
+after 1.minute do
+  puts "ding!"
+end
 
-```ruby
-(main)> now.timezone
-=> #<__NSTimeZone:0x9384c70>
-(main)> now.timezone.name
-=> "America/Denver"
-(main)> now.utc_offset
-=> -21600
-(main)> now.utc_offset / 1.hour
-=> -6
+# other time-related methods
+# for compatibility with Time methods, the mins/secs (and min/sec) aliases are provided.  Personally,
+# I like the more verbose minutes/seconds.
+1.millisecond  || 2.milliseconds
+1.millisec     || 2.millisecs
+1.second  || 2.seconds
+1.sec     || 2.secs     # aliases
+1.minute  || 2.minutes  # 1.minute = 60 seconds
+1.min     || 2.mins     # aliases
+1.hour    || 2.hours    # 1.hour = 60 minutes
+1.day     || 2.days     # 1.day = 24 hours
+1.week    || 2.weeks    # 1.week = 7 days
+# sensible values for 'month' and 'year', even though we all know you can't
+# **really** define them this way (go back to python if you find your brain hemorrhaging):
+1.month   || 2.months   # 1.month = 30 days
+1.year    || 2.years    # 1.year = 365 days
 ```
 
-The `delta` method is smart.  See the tests!  It will do its best to compensate
-for daylight savings, leap years, different numbers of days in the month, and so
-on.
+Events
+-----
 
-```ruby
-(main)> feb_28_2012 = NSDate.from_components(year:2012, month: 2, day: 28)
-=> 2012-02-28 17:00:00 -0700
-
-# add an hour or two
-(main)> feb_28_2012.delta(hours:1)
-=> 2012-02-28 18:00:00 -0700
-(main)> feb_28_2012.delta(hours:2)
-=> 2012-02-28 19:00:00 -0700
-
-# add some days
-(main)> feb_28_2012.delta(days:1)
-=> 2012-02-29 17:00:00 -0700
-(main)> feb_28_2012.delta(days:2)
-=> 2012-03-01 17:00:00 -0700
-
-# how about a month?
-(main)> feb_28_2012.delta(months:1)
-=> 2012-03-28 17:00:00 -0600  # look, the time didn't change, event though there was a DST change in this period!
-
-# cool, but if you want a more literal "24 hours", specify a time unit
-(main)> feb_28_2012.delta(months:1, hours:0)
-=> 2012-03-28 18:00:00 -0600  # disable the DST fix by specifying hours, minutes, or seconds (a "precise" delta)
-
-# in one year, it will still be Feb 28th
-(main)> feb_28_2012.delta(years:1)
-=> 2013-02-28 17:00:00 -0700
-
-# and we already know what adding a day looks like
-(main)> feb_28_2012.delta(days:1)
-=> 2012-02-29 17:00:00 -0700
-
-# a year and a day is tricky, because do we add a day, then a year?  or add a
-# year and then a day?  well, i'll tell you, **I** add a day and then a year,
-# which is feb 29th, which is no good, and the algorithm rolls back days to the
-# last day of the month, so we get the 28th.
-(main)> feb_28_2012.delta(days:1, years:1)
-=> 2013-02-28 17:00:00 -0700
-
-# adding 2 days puts us into March, which then "looks right", but it's both
-# right AND wrong, depending on how you look at it.  Another example is below,
-# where we add a month to January 30th.  Really, though, think of this: how
-# often do you need to add a year AND a day!?  Adding a year is more common, and
-# this is showing that adding a year to Feb 29th will give you Feb 28th, which I
-# think is better than March 1st.
-(main)> feb_28_2012.delta(days:2, years:1)
-=> 2013-03-01 17:00:00 -0700
-
-# Crazier: add a day (Feb 29th), then a month (March 29th), THEN a year.
-(main)> feb_28_2012.delta(days:1, years:1, months:1)
-=> 2013-03-29 17:00:00 -0600
-
-# k, for the next examples, we need a new date, and this is a non-leap year.
-(main)> jan_29_2013 = feb_28_2012.delta(days:1, months:11)
-=> 2013-01-29 17:00:00 -0700
-
-# what is 1/29/2013 plus two months?  easy!  march 29, 2013
-(main)> jan_29_2013.delta(months:2)
-=> 2013-03-29 17:00:00 -0600
-
-# Yeah, smart guy?  Well then what is 1/29/2013 plus ONE month. It's Feb 28th.
-# When someone says "see you in a month!" they mean "next month", not "in the
-# early part of two months in the future", which is where the math will take you
-# if you don't add a "day of month" correction.
-(main)> jan_29_2013.delta(months:1)
-=> 2013-02-28 17:00:00 -0700
-# but last year was a leap year, so we should get Feb 29th, 2012:
-(main)> jan_29_2013.delta(months:1, years: -1)
-=> 2012-02-29 17:00:00 -0700  # success!
-
-# do other deltas work in reverse?  fuuuuuu...
-(main)> jan_29_2013.delta(months:-11)
-=> 2012-02-29 17:00:00 -0700
-# ...ck yeah!  :-)
-
-# daylight savings!?  GEEZ dates are annoying
-(main)> mar_10_2013 = NSDate.from_components
-
-# unfortunately you will, in the edge cases, end up with stuff like this:
-(main)> feb_28_2012 == feb_28_2012.delta(days:1, months:12).delta(days: -1, months:-12)
-=> 2012-02-29 00:00:00 -0700
-```
+> `require 'sugarcube-events'`
 
-NSError
--------
+Inspired by [BubbleWrap's][BubbleWrap] `when` method, but I prefer jQuery-style
+verbs and SugarCube symbols.  Adds methods to UIControl and UITextView.
 
-`NSError.new` was just a mess, so I made it a legal method.
+UIControl
+-----------
 
 ```ruby
-NSError.new('Error Message')  # code: 0, domain: 'Error'
-# with options
-NSError.new('Error Message', code: 404)
-
-# error messages ('Error Message' in this example) are stored in a Hash with the
-# key 'NSLocalizedDescriptionKey'. If you pass a `userInfo` option, it will get
-# merged with this array.  So you can ignore that ugly-looking key.
-NSError.new('Error Message', code: 404, userInfo: { warnings: ['blabla'] })
-```
+button = UIButton.alloc.initWithFrame([0, 0, 10, 10])
 
-NSURL
--------
+button.on(:touch) { my_code }
+button.on(:touch_up_outside, :touch_cancel) { |event|
+  puts event.inspect
+  # my_code...
+}
 
-```ruby
-# see String for easy URL creation
-"https://github.com".nsurl.open  # => UIApplication.sharedApplication.openURL(NSURL.URLWithString("https://github.com"))
+# remove handlers
+button.off(:touch, :touch_up_outside, :touch_cancel)
+button.off(:all)
 ```
 
-NSString
-----------
-
-```ruby
-# UIImage from name
-"my_image".uiimage  # => UIImage.imageNamed("my_image")
-"pattern".uicolor == "pattern".uiimage.uicolor  # => UIColor.colorWithPatternImage(UIImage.imageNamed("pattern"))
-
-# UIFont from name
-"my_font".uifont # => UIFont.fontWithName("my_font", size:UIFont.systemFontSize)
-"my_font".uifont(20) # => UIFont.fontWithName("my_font", size:20)
+You can only remove handlers by "type", not by the action.  e.g. If you bind
+three `:touch` events, calling `button.off(:touch)` will remove all three.
 
-# UIColor from image name or hex code
-"pattern".uicolor # => UIColor.colorWithPatternImage(UIImage.imageNamed('pattern'))
-"#ff00ff".uicolor == :fuchsia.uicolor == 0xff00ff.uicolor # => UIColor.colorWithRed(1.0, green:0.0, blue:1.0, alpha:1.0)
-"#f0f".uicolor(0.5) == :fuchsia.uicolor(0.5) == 0xff00ff.uicolor(0.5) # => UIColor.colorWithRed(1.0, green:1.0, blue:1.0, alpha:0.5)
-# note: 0xf0f.uicolor == 0x000f0f.uicolor.  There's no way to tell the difference
-# at run time between those two Fixnum literals.
+UITextView
+------------
 
-# NSLocalizedString from string
-"hello".localized  # => NSBundle.mainBundle.localizedStringForKey("hello", value:nil, table:nil)
-"hello"._          # == "hello".localized
-"hello".localized('Hello!', 'hello_table')  # => ...("hello", value:'Hello!', table:'hello_table')
+You MUST call the `off` methods, because these methods use `NSNotification`s,
+and you must turn off listeners.
 
-# file operations
-"my.plist".exists?   # => NSFileManager.defaultManager.fileExistsAtPath("my.plist")
-"my.plist".document  # => NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, true)[0].stringByAppendingPathComponent("my.plist")
-"my.plist".cache  # => NSSearchPathForDirectoriesInDomains(NSCachesDirectory, NSUserDomainMask, true)[0].stringByAppendingPathComponent("my.plist")
-"my.plist".remove!  # => NSFileManager.defaultManager.removeItemAtPath("my.plist".document, error: error)  (returns error, if any occurred)
+There are two aliases for each event. I prefer the present tense (jQuery-style `on :change`),
+but UIKit prefers past simple (`UITextViewTextDidBeginEditingNotification`).
 
-# get the resource path, useful if you include json files or images you manipulate in the app
-"my.plist".resource  # => NSBundle.mainBundle.resourcePath.stringByAppendingPathComponent("my.plist")
-# same, but get a URL instead - often used to display a static HTML page that is stored in resources
-"index.html".resource_url  # => NSBundle.mainBundle.URLForResource("index", withExtension:"html")
+So these are all the same:
 
-# access data from Info.plist
-"CFBundleVersion".info_plist  # => NSBundle.mainBundle.infoDictionary["CFBundleVersion"]
+    :editing_did_begin  :begin
+    :editing_did_change :change
+    :editing_did_end    :end
 
-# NSURL
-"https://github.com".nsurl  # => NSURL.URLWithString("https://github.com")
+```ruby
+text_view = UITextView.new
+text_view.on :begin do
+  p 'wait for it...'
+end
+text_view.on :change do
+  p text_view.text
+end
+text_view.on :end do
+  p 'done!'
+end
 
-# check if string is not a number
-"pi".nan? # => NSNumberFormatter.alloc.init.numberFromString("pi").nil?
+# later... like in `viewWillDisappear`.  I'll use the alternative aliases here
+text_view.off :editing_did_change, :editing_did_end, :editing_did_begin
 ```
 
-NSIndexPath
--------------
+Gestures
+-----
 
-Use the `IndexPath` class to match `NSIndexPath` objects, for instance in a
-`UITableViewDelegate`.
+> `require 'sugarcube-gestures'`
+
+SugarCube's gesture support is very similar to BubbleWrap's, and it's entirely
+possible that the two will be merged into one thing.  But SugarCube is all about
+extending base classes, whereas BubbleWrap tends to add *new* classes to do the
+heavy lifting.  Plus the options you pass to SugarCube are very different, and
+the prefix is "on" instead of "when" (e.g. "on_pan" instead of "when_panned")
 
 ```ruby
-index_path = [0, 2].nsindexpath
-case index_path
-when IndexPath[0]
-when IndexPath[1, 0..5]
-when IndexPath[1, 5..objects.length]
+view.on_pan do |gesture|
+  location = gesture.view.locationInView(view)
 end
-[0, 2].nsindexpath.to_a == [0, 2]  # => true
+
+# other gesture methods, with common options:
+view.on_tap   # use system defaults
+view.on_tap(1)  # number of taps
+view.on_tap(taps: 1, fingers: 1)  # number of taps and number of fingers
+
+view.on_pinch   # no options
+view.on_rotate  # no options
+
+view.on_swipe   # use system defaults
+view.on_swipe :left
+view.on_swipe(direction: :left, fingers: 1)
+view.on_swipe(direction: UISwipeGestureRecognizerDirectionLeft, fingers: 1)
+
+view.on_pan   # use system defaults
+view.on_pan(2)  # minimum and maximum fingers required
+view.on_pan(fingers: 2)
+view.on_pan(min_fingers: 2, max_fingers: 3)
+
+view.on_press   # use system defaults
+view.on_press(1.5)  # duration
+view.on_press(duration: 1.5, taps: 1, fingers: 1)
 ```
 
-Symbol
---------
+Notifications
+-----
+
+> `require 'sugarcube-notifications'`
 
-This is the "big daddy".  Lots of sugar here...
+Makes it easy to post a notification to some or all objects.
 
 ```ruby
-:center.uialignment  # => UITextAlignmentCenter
-:upside_down.uiorientation  # => UIDeviceOrientationPortraitUpsideDown
-:rounded.uibuttontype  # => UIButtonTypeRoundedRect
-:highlighted.uicontrolstate  # => UIControlStateHighlighted
-:touch.uicontrolevent  # => UIControlEventTouchUpInside
-:change.uicontrolevent  # => UIControlEventValueChanged
-:all.uicontrolevent  # => UIControlEventAllEvents
-:blue.uicolor  # UIColor.blueColor
+# this one is handy, I think:
+MyNotification = "my notification"
+MyNotification.post_notification  # => NSNotificationCenter.defaultCenter.postNotificationName(MyNotification, object:nil)
+MyNotification.post_notification(obj)  # => NSNotificationCenter.defaultCenter.postNotificationName(MyNotification, object:obj)
+MyNotification.post_notification(obj, user: 'dict')  # => NSNotificationCenter.defaultCenter.postNotificationName(MyNotification, object:obj, userInfo:{user: 'dict'})
 
-# these are really handy for custom buttons - touch_start means the finger is inside the button, touch_stop is outside the button or canceled
-:touch_start  # => UIControlEventTouchDown | UIControlEventTouchDragEnter
-:touch_stop   # => UIControlEventTouchUpInside | UIControlEventTouchCancel | UIControlEventTouchDragExit
+# you can access the userInfo dictionary directly from the notification
+def notified(notification)
+  notification[:user]  # => 'dict'
+end
 
-# all CSS colors are supported, and alpha
-# (no "grey"s, only "gray"s, consistent with UIKit, which only provides "grayColor")
-:firebrick.uicolor(0.25)  # => 0xb22222.uicolor(0.25)
-:bold.uifont  # UIFont.boldSystemFontOfSize(UIFont.systemFontSize)
-:bold.uifont(10)  # UIFont.boldSystemFontOfSize(10)
-:small.uifontsize # => UIFont.smallSystemFontSize
-:small.uifont  # => UIFont.systemFontOfSize(:small.uifontsize)
-:bold.uifont(:small)  # UIFont.boldSystemFontOfSize(:small.uifontsize)
-:large.uiactivityindicatorstyle  # :large, :white, :gray
-:bar.uisegmentedstyle   # :plain, :bordered, :bar, :bezeled
+# very similar to add or remove an observer
+MyNotification.add_observer(observer, :method_name)
+MyNotification.add_observer(observer, :method_name, object)
 
-# UITableView and UITableViewCell have LOTS of associated constants... I'm
-# adding them as I come across them.
-:automatic.uitablerowanimation   # or .uitableviewrowanimation
-:default.uitablecellstyle        # or .uitableviewcellstyle
-:disclosure.uitablecellaccessory  # or .uitableviewcellaccessorytype
-:blue.uitablecellselectionstyle  # or .uitableviewcellselectionstyle
+# remove the observer
+MyNotification.remove_observer(observer)
+MyNotification.remove_observer(observer, object)
 ```
 
 UIImage
----------
+-----
 
-```ruby
-image = "my_image".uiimage
-image.uicolor # => UIColor.colorWithPatternImage(image)
-```
+Image Manipulation - VERY handy!  Includes some quick maniputions on UIImage,
+and adds an interface to chain together CIFilters.  Plus, you can refer to
+`cifilter.rb` to find out what filters are supported in iOS (all supported
+filters get a class method in this file).
 
-###### Image Manipulation - VERY handy!
+> `require 'sugarcube-image'`
 
+###### UIImage additions
 ```ruby
 image.scale_to [37, 37]
 image.rounded  # default: 5 pt radius
@@ -651,24 +450,107 @@ image.masked(mask_image)
 image_ab = image_a << image_b
 ```
 
-#### 568
+###### CIFilter additions
+```ruby
+# create a filter
+gaussy = CIFilter.gaussian_blur(radius: 5)
+gaussy = CIFilter.gaussian_blur(5)  # this also works - you can find the arg order by looking in cifilter.rb
 
-If you `require 'sugarcube-568'` in your Rakefile, you can use
-`UIImage.imageNamed(name)` or `name.uiimage` to load images that are specific to
-the 4" iphone.
+# apply a filter to a UIImage
+new_image = image.apply_filter(gaussy).uiimage  # apply_filter returns a CIImage, which is converted to UIImage
+
+# apply a chain of filters using the `|` operator or `apply_filter`
+darken = CIFilter.color_controls(saturation: 0, brightness: 0)
+new_image = image.apply_filter(gaussy).apply_filter(darken).uiimage
+```
+
+If you include `sugarcube-pipes` you can use the `|` operator to chain filters:
 
 ```ruby
-'tall'.uiimage  # => UIImage.imageNamed('tall')
-# => tall.png on iphone 3g
-# => tall@2x.png on iphone 4
-# => tall-568h@2x.png on iphone 5
+# using the filters from above
+new_image = image | gaussy | darken | UIImage
+new_view = view | gaussy | darken | UIView
 ```
 
-This code is ported from <https://github.com/gaj/imageNamed568>, which I had
-some problems with on RubyMotion (it worked, but not *always*.  Very strange).
+There are 91 filters available in iOS 6, I won't list them here, but check out
+[the Apple documentation][core-image-filters] to read about them, and study
+[cifilter.rb][].
+
+[core-image-filters]: http://developer.apple.com/library/mac/#documentation/GraphicsImaging/Reference/CoreImageFilterReference/Reference/reference.html
+[cifilter.rb]: https://github.com/colinta/sugarcube/blob/1.0/lib/sugarcube-image/cifilter.rb
+[cifilter.rb-post-merge]: https://github.com/rubymotion/sugarcube/blob/master/lib/sugarcube-image/cifilter.rb
+
+UIColor
+-----
+
+> `require 'sugarcube-color'`
+
+Methods to merge or manipulate a color, or to get information about a color.
+Works best on RGB colors, but HSB will work well, too.  `UIColor`s based on
+image patterns can't easily be inverted or mixed.
+
+Any classes that have a well-defined "color" representation are given a
+`uicolor` method, so it's easy to create a color from hex codes, css names,
+or images (as patterns).
+
+```ruby
+:blue.uicolor  # UIColor.blueColor
+# uicolor() accepts an alpha value, too
+:blue.uicolor(0.5)
+
+# all CSS colors are supported (but no "grey" aliases, consistent with UIKit,
+# which only provides "grayColor")
+:firebrick.uicolor  # => 0xb22222.uicolor
+
+# RGB values, in the range 0..255.
+[160, 210, 242].uicolor  # => UIColor.colorWithRed(0.6274, green:0.8235, blue:0.9490, alpha:1.0)
+[160, 210, 242].uicolor(0.5)  # => UIColor.colorWithRed(0.6274, green:0.8235, blue:0.9490, alpha:0.5)
+
+# create a UIColor from a hex value
+0xffffff.uicolor # => UIColor.colorWithRed(1.0, green:1.0, blue:1.0, alpha:1.0)
+0xffffff.uicolor(0.5) # => UIColor.colorWithRed(1.0, green:1.0, blue:1.0, alpha:0.5)
+
+# works when using strings, too
+"#fff".uicolor # => UIColor.whiteColor
+"#ffffff".uicolor # => UIColor.whiteColor
+"#ff00ff".uicolor == :fuchsia.uicolor == 0xff00ff.uicolor # => UIColor.colorWithRed(1.0, green:0.0, blue:1.0, alpha:1.0)
+"#f0f".uicolor(0.5) == :fuchsia.uicolor(0.5) == 0xff00ff.uicolor(0.5) # => UIColor.colorWithRed(1.0, green:1.0, blue:1.0, alpha:0.5)
+
+# note: 0xf0f.uicolor == 0x000f0f.uicolor.  There's no way to tell the difference
+# at run time between those two Fixnum literals.
+
+# UIColor from image name, if the first character is not "#"
+"pattern".uicolor == "pattern".uiimage.uicolor  # => UIColor.colorWithPatternImage(UIImage.imageNamed("pattern"))
+```
+
+These methods are added onto the UIColor class:
+
+```ruby
+:red.uicolor.invert # => UIColor.cyanColor
+:blue.uicolor.invert # => UIColor.yellowColor
+:green.uicolor.invert # => UIColor.magentaColor
+:red.uicolor + :blue.uicolor # => UIColor.purpleColor
+:red.uicolor + :green.uicolor # => :olive.uicolor
+# (I didn't know that until I tried it in the REPL, but it was pretty cool to
+# see the UIColor#to_s method match that mixture to olive!)
+
+# a more generic color mixing method (`+` delegates to this method):
+:white.uicolor.mix_with(:black.uicolor, 0)  # => :white
+:white.uicolor.mix_with(:black.uicolor, 0.25)  # => 0x404040.uicolor
+:white.uicolor.mix_with(:black.uicolor, 0.5)  # => :gray, same as :white.uicolor + :black.uicolor
+:white.uicolor.mix_with(:black.uicolor, 0.75)  # => 0xbfbfbf.uicolor
+:white.uicolor.mix_with(:black.uicolor, 1)  # => :black
+
+# convert to CGColor
+color.cgcolor
+```
+
+Factories
+-----
+
+> `require 'sugarcube-factories'`
 
-UIAlertView
---------
+###### UIAlertView
 
 Accepts multiple buttons and handlers.  In its simplest form, you can pass just
 a title and block.
@@ -695,8 +577,7 @@ UIAlertView.alert "I mean, is this cool?", buttons: %w[No! Sure! Hmmmm],
   success: proc { |pressed| self.proceed if pressed == "Sure!" }
 ```
 
-UIActionSheet
---------
+###### UIActionSheet
 
 This is very similar to `UIAlertView.alert`, but instead of `cancel` and
 `success` handlers, you can have `cancel, success, and destructive` handlers,
@@ -725,352 +606,220 @@ UIActionSheet.alert 'I mean, is this cool?', buttons: ['Nah', 'With fire!', 'Sur
   success: proc { |pressed| self.proceed if pressed == 'Sure' }
 ```
 
-UIColor
----------
-
-Methods to merge or manipulate a color, or to get information about a color.
-Works best on RGB colors, but HSB will work well, too.  `UIColor`s based on
-image patterns can't easily be inverted or mixed.
-
-```ruby
-:red.uicolor.invert # => UIColor.cyanColor
-:blue.uicolor.invert # => UIColor.yellowColor
-:green.uicolor.invert # => UIColor.magentaColor
-:red.uicolor + :blue.uicolor # => UIColor.purpleColor
-:red.uicolor + :green.uicolor # => :olive.uicolor
-# (I didn't know that until I tried it in the REPL, but it was pretty cool to
-# see the UIColor#to_s method match that mixture to olive!)
-
-# a more generic color mixing method (`+` delegates to this method):
-:white.uicolor.mix_with(:black.uicolor, 0)  # => :white
-:white.uicolor.mix_with(:black.uicolor, 0.25)  # => 0x404040.uicolor
-:white.uicolor.mix_with(:black.uicolor, 0.5)  # => :gray, same as :white + :black
-:white.uicolor.mix_with(:black.uicolor, 0.75)  # => 0xbfbfbf.uicolor
-:white.uicolor.mix_with(:black.uicolor, 1)  # => :black
-```
-
-UIView
---------
-
-```ruby
-UIView.first_responder  # => returns the first responder, starting at UIApplication.sharedApplication.keyWindow
-my_view.first_responder  # => also returns the first responder, but starts looking in my_view
-my_view.controller  # => returns the UIViewController that this view belongs to
-self.view << subview  # => self.view.addSubview(subview)
-self.view.show  # => self.hidden = false
-self.view.hide  # => self.hidden = true
-
-# convert to UIImage.  retina-ready.
-my_view.uiimage
-# that will use the `bounds` property to size the image.  but if you want a
-# screen shot of the contents of a scroll view, pass in `true` or `:all` to this
-# method.
-my_scroll_view.uiimage(:all)
-```
-
-When defining a UIView subclass, you often have attributes that affect your
-`drawRect` method (99% of the time, ALL the attributes affect drawing, right?).
-So SugarCube adds a `attr_updates` method, which creates an attribute identical
-to `attr_accessor` but the setter calls setNeedsDisplay if the new value != the
-old value.
-
+###### UIButton
 ```ruby
-class NiftyView < UIView
-  attr_updates :insets, :pattern
-
-  def drawRect(rect)
-    # ...
-  end
-end
+UIButton.buttonWithType(:custom.uibuttontype)
+# =>
+UIButton.custom
 
-nifty_view.pattern = 'my_pattern'  # => setNeedsDisplay gets called
-nifty_view.pattern = 'my_pattern'  # => setNeedsDisplay doesn't get called, because the value didn't change.
+UIButton.custom            => UIButton.buttonWithType(:custom.uibuttontype)
+UIButton.rounded           => UIButton.buttonWithType(:rounded.uibuttontype)
+UIButton.rounded_rect      => UIButton.buttonWithType(:rounded_rect.uibuttontype)
+UIButton.detail            => UIButton.buttonWithType(:detail.uibuttontype)
+UIButton.detail_disclosure => UIButton.buttonWithType(:detail_disclosure.uibuttontype)
+UIButton.info              => UIButton.buttonWithType(:info.uibuttontype)
+UIButton.info_light        => UIButton.buttonWithType(:info_light.uibuttontype)
+UIButton.info_dark         => UIButton.buttonWithType(:info_dark.uibuttontype)
+UIButton.contact           => UIButton.buttonWithType(:contact.uibuttontype)
+UIButton.contact_add       => UIButton.buttonWithType(:contact_add.uibuttontype)
 ```
 
-###### Animations
+###### UITableView
 
-jQuery-like animation methods.  They accept a "completed" callback handler that
-accepts an optional 'completed' boolean (the
-`UIView.animateWithDuration(delay:options:animations:completion:)`) method
-provides it to all its completion handlers).
+Default frame is `[[0, 0], [0, 0]]`, but most containers will resize it to be
+the correct size.  But heads up, it *was* `[[0, 0], [320, 480]]` (until
+the iphone 5 / 4-inch retina came out).
 
 ```ruby
-# default timeout is 0.3
-view.fade_out
-
-# with a callback
-view.fade_out do
-  view.removeFromSuperview
-end
-
-# and the completed argument
-view.fade_out do |completed|
-  view.removeFromSuperview
-end
-
-# fade_out options
-view.fade_out(duration: 0.5,
-                 delay: 0,
-               options: UIViewAnimationOptionCurveLinear,
-               opacity: 0.5) do
-  view.removeFromSuperview
-end
+UITableView.alloc.initWithFrame([[0, 0], [0, 0]], style: :plain.uitableviewstyle)
+UITableView.alloc.initWithFrame([[0, 0], [320, 480]], style: :plain.uitableviewstyle)
+UITableView.alloc.initWithFrame([[0, 0], [320, 568]], style: :plain.uitableviewstyle)
+# custom frame:
+UITableView.alloc.initWithFrame([[0, 0], [320, 400]], style: :grouped.uitableviewstyle)
 
-view.move_to([0, 100])   # move to position 0, 100
-view.delta_to([0, 100])  # move over 0, down 100, from current position
-
-view.rotate_to Math::PI  # rotate view upside down
-view.rotate 45.degrees  # rotate *an additional* 45 degrees
-view.rotate_to(duration: 0.5, angle: 45.degrees)  # using options
-
-view.slide :left   # slides the entire view left, right, up, or down. The
-                   # default amount is the width of the view being moved, but
-                   # you can override
-view.slide :left, 320
-
-view.shake  # shakes the view.
-# options w/ default values:
-shake offset: 8,   # move 8 px left, and 8 px right
-      repeat: 3,   # three times
-    duration: 0.3, # for a total of 0.3 seconds
-     keypath: 'transform.translate.x'
-
-# vigorous nodding - modifying transform.translation.y:
-view.shake offset: 20, repeat: 10, duration: 5, keypath: 'transform.translation.y'
-# an adorable wiggle - modifying transform.rotation:
-view.shake offset: 0.1, repeat: 2, duration: 0.5, keypath: 'transform.rotation'
-
-# this was pulled off warrenm's AHAlertView project.  I thought the effect was
-# awesome, and deserved more attention!
-# https://github.com/warrenm/AHAlertView
-view.tumble  # the view will fall and rotate - a good 'cancel button effect'
+# =>
+UITableView.plain
+UITableView.plain([[0, 0], [320, 480]])
+UITableView.plain([[0, 0], [320, 568]])
+# custom frame:
+UITableView.grouped([[0, 0], [320, 400]])
 ```
 
-The default behavior on all the animation methods is to animate from "the
-current" position (`UIViewAnimationOptionBeginFromCurrentState`). To disable
-that, you can either assign `options:` to something else, or you can disable
+###### UITableViewCell
 
 ```ruby
-# *just* that option.
-view.slide :left, from_current: false
-```
-
-Other options can be assigned this way, like the curve
+# factory methods, named for the cell style. cell identifier is required.
+UITableViewCell.default('cell_identifier')
+UITableViewCell.value1('cell_identifier')
+UITableViewCell.value2('cell_identifier')
+UITableViewCell.subtitle('cell_identifier')
 
-```ruby
-view.slide :left, from_current: false, curve: :ease_in  # :ease_in_out, :ease_in, :ease_out, :linear
+# you can options for the common settings
+cell = UITableViewCell.default('cell_identifier',
+  accessory: :disclosure,
+  selection: :blue,
+  text: 'text',
+  image: 'icon', # coerced into a UIImage
+  )
 ```
 
-Allow/disallow user interaction
+###### UISegmentedControl
 
 ```ruby
-view.slide :left, allow_interaction: true
-```
+control = UISegmentedControl.alloc.initItems(["one", "ah-two-whoo", "thr-r-r-ree"])
+control.segmentedControlStyle = :bar.uisegmentedstyle
 
-Not all options are configurable this way. Refer to `UIViewAnimationOptions` and
-assign them direcly to `options:` if there are options you need that are not
-listed here.
+# =>
 
-```ruby
-view.slide :left, options: UIViewAnimationOptionAllowAnimatedContent | UIViewAnimationOptionCurveEaseInOut
+UISegmentedControl.bar(["one", "ah-two-whoo", "thr-r-r-ree"])
+# plain, bordered, and bezeled are the other types
 ```
 
-Using the completed callback you can string animations together for a low-tech
-animation sequence.
+###### UIActivityViewIndicator
 
 ```ruby
-view.slide(:left, 20) do
-  view.slide(:up, 20) do
-    view.slide(:right, 20) do
-      view.slide(:down, 20) do
-        view.fade_out
-      end
-    end
-  end
-end
-```
+UIActivityIndicatorView.alloc.initWithActivityIndicatorStyle(UIActivityIndicatorViewStyleWhite)
+UIActivityIndicatorView.alloc.initWithActivityIndicatorStyle(UIActivityIndicatorViewStyleWhiteLarge)
+UIActivityIndicatorView.alloc.initWithActivityIndicatorStyle(UIActivityIndicatorViewStyleGray)
 
-Those be some gnarly callbacks.  You can write this as a chain instead!
+# =>
 
-```ruby
-UIView.animation_chain {
-  view.slide(:left, 20)
-}.and_then {
-  view.slide(:up, 20)
-}.and_then {
-  view.slide(:right, 20)
-}.and_then {
-  view.slide(:down, 20)
-}.and_then {
-  view.fade_out
-}.start
+UIActivityIndicatorView.white
+UIActivityIndicatorView.large
+UIActivityIndicatorView.gray
 ```
 
-Behind the scenes, any calls to a SugarCube animate method (`slide`, `fade`,
-`rotate`) will be setup to run *immediately* instead of in a
-`UIView#animateWithDuration(...)` block.  You can also do multiple animations
-within that block, as long as no two animations affect the same property:
-
-```ruby
-UIView.animation_chain {
-  view.slide(:left, 20)
-  view.rotate(90.degrees)
-}.and_then {
-  view.slide(:up, 20)
-  view.rotate(90.degrees)
-}.and_then {
-  view.slide(:right, 20)
-  view.rotate(90.degrees)
-}.and_then {
-  view.slide(:down, 20)
-  view.rotate(90.degrees)
-}.and_then {
-  view.fade_out
-  view.rotate_to(0.degrees)
-}.start
-```
+###### UIBarButtonItem
 
-Chains can also be written like this:
+These factory methods accept a block, which will get wired up as a
+target/action.
 
 ```ruby
-chain = UIView.animation_chain
-chain << proc { view.slide(:left, 20) }
-chain << proc { view.slide(:up, 20) }
-chain << proc { view.slide(:right, 20) }
-chain << proc { view.slide(:down, 20) }
-chain << proc { view.fade_out }
-chain.start
-```
-
-**AND** chains can be looped!  Either number of times, or call `stop` on the
-chain.
+# Get an instance containing the specified system item.
+UIBarButtonItem.done do
+  self.dismissViewControllerAnimated true, completion:nil
+end
+# =>
+UIBarButtonItem.alloc.initWithBarButtonSystemItem(:done.uibarbuttonitem, target:self, action:"action:")
+# with 'action' defined as:
+def action(sender)
+  self.dismissViewControllerAnimated true, completion:nil
+end
 
-```ruby
-chain = UIView.animation_chain {
-  view.slide(:left, 20)
-}.and_then {
-  view.slide(:right, 20)
-}.loop  # loop forever
-2.seconds.later { chain.stop }  # the animation will complete, but not loop again
-chain.loop(10)  # would loop 10 times
-
-# if you're impatient
-chain.abort
-# will stop the animation at the end of whatever block it is in, so it could be
-# in a strange position, depending on where in the chain it is.  Better to call
-# `stop`
+# the method names are 1::1 with the uibarbuttonitem constants in symbol.rb
+UIBarButtonItem.cancel { ... }           => UIBarButtonItem.alloc.initWithBarButtonSystemItem(:cancel.uibarbuttonitem, target:self, action:"action:")
+UIBarButtonItem.edit { ... }             => UIBarButtonItem.alloc.initWithBarButtonSystemItem(:edit.uibarbuttonitem, target:self, action:"action:")
+UIBarButtonItem.save { ... }             => UIBarButtonItem.alloc.initWithBarButtonSystemItem(:save.uibarbuttonitem, target:self, action:"action:")
+  .
+  .
+  .
+UIBarButtonItem.page_curl { ... }         => UIBarButtonItem.alloc.initWithBarButtonSystemItem(:page_curl.uibarbuttonitem, target:self, action:"action:")
 ```
 
-##### View factories
-
-###### UIButton
+For custom `UIBarButtonItem`s, you can use the `titled` and `imaged` methods:
 
 ```ruby
-UIButton.buttonWithType(:custom.uibuttontype)
+# Create a UIBarButtonItem, specifying the title
+UIBarButtonItem.titled('Close') do
+  self.dismissViewControllerAnimated(true, completion:nil)
+end
 # =>
-UIButton.custom
+UIBarButtonItem.alloc.initWithTitle('Close', style: :bordered.uibarbuttonstyle, target:self, action:"action:")
+def action(sender)
+  self.dismissViewControllerAnimated(true, completion:nil)
+end
 
-UIButton.custom            => UIButton.buttonWithType(:custom.uibuttontype)
-UIButton.rounded           => UIButton.buttonWithType(:rounded.uibuttontype)
-UIButton.rounded_rect      => UIButton.buttonWithType(:rounded_rect.uibuttontype)
-UIButton.detail            => UIButton.buttonWithType(:detail.uibuttontype)
-UIButton.detail_disclosure => UIButton.buttonWithType(:detail_disclosure.uibuttontype)
-UIButton.info              => UIButton.buttonWithType(:info.uibuttontype)
-UIButton.info_light        => UIButton.buttonWithType(:info_light.uibuttontype)
-UIButton.info_dark         => UIButton.buttonWithType(:info_dark.uibuttontype)
-UIButton.contact           => UIButton.buttonWithType(:contact.uibuttontype)
-UIButton.contact_add       => UIButton.buttonWithType(:contact_add.uibuttontype)
-```
 
-###### UITableView
+# You can also specify the style.
+UIBarButtonItem.titled('Close', :plain) do  # :plain, :bordered, :done
+  # ...
+end
 
-Default frame is `[[0, 0], [0, 0]]`, but most containers will resize it to be
-the correct size.  But heads up, it *was* `[[0, 0], [320, 480]]` (until
-the iphone 5 / 4-inch retina came out).
+# Or specify the image instead
+UIBarButtonItem.imaged('close_icon') do  # 'close_icon' will be coerced into a UIImage
+  # ...
+end
+# =>
+UIBarButtonItem.alloc.initWithImage('Close'.uiimage, style: :bordered.uibarbuttonstyle, ...)
 
-```ruby
-UITableView.alloc.initWithFrame([[0, 0], [0, 0]], style: :plain.uitableviewstyle)
-UITableView.alloc.initWithFrame([[0, 0], [320, 480]], style: :plain.uitableviewstyle)
-UITableView.alloc.initWithFrame([[0, 0], [320, 568]], style: :plain.uitableviewstyle)
-# custom frame:
-UITableView.alloc.initWithFrame([[0, 0], [320, 400]], style: :grouped.uitableviewstyle)
+# And, like `titled`, specify the style
+UIBarButtonItem.imaged('close'.uiimage, :done) do
+  # ...
+end
 
-# =>
-UITableView.plain
-UITableView.plain([[0, 0], [320, 480]])
-UITableView.plain([[0, 0], [320, 568]])
-# custom frame:
-UITableView.grouped([[0, 0], [320, 400]])
+# If you provide two images, they will be used as the portrait and landscape images
+UIBarButtonItem.imaged(['portrait'.uiimage, 'landscape'.uiimage) do
+  # ...
+end
+# =>
+UIBarButtonItem.alloc.initWithImage('portrait'.uiimage, landscapeImagePhone:'landscape'.uiimage, style: :bordered.uibarbuttonstyle, target:self, action:"action:")
 ```
 
-###### UITableViewCell
-
+Example Usage:
 ```ruby
-# factory methods, named for the cell style. cell identifier is required.
-UITableViewCell.default('cell_identifier')
-UITableViewCell.value1('cell_identifier')
-UITableViewCell.value2('cell_identifier')
-UITableViewCell.subtitle('cell_identifier')
-
-# you can options for the common settings
-cell = UITableViewCell.default('cell_identifier',
-  accessory: :disclosure,
-  selection: :blue,
-  text: 'text',
-  image: 'icon', # coerced into a UIImage
-  )
+toolbar = UIToolbar.new
+toolbar.items = [
+  @image_picker_button = UIBarButtonItem.camera { presentImagePickerController(self) },
+  UIBarButtonItem.flexiblespace,
+  @saveButton = UIBarButtonItem.save { save_photo(self) }
+]
 ```
 
-###### UISegmentedControl
-
+###### NSError
 ```ruby
-control = UISegmentedControl.alloc.initItems(["one", "ah-two-whoo", "thr-r-r-ree"])
-control.segmentedControlStyle = :bar.uisegmentedstyle
-
-# =>
-
-UISegmentedControl.bar(["one", "ah-two-whoo", "thr-r-r-ree"])
+# usually, NSError.new doesn't work, because the only initializer for NSError
+# needs more arguments.  This method passes some defaults in.
+NSError.new('message')
+# same as =>
+NSError.new('message', domain: 'Error', code: 0, userInfo: {})
 ```
 
-###### UIActivityViewIndicator
+Animations ([wiki][Animations Wiki])
+-----
 
-```ruby
-UIActivityIndicatorView.alloc.initWithActivityIndicatorStyle(:white.uiactivityindicatorstyle)
-UIActivityIndicatorView.alloc.initWithActivityIndicatorStyle(:large.uiactivityindicatorstyle)
-UIActivityIndicatorView.alloc.initWithActivityIndicatorStyle(:gray.uiactivityindicatorstyle)
+> `require 'sugarcube-animations'`
 
-# =>
+Careful, once you start using these helpers, you'll never go back.
 
-UIActivityIndicatorView.white
-UIActivityIndicatorView.large
-UIActivityIndicatorView.gray
+```ruby
+view.fade_out
+view.slide :left, 100
+view.rotate_to 180.degrees
+view.shake  # great for showing invalid form elements
+view.tumble  # great way to dismiss an alert-like-view
 ```
 
-UIControl
------------
-
-Inspired by [BubbleWrap's][BubbleWrap] `when` method, but I prefer jQuery-style
-verbs and SugarCube symbols.
+These helpers all delegate to the `UIView.animate` method, which accepts all the
+options that `UIView.animateWithDuration(delay:options:animations:completion:)`
+accepts, but they are optional, and they will play nicely inside an animation
+chain.
 
 ```ruby
-button = UIButton.alloc.initWithFrame([0, 0, 10, 10])
+UIView.animate do
+  view.alpha = 0
+end
+```
 
-button.on(:touch) { my_code }
-button.on(:touch_up_outside, :touch_cancel) { |event|
-  puts event.inspect
-  # my_code...
-}
+The [wiki] page documents all the different animation methods, and documents
+animation chaining, which looks like this:
 
-# remove handlers
-button.off(:touch, :touch_up_outside, :touch_cancel)
-button.off(:all)
+```ruby
+# fade out and slide left, then fade back in while returning to original position
+UIView.animation_chain do
+  view.fade_out
+  view.slide :left
+end.and_then do
+  view.fade_in
+  view.slide :right
+end.start
 ```
 
-You can only remove handlers by "type", not by the action.  e.g. If you bind
-three `:touch` events, calling `button.off(:touch)` will remove all three.
+[Animations Wiki]: https://github.com/rubymotion/sugarcube/wiki/Animations
+
+Modal
+-----
 
-UIViewController
-------------------
+> `require 'sugarcube-modal'`
 
 It is nice that *any* `UIViewController` can present a modal, but if you have
 tabs or navs or crap in the way, this is actually *NOT* what you want.  You
@@ -1080,7 +829,8 @@ And since this is a property on `UIWindow`, which is more-or-less a constant, we
 can make this the easiest to do!
 
 ```ruby
-include SugarCube::Modal
+include SugarCube::Modal  # make these methods available globally
+
 view_ctlr = EditSomethingViewController.new
 present_modal(view_ctlr)
 # ...later, when all is well...
@@ -1101,247 +851,331 @@ re-defined on `UIViewController` for this purpose:
 controller.present_modal(other_controller) { puts "presented" }
 ```
 
-UINavigationController
-------------------------
+Numbers
+-----
 
-`push`, `<<` and `pop` instead of `pushViewController` and `popViewController`.
+> `require 'sugarcube-numbers'`
 
-animated is `true` for all these.
+### Converting input
 
-`pop` accepts an argument: either a view controller to pop to, or the symbol
-`:root` which does what you might expect
+Uses `NSNumberFormatter` to try and parse a human-readable number string.
 
 ```ruby
-nav_ctlr << root_ctlr
-# or nav_ctlr.push(root_ctlr)
-nav_ctlr << new_ctlr
-# ... imagine we push on a ton of controllers ...
-nav_ctlr << another_ctlr
-nav_ctlr << last_ctlr
-nav_ctlr.pop # => pops to another_ctlr, because it's next on the stack
-nav_ctlr.pop new_ctlr # => pops to new_ctlr
-nav_ctlr.pop :root  # => pops to root_ctlr, because it's on the bottom
+if input.nan?
+  UIAlertView.alert('not a number!')
+else
+  number = input.to_number
+end
 ```
 
-UITabBarController
-------------------------
+### Pretty print numbers
 
-I have mixed feelings about adding this extension, but **I** needed it, so maybe
-you will, too...  Usually a `UITabBarController` has a static number of tabs,
-but in my case, I needed to be able to add one later, when a certain condition
-was met.
+Use NSNumberFormatter to easily format a number in the current locale
 
 ```ruby
-controllers = tabbar_ctlr.viewControllers
-controllers << new_ctlr
-tabbar_ctlr.setViewControllers(controllers, animated: true)
+10000.string_with_style  # => "10,000"
+10000.string_with_style(NSNumberFormatterCurrencyStyle)  # => "$10,000.00"
+# will convert symbol-constants using the sugarcube-constants package, if it is available
+10000.string_with_style(:currency)  # => "$10,000.00"
+```
 
-# =>
+### Percent
 
-tabbar_ctlr << new_ctlr
+```ruby
+100.0.percent # => 1.00
+55.0.percent # => 0.55
 ```
 
-UITextView
-------------
+### Ordinals
 
-Added some `UIControl`-like event binding.  You MUST call the `off` methods,
-because these methods use `NSNotification`s, and you must turn off listeners.
+```ruby
+# some number-to-string stuff
+1.nth  # => 'st'
+2.nth  # => 'nd'
+3.nth  # => 'rd'
+4.nth  # => 'th'
+11.nth  # => 'th'
+13.nth  # => 'th'
+21.nth  # => 'st'
+23.nth  # => 'rd'
+```
 
-There are two aliases for each event. I prefer the present tense (jQuery-style `on :change`),
-but UIKit prefers past simple (`UITextViewTextDidBeginEditingNotification`).
+### Angles
 
-So these are all the same:
+Since you always want to work in radians, calling `10.degrees` returns 10°, *in
+radians*.  You can convert back to degrees using `to_degrees`.  Lastly, you can
+specify a multiple of π as a number:
 
-    :editing_did_begin  :begin
-    :editing_did_change :change
-    :editing_did_end    :end
+```ruby
+10.degrees  # => π / 18
+45.degrees  # => π / 4
+3.14159.to_degrees  # => approx 180
+2.pi  # => 6.28318...
+```
+
+### Distances
+
+If you thought conversion from degrees to radians looks weird, you'll hate
+conversion from meters to miles:
 
 ```ruby
-text_view = UITextView.new
-text_view.on :editing_did_begin do
-  p 'wait for it...'
-end
-text_view.on :editing_did_change do
-  p text_view.text
-end
-text_view.on :editing_did_end do
-  p 'done!'
-end
+distance = 1500  # this is in meters.  why?  because all the methods that return
+                 # a "distance" return it in meters
+distance = 2.miles  # => 3218.688, that's how many meters are in 2 miles
+1500.in_miles  # converts meters to miles => 0.932056427001953
+```
 
-# later... like in `viewWillDisappear`.  I'll use the alternative aliases here
-text_view.off :change, :end, :begin
+### Sizes
+
+Similar conversion methods for hard disk sizes.  Uses the "mebi-byte" concepts,
+e.g. 1024 bytes in a kilobyte.
+
+```ruby
+1.byte      # => 1
+1.kilobyte  # => 1024
+1.megabyte  # => 1048576
+1.gigabyte  # => 1073741824
+1.terabyte  # => 1099511627776
+1.petabyte  # => 1125899906842624
+1.exabyte   # => 1152921504606846976
+
+1.megabyte.in_kilobytes   # => 1024
+```
+
+AttributedString
+-----
+
+> `require 'sugarcube-attributedstring'`
+
+These are pretty fun!  Check out [nsattributedstring_spec.rb][] for all the
+supported attributes (in theory they are all supported, but there's weird
+issues with missing constants).
+
+[nsattributedstring.rb]: https://github.com/rubymotion/sugarcube/blob/master/lib/sugarcube-attributedstring/nsattributedstring.rb
+
+```ruby
+'test'.nsattributedstring({})  #=> NSAttributedString.alloc.initWithString('test', attributes:{})
+'test'.attrd  # => alias for `nsattributedstring`
+'test'.bold  # => NSAttributedString.alloc.initWithString('test', attributes:{NSFontAttributeName => :bold.uifont})
+'test'.italic  # => NSAttributedString.alloc.initWithString('test', attributes:{NSFontAttributeName => :italic.uifont})
+'test'.underline  # => NSAttributedString.alloc.initWithString('test', attributes:{NSUnderlineStyleAttributeName => NSUnderlineStyleSingle})
+
+# you can chain 'em, too.
+'test'.bold.underline
+# If you look up NSAttributedString Application Kit Additions, you can see all
+# the constants.  Each of those has a method on NSAttributedString.
+
+# you can add 'em, but the FIRST one MUST be an NSAttributedString
+'test'.attrd + '-ing'.italic
+
+# And there's where it gets FUN:
+('This'.italic + ' is going to be ' + 'FUN'.bold).underline
+```
+
+And you can easily turn an attributed string into a label, if you include the
+`sugarcube-uikit` package.
+
+```ruby
+view << (("We just met\n".attrd +
+          "and this is " + "CRAZY".italic + "\n"
+          "But here's my " + "id_rsa.pub".monospace + " file,\n" +
+          "so give me SSH access.").uilabel
 ```
 
-UILabel
-----------
+568
+-----
+
+> `require 'sugarcube-568'`
 
-Added simple `fit_to_size` function to the label, which will start at the supplied font size
-and then squeeze down until all the text fits.  This way you can assure any dynamic text will completely display
-in a given label frame.
+If you `require 'sugarcube-568'` in your Rakefile, you can use
+`UIImage.imageNamed(name)` or `name.uiimage` to load images that are specific to
+the 4" iphone.
 
-The font size changes instead of the frame size.
 ```ruby
-# this will try to make the containing text fit at font size 40, but squeeze as needed.
-@label.fit_to_size(40)
-puts @label.font.pointSize # => Will be 40 or less depending on the font type and label frame.
+'tall'.uiimage  # => UIImage.imageNamed('tall')
+# => tall.png on iphone 3g
+# => tall@2x.png on iphone 4
+# => tall-568h@2x.png on iphone 5
 ```
 
+This code is ported from <https://github.com/gaj/imageNamed568>, which I had
+some problems with on RubyMotion (it worked, but not *always*.  Very strange).
+
+Files
+-----
 
+Methods to find document files, resource files, cache files, and to access
+entries out of the Info.plist file.
 
-UIBarButtonItem
-----------------------
+> `require 'sugarcube-files'`
 
 ```ruby
-# Get an instance containing the specified system item.
-UIBarButtonItem.done do
-  self.dismissViewControllerAnimated true, completion:nil
-end
-# =>
-UIBarButtonItem.alloc.initWithBarButtonSystemItem(:done.uibarbuttonitem, target:self, action:"action:")
-# with 'action' defined as:
-def action(sender)
-  self.dismissViewControllerAnimated true, completion:nil
-end
+# file operations
+"my.plist".exists?   # => NSFileManager.defaultManager.fileExistsAtPath("my.plist")
+"my.plist".document  # => NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, true)[0].stringByAppendingPathComponent("my.plist")
+"my.plist".cache  # => NSSearchPathForDirectoriesInDomains(NSCachesDirectory, NSUserDomainMask, true)[0].stringByAppendingPathComponent("my.plist")
+"my.plist".remove!  # => NSFileManager.defaultManager.removeItemAtPath("my.plist".document, error: error)  (returns error, if any occurred)
 
-# the method names are 1::1 with the uibarbuttonitem constants in symbol.rb
-UIBarButtonItem.cancel { ... }           => UIBarButtonItem.alloc.initWithBarButtonSystemItem(:cancel.uibarbuttonitem, target:self, action:"action:")
-UIBarButtonItem.edit { ... }             => UIBarButtonItem.alloc.initWithBarButtonSystemItem(:edit.uibarbuttonitem, target:self, action:"action:")
-UIBarButtonItem.save { ... }             => UIBarButtonItem.alloc.initWithBarButtonSystemItem(:save.uibarbuttonitem, target:self, action:"action:")
-  .
-  .
-  .
-UIBarButtonItem.pagecurl { ... }         => UIBarButtonItem.alloc.initWithBarButtonSystemItem(:pagecurl.uibarbuttonitem, target:self, action:"action:")
+# get the resource path, useful if you include json files or images you manipulate in the app
+"my.plist".resource  # => NSBundle.mainBundle.resourcePath.stringByAppendingPathComponent("my.plist")
+# same, but get a URL instead - often used to display a static HTML page that is stored in resources
+"index.html".resource_url  # => NSBundle.mainBundle.URLForResource("index", withExtension:"html")
 
-# Create a UIBarButtonItem, specifying the title
-UIBarButtonItem.titled('Close') do
-  self.dismissViewControllerAnimated(true, completion:nil)
-end
-# =>
-UIBarButtonItem.alloc.initWithTitle('Close', style: :bordered.uibarbuttonstyle, target:self, action:"action:")
-def action(sender)
-  self.dismissViewControllerAnimated(true, completion:nil)
-end
+# access data from Info.plist
+"CFBundleVersion".info_plist  # => NSBundle.mainBundle.infoDictionary["CFBundleVersion"]
+```
 
+Localized
+-----
 
-# You can also specify the style.
-UIBarButtonItem.titled('Close', :plain) do  # :plain, :bordered, :done
-  # ...
-end
+> `require 'sugarcube-localized'`
 
+```ruby
+# NSLocalizedString from string
+"hello".localized  # => NSBundle.mainBundle.localizedStringForKey("hello", value:nil, table:nil)
+"hello"._          # == "hello".localized
+"hello".localized('Hello!', 'hello_table')  # => ...("hello", value:'Hello!', table:'hello_table')
 
-# Or specify the image instead
-UIBarButtonItem.imaged('close_icon') do  # 'close_icon' will be coerced into a UIImage
-  # ...
-end
-# =>
-UIBarButtonItem.alloc.initWithImage('Close'.uiimage, style: :bordered.uibarbuttonstyle, ...)
+# If you have an NSError object, you can retrieve the localizedDescription the same way:
+error.localized
+error._
+```
 
-# And, like `titled`, specify the style
-UIBarButtonItem.imaged('close'.uiimage, :done) do
-  # ...
-end
+NSCoder
+-----
 
-# If you provide two images, they will be used as the portrait and landscape images
-UIBarButtonItem.imaged(['portrait'.uiimage, 'landscape'.uiimage) do
-  # ...
-end
-# =>
-UIBarButtonItem.alloc.initWithImage('portrait'.uiimage, landscapeImagePhone:'landscape'.uiimage, style: :bordered.uibarbuttonstyle, target:self, action:"action:")
+Shorthands and hash-like access to the coder/decoder objects.
+
+> `require 'sugarcube-nscoder'`
+
+```ruby
+# hash access is the handiest
+coder['key'] = self.value
+self.value = decoder['key']
+
+# but if you want to store booleans and such (in their C form,
+# which will take up less space):
+coder.set('sugarcube_is_neat', toBool: self.sugarcube_is_neat?)
+self.sugarcube_is_neat = decoder.bool('sugarcube_is_neat')
+
+coder.set('number_of_things', toInt:self.number_of_things)
+self.number_of_things = decoder.int('number_of_things')
+
+# the entire list:
+coder.set(key, toBool:value)
+coder.set(key, toDouble:value)
+coder.set(key, toFloat:value)
+coder.set(key, toInt:value)
+coder.set(key, toPoint:value)
+coder.set(key, toRect:value)
+coder.set(key, toSize:value)
+
+decoder.bool(key)
+decoder.double(key)
+decoder.float(key)
+decoder.int(key)
+decoder.point(key)
+decoder.rect(key)
+decoder.size(key)
 ```
 
-Example Usage:
+NSData
+-----
+
+> `require 'sugarcube-nsdata'`
+
+Going to and from `NSData` is really useful when doing HTTP posts.
+
 ```ruby
-toolbar = UIToolbar.new
-toolbar.items = [
-  @image_picker_button = UIBarButtonItem.camera { presentImagePickerController(self) },
-  UIBarButtonItem.flexiblespace,
-  @saveButton = UIBarButtonItem.save { save_photo(self) }
-]
+# default string encoding is UTF8, you can pass other encodings to this method
+string_data = 'String'.nsdata
+
+# PNG data representation
+image = 'an image'.uiimage
+image_data = image.nsdata
+
+# this will download the URL contents
+url = 'http://localhost'.nsurl
+url.nsdata  # => NSData.dataWithContentsOfURL(self)
+
+string_data.nsstring  # => 'String'
+image_data.nsimage  # => whatever 'an image' was
 ```
 
-NSNotificationCenter
-----------------------
+NSDate ([wiki][NSDate Wiki])
+-----
 
-Makes it easy to post a notification to some or all objects.
+> `require 'sugarcube-nsdate'`
 
-```ruby
-# this one is handy, I think:
-MyNotification = "my notification"
-MyNotification.post_notification  # => NSNotificationCenter.defaultCenter.postNotificationName(MyNotification, object:nil)
-MyNotification.post_notification(obj)  # => NSNotificationCenter.defaultCenter.postNotificationName(MyNotification, object:obj)
-MyNotification.post_notification(obj, user: 'dict')  # => NSNotificationCenter.defaultCenter.postNotificationName(MyNotification, object:obj, userInfo:{user: 'dict'})
+This package includes additions to the `NSDate` class, and related additions to
+`Fixnum` and `NSString`.  There's a lot here, so check out the [wiki][NSDate Wiki]
+for detailed information.
 
-# you can access the userInfo dictionary directly from the notification
-def notified(notification)
-  notification[:user]  # => 'dict'
-end
+[NSDate Wiki]: https://github.com/rubymotion/sugarcube/wiki/NSDate
 
-# very similar to add or remove an observer
-MyNotification.add_observer(observer, :method_name)
-MyNotification.add_observer(observer, :method_name, object)
+Foundation
+-----
 
-# remove the observer
-MyNotification.remove_observer(observer)
-MyNotification.remove_observer(observer, object)
+Smaller additions to the CoreFoundation classes.  Some extensions, like
+`NSDate`, are large enough that they get broken out into their own packages.
+
+> `require 'sugarcube-foundation'`
+
+###### NSArray
+```ruby
+[1, 3].nsindexpath  # NSIndexPath.indexPathWithIndex(1).indexPathByAddingIndex(3)
+[1, 3].nsindexset
+[1, 3].nsset
 ```
 
-NSTimer
----------
+###### NSIndexSet
+```ruby
+index_set.to_a  # => [1, 2, ...]
+```
 
+###### NSIndexPath
 ```ruby
-# once
-1.second.later do
-  @view.shake
-end
-# repeating
-1.second.every do
-  @view.shake
-end
+index_path.to_a  # => [1, 2, ...]
+```
 
-# you can assign the return value (an NSTimer)
-timer = 1.second.every do
-  @view.shake
-end
-# and invalidate it
-timer.invalidate
+###### NSString
+```ruby
+'https://github.com'.nsurl
+'/path/to/file'.fileurl
+'https://google.com/search?q=' + 'search terms'.escape_url
+'%20'.unescape_url
+```
 
-# the `every` method is available in the SugarCube::Timer module,
-# which you might find more readable
-include SugarCube::Timer
-every 1.minute do
-  puts "tick"
-end
+###### NSURL
+```ruby
+url = 'https://github.com'.nsurl
+url.can_open?  # => true, it will open in safari
+url.open  # opens in safari
+url.nsurlrequest  # convert to NSURLRequest object
+```
 
-# might as well make an alias
-after 1.minute do
-  puts "ding!"
-end
+IndexPath
+-----
 
-# other time-related methods
-# for compatibility with Time methods, the mins/secs (and min/sec) aliases are provided.  Personally,
-# I like the more verbose minutes/seconds.
-1.millisecond  || 2.milliseconds
-1.millisec     || 2.millisecs
-1.second  || 2.seconds
-1.sec     || 2.secs     # aliases
-1.minute  || 2.minutes  # 1.minute = 60 seconds
-1.min     || 2.mins     # aliases
-1.hour    || 2.hours    # 1.hour = 60 minutes
-1.day     || 2.days     # 1.day = 24 hours
-1.week    || 2.weeks    # 1.week = 7 days
-# sensible values for 'month' and 'year', even though we all know you can't
-# **really** define them this way (go back to python if you find your brain
-# hemorrhaging):
-1.month   || 2.months   # 1.month = 30 days
-1.year    || 2.years    # 1.year = 365 days
+> `require 'sugarcube-indexpath`
 
-# some comparison methods
-date1.today?
-date2.same_day? date1
+Use the `IndexPath` class to match `NSIndexPath` objects, for instance in a
+`UITableViewDelegate`.
+
+```ruby
+index_path = [0, 2].nsindexpath
+case index_path
+when IndexPath[0]
+when IndexPath[1, 0..5]
+when IndexPath[1, 5..objects.length]
+end
+[0, 2].nsindexpath.to_a == [0, 2]  # => true
 ```
 
 NSUserDefaults
-----------------
+-----
+
+> `require 'sugarcube-nsuserdefaults'`
 
 This file does *one* thing very **DANGEROUS**... to "help" with defaults.
 
@@ -1386,6 +1220,9 @@ NSUserDefaults['test'] = test  # saved
 CoreGraphics
 --------------
 
+*This package is installed automatically, because so many other packages depend
+on it. It does not add any methods to built-in classes.*
+
 ###### Is it `CGMakeRect` or `CGRectMake`?  What arguments does `CGRect.new` take?
 
 Instead, just use the coercion methods `Rect()`, `Size()` and `Point()`.  They
@@ -1423,8 +1260,51 @@ f = Rect(p, [w, h])
 f = Rect([x, y], s)
 ```
 
+Pointer
+-----
+
+> `require 'sugarcube-pointer'`
+
+These are not UIKit-related, so I reverted to Ruby's preferred `to_foo`
+convention.
+
+```ruby
+[0.0, 1.1, 2.2].to_pointer(:float)
+
+# is equivalent to
+floats = Pointer.new(:float, 3)
+floats[0] = 0.0
+floats[1] = 1.1
+floats[2] = 2.2
+```
+
+To_s
+-----
+
+> `require 'sugarcube-to_s'`
+
+`to_s` methods are defined on the following classes:
+
+* NSError
+* NSIndexPath
+* NSLayoutConstraint
+* NSNotification
+* NSSet
+* NSURL
+* UIColor
+* UIEvent
+* UIView
+* UILabel
+* UITextField
+* UITouch
+* UIViewController
+
+The output of these is (much?) more useful than the default.
+
 CoreLocation
---------------
+-----
+
+> `require 'sugarcube-corelocation'`
 
 Open up `CLLocationCoordinate2D` to provide handy-dandies
 
@@ -1435,7 +1315,7 @@ Open up `CLLocationCoordinate2D` to provide handy-dandies
 => #<CLLocationCoordinate2D latitude=39.2681274414062 longitude=-84.2576293945312>
 > denver_co.distance_to(loveland_oh)
 => 1773425.5  # in meters
-> denver_co.distance_to(loveland_oh).miles
+> denver_co.distance_to(loveland_oh).in_miles
 => 1101.955078125
 > denver_co.delta_miles(1101.6, -32.556)
 => #<CLLocationCoordinate2D latitude=39.2681427001953 longitude=-84.2577209472656>
@@ -1445,399 +1325,95 @@ Open up `CLLocationCoordinate2D` to provide handy-dandies
 => 0.00502094626426697
 ```
 
-REPL View adjustments
------------------------
-
-Pixel pushing is an unfortunate but necessary evil.  Well, at least we can make
-it a little less painful.  SugarCube provides a library that adds some methods
-that are meant to be used in the REPL.
-
-`require "sugarcube-repl"`
-
-The actual code is, for historical reasons, in the `SugarCube::Adjust` module,
-which is included by default.  But to really be handy you'll want to require the
-`sugarcube-repl` package.
-
-#### Finding the view you want.
-
-This is often touted as the *most useful feature* of SugarCube!
-
-```
-(main)> tree
-  0: . UIWindow(#6e1f950: [[0.0, 0.0], [320.0, 480.0]])
-  1: `-- UIView(#8b203b0: [[0.0, 20.0], [320.0, 460.0]])
-  2:     +-- UIButton(#d028de0: [[10.0, 10.0], [320.0, 463.400512695312]])
-  3:     |   `-- UIImageView(#d02aaa0: [[0.0, 0.0], [320.0, 463.400512695312]])
-  4:     +-- UIRoundedRectButton(#d02adb0: [[55.0, 110.0], [210.0, 20.0]])
-  5:     |   `-- UIButtonLabel(#d02af00: [[73.0, 0.0], [63.0, 19.0]], text: "Button 1")
-  6:     +-- UIRoundedRectButton(#d028550: [[60.0, 30.0], [200.0, 20.0]])
-  7:     |   `-- UIButtonLabel(#d02afb0: [[68.0, 0.0], [63.0, 19.0]], text: "Button 2")
-  8:     `-- UIRoundedRectButton(#d02b220: [[70.0, 30.0], [300.0, 20.0]])
-  9:         `-- UIButtonLabel(#d02b300: [[118.0, 0.0], [63.0, 19.0]], text: "Button 3")
-```
-
-SugarCube provides lot of `to_s` methods on UIKit objects - that is so that this
-tree view is really easy to find the view you want.  Once you do find the one
-you want, you can fetch it out of that list using the `adjust` method, which is
-aliased to `a` to make it easy on the fingers.
-
-```
-(main)> a 6
-=> UIRoundedRectButton(#d028550: [[60.0, 30.0], [200.0, 20.0]]), child of UIView(#8b203b0)
-```
-
-Now that we've chose the button, it is available in the `a` method, *and* there
-are a bunch of methods in the SugarCube::Adjust module that act on that object.
-Most of these methods help you adjust the frame of a view.
-
-```ruby
-> up 1
-> down 1  # same as `up -1`
-> down  # defaults to 1 anyway
-> left 10
-> right 10
-> left  # => left 1
-> origin 10, 12  # move to x:10, y:12
-> wider 15
-> thinner 10
-> taller  # => taller 1
-> shorter  # => shorter 1
-> size 100, 10  # set size to width:100, height: 10
-> shadow(opacity: 0.5, offset: [0, 0], color: :black, radius: 1)  # and path, which is a CGPath object.
-> center  # See `Centering` section below
-> restore  # original frame and shadow is saved when you first call `adjust`
-```
-
-Here are the short versions of those methods.
-
-```ruby
-> u          # up, default value=1
-> d          # down
-> l          # left
-> r          # right
-> w          # wider
-> n          # thiNNer
-> t          # taller
-> s          # shorter
-> o 10, 12   # origin
-> o [10, 12]
-> o CGPoint.new(10, 12)
-> o Point(10, 12)
-> z 100, 10  # siZe, also accepts an array, CGSize, or Size()
-             # and frame
-> f [[0,0], [0,0]]
-             # sHadow
-> h opacity: 0.5, offset: [0, 0], color: :black, radius: 1
-
-# frame, size, origin, and shadow can also be used as getters
-> f
-[[0, 0], [320, 568]]
-> o          # origin
-[0, 0]
-> z          # size
-[320, 568]
-> h          # this returns an object identical to what you can pass to `shadow`
-{opacity: 0.5, offset: [0, 0], color: :black, radius: 1}
-
-# and of course the `a` method returns the current object
-> a
-=> UITextField(#9ce6470, [[46, 214], [280, 33]], text: "hi!"), child of UIView(#10a6da20)
-```
-
-The most useful feature of the REPL adjustment is the ability to quickly
-position and size your UI elements __visually__ and then paste the final values
-into your code.  In order to better accomodate that, `adjust` has an option to
-modify the output format.  Many thanks to [Thom Parkin][] for developing these
-output formatters.
-
-```
-(main)> repl_format :ruby
-```
-
-Currently supported is:
-
-* RubyMotion (Default) (`:ruby`)
-* Objective-C (`:objc`)
-* JSON (`:json`)
-
-#### Objective-C style
-
-```
-(main)> repl_format :objc
-(main)> tree
-  0: . UIWindow(#6e27180: {{0, 0}, {320, 480}})
-  1: `-- UIView(#8d631b0: {{0, 20}, {320, 460}})
-  2:     +-- UIButton(#6d6c090: {{10, 10}, {320, 463.401}})
-  3:     |   `-- UIImageView(#8d67e00: {{0, 0}, {320, 463.401}})
-  4:     `-- UIRoundedRectButton(#8d68170: {{10, 30}, {30, 200}})
-  5:         `-- UIButtonLabel(#8d69c30: {{2, 90}, {26, 19}})
-=> UIWindow(#6e27180, {{0, 0}, {320, 480}},
-
-# you can pass the format into the adjust method:
-(main)> a 4, :objc
-=> "UIRoundedRectButton(#8d68170: {{10.0, 30.0}, {200.0, 30.0}})"
-
-# it will continue to be used in subsequent calls
-(main)> wider 15
-{{10.0, 30.0}, {200.0, 45.0}}
-=> "UIRoundedRectButton(#8d68170: {{10.0, 30.0}, {200.0, 45.0}}) child of UIView(#8d631b0)"
-```
-
-#### JSON (or GeoMotion)
-
-```
-(main)> a 1, :json
-=> "UIView(#8d631b0: {x: 0.0, y: 20.0, height: 460.0, width: 320.0})"
-(main)> wider 30
-=> "CGRect(#6e9c9f0: {x: 0.0, y: 20.0, height: 460.0, width: 350.0})"
-(main)> right 130
-=> "CGRect(#8dc6a40: {x: 130.0, y: 20.0, height: 460.0, width: 350.0})"
-(main)> tree
-  0: . UIWindow(#6e27180: {x: 0.0, y: 0.0, height: 480.0, width: 320.0})
-  1: `-- UIView(#8d631b0: {x: 130.0, y: 20.0, height: 460.0, width: 350.0})
-  2:     +-- UIButton(#6d6c090: {x: 10.0, y: 10.0, height: 463.400512695312, width: 320.0})
-  3:     |   `-- UIImageView(#8d67e00: {x: 0.0, y: 0.0, height: 463.400512695312, width: 320.0})
-  4:     `-- UIRoundedRectButton(#8d68170: {x: 10.0, y: 30.0, height: 200.0, width: 45.0})
-  5:         `-- UIButtonLabel(#8d69c30: {x: 4.0, y: 90.0, height: 19.0, width: 37.0})
-=> UIWindow(#6e27180: {x: 0.0, y: 0.0, height: 480.0, width: 320.0})
-```
-
-###  CENTER (in parent frame)
-
-It is called as `center(which_index, of_total_number, direction)`. The order can
-be changed, and all the arguments are optional.  Default values are
-`center(1, 1, 'h')` (center the item horizontally).
-
-You can set 'direction' using a string or symbol: 'horiz', 'vert', 'x', even 'x
-and y'.  The method searches for the letters `[xyhv]`.
-
-Here are a few examples:
-
-```
-(main)> center
-[[145.0, 30.0], [30.0, 200.0]]
-UIRoundedRectButton.origin = [145.0, 30.0]
-=> "[[145.0, 30.0], [30.0, 200.0]]"
-```
-
-In order to place that same button in the center of the screen - horizontally
-and vertically - you can use this shorthand syntax:
-
-`center :xy`
-
-If you have three buttons and want them spaced evenly (vertically) across their
-parent frame, you can accomplish that this way:
-
-```
-(main)> tree
-  0: . UIWindow(#6e1f950: [[0.0, 0.0], [320.0, 480.0]])
-  1: `-- UIView(#8b203b0: [[0.0, 20.0], [320.0, 460.0]])
-  2:     +-- UIButton(#d028de0: [[10.0, 10.0], [320.0, 464]])
-  3:     |   `-- UIImageView(#d02aaa0: [[0.0, 0.0], [320.0, 464]])
-  4:     +-- UIRoundedRectButton(#d02adb0: [[55.0, 110.0], [210.0, 20.0]], text: "Button 1")
-  5:     |   `-- UIButtonLabel(#d02af00: [[73.0, 0.0], [63.0, 19.0]])
-  6:     +-- UIRoundedRectButton(#d028550: [[60.0, 30.0], [200.0, 20.0]], text: "Button 2")
-  7:     |   `-- UIButtonLabel(#d02afb0: [[68.0, 0.0], [63.0, 19.0]])
-  8:     `-- UIRoundedRectButton(#d02b220: [[70.0, 30.0], [300.0, 20.0]], text: "Button 3")
-  9:         `-- UIButtonLabel(#d02b300: [[118.0, 0.0], [63.0, 19.0]])
-=> UIWindow(#6e1f950, [[0.0, 0.0], [320.0, 480.0]])
-# grab the first button, and center it vertically.  It is the first of three buttons
-(main)> a 4; center 1, 3, :vert; center
-[[55.0, 110.0], [210.0, 20.0]]
-UIRoundedRectButton.origin = [55.0, 110.0]
-=> "[[55.0, 110.0], [210.0, 20.0]]"
-# grab the second button.  The first parameter changes to `2`, because this
-# button is in the second position.
-(main)> a 6; center 2, 3, :vert; center
-[[60.0, 220.0], [200.0, 20.0]]
-UIRoundedRectButton.origin = [60.0, 220.0]
-=> "[[60.0, 220.0], [200.0, 20.0]]"
-# grab the third button and place it in the third position
-(main)> a 8; center 3, 3, :vert; center
-[[10.0, 330.0], [300.0, 20.0]]
-UIRoundedRectButton.origin = [10.0, 330.0]
-=> "[[10.0, 330.0], [300.0, 20.0]]"
-```
-
-The calculated positions (x,y) are in the REPL output
-
-#### Finding the *[controller,layer,...]* you want.
-
-**Don't stop there!**
+Pipes
+-----
 
-You can analyze `UIViewController` and `CALayer` hierarchies, too.  There's even
-a handy `root` method to grab the `rootViewController`:
+This package short-circuits the `|` operator to perform coercion and filtering
+between all sorts of objects.
 
-```ruby
-(main)> tree root
-  0: . #<MainScreenController:0xac23b80>
-  1: +-- #<ScheduleViewController:0x13185d00>
-  2: |   +-- #<ScheduleTableController:0x131862f0>
-  3: |   `-- #<ScheduleCalendarController:0x131bba90>
-  4: +-- #<CameraViewController:0x13191380>
-  5: +-- #<UINavigationController:0xac01ea0>
-  6: |   `-- #<UITableViewController:0xac04e30>
-  7: +-- #<PicturesViewController:0x1403ede0>
-  8: `-- #<MessagesViewController:0x131a1bc0>
-=> #<MainScreenController:0xac23b80>
-```
+### Coercion
 
-If you have a tree structure and you want to output it using `tree`, you can do
-so by passing either a method name (that should return an array) or a block. The
-block will be passed your object, and should return the children.
+Any object that defines a coercion method (image.uicolor, string.uiimage,
+:symbol.uifont) can use the `|` and the class name to perform the same method.
 
 ```ruby
-class Foo
-  attr_accessor :children
-end
-```
-```
-(main)> foo = Foo.new
-(main)> foo.children = [Foo.new,Foo.new,Foo.new]
-(main)> tree foo, :children
-(main)> tree foo, :children
-  0: . #<Foo:0x12d6e0d0>
-  1: +-- #<Foo:0x114146c0>
-  2: +-- #<Foo:0x114149d0>
-  3: `-- #<Foo:0x114149e0>
-
-=> #<Foo:0x12d6e0d0 @children=[#<Foo:0x114146c0>, #<Foo:0x114149d0>, #<Foo:0x114149e0>]>
-(main)> tree(foo) { |f| f.children }
-  0: . #<Foo:0x12d6e0d0>
-  1: +-- #<Foo:0x114146c0>
-  2: +-- #<Foo:0x114149d0>
-  3: `-- #<Foo:0x114149e0>
-
-=> #<Foo:0x12d6e0d0 @children=[#<Foo:0x114146c0>, #<Foo:0x114149d0>, #<Foo:0x114149e0>]>
+:label | UIFont  # => # :label.uifont
+"image_name" | UIImage  # => "image_name".uiimage
+view | UIImage | UIColor  # => view.uiimage.uicolor
 ```
 
-##### Global objects
+### Filters
 
-The adjust and tree methods act on global objects.  Once either of these methods
-is used, you can access that global if you want:
+You can pipe objects that have some idea of "filter", like using an image mask
+or image filter.
 
 ```ruby
-$sugarcube_view  # => the view (or any object) being 'adjusted' (accessible using `adjust` or `a`)
-$sugarcube_items  # => the list of views that was output using `tree`
+image | mask  # => image.masked(mask)
+image | darken_cifilter  # => image.apply_filter(darken_cifilter)
+# this one is... interesting!
+"My name is Mud" | /\w+$/   # => "Mud"
+"My name is Mud" | /\d+$/   # => nil
+"My name is Mud" | "Mud"  # => "Mud"
+"My name is Mud" | "Bob"    # => nil
 ```
 
+Awesome
+-----
 
-Pointers
-----------
-
-These are not UIKit-related, so I reverted to Ruby's preferred `to_foo`
-convention.
-
-```ruby
-[0.0, 1.1, 2.2].to_pointer(:float)
-
-# is equivalent to
-floats = Pointer.new(:float, 3)
-floats[0] = 0.0
-floats[1] = 1.1
-floats[2] = 2.2
-```
+> `require 'sugarcube-awesome'`
 
-UUID
-------
+SugarCube adds support for [Motion-Awesome][motion-awesome]!  The `awesome_icon`
+method is added to `Symbol`, which returns an NSAttributedString that uses the
+MotionAwesome font.  You can pass in `:size` and `:color` options.
 
-Quick wrapper for `CFUUIDCreate()` and `CFUUIDCreateString()`.  Identical to the
-`BubbleWrap::create_uuid` method.
+`sugarcube-attributedstring` is not required for this extension to function, but
+it adds `NSAttributedString` methods that really help.  Below I'm usind `#+` and
+`#bold` and `#color` to construct an `NSAttributedString`.
 
 ```ruby
-> SugarCube::UUID::uuid
-"0A3A76C6-9738-4458-969E-3B9DF174A3D9"
+# in Rakefile
+require 'sugarcube-awesome'
+require 'sugarcube-attributedstring'
 
-# or
-> include SugarCube::UUID
-> uuid
-# => "0A3A76C6-9738-4458-969E-3B9DF174A3D9"
+# in your app
+label.attributedText = (:down_arrow.awesome_icon + ' Going down?'.bold).color(:white)
+# OR for buttons
+button.setAttributedTitle(:twitter.awesome_icon, forState:UIControlStateNormal)
 ```
 
-Ruby on Rails Ripoffs (RoR-R?)
----------------
-
-aka `ActiveSupport`.  Now that Thomas Kadauke has released [motion-support][],
-consider these extensions deprecated.  They will be removed in version 1.0.
-
-```ruby
-# truthiness with `blank?`
-nil.blank?    # => true
-false.blank?  # => true
-''.blank?     # => true
-[].blank?     # => true
-{}.blank?     # => true
-
-0.blank?        # => false
-true.blank?     # => false
-'a'.blank?      # => false
-['a'].blank?    # => false
-{a: 'a'}.blank? # => false
-
-# and my favorite
-1.in? [1,2,3]  # => true
-1.in? 4..5     # => false
-```
+[motion-awesome]: http://derailed.github.io/motion-awesome/
 
-Gestures
---------
+Anonymous
+-----
 
-Sugarcube's gesture support is very similar to BubbleWrap's, and it's entirely
-possible that the two will be merged into one thing.  But SugarCube is all about
-extending base classes, whereas BubbleWrap tends to add *new* classes to do the
-heavy lifting.  Plus the options you pass to SugarCube are very different, and
-the prefix is "on" instead of "when" (e.g. "on_pan" instead of "when_panned")
+> `require 'sugarcube-anonymous'`
 
-Gestures are an "opt-in" extension.  In your Rakefile, add
-`require 'sugarcube-gestures'`.
+Convert `Hash`es into an "anonymous object".  Existing keys will be able to be
+accessed using method names.  Uses the `SugarCube::Anonymous` class to
+accomplish this, though the usual interface is via `Hash#to_object`.
 
 ```ruby
-require 'sugarcube-gestures'
-
-view.on_pan { |gesture|
-  location = gesture.view.locationInView(view)
-}
-
-# other gesture methods, with common options:
-view.on_tap   # use system defaults
-view.on_tap(1)  # number of taps
-view.on_tap(taps: 1, fingers: 1)  # number of taps and number of fingers
-
-view.on_pinch   # no options
-view.on_rotate  # no options
-
-view.on_swipe   # use system defaults
-view.on_swipe :left
-view.on_swipe(direction: :left, fingers: 1)
-view.on_swipe(direction: UISwipeGestureRecognizerDirectionLeft, fingers: 1)
+h = { foo: 'FOO', 'bar' => 'BAR' }.to_object
 
-view.on_pan   # use system defaults
-view.on_pan(2)  # minimum and maximum fingers required
-view.on_pan(fingers: 2)
-view.on_pan(min_fingers: 2, max_fingers: 3)
+# You can use methods instead of keys.
+h.foo         # => h[:foo]
+h.bar         # => h['bar']
+h.foo = 'Foo' # => h[:foo] = 'Foo'
+h.bar = 'Bar' # => h['bar'] = 'Bar'
 
-view.on_press   # use system defaults
-view.on_press(1.5)  # duration
-view.on_press(duration: 1.5, taps: 1, fingers: 1)
+# only existing keys are accessed this way
+h.baz          # => NoMethodError
+h.baz = 'baz'  # => NoMethodError
 ```
 
 Unholy
---------
-
-These methods are just about as opinionated as they get - even more than the RoR
-additions.  They are not included by default, so please don't freak out about
-them.  I add them here because I don't think anyone will notice if I do, and I
-use these everywhere. :poop:
-
-### `ivar`
-
-###### Rakefile
+-----
 
-```ruby
-require 'sugarcube-unholy'
-```
+> `require 'sugarcube-unholy'`
 
-###### Elsewhere
+I added these a long time ago to SugarCube, and so it's possible some people use
+these extensions. Honestly, I should have put them somewhere else, they are
+silly and not terribly useful, except maybe to me (I use them a lot!). :poop:
 
 ```ruby
 class Baz ; end
@@ -1847,10 +1423,25 @@ foo = Baz.new
 foo.instance_variable_set(:bar.ivar, value)  # => foo.instance_variable_set(:@bar, value)
 foo.instance_variable_set(var_name.ivar, value)  # => foo.instance_variable_set("@#{var_name}", value)
 
+# (:symbol || 'string').setter
+foo.send(varname.setter, 'value')
+
 # (:symbol || 'string').cvar
 Baz.class_variable_set(var_name.cvar, value)  # => Baz.class_variable_set("@@#{var_name}", value)
 ```
 
+Legacy
+-----
+
+> `require 'sugarcube-legacy'`
+
+This is where deprecated methods go to suffer a long, slow death.
+
+Contributions
+=====
+
+If you want to see new features, please fork, commit, and pull-request! :smiley:
+
 [BubbleWrap]: https://github.com/rubymotion/BubbleWrap
 [sweettea]: https://github.com/colinta/sweettea
 [teacup]: https://github.com/rubymotion/teacup