sugarcube 0.9.2 → 0.9.3

data/README.md

@@ -80,9 +80,12 @@ Examples
 100.0.percent # => 1.00
 55.0.percent # => 0.55
 
-1.3.seconds.later do
-  @someview.fade_out
-end
+# convert to radians.  does this look weird?
+180.degrees # => Math::PI
+
+# convert multiples of pi
+2.pi   # => 2 * Math::PI
+0.5.pi # => 0.5 * Math::PI
 ```
 
  NSDate
@@ -93,10 +96,10 @@ 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)
 
-1. Adds the following methods to get date and time components: `date, time, datetime`.
+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 == date2.date`.
+   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
@@ -110,11 +113,11 @@ recurring events)
 ```
 (main)> now = NSDate.new  # Time.new is the same thing
 => 2012-09-13 09:19:06 -0600
-(main)> now.date
+(main)> now.date_array
 => [2012, 9, 13]
-(main)> now.time
+(main)> now.time_array
 => [9, 19, 6]
-(main)> now.datetime
+(main)> now.datetime_array
 => [2012, 9, 13, 9, 19, 6]
 ```
 
@@ -154,33 +157,58 @@ the offset in hours.  `utc_offset` is built into `Time`, not added by SugarCube.
 The `delta` method is smart.
 
 ```ruby
-(main)> feb_28_2012_stamp = 1330473600  # what, you don't have this memorized?
-=> 1330473600
-(main)> feb_28_2012 = Time.at(feb_28_2012_stamp)
+(main)> feb_28_2012 = Time.at(1330473600)
 => 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!
+
+# 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 (fab 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
 
@@ -188,19 +216,22 @@ The `delta` method is smart.
 (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.  trust me.  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.
+# 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!
 
-# does it work in reverse?  fuuuuuu...
+# do other deltas work in reverse?  fuuuuuu...
 (main)> jan_29_2013.delta(months:-11)
 => 2012-02-29 17:00:00 -0700
 # ...ck yeah!  :-)
 
-# unfortunately you will end up with stuff like this:
+# 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(months:-12)
 => true
 ```
@@ -273,7 +304,7 @@ This is the "big daddy".  Lots of sugar here...
 :rounded.uibuttontype  # => UIButtonTypeRoundedRect
 :highlighted.uicontrolstate  # => UIControlStateHighlighted
 :touch.uicontrolevent  # => UIControlEventTouchUpInside
-:changed.uicontrolevent  # => UIControlEventValueChanged
+:change.uicontrolevent  # => UIControlEventValueChanged
 :all.uicontrolevent  # => UIControlEventAllEvents
 :blue.uicolor  # UIColor.blueColor
 # all CSS colors are supported, and alpha
@@ -441,6 +472,31 @@ button.off(:all)
 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.
 
+ UIViewController
+------------------
+
+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
+should use the `rootViewController` (whatever it may be) to present to modal.
+
+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
+view_ctlr = EditSomethingViewController.new
+present_modal(view_ctlr)
+# ...later, when all is well...
+dismiss_modal
+```
+
+These accept completion blocks:
+
+```ruby
+present_modal(view_ctlr) { puts "here!" }
+dismiss_modal { puts "gone!" }
+```
+
  UINavigationController
 ------------------------
 
@@ -473,6 +529,37 @@ tabbar_ctlr.setViewControllers(controllers, animated: true)
 # =>
 
 tabbar_ctlr << new_ctlr
+```
+
+ UITextView
+------------
+
+Added some `UIControl`-like event binding.  You MUST call the `off` methods,
+because these methods use `NSNotification`s, and you must turn off listeners.
+
+There are two aliases for each event. I prefer the present tense (jQuery-style `on :change`),
+but UIKit prefers past simple (`UITextViewTextDidBeginEditingNotification`).
+
+So these are all the same:
+
+    :editing_did_begin  :begin
+    :editing_did_change :change
+    :editing_did_end    :end
+
+```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
+
+# later... like in `viewWillDisappear`.  I'll use the alternative aliases here
+text_view.off :change, :end, :begin
 ```
 
  NSNotificationCenter
@@ -488,9 +575,11 @@ Makes it easy to post a notification to some or all objects.
 
 # very similar to add or remove an observer
 "my notification".add_observer(observer, :method_name)
-"my notification".add_observer(observer, :method_name, target)
+"my notification".add_observer(observer, :method_name, object)
+
+# remove the observer
 "my notification".remove_observer(observer)
-"my notification".remove_observer(observer, target)
+"my notification".remove_observer(observer, object)
 ```
 
  NSTimer

data/lib/sugarcube/modal.rb

@@ -0,0 +1,12 @@
+module SugarCube
+  module Modal
+    module_function
+    def present_modal(view_ctlr, &block)
+      UIApplication.sharedApplication.keyWindow.rootViewController.presentViewController(view_ctlr, animated:true, completion:block)
+    end
+
+    def dismiss_modal(&block)
+      UIApplication.sharedApplication.keyWindow.rootViewController.dismissViewControllerAnimated(true, completion:block)
+    end
+  end
+end

data/lib/sugarcube/notifications.rb

@@ -12,15 +12,15 @@ class NSString
     end
   end
 
-  def add_observer(observer, message, object=nil)
-    NSNotificationCenter.defaultCenter.addObserver(observer,
-            selector: message,
+  def add_observer(target, action, object=nil)
+    NSNotificationCenter.defaultCenter.addObserver(target,
+            selector: action,
             name: self,
             object: object)
   end
 
-  def remove_observer(observer, object=nil)
-    NSNotificationCenter.defaultCenter.removeObserver(observer, name:self, object:object)
+  def remove_observer(target, object=nil)
+    NSNotificationCenter.defaultCenter.removeObserver(target, name:self, object:object)
   end
 
 end

data/lib/sugarcube/nsdate.rb

@@ -4,6 +4,8 @@ class NSDate
   end
   alias timeZone timezone
 
+  # In the rare case you actually get an NSDate object - not a Time object - this
+  # method is actually useful.
   def utc_offset
     return self.timezone.secondsFromGMT
   end
@@ -12,25 +14,45 @@ class NSDate
     self.year % 4 == 0 and self.year % 100 != 0 or self.year % 400 == 0
   end
 
-  def date
+  #  (main)> t = Time.new
+  #  => 2012-09-27 11:29:12 +0900
+  #  (main)> t.time_array
+  #  => [2012, 9, 27]
+  def date_array
     return [self.year, self.month, self.day]
   end
 
-  def time
+  #  (main)> t = Time.new
+  #  => 2012-09-27 11:29:12 +0900
+  #  (main)> t.time_array
+  #  => [11, 29, 12]
+  def time_array
     return [self.hour, self.min, self.sec]
   end
 
-  def datetime
+  #  (main)> t = Time.new
+  #  => 2012-09-27 11:29:12 +0900
+  #  (main)> t.time_array
+  #  => [2012, 9, 12, 11, 29, 12]
+  def datetime_array
     return [self.year, self.month, self.day, self.hour, self.min, self.sec]
   end
 
+  #  (main)> t = Time.new
+  #  => 2012-09-27 11:29:12 +0900
+  #  (main)> t.start_of_day
+  #  => 2012-09-27 00:00:00 +0900
   def start_of_day
     time_interval = self.hour.hours + self.min.minutes + self.sec
     return self - time_interval
   end
 
+  #  (main)> t = Time.new
+  #  => 2012-09-27 11:29:12 +0900
+  #  (main)> t.end_of_day
+  #  => 2012-09-28 00:00:00 +0900
   def end_of_day
-    time_interval = (23 - self.hour).hours + (59 - self.min).minutes + 60 - self.sec
+    time_interval = (23 - self.hour).hours + (59 - self.min).minutes - self.sec + 60
     return self + time_interval
   end
 

data/lib/sugarcube/numeric.rb

@@ -4,66 +4,12 @@ class Numeric
     self / 100.0
   end
 
-  def seconds
-    self
+  def degrees
+    self / 180.0 * Math::PI
   end
-  alias second seconds
-  alias sec seconds
-  alias secs seconds
 
-  def minutes
-    self * 60
+  def pi
+    self * Math::PI
   end
-  alias minute minutes
-  alias min minutes
-  alias mins minutes
 
-  def hours
-    self * 3600
-  end
-  alias hour hours
-
-  def days
-    self.hours * 24
-  end
-  alias day days
-
-  def weeks
-    self.days * 7
-  end
-  alias week weeks
-
-  def months
-    self.days * 30
-  end
-  alias month months
-
-  def years
-    self.days * 365
-  end
-  alias year years
-
-  def later(user_info=nil, &fire)
-    NSTimer.scheduledTimerWithTimeInterval(self.to_f, target: fire, selector: 'call:', userInfo: user_info, repeats: false)
-  end
-
-  def every(user_info=nil, &fire)
-    NSTimer.scheduledTimerWithTimeInterval(self.to_f, target: fire, selector: 'call:', userInfo: user_info, repeats: true)
-  end
-
-end
-
-
-module SugarCube
-  module Timer
-    module_function
-
-    def every(time, user_info=nil, &fire)
-      time.every user_info, &fire
-    end
-
-    def after(time, user_info=nil, &fire)
-      time.later user_info, &fire
-    end
-  end
 end

data/lib/sugarcube/symbol.rb

@@ -119,6 +119,9 @@ class Symbol
     touch: UIControlEventTouchUpInside,
     touch_up: UIControlEventTouchUpInside,
     touch_down: UIControlEventTouchDown,
+    change:  UIControlEventValueChanged|UIControlEventEditingChanged,
+    # I'm leaving this for backwards compatibility.  please use 'change' or
+    # 'editing_did_change':
     changed: UIControlEventValueChanged|UIControlEventEditingChanged,
 
     touch_down_repeat: UIControlEventTouchDownRepeat,
@@ -133,7 +136,10 @@ class Symbol
     value_changed: UIControlEventValueChanged,
 
     editing_did_begin: UIControlEventEditingDidBegin,
+    # nice.  very consistent APPLE:
     editing_changed: UIControlEventEditingChanged,
+    # now here's consistency:
+    editing_did_change: UIControlEventEditingChanged,
     editing_did_end: UIControlEventEditingDidEnd,
     editing_did_endonexit: UIControlEventEditingDidEndOnExit,
 
@@ -159,6 +165,7 @@ class Symbol
 
   @returnkeys = {
     default:       UIReturnKeyDefault,
+    return:        UIReturnKeyDefault,
     go:            UIReturnKeyGo,
     google:        UIReturnKeyGoogle,
     join:          UIReturnKeyJoin,
@@ -271,12 +278,17 @@ class Symbol
   @keyboardtypes = {
     default:               UIKeyboardTypeDefault,
     asciicapable:          UIKeyboardTypeASCIICapable,
+    ascii:                 UIKeyboardTypeASCIICapable,
     numbersandpunctuation: UIKeyboardTypeNumbersAndPunctuation,
     url:                   UIKeyboardTypeURL,
     numberpad:             UIKeyboardTypeNumberPad,
+    number:                UIKeyboardTypeNumberPad,
     phonepad:              UIKeyboardTypePhonePad,
+    phone:                 UIKeyboardTypePhonePad,
     namephonepad:          UIKeyboardTypeNamePhonePad,
+    nameandphone:          UIKeyboardTypeNamePhonePad,
     emailaddress:          UIKeyboardTypeEmailAddress,
+    email:                 UIKeyboardTypeEmailAddress,
   }
 
   private

data/lib/sugarcube/timer.rb

@@ -0,0 +1,63 @@
+class Numeric
+  def seconds
+    self
+  end
+  alias second seconds
+  alias sec seconds
+  alias secs seconds
+
+  def minutes
+    self * 60
+  end
+  alias minute minutes
+  alias min minutes
+  alias mins minutes
+
+  def hours
+    self * 3600
+  end
+  alias hour hours
+
+  def days
+    self.hours * 24
+  end
+  alias day days
+
+  def weeks
+    self.days * 7
+  end
+  alias week weeks
+
+  def months
+    self.days * 30
+  end
+  alias month months
+
+  def years
+    self.days * 365
+  end
+  alias year years
+
+  def later(user_info=nil, &fire)
+    NSTimer.scheduledTimerWithTimeInterval(self.to_f, target: fire, selector: 'call:', userInfo: user_info, repeats: false)
+  end
+
+  def every(user_info=nil, &fire)
+    NSTimer.scheduledTimerWithTimeInterval(self.to_f, target: fire, selector: 'call:', userInfo: user_info, repeats: true)
+  end
+end
+
+
+module SugarCube
+  module Timer
+    module_function
+
+    def every(time, user_info=nil, &fire)
+      time.every user_info, &fire
+    end
+
+    def after(time, user_info=nil, &fire)
+      time.later user_info, &fire
+    end
+  end
+end

data/lib/sugarcube/uicontrol.rb

@@ -7,7 +7,8 @@ class UIControl
     @sugarcube_callbacks ||= Hash.new { |hash, key| hash[key] = [] }
   end
 
-  # Add event handlers to UIControls
+  # Add event handlers to UIControls.  See symbol.rb for the uicontrolevent
+  # constant aliases.
   #
   # @example
   #   button = UIButton.alloc.initWithFrame([0, 0, 10, 10])
@@ -24,12 +25,18 @@ class UIControl
     self
   end
 
-  # Removes all events that were bound with `on`.
+  # Removes all events that were bound with `on`.  See symbol.rb for the
+  # uicontrolevent constant aliases.
   #
   # @example
   #   button.off(:touch)
   #   button.off(:touchupoutside, :touchcancel)
+  #   button.off  # all events
   def off(*events)
+    if events.length == 0
+      events = sugarcube_callbacks.keys
+    end
+
     events.each do |event|
       event = event.uicontrolevent unless event.is_a? Fixnum
 

data/lib/sugarcube/uiimage.rb

@@ -1,7 +1,6 @@
 class UIImage
   def uiimage ; self ; end
 
-
   def uicolor(alpha=nil)
     color = UIColor.colorWithPatternImage(self)
     if not alpha.nil?

data/lib/sugarcube/uitextview.rb

@@ -0,0 +1,78 @@
+class UITextView
+
+  def sugarcube_callbacks
+    @sugarcube_callbacks ||= Hash.new { |h,k| h[k] = [] }
+  end
+
+  # Add event handlers to UITextView, with the same syntax as `UIControl`
+  # objects.  Present tense and past simple aliases are provided. (e.g.
+  # `editing_did_change` and `change`)
+  #
+  # @example
+  #   text_view = UITextView.alloc.initWithFrame([0, 0, 10, 10])
+  #   text_view.on(:editing_did_change) { my_code }
+  #   # alias:
+  #   text_view.on(:change) { my_code }
+  #   text_view.on(:editing_did_begin, :editing_did_end) { my_code }
+  def on(*events, &block)
+    events.each do |event|
+      case event
+      when :editing_did_begin, :begin, UITextViewTextDidBeginEditingNotification
+        _onEventNotification(UITextViewTextDidBeginEditingNotification, &block)
+      when :editing_did_change, :change, UITextViewTextDidChangeNotification
+        _onEventNotification(UITextViewTextDidChangeNotification, &block)
+      when :editing_did_end, :end, UITextViewTextDidEndEditingNotification
+        _onEventNotification(UITextViewTextDidEndEditingNotification, &block)
+      else
+        raise "Unknown or unsupported event #{event} in UITextView#on"
+      end
+    end
+
+    self
+  end
+
+  # Removes all events that were bound with `on`.  Present tense and past simple
+  # aliases are provided. (e.g. `editing_did_change` and `change`)
+  #
+  # @example
+  #   text_view.off(:change)
+  #   # alias:
+  #   text_view.off(:editing_did_change)
+  #   text_view.off(:editing_did_begin, :editing_did_end)
+  #   text_view.off  # all events
+  def off(*events)
+    if events.length == 0
+      events = self.sugarcube_callbacks.keys
+    end
+
+    events.each do |event|
+      case event
+      when :editing_did_begin, :begin, UITextViewTextDidBeginEditingNotification
+        _offEventNotification(UITextViewTextDidBeginEditingNotification)
+      when :editing_did_change, :change, UITextViewTextDidChangeNotification
+        _offEventNotification(UITextViewTextDidChangeNotification)
+      when :editing_did_end, :end, UITextViewTextDidEndEditingNotification
+        _offEventNotification(UITextViewTextDidEndEditingNotification)
+      else
+        raise "Unknown or unsupported event #{event} in UITextView#on"
+      end
+    end
+
+    self
+  end
+
+private
+  def _onEventNotification(notication, &block)
+    self.sugarcube_callbacks[notication] << NSNotificationCenter.defaultCenter.addObserverForName(notication,
+          object: self,
+           queue: NSOperationQueue.mainQueue,
+      usingBlock: block)
+  end
+
+  def _offEventNotification(nofication)
+    self.sugarcube_callbacks[nofication].each do |callback_observer|
+      NSNotificationCenter.defaultCenter.removeObserver(callback_observer)
+    end
+  end
+
+end

data/lib/sugarcube/version.rb

@@ -1,3 +1,3 @@
 module SugarCube
-  Version = '0.9.2'
+  Version = '0.9.3'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sugarcube
 version: !ruby/object:Gem::Version
-  version: 0.9.2
+  version: 0.9.3
   prerelease: 
 platform: ruby
 authors:
@@ -10,11 +10,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-09-15 00:00:00.000000000 Z
+date: 2012-09-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &70267775597160 !ruby/object:Gem::Requirement
+  requirement: &70363874967320 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -22,10 +22,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70267775597160
+  version_requirements: *70363874967320
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70267775595020 !ruby/object:Gem::Requirement
+  requirement: &70363874965460 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -33,7 +33,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70267775595020
+  version_requirements: *70363874965460
 description: ! '== Description
 
 
@@ -73,6 +73,7 @@ files:
 - lib/sugarcube/document.rb
 - lib/sugarcube/exceptions.rb
 - lib/sugarcube/fixnum.rb
+- lib/sugarcube/modal.rb
 - lib/sugarcube/notifications.rb
 - lib/sugarcube/nsdate.rb
 - lib/sugarcube/nsdate_delta.rb
@@ -83,6 +84,7 @@ files:
 - lib/sugarcube/numeric.rb
 - lib/sugarcube/symbol.rb
 - lib/sugarcube/symbol/symbol_uicolor.rb
+- lib/sugarcube/timer.rb
 - lib/sugarcube/to_s/nsset.rb
 - lib/sugarcube/to_s/uievent.rb
 - lib/sugarcube/to_s/uitouch.rb
@@ -96,6 +98,7 @@ files:
 - lib/sugarcube/uipickerview.rb
 - lib/sugarcube/uisegmentedcontrol.rb
 - lib/sugarcube/uitableview.rb
+- lib/sugarcube/uitextview.rb
 - lib/sugarcube/uiview.rb
 - lib/sugarcube/uiviewcontroller.rb
 - lib/sugarcube/uuid.rb