opal-browser 0.1.0.beta1 → 0.2.0.beta1

data/opal/browser/interval.rb

@@ -1,15 +1,18 @@
 module Browser
 
-# This class wraps `setInterval`.
+# Allows you to create an interval that executes the function every given
+# seconds.
+#
+# @see https://developer.mozilla.org/en-US/docs/Web/API/Window.setInterval
 class Interval
   # @!attribute [r] every
-  # @return [Number] the seconds every which the block is called
+  # @return [Float] the seconds every which the block is called
   attr_reader :every
 
   # Create and start an interval.
   #
   # @param window [Window] the window to start the interval on
-  # @param time [Number] seconds every which to call the block
+  # @param time [Float] seconds every which to call the block
   def initialize(window, time, &block)
     @window = Native.convert(window)
     @every  = time
@@ -32,20 +35,14 @@ class Interval
   end
 
   # Abort the interval, it won't be possible to start it again.
-  #
-  # @return [self]
   def abort
     `#@window.clearInterval(#@id)`
 
     @aborted = true
     @id      = nil
-
-    self
   end
 
   # Stop the interval, it will be possible to start it again.
-  #
-  # @return [self]
   def stop
     `#@window.clearInterval(#@id)`
 
@@ -54,16 +51,12 @@ class Interval
   end
 
   # Start the interval if it has been stopped.
-  #
-  # @return [self]
   def start
     raise "the interval has been aborted" if aborted?
 
     return unless stopped?
 
     @id = `#@window.setInterval(#{@block.to_n}, #@every * 1000)`
-
-    self
   end
 end
 
@@ -71,6 +64,7 @@ class Window
   # Execute the block every given seconds.
   #
   # @param time [Float] the seconds between every call
+  #
   # @return [Interval] the object representing the interval
   def every(time, &block)
     Interval.new(@native, time, &block)
@@ -80,6 +74,7 @@ end
 end
 
 class Proc
+  # (see Browser::Window#every)
   def every(time)
     $window.every(time, &self)
   end

data/opal/browser/location.rb

@@ -1,5 +1,8 @@
 module Browser
 
+# Allows manipulation of a location, usually from {Window} and {DOM::Document}.
+#
+# @see https://developer.mozilla.org/en-US/docs/Web/API/Location
 class Location
   include Native
 
@@ -66,9 +69,16 @@ class Location
 end
 
 class Window
-  # Get the {Location} object for this window.
-  #
-  # @return [Location]
+  # @!attribute [r] location
+  # @return [Location] the location for the window
+  def location
+    Location.new(`#@native.location`) if `#@native.location`
+  end
+end
+
+class DOM::Document < DOM::Element
+  # @!attribute [r] location
+  # @return [Location] the location for the document
   def location
     Location.new(`#@native.location`) if `#@native.location`
   end

data/opal/browser/navigator.rb

@@ -1,6 +1,8 @@
 module Browser
 
-# Class that represents the browser attributes.
+# Representation of the navigator application.
+#
+# @see https://developer.mozilla.org/en-US/docs/Web/API/Navigator
 class Navigator
   include Native
 
@@ -8,7 +10,7 @@ class Navigator
   Product = Struct.new(:name, :version)
   Vendor  = Struct.new(:name, :version)
 
-  # Class that represents a MIME type.
+  # Representation of a MIME type.
   class MimeType
     include Native
 
@@ -33,7 +35,9 @@ class Navigator
     alias_native :type
   end
 
-  # Class to represent a browser plugin.
+  # Representation of a navigator plugin.
+  #
+  # @see https://developer.mozilla.org/en-US/docs/Web/API/Plugin
   class Plugin < Native::Array
     def initialize(plugin)
       super plugin do |m|
@@ -140,9 +144,8 @@ class Navigator
 end
 
 class Window
-  # Get the {Navigator} object for this window.
-  #
-  # @return [Navigator]
+  # @!attribute [r] navigator
+  # @return [Navigator] the navigator
   def navigator
     Navigator.new(`#@native.navigator`) if `#@native.navigator`
   end

data/opal/browser/screen.rb

@@ -1,5 +1,8 @@
 module Browser
 
+# Representation of the screen the window is being rendered on.
+#
+# @see https://developer.mozilla.org/en-US/docs/Web/API/Window.screen
 class Screen
   include Native
   include DOM::Event::Target
@@ -8,30 +11,53 @@ class Screen
     Screen.new(value) if Native.is_a?(value, `window.Screen`)
   }
 
+  Depth = Struct.new(:color, :pixel)
+
+  # @!attribute [r] width
+  # @return [Integer] the width of the screen in pixels
   alias_native :width
+
+  # @!attribute [r] height
+  # @return [Integer] the height of the screen in pixels
   alias_native :height
 
+  # @!attribute [r] size
+  # @return [Size] the size in pixels
   def size
     Size.new(width, height)
   end
 
+  # @!attribute [r] x
+  # @return [Integer] the offset from the top left corner of the screen in
+  #                   pixels
   alias_native :x, :top
+
+  # @!attribute [r] y
+  # @return [Integer] the offset from the top left corner of the screen in
+  #                   pixels
   alias_native :y, :left
 
+  # @!attribute [r] position
+  # @return [Position] the offset from the top left corner of the screen in
+  #                    pixels
   def position
     Position.new(x, y)
   end
 
-  alias_native :color_depth, :colorDepth
-  alias_native :pixel_depth, :pixelDepth
+  # @!attribute [r] depth
+  # @return [Depth] the screen depth
+  def depth
+    Depth.new(`#@native.colorDepth`, `#@native.pixelDepth`)
+  end
 
+  # @!attribute [r] orientation
+  # @return [String] the orientation of the screen
   alias_native :orientation
 end
 
 class Window
-  # Get the {Screen} for this window.
-  #
-  # @return [Screen]
+  # @!attribute [r] screen
+  # @return [Screen] the screen for the window
   def screen
     Screen.new(`#@native.screen`)
   end

data/opal/browser/socket.rb

@@ -1,9 +1,12 @@
 module Browser
 
-# This class wraps `WebSocket`.
+# A {Socket} allows the browser and a server to have a bidirectional data
+# connection.
+#
+# @see https://developer.mozilla.org/en-US/docs/Web/API/WebSocket
 class Socket
   def self.supported?
-    defined? `window.WebSocket`
+    Browser.supports? :WebSocket
   end
 
   include Native
@@ -18,8 +21,9 @@ class Socket
   #
   # @param url [String] the URL to connect to
   # @param protocol [String] the protocol to use
-  # @yield if the block has no parameters it's instance_exec'd, otherwise it's
-  #        called with self
+  #
+  # @yield if the block has no parameters it's `instance_exec`d, otherwise it's
+  #        called with `self`
   def initialize(url, protocol = nil, &block)
     if native?(url)
       super(url)

data/opal/browser/storage.rb

@@ -1,19 +1,24 @@
-#--
-#            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
-#                    Version 2, December 2004
-#
-#            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
-#   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
-#
-#  0. You just DO WHAT THE FUCK YOU WANT TO.
-#++
-
 require 'json'
 require 'stringio'
 
 module Browser
 
-class Storage < Hash
+# A {Storage} allows you to store data across page loads and browser
+# restarts.
+#
+# Compatibility
+# -------------
+# The compatibility layer will try various implementations in the following
+# order.
+#
+# + [window.localStorage](https://developer.mozilla.org/en-US/docs/Web/Guide/API/DOM/Storage#localStorage)
+# + [window.globalStorage](https://developer.mozilla.org/en-US/docs/Web/Guide/API/DOM/Storage#globalStorage)
+# + [document.body.addBehavior](http://msdn.microsoft.com/en-us/library/ms531424(VS.85).aspx)
+# + [document.cookie](https://developer.mozilla.org/en-US/docs/Web/API/document.cookie)
+#
+# @see https://developer.mozilla.org/en-US/docs/Web/Guide/API/DOM/Storage
+# @todo remove method_defined? checks when require order is fixed
+class Storage
   def self.json_create(data)
     data.delete(JSON.create_id)
 
@@ -22,47 +27,106 @@ class Storage < Hash
     }]
   end
 
+  include Enumerable
+
+  # @!attribute [r] name
+  # @return [String] the name of the storage
   attr_reader :name
 
+  # Create a new storage on the given window with the given name.
+  #
+  # @param window [native] the window to save the storage to
+  # @param name [String] the name to use to discern different storages
   def initialize(window, name)
     super()
 
     @window = window
     @name   = name
+    @data   = {}
 
     autosave!
-
-    init if respond_to? :init
+    init
   end
 
+  # @!attribute [r] encoded_name
+  # @return [String] the generated name
   def encoded_name
-    "$opal.storage.#{@name}"
+    "$opal.storage.#@name"
   end
 
-  def autosave?;    @autosave;         end
-  def autosave!;    @autosave = true;  end
-  def no_autosave!; @autosave = false; end
+  # Check if autosaving is enabled.
+  #
+  # When autosaving is enabled the {Storage} is saved every time a change is
+  # made, otherwise you'll have to save it manually yourself.
+  def autosave?
+    @autosave
+  end
+
+  # Enable autosaving.
+  def autosave!
+    @autosave = true
+  end
+
+  # Disable autosaving.
+  def no_autosave!
+    @autosave = false
+  end
+
+  # Iterate over the (key, value) pairs in the storage.
+  #
+  # @yield [key, value]
+  def each(&block)
+    return enum_for :each unless block
+
+    @data.each(&block)
+
+    self
+  end
 
-  def replace(what)
-    if what.is_a?(String)
-      super JSON.parse(what)
+  # Get a value in the storage.
+  def [](key)
+    @data[key]
+  end
+
+  # Set a value in the storage.
+  def []=(key, value)
+    @data[key] = value
+
+    save if autosave?
+  end
+
+  # Delete a value from the storage.
+  def delete(key)
+    @data.delete(key).tap {
+      save if autosave
+    }
+  end
+
+  # Clear the storage.
+  def clear
+    @data.clear.tap {
+      save if autosave?
+    }
+  end
+
+  # Replace the current storage with the given one.
+  #
+  # @param new [Hash, String] if new is a {String} it will be parsed as JSON
+  def replace(new)
+    if String === new
+      @data.replace(JSON.parse(new))
     else
-      super
+      @data.replace(new)
     end
   end
 
-  %w([]= delete clear).each {|name|
-    define_method name do |*args|
-      # FIXME: remove the application when it's fixed
-      super(*args).tap {
-        save if autosave?
-      }
-    end
-  }
+  # @!method init
+  #   @private
 
-  def save; end
+  # @!method save
+  #   Persist the current state to the storage.
 
-  if `window.localStorage`
+  if Browser.supports? 'Storage.local'
     def init
       replace `#@window.localStorage[#{encoded_name}] || '{}'`
     end
@@ -70,7 +134,7 @@ class Storage < Hash
     def save
       `#@window.localStorage[#{encoded_name}] = #{JSON.dump(self)}`
     end
-  elsif `window.globalStorage`
+  elsif Browser.supports? 'Storage.global'
     def init
       replace `#@window.globalStorage[#@window.location.hostname][#{encoded_name}] || '{}'`
     end
@@ -78,7 +142,7 @@ class Storage < Hash
     def save
       `#@window.globalStorage[#@window.location.hostname][#{encoded_name}] = #{JSON.dump(self)}`
     end
-  elsif `document.body.addBehavior`
+  elsif Browser.supports? 'Element.addBehavior'
     def init
       %x{
         #@element = #@window.document.createElement('link');
@@ -110,6 +174,9 @@ class Storage < Hash
     end
   end
 
+  # Convert the storage to JSON.
+  #
+  # @return [String] the JSON representation
   def to_json
     io = StringIO.new("{")
 
@@ -126,7 +193,15 @@ class Storage < Hash
   end
 end
 
+# A {SessionStorage} allows you to store data across page reloads, as long as the session
+# is active.
+#
+# @see https://developer.mozilla.org/en-US/docs/Web/Guide/API/DOM/Storage#sessionStorage
 class SessionStorage < Storage
+  def self.supported?
+    Browser.supports? 'Storage.session'
+  end
+
   def init
     replace `#@window.sessionStorage[#{encoded_name}] || '{}'`
   end
@@ -137,10 +212,20 @@ class SessionStorage < Storage
 end
 
 class Window
+  # Get a storage with the given name.
+  #
+  # @param name [Symbol] the name of the storage
+  #
+  # @return [Storage]
   def storage(name = :default)
     Storage.new(to_n, name)
   end
 
+  # Get a session storage with the given name.
+  #
+  # @param name [Symbol] the name of the storage
+  #
+  # @return [SessionStorage]
   def session_storage(name = :default)
     SessionStorage.new(to_n, name)
   end