motion-firebase 1.0.5 → 1.0.6

data/.gitignore

@@ -15,3 +15,4 @@ nbproject
 .sass-cache
 .idea
 *.gem
+/.dat*

data/README.md

@@ -3,7 +3,7 @@ motion-firebase
 
 A RubyMotion wrapper for the Firebase SDK.
 
-Just the main class `Firebase` is wrapped.
+Adds more rubyesque methods to the built-in classes.
 
 Versioning
 -------
@@ -16,17 +16,6 @@ SDK
 
 # Firebase Class Reference
 
-## Overview
-
-A `Firebase` reference represents a particular location in your Firebase and can
-be used for reading or writing data to that Firebase location.
-
-This class is the starting point for all Firebase operations. After you’ve
-initialized it with `Firebase.new` you can use it to read data (ie. `on() {}`),
-write data (ie. `[key]=`), and to create new Firebase references (ie. `[]`).
-
-## Tasks
-
 ##### Initializing a Firebase object
 
     Firebase.new(url)
@@ -133,6 +122,7 @@ write data (ie. `[key]=`), and to create new Firebase references (ie. `[]`).
 ##### Retrieving String Representation
 
     firebase.to_s
+    firebase.inspect
 
 ##### Properties
 
@@ -146,366 +136,51 @@ write data (ie. `[key]=`), and to create new Firebase references (ie. `[]`).
     Firebase.sdkVersion
 
 
-## Properties
-
-#### name
-
-Gets last token in a Firebase location (e.g. ‘fred’ in https://SampleChat.firebaseIO-demo.com/users/fred))
-
-###### Return Value
-
-The name of the location this reference points to.
-
-
-#### parent
-
-Get a Firebase reference for the parent location. If this instance refers to the
-root of your Firebase, it has no parent, and therefore parent( ) will return `nil`.
-
-###### Return Value
-
-A Firebase reference for the parent location.
-
-
-#### root
-
-Get a Firebase reference for the root location
-
-###### Return Value
-
-A new Firebase reference to root location.
-
-
-## Class Methods
-
-#### sdkVersion
-
-Retrieve the Firebase SDK version.
-
-
-#### dispatch_queue=(queue)
-
-Set the default dispatch queue for event blocks.
-
-###### Parameters
-
-    queue
-*The queue to set as the default for running blocks for all Firebase event
-types.*
-
-## Instance Methods
-
-
-#### auth(credential, options={}, &and_then) { |error| }
-
-###### Parameters
-
-Authenticate access to this Firebase using the provided credentials. The
-completion block will be called with the results of the authenticated attempt,
-and the disconnect block will be called if the credentials become invalid at
-some point after authentication has succeeded.
-
-    credential
-*The Firebase authentication JWT generated by a secure code on a remote server.*
-
-    and_then || options[:completion]
-*This block will be called with the results of the authentication attempt*
-
-    options[:disconnect]
-*This block will be called if at any time in the future the credentials become
-invalid*
-
-
-#### cancel_disconnect(&and_then)
-
-Cancel any operations that are set to run on disconnect. If you previously
-called `on_disconnect`, and no longer want the values updated when the
-connection is lost, call `cancel_disconnect`
-
-###### Parameters
-
-    and_then
-*A block that will be triggered once the Firebase servers have acknowledged the
-cancel request.*
-
-
-#### [](*children)
-
-Get a Firebase reference for the location at the specified relative path. The
-relative path can either be a simple child name (e.g. ‘fred’) or a deeper
-slash-separated path (e.g. ‘fred/name/first’).
-
-    firebase['fred']
-    firebase['fred/name/first']
-    firebase['fred', 'name', 'first']
-
-###### Parameters
-
-    children
-*A relative path from this location to the desired child location(s).*
-
-###### Return Value
-
-A Firebase reference for the specified relative path.
-
-
-#### []
-
-`firebase[]` generates a new child location using a unique name and returns a
-Firebase reference to it. This is useful when the children of a Firebase
-location represent a list of items.
-
-The unique name generated by `firebase[]` is prefixed with a client-generated
-timestamp so that the resulting list will be chronologically-sorted.
-
-###### Return Value
-
-A Firebase reference for the generated location.
-
-
-#### to_s
-
-Gets the absolute URL of this Firebase location.
-
-
-#### Firebase.new(url)
-
-Initialize this Firebase reference with an absolute URL.
-
-###### Parameters
+# FirebaseAuthClient Class Reference
 
-    url
-*The Firebase URL (ie: https://SampleChat.firebaseIO-demo.com)*
+##### Initializing a FirebaseAuthClient instance
 
+    ref = Firebase.new(url)
+    auth = FirebaseAuthClient.new(ref)
 
-#### on(event_type, options, &and_then) { |snapshot| }
-#### on(event_type, options, &and_then) { |snapshot, previous_sibling_name| }
+##### Checking current authentication status
 
-`on()` is used to listen for data changes at a particular location. This is the
-primary way to read data from Firebase. Your block will be triggered for the
-initial data and again whenever the data changes.
+    auth.check { |error, user| }
 
-If the block accepts two arguments, events of type `:added`, `:moved`, and
-`:changed` will be passed the name of the previous node by priority order.
+##### Removing any existing authentication
 
-Use `off(handle)` to stop receiving updates.
+    auth.logout
 
-Supported events types for all realtime observers are specified as:
+##### Email/password authentication methods
 
-    :added    # fired when a new child node is added to a location
-    :removed  # fired when a child node is removed from a location
-    :changed  # fired when a child node at a location changes
-    :moved    # fired when a child node moves relative to the other child nodes at a location
-    :value    # fired when any data changes at a location and, recursively, any children
+`credentials` for `create,remove,login` should include `:email` and `:password`.
+For `update`, `credentials` should include `:email`, `:old_password` and
+`:new_password`.
 
-###### Parameters
+    auth.create(email: 'hello@example.com', password: '12345') { |error, user| }
+    auth.remove(email: 'hello@example.com', password: '12345') { |error, user| }
+    auth.login(email: 'hello@example.com', password: '12345') { |error, user| }
+    auth.update(email: 'hello@example.com', old_password: '12345', new_password: '54321') { |error, success| }
 
-    event_type
-*The type of event to listen for.*
+##### Facebook authentication methods
 
-    and_then || options[:completion]
-*The block that should be called with initial data and updates as a
-`FDataSnapshot`, and optionally the previous child’s name.*
+`credentials` should include `:app_id` and `:permissions`
 
-    options[:disconnect]
-*The block that should be called if this client no longer has permission to
-receive these events*
+    auth.login_facebook(app_id: '123abc', permissions: ['email']) { |error, user| }
 
-###### Return Value
+##### Twitter authentication methdos
 
-A handle used to unregister this block later using `off(handle)`
+`credentials` should include `:app_id` and `:on_multiple` block. The
+`:on_multiple` block is called when more than one account is found.  It is
+passed an array of usernames and should return an index or `NSNotFound`.
 
+    auth.login_to_twitter(app_id: '123abc', on_multiple: ->(usernames) { return 0 }) { |error, user| }
 
-#### once(event_type, options, &and_then) { |snapshot| }
-#### once(event_type, options, &and_then) { |snapshot, previous_sibling_name| }
-
-#### observeSingleEventOfType:andPreviousSiblingNameWithBlock:
-
-This is equivalent to `on()`, except the block is immediately canceled after the
-initial data is returned.
-
-If the block accepts two arguments, events of type `:added`, `:moved`, and
-`:changed` will be passed the name of the previous node by priority order.
-
-###### Parameters
-
-    event_type
-*The type of event to listen for.*
-
-    and_then || options[:completion]
-*The block that should be called with initial data and updates as a
-`FDataSnapshot`, and optionally the previous child’s name.*
-
-    options[:disconnect]
-*The block that should be called if this client no longer has permission to
-receive these events*
-
-
-#### on_disconnect(nil, &and_then) { |error| }
-#### on_disconnect(value, &and_then) { |error| }
-#### on_disconnect(values, &and_then) { |error| }
-#### on_disconnect(value, priority:priority, &and_then) { |error| }
-
-Ensure the data at this location is removed when the client is disconnected (due
-to closing the app, navigating to a new page, or network issues).
-
-`on_disconnect` is especially useful for implementing “presence” systems.
-
-###### Parameters
-    value
-*The value to be set after the connection is lost. Special value `nil` will
-remove the value, and a dictionary can be sent to update multiple child node
-names and the values to set them to.*
-
-    priority
-*The priority to be set after the connection is lost.*
-
-    and_then
-*Block to be triggered when the operation has been queued up on the Firebase
-servers*
-
-
-#### off
-#### off(handle)
-
-Detach a block previously attached with `on()`, or remove all observer events.
-
-###### Parameters
-    handle
-The handle returned by the call to observeEventType:withBlock: which we are
-trying to remove.  If no handle is passed, all ovservers are removed.
-
-
-#### clear!(&and_then) { |error| }
-
-Remove the data at this Firebase location. Any data at child locations will also
-be deleted.
-
-The effect of the delete will be visible immediately and the corresponding
-events will be triggered. Synchronization of the delete to the Firebase servers
-will also be started.
-
-`clear!` is equivalent to calling `value(nil)`
-
-###### Parameters
-    and_then
-*The block to be called after the remove has been committed to the Firebase
-servers.*
-
-#### run(options={}, &transaction) { |data| }
-
-Performs an optimistic-concurrency transactional update to the data at this
-location. Your block will be called with an FMutableData instance that contains
-the current data at this location. Your block should update this data to the
-value you wish to write to this location, and then return an instance of
-FTransactionResult with the new data.
-
-If, when the operation reaches the server, it turns out that this client had
-stale data, your block will be run again with the latest data from the server.
-
-When your block is run, you may decide to abort the transaction by return
-`FTransactionResult.abort`.
-
-Since your block may be run multiple times, this client could see several
-immediate states that don’t exist on the server. You can suppress those
-immediate states until the server confirms the final state of the transaction.
-
-###### Parameters
-    transaction || options[:transaction]
-*This block receives the current data at this location and must return an
-instance of FTransactionResult*
-
-    options[:completion]
-*This block will be triggered once the transaction is complete, whether it was
-successful or not. It will indicate if there was an error, whether or not the
-data was committed, and what the current value of the data at this location is.*
-
-    options[:local]
-*Set this to `false` to suppress events raised for intermediate states, and only
-get events based on the final state of the transaction.*
-
-
-#### priority=(priority)
-#### priority(priority, &and_then) { |error| }
-
-Set a priority for the data at this Firebase location. Priorities can be used to
-provide a custom ordering for the children at a location (if no priorities are
-specified, the children are ordered by name).
-
-You cannot set a priority on an empty location. For this reason
-`value(priority:)` should be used when setting initial data with a specific
-priority and `priority()` should be used when updating the priority of existing
-data.
-
-Children are sorted based on this priority using the following rules:
-
-Children with no priority (a `nil` priority) come first. They are ordered
-lexicographically by name. Children with a priority that is parsable as a number
-come next. They are sorted numerically by priority first (small to large) and
-lexicographically by name second (A to z). Children with non-numeric priorities
-come last. They are sorted lexicographically by priority first and
-lexicographically by name second. Setting the priority to `nil` removes any
-existing priority. Note that priorities are parsed and ordered as IEEE 754
-double-precision floating-point numbers.
-
-###### Parameters
-    priority
-*The priority to set at the specified location.*
-
-    and_then
-*The block that is triggered after the priority has been written on the
-servers.*
-
-
-#### value=(value)
-#### value(value)
-
-Write data to this Firebase location.
-
-This will overwrite any data at this location and all child locations.
-
-Data types that can be set are:
-
-    String, 'Hello World'
-    Numeric, Boolean — true, 43, 4.333
-    Hash, {'key' => 'value', 'nested' => {'another': 'value' => }
-    Array, []
-
-The effect of the write will be visible immediately and the corresponding events
-will be triggered. Synchronization of the data to the Firebase servers will also
-be started.
-
-Passing `nil` for the new value is equivalent to calling `clear!` all data at
-this location or any child location will be deleted.
-
-Note that `value` will remove any priority stored at this location, so if
-priority is meant to be preserved, you should use `value(priority:)` instead.
-
-Priorities are used to order items.
-
-###### Parameters
-    value
-*The value to be written.*
-
-    priority
-*The priority to be attached to that data.*
-
-
-#### unauth
-
-Removes any credentials associated with this Firebase
-
-
-#### update(values)
-#### update(values, &and_then) { |error| }
-
-Update changes the values of the keys specified in the dictionary without
-overwriting other keys at this location.
+##### Global configuration and settings
 
-###### Parameters
-    values
-*A dictionary of the keys to change and their new values*
+    FirebaseAuthClient.sdkVersion
 
-    and_then
-*The block that is triggered after the update has been written on the Firebase servers*
+##### Retrieving String Representation
 
+    firebase.to_s
+    firebase.inspect

data/app/app_delegate.rb

@@ -54,7 +54,7 @@ class MyController < UIViewController
     self.chat = []
 
     # Initialize the root of our Firebase namespace.
-    self.firebase = Firebase.alloc.initWithUrl(FirechatNS)
+    self.firebase = Firebase.new(FirechatNS)
 
     # Pick a random number between 1-1000 for our username.
     self.title = "Guest0x#{(rand * 1000).round.to_s(16).upcase}"
@@ -76,7 +76,7 @@ class MyController < UIViewController
 
     # This will also add the message to our local array self.chat because
     # the FEventTypeChildAdded event will be immediately fired.
-    self.firebase[].setValue({'name' => self.title, 'text' => text_field.text})
+    self.firebase << {'name' => self.title, 'text' => text_field.text}
 
     text_field.text = ''
     false

data/lib/firebase/firebase.rb

@@ -1,5 +1,23 @@
 class Firebase
 
+  def self.convert_event_type(event_type)
+    case event_type
+    when :child_added, :added
+      return FEventTypeChildAdded
+    when :child_moved, :moved
+      FEventTypeChildMoved
+    when :child_changed, :changed
+      return FEventTypeChildChanged
+    when :child_removed, :removed
+      return FEventTypeChildRemoved
+    when :value
+      return FEventTypeValue
+    else
+      NSLog("Unknown event type #{event_type.inspect}")
+    end
+    return event_type
+  end
+
   def self.new(url)
     alloc.initWithUrl(url)
   end
@@ -120,63 +138,6 @@ class Firebase
     return self
   end
 
-  def on(event_type, options={}, &and_then)
-    and_then = and_then || options[:completion]
-    raise "event handler is required" unless and_then
-    raise "event handler must accept one or two arguments" unless and_then.arity == 1 || and_then.arity == 2
-
-    event_type = Firebase._convert_event_type(event_type)
-    disconnect_block = options[:disconnect]
-    raise ":disconnect handler must not accept any arguments" if disconnect_block && disconnect_block.arity > 0
-
-    if and_then.arity == 1
-      if disconnect_block
-        observeEventType(event_type, withBlock:and_then, withCancelBlock:disconnect_block)
-      else
-        observeEventType(event_type, withBlock:and_then)
-      end
-    else
-      if disconnect_block
-        observeEventType(event_type, andPreviousSiblingNameWithBlock:and_then, withCancelBlock:disconnect_block)
-      else
-        observeEventType(event_type, andPreviousSiblingNameWithBlock:and_then)
-      end
-    end
-  end
-
-  def once(event_type, options={}, &and_then)
-    and_then = and_then || options[:completion]
-    raise "event handler is required" unless and_then
-    raise "event handler must accept one or two arguments" unless and_then.arity == 1 || and_then.arity == 2
-
-    event_type = Firebase._convert_event_type(event_type)
-    disconnect_block = options[:disconnect]
-    raise ":disconnect handler must not accept any arguments" if disconnect_block && disconnect_block.arity > 0
-
-    if and_then.arity == 1
-      if disconnect_block
-        observeSingleEventOfType(event_type, withBlock:and_then, withCancelBlock:disconnect_block)
-      else
-        observeSingleEventOfType(event_type, withBlock:and_then)
-      end
-    else
-      if disconnect_block
-        observeSingleEventOfType(event_type, andPreviousSiblingNameWithBlock:and_then, withCancelBlock:disconnect_block)
-      else
-        observeSingleEventOfType(event_type, andPreviousSiblingNameWithBlock:and_then)
-      end
-    end
-  end
-
-  def off(handle=nil)
-    if handle
-      removeObserverWithHandle(handle)
-    else
-      removeAllObservers
-    end
-    return self
-  end
-
   def cancel_disconnect(&and_then)
     if and_then
       cancelDisconnectOperationsWithCompletionBlock(and_then)
@@ -220,23 +181,4 @@ class Firebase
     "#<#{self.class}:0x#{self.object_id.to_s(16)}>"
   end
 
-private
-  def self._convert_event_type(event_type)
-    case event_type
-    when :child_added, :added
-      return FEventTypeChildAdded
-    when :child_moved, :moved
-      FEventTypeChildMoved
-    when :child_changed, :changed
-      return FEventTypeChildChanged
-    when :child_removed, :removed
-      return FEventTypeChildRemoved
-    when :value
-      return FEventTypeValue
-    else
-      NSLog("Unknown event type #{event_type.inspect}")
-    end
-    return event_type
-  end
-
 end

data/lib/firebase/fquery.rb

@@ -0,0 +1,76 @@
+class FQuery
+
+  def on(event_type, options={}, &and_then)
+    and_then = and_then || options[:completion]
+    raise "event handler is required" unless and_then
+    raise "event handler must accept one or two arguments" unless and_then.arity == 1 || and_then.arity == 2
+
+    event_type = Firebase.convert_event_type(event_type)
+    disconnect_block = options[:disconnect]
+    raise ":disconnect handler must not accept any arguments" if disconnect_block && disconnect_block.arity > 0
+
+    if and_then.arity == 1
+      if disconnect_block
+        return observeEventType(event_type, withBlock:and_then, withCancelBlock:disconnect_block)
+      else
+        return observeEventType(event_type, withBlock:and_then)
+      end
+    else
+      if disconnect_block
+        return observeEventType(event_type, andPreviousSiblingNameWithBlock:and_then, withCancelBlock:disconnect_block)
+      else
+        return observeEventType(event_type, andPreviousSiblingNameWithBlock:and_then)
+      end
+    end
+  end
+
+  def once(event_type, options={}, &and_then)
+    and_then = and_then || options[:completion]
+    raise "event handler is required" unless and_then
+    raise "event handler must accept one or two arguments" unless and_then.arity == 1 || and_then.arity == 2
+
+    event_type = Firebase.convert_event_type(event_type)
+    disconnect_block = options[:disconnect]
+    raise ":disconnect handler must not accept any arguments" if disconnect_block && disconnect_block.arity > 0
+
+    if and_then.arity == 1
+      if disconnect_block
+        return observeSingleEventOfType(event_type, withBlock:and_then, withCancelBlock:disconnect_block)
+      else
+        return observeSingleEventOfType(event_type, withBlock:and_then)
+      end
+    else
+      if disconnect_block
+        return observeSingleEventOfType(event_type, andPreviousSiblingNameWithBlock:and_then, withCancelBlock:disconnect_block)
+      else
+        return observeSingleEventOfType(event_type, andPreviousSiblingNameWithBlock:and_then)
+      end
+    end
+  end
+
+  def off(handle=nil)
+    if handle
+      removeObserverWithHandle(handle)
+    else
+      removeAllObservers
+    end
+    return self
+  end
+
+  def start_at(priority)
+    queryStartingAtPriority(priority)
+  end
+
+  def start_at(priority, child:child)
+    queryStartingAtPriority(priority, andChildName:child)
+  end
+
+  def end_at(priority)
+    queryEndingAtPriority(priority)
+  end
+
+  def end_at(priority, child:child)
+    queryEndingAtPriority(priority, andChildName:child)
+  end
+
+end

data/lib/firebase/version.rb

@@ -1,5 +1,5 @@
 module Motion
   module Firebase
-    Version = '1.0.5'
+    Version = '1.0.6'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: motion-firebase
 version: !ruby/object:Gem::Version
-  version: 1.0.5
+  version: 1.0.6
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-17 00:00:00.000000000 Z
+date: 2013-04-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -45,6 +45,7 @@ files:
 - app/app_delegate.rb
 - lib/firebase/firebase.rb
 - lib/firebase/firebase_auth_client.rb
+- lib/firebase/fquery.rb
 - lib/firebase/version.rb
 - lib/motion-firebase-auth.rb
 - lib/motion-firebase-facebook.rb