PackingPeanut

Cross Platform App Persistence

Inspired by BubbleWrap's easy syntax for App Persistence - Now a CROSS PLATFORM App Persistence Gem for RubyMotion.

There is a sedulous effort to make this syntax fit BubbleWrap's as much as possible for easy replacement 😈

GITHUB HOMEPAGE

Installation

Step 1: Add this line to your application's Gemfile:

gem 'PackingPeanut'

Step 2: And then execute:

$ bundle

Step 3: IF on Android:

$ [bundle exec] rake gradle:install

Usage

It's as simple as:

App::Persistence[:foo] = true
# App::Persistence[:foo] would now return true

Whirlwind Tour via the REPL

# ONLY ANDROID REQUIRES CONTEXT!
# See the section on Android context for more info
$ App::Persistence.context = self
=> #<MainActivity:0x1d20058e>
$ App::Persistence['dinner'] = "nachos"
=> "nachos"
$ App::Persistence['dinner']
=> "nachos"
$ App::Persistence[:lunch] = "tacos"
=> "tacos" # Use symbols or strings as you please
$ App::Persistence.all
=> {"dinner"=>"nachos", "lunch"=>"tacos"}
$ App::Persistence.storage_file = "some_new_file"
=> "some_new_file"
$ App::Persistence['dinner']
=> nil  # empty because we're now outside the default storage file.

Friendly aliases:

# You can use PP instead of App::Persistence if you like
$ PP['some_boolean'] = true
# You can use PackingPeanut (true name) if you like
$ PackingPeanut['so_easy'] = true

Access deeper features:

# On Android you can set prefrence_modes for cross/app communication
$ App::Persistence.preference_mode = :world_readable
=> :world_readable

What are preference modes?

Preference Modes are Android Operating modes, used to control permission levels on the persistence file.

Memorizable symbols and their corresponding constants:

    PREFERENCE_MODES = {
      private: MODE_PRIVATE,
      readable: MODE_WORLD_READABLE,
      world_readable: MODE_WORLD_READABLE,
      writable: MODE_WORLD_WRITEABLE,
      world_writable: MODE_WORLD_WRITEABLE,
      multi: MODE_MULTI_PROCESS,
      multi_process: MODE_MULTI_PROCESS
    }

Use 0 or MODE_PRIVATE for the default operation, MODE_WORLD_READABLE and MODE_WORLD_WRITEABLE for more permissive modes. The bit MODE_MULTI_PROCESS can also be used if multiple processes are mutating the same SharedPreferences file. MODE_MULTI_PROCESS is always on in apps targeting Gingerbread (Android 2.3) and below, and off by default in later versions.

Dependencies

Adding Darin's moran gem allowed serialization of hashes for Android. This means motion-gradle is also necessary for complete Packing Peanut excellence on Android.

Tests?

• iOS: Yup!
• Android: Boy that would be nice wouldn't it?

PackingPeanut Alongside Bubblewrap on iOS?

It's meant to look just like BubbleWrap, not fight with it. If you include the BubbleWrap library, PackingPeanut will gracefully bow out of the App::Persistence namespace. You can still access PackingPeanut with PP or PackingPeanut.

Explain this Android context thing Again

Just like a conversation taken out of context can be confusing, Android has a lot of moving parts and requires just about EVERYTHING that would be a lib component to understand the context. When accessing persistent data, context is required. You can easily handle this by giving PackingPeanut your application context in your Application startup file.

PackingPeanut Context Examples:

# Providing Context - Regular
class MyApplication < Android::App::Application
  def onCreate
    PP.context = self
  end
end

# Providing Context with BluePotion
class MyApplication < PMApplication
  def on_create
    PP.context = self
  end
end

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Ponder life... for at least like... 5 minutes
6. Create new Pull Request