motion-settings 0.0.1

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+.DS_STORE

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in motion-settings.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Jonathan Silverman
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,142 @@
+RubyMotion-UserSettings
+===================
+
+An extension to allow RubyMotion apps easy access to reading, writing, and persisting user settings and other objects on iOS via NSUserDefaults.
+
+Installation
+------------
+
+Copy the `rmsettable.rb` and `rmsettings.rb` into your `/app` directory. As there isn't yet a convention for where to put these sorts of files, I'd recommend adding a `/app/lib/rm_settings` directory.
+
+    /project
+      /app
+        /lib
+          /rm_settings
+             rmsettable.rb
+             rmsettings.rb
+
+Setup
+-----
+
+Given the way RubyMotion compiles files, you will probably need to add the RMSettings files to your `Rakefile` files_dependencies options.
+
+```ruby
+Motion::Project::App.setup do |app|
+  app.files_dependencies  'app/app_delegate.rb' => 'app/lib/rm_settings/rmsettable.rb',
+                          'app/lib/rm_settings/rmsettable.rb' => 'app/lib/rm_settings/rmsettings.rb'
+
+  ...
+```
+
+Usage
+-----
+
+### Initializing
+
+To begin, include `RMSettable` inside the `AppDelegate` class of `/app/app_delegate.rb` and call the `rm_settable` function with your other `didFinishLaunchingWithOptions` code.
+
+```ruby
+class AppDelegate
+  include RMSettable
+
+  def application(application, didFinishLaunchingWithOptions:launchOptions)
+    rm_settable :name, :background_color
+
+  ...
+```
+
+In its simplest form, the `rm_settable` function is called with a list of symbols for the settings your app will save to the NSUserDefaults.
+
+```ruby
+  rm_settable :name, :background_color
+```
+
+By default, the settings are stored as objects. If you wish to cast as a specific type, you may declare that as a hash on the key.
+
+```ruby
+  rm_settable :name, age: {type: :integer}, completed_tutorial: {type: :boolean}
+```
+
+The types available derive from the NSUserDefault class.  They can be :array, :boolean, :data, :dictionary, :double, :float, :integer, :object, :string_array, :string, or :url.
+
+### Options
+
+Additionally, you can include a hash of options to affect the way RMSettings works.
+
+```ruby
+  rm_settable age:, name: {type: :string}, options: {autosave: false, default_type: :integer}
+```
+
+```ruby
+  rm_settable options: {lenient_keys: true}
+```
+
+#### Available Options
+*   `autosave` _(true)_
+
+    By default, settings are synchronized to the device as soon as
+    it is updated. However, if you are updating a lot of items at once
+    or would prefer to manually call save on the settings object, set
+    this to false. Be aware that iOS will still save the settings
+    periodically without being explicitly called.
+
+    Regardless of this setting, settings will also be saved when
+    `applicationDidEnterBackground` or `applicationWillTerminate` is called
+    on the app.  To prevent this behaviour, you must override these methods
+    in your `app_delegate.rb`.
+
+*   `default_type` _(:object)_
+
+    Items are saved as objects. You many also specify a particular
+    type when you declare the setting names. With this setting you
+    may override the default type for all settings.
+
+*   `lenient_keys` _(false)_
+
+    If you don't want to declare any or all of the settings you will
+    be storing, set this to true. Any setting not explicitly declared
+    will still be stored and retrieved as the default setting type.
+
+### Reading and Writing User Settings
+
+A method named `settings` is added to the application's delegate and supplies a simple interface to the user settings.
+
+```ruby
+  # write a setting
+  UIApplication.sharedApplication.delegate.settings.name         = 'Karl Pilkington'
+  UIApplication.sharedApplication.delegate.settings[:head_shape] = 'Orange'
+
+  # read a setting
+  @name       = UIApplication.sharedApplication.delegate.settings.name
+  @head_shape = UIApplication.sharedApplication.delegate.settings[:head_shape]
+
+  # check a setting's boolean value or blankness
+  UIApplication.sharedApplication.delegate.settings.name?
+
+  # reset a setting to its default (also aliased as 'reset' or 'remove')
+  UIApplication.sharedApplication.delegate.settings.delete :name
+```
+
+Extras
+------
+
+Convenience subclasses are provided for `UIViewController` and `UIView` called `RMViewController` and `RMView`. If you derive your views and controllers form these classes you will have even easier access to the application's settings.
+
+```ruby
+class MyCoolView < RMView
+
+  def headClassifier
+    if !settings.head_shape? and settings.username =~ /karl\spilkington/i
+      settings.head_shape = 'Orange'
+    end
+  end
+  ...
+```
+
+To Do
+-----
+* Add tests
+* Add error reporting
+* Check that passed data types are valid
+* Add support for setting default value at declaration
+

data/Rakefile

@@ -0,0 +1,2 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"

data/lib/motion-settings.rb

@@ -0,0 +1,8 @@
+require "motion-settings/version"
+
+Motion::Project::App.setup do |app|
+    app.development do
+        app.files << File.expand_path(File.dirname(__FILE__) + '/motion-settings/rmsettable.rb')
+        app.files << File.expand_path(File.dirname(__FILE__) + '/motion-settings/rmsettings.rb')
+    end
+end

data/lib/motion-settings/rmsettable.rb

@@ -0,0 +1,97 @@
+# rmsettable.rb
+# https://github.com/AaronH/RubyMotion-UserSettings
+
+module RMSettable
+
+  def rm_settable(*args)
+    # Call this in your app_delegate.rb as part of the didFinishLaunchingWithOptions setup.
+    #
+    # The arguments can consist of symbols for various settings you wish to store.
+    #
+    #    rm_settable :name, :background_color
+    #
+    #
+    # By default, the keys store and retrieve generic objects. If you wish to specify a
+    # particular type, you may declare that as a hash on the key.
+    #
+    #    rm_settable :name, age: {type: :integer}, superstar: {type: :boolean}
+    #
+    # AVAILABLE TYPES :array, :boolean, :data, :dictionary, :double, :float,
+    #                 :integer, :object, :string_array, :string, :url
+    #
+    #
+    # You can also include a hash of options.
+    #
+    #    rm_settable name: {type: :string}, age: options: {autosave: false, default_type: :integer}
+    #
+    #    rm_settable options: {:lenient_keys}
+    #
+    # AVAILBLE OPTIONS
+    #        :autosave  true (default)
+    #                   By default, settings are synchronized to the device as soon as
+    #                   it is updated. However, if you are updating a lot of items at once
+    #                   or would prefer to manually call save on the settings object, set
+    #                   this to false. Be aware that iOS will still save the settings
+    #                   periodically without being explicitly called.
+    #
+    #    :default_type  :object (default)
+    #                   Items are saved as objects. You many specify the type
+    #                   when you declare the setting names or override the default
+    #                   expected for all item.
+    #
+    #    :lenient_keys  false (default)
+    #                   If you don't want to declare any or all of the settings you will
+    #                   be storing, set this to true. Any setting not explicitly declared
+    #                   will be stored and retrieved as the default setting type.
+    #
+    @rm_settings = RMSettings.new args
+  end
+
+
+  def applicationDidEnterBackground(application)
+    # make sure we save any unsaved settings when going to the background
+    # if you override this method in the app_delegate
+    # be sure to call super to save any unsaved settings
+    rm_settings.save
+  end
+
+  def applicationWillTerminate(application)
+    # make sure we save any unsaved settings when being terminated
+    # if you override this method in the app_delegate
+    # be sure to call super to save any unsaved settings
+    rm_settings.save
+  end
+
+  def settings
+    # provide access to the RMSettings object to the app_delegate
+    rm_settings
+  end
+
+  def self.included(base)
+    base.class_eval do
+      attr_accessor :rm_settings
+    end
+  end
+end
+
+# These subclasses provide easy access to the app_delegate and settings object.
+# If you wish to call settings directly from your controller or view, be sure
+# to inherit from these classes
+class RMView < UIView
+  def settings
+    application.settings
+  end
+
+  def application
+    UIApplication.sharedApplication.delegate
+  end
+end
+
+class RMViewController < UIViewController
+  def settings
+    application.settings
+  end
+  def application
+    UIApplication.sharedApplication.delegate
+  end
+end

data/lib/motion-settings/rmsettings.rb

@@ -0,0 +1,182 @@
+# rmsettings.rb
+# https://github.com/AaronH/RubyMotion-UserSettings
+
+class RMSettings
+  attr_accessor :settings, :available, :keys, :options
+
+  def initialize(*args)
+    # Initializes the available settings and options
+    # See rmsettable.rb for details on the various options
+    args = args.flatten.compact.uniq
+    @available  = {}
+    @settings ||= NSUserDefaults.standardUserDefaults
+
+    user_options = (args.select{|a| a.is_a? Hash}.first || {}).delete(:options) || {}
+    @options  = { autosave:     true,
+                  lenient_keys: false,
+                  default_type: :object}.merge(user_options)
+
+    args.flatten.each do |item|
+      if item.is_a?(Symbol)
+        @available[item] = {type: @options[:default_type]}
+      elsif item.is_a?(Hash)
+        item.each do |key, value|
+          @available[key] = value
+        end
+      end
+    end
+    @keys = @available.keys
+  end
+
+  def save
+    # Save all current settings to the device.
+    # Can be called manually but is generally called automatically
+    # after updating a key unless the :autosave option is false.
+    settings.synchronize
+  end
+
+  def autosave
+    # Automatically saves the data unless autosave is false.
+    save if autosave?
+  end
+
+  def autosave?
+    # Check to see if the autosave option is selected
+    options[:autosave]
+  end
+
+  def default_type_for(key)
+    # Determine the appropriate type for reading and writing item
+    ((@available[key] || {})[:type] || @options[:default_type])
+  end
+
+  def setting_for?(key)
+    # Call to check boolean status of a particular key.
+    # Generally called dynamically from the method_missing function.
+    #
+    #    settings.setting_for? :tutorial_completed
+    #
+    #    settings.tutorial_completed?
+    #
+    value = setting_for(key)
+    case default_type_for(key)
+    when :string, :array
+      value.empty?
+    else
+      !!value
+    end
+  end
+
+  def save_setting(key, value)
+    # Save the contents of value to the key.
+    # Returns the value of the key after setting.
+    #
+    # Generally called dynamically from the method_missing function.
+    #
+    #    settings.save_setting :name, 'Karl Pilkington'
+    #
+    #    settings.head_shape = 'Orange'
+    #
+    case default_type_for(key)
+    when :boolean
+      settings.setBool    value, forKey: key
+    when :double
+      settings.setDouble  value, forKey: key
+    when :float
+      settings.setFloat   value, forKey: key
+    when :integer
+      settings.setInteger value, forKey: key
+    when :object
+      settings.setObject  value, forKey: key
+    when :url
+      settings.setURL     value, forKey: key
+    else
+      settings.setObject  value, forKey: key
+    end
+
+    autosave
+
+    # return the current value
+    setting_for key
+  end
+  alias :[]= :save_setting
+
+  def setting_for(key)
+    # Read the contents of a given key.
+    #
+    # Generally called dynamically from the method_missing function.
+    #
+    #    settings.setting_for :nickname
+    #
+    #    settings.nickname
+    #
+    case default_type_for(key)
+    when :array
+      settings.arrayForKey      key
+    when :boolean
+      settings.boolForKey       key
+    when :data
+      settings.dataForKey       key
+    when :dictionary
+      settings.dictionaryForKey key
+    when :double
+      settings.doubleForKey     key
+    when :float
+      settings.floatForKey      key
+    when :integer
+      settings.integerForKey    key
+    when :object
+      settings.objectForKey     key
+    when :string_array
+      settings.stringArrayForKey key
+    when :string
+      settings.stringForKey     key
+    when :url
+      settings.URLForKey        key
+    end
+  end
+  alias :[] :setting_for
+
+  def remove(key)
+    # Resets the key to it's default value and returns that value
+    # Aliased as delete and reset
+    settings.removeObjectForKey key
+    autosave
+    setting_for key
+  end
+  alias :delete :remove
+  alias :reset  :remove
+
+  def valid_key?(key)
+    # Checks to see if the method_missing key has been declared
+    # unless that functionality has been turned off in the settings
+    @options[:lenient_keys] or keys.include?(key)
+  end
+
+  def method_missing(method, *args)
+    # Split the method to componenet parts to do our magic.
+    if m = method.to_s.match(/^([^\?\=]+)([\?\=])?$/)
+      base_key        = m[1].to_sym
+      method_modifier = m[2]
+      # Check if we want to do something here.
+      if valid_key?(base_key)
+        return  case method_modifier
+                when nil
+                  # Call the reader
+                  setting_for(base_key)
+                when '='
+                  # Call the writer
+                  save_setting(base_key, [*args].flatten.first)
+                when '?'
+                  # Call the boolean check
+                  setting_for?(base_key)
+                else
+                  # Nothing to do, so let's fail
+                  super
+                end
+      end
+    end
+    super
+  end
+
+end

data/lib/motion-settings/version.rb

@@ -0,0 +1,5 @@
+module Motion
+  module Settings
+    VERSION = "0.0.1"
+  end
+end

data/motion-settings.gemspec

@@ -0,0 +1,17 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/motion-settings/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Jonathan Silverman"]
+  gem.email         = ["jsilver@mdx.la"]
+  gem.description   = %q{A convenience wrapper to allow RubyMotion apps easy access to reading, writing, and persisting values via NSUserDefaults.}
+  gem.summary       = %q{RubyMotion Settings Library}
+  gem.homepage      = "https://github.com/jsilverMDX/RubyMotion-UserSettings"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "motion-settings"
+  gem.require_paths = ["lib"]
+  gem.version       = Motion::Settings::VERSION
+end

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: motion-settings
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Jonathan Silverman
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-07-08 00:00:00.000000000 Z
+dependencies: []
+description: A convenience wrapper to allow RubyMotion apps easy access to reading,
+  writing, and persisting values via NSUserDefaults.
+email:
+- jsilver@mdx.la
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/motion-settings.rb
+- lib/motion-settings/rmsettable.rb
+- lib/motion-settings/rmsettings.rb
+- lib/motion-settings/version.rb
+- motion-settings.gemspec
+homepage: https://github.com/jsilverMDX/RubyMotion-UserSettings
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: RubyMotion Settings Library
+test_files: []