mobility 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: aac3bb5bf5117b879aeeeea717cfd40bca0bbf55
-  data.tar.gz: 8348b8cd48048d74457084c434488abdb5ffc73f
+  metadata.gz: c1cb9733fa29691f2e0097d9e500081919e132a0
+  data.tar.gz: e3a4a9ad74165350fd1cd331f2a794e1b2402c1b
 SHA512:
-  metadata.gz: d7f75384116e3af82a6f6d6424a0bed7532fef85868939c050abe295495adbfb9addf118c47bde7087b30942c2edf201263bed57c7ecb38ab42b1e52a6275d95
-  data.tar.gz: de8f613e3047477e9ee5d2de368bb71cbb1d3a9101404f810d765f430dedd8db626b77403e46fba047ec1573e7eb751a45f4763bbf4fe5782c802d8b881fbbad
+  metadata.gz: 8968a7a6c8b73f8c9e588050c1d07fe5fc6145fff554d419ee1bfb5c1e284c3587ea221a7cb31bcddc6976e6bafea5a8f19738a6d6fd4e768720a49cf5f7aa90
+  data.tar.gz: efdd9d229d550a3fd09358e42e372aadb0f7df9e0372ca8e79f53996a33d55a13b866ec9c8dfd143f19d5ad078c2ab64d7353df8ac69b95113ee550d804d81f2

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Mobility Changelog
 
-## 0.1.2
+## 0.1
 
-* Fix issues with querying in ActiveRecord jsonb and hstore backends (758608294076249f1a66553c55531fc7897a71e3 and 5e6addd6f01cf255f5e71666324502ace96d3eac)
+### 0.1.3
+
+* Add homepage to gemspec
+* Pass backend class as context to `translates`
+  ([adf93e3c6bb314b73fbd43b221819310a1407c4d](https://github.com/shioyama/mobility/commit/adf93e3c6bb314b73fbd43b221819310a1407c4d))
+
+### 0.1.2
+
+* Fix issues with querying in ActiveRecord jsonb and hstore backends
+  ([527908d9317daee6bf91e3e1a188fb64365f7bab](https://github.com/shioyama/mobility/commit/527908d9317daee6bf91e3e1a188fb64365f7bab)
+  and
+  [5e6addd6f01cf255f5e71666324502ace96d3eac](https://github.com/shioyama/mobility/commit/5e6addd6f01cf255f5e71666324502ace96d3eac))

data/Gemfile.lock

@@ -1,42 +1,43 @@
 PATH
   remote: .
   specs:
-    mobility (0.1.1)
+    mobility (0.1.2)
       i18n (>= 0.6.10)
       request_store (~> 1.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    actionpack (5.0.1)
-      actionview (= 5.0.1)
-      activesupport (= 5.0.1)
-      rack (~> 2.0)
-      rack-test (~> 0.6.3)
-      rails-dom-testing (~> 2.0)
+    actionpack (4.2.7.1)
+      actionview (= 4.2.7.1)
+      activesupport (= 4.2.7.1)
+      rack (~> 1.6)
+      rack-test (~> 0.6.2)
+      rails-dom-testing (~> 1.0, >= 1.0.5)
       rails-html-sanitizer (~> 1.0, >= 1.0.2)
-    actionview (5.0.1)
-      activesupport (= 5.0.1)
+    actionview (4.2.7.1)
+      activesupport (= 4.2.7.1)
       builder (~> 3.1)
       erubis (~> 2.7.0)
-      rails-dom-testing (~> 2.0)
+      rails-dom-testing (~> 1.0, >= 1.0.5)
       rails-html-sanitizer (~> 1.0, >= 1.0.2)
-    activemodel (5.0.1)
-      activesupport (= 5.0.1)
-    activerecord (5.0.1)
-      activemodel (= 5.0.1)
-      activesupport (= 5.0.1)
-      arel (~> 7.0)
-    activesupport (5.0.1)
-      concurrent-ruby (~> 1.0, >= 1.0.2)
+    activemodel (4.2.7.1)
+      activesupport (= 4.2.7.1)
+      builder (~> 3.1)
+    activerecord (4.2.7.1)
+      activemodel (= 4.2.7.1)
+      activesupport (= 4.2.7.1)
+      arel (~> 6.0)
+    activesupport (4.2.7.1)
       i18n (~> 0.7)
+      json (~> 1.7, >= 1.7.7)
       minitest (~> 5.1)
+      thread_safe (~> 0.3, >= 0.3.4)
       tzinfo (~> 1.1)
-    arel (7.1.4)
+    arel (6.0.4)
     builder (3.2.3)
     byebug (9.0.6)
     coderay (1.1.1)
-    concurrent-ruby (1.0.4)
     database_cleaner (1.5.3)
     diff-lcs (1.3)
     erubis (2.7.0)
@@ -60,6 +61,7 @@ GEM
       guard-compat (~> 1.1)
       rspec (>= 2.99.0, < 4.0)
     i18n (0.7.0)
+    json (1.8.6)
     listen (3.1.5)
       rb-fsevent (~> 0.9, >= 0.9.4)
       rb-inotify (~> 0.9, >= 0.9.7)
@@ -72,7 +74,7 @@ GEM
     minitest (5.10.1)
     mysql2 (0.3.21)
     nenv (0.3.0)
-    nokogiri (1.7.0.1)
+    nokogiri (1.6.8.1)
       mini_portile2 (~> 2.1.0)
     notiffany (0.1.1)
       nenv (~> 0.1)
@@ -85,18 +87,20 @@ GEM
     pry-byebug (3.4.2)
       byebug (~> 9.0)
       pry (~> 0.10)
-    rack (2.0.1)
+    rack (1.6.5)
     rack-test (0.6.3)
       rack (>= 1.0)
-    rails-dom-testing (2.0.2)
-      activesupport (>= 4.2.0, < 6.0)
-      nokogiri (~> 1.6)
+    rails-deprecated_sanitizer (1.0.3)
+      activesupport (>= 4.2.0.alpha)
+    rails-dom-testing (1.0.7)
+      activesupport (>= 4.2.0.beta, < 5.0)
+      nokogiri (~> 1.6.0)
+      rails-deprecated_sanitizer (>= 1.0.1)
     rails-html-sanitizer (1.0.3)
       loofah (~> 2.0)
-    railties (5.0.1)
-      actionpack (= 5.0.1)
-      activesupport (= 5.0.1)
-      method_source
+    railties (4.2.7.1)
+      actionpack (= 4.2.7.1)
+      activesupport (= 4.2.7.1)
       rake (>= 0.8.7)
       thor (>= 0.18.1, < 2.0)
     rake (10.5.0)
@@ -134,7 +138,7 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
-  activerecord (>= 5.0, < 5.1)
+  activerecord (>= 4.2.6, < 5.0)
   bundler (~> 1.12)
   database_cleaner (~> 1.5.3)
   generator_spec (~> 0.9.3)

data/README.md

@@ -1,6 +1,14 @@
+[gem]: https://rubygems.org/gems/mobility
+[travis]: https://travis-ci.org/shioyama/mobility
+[gemnasium]: https://gemnasium.com/shioyama/mobility
+[codeclimate]: https://codeclimate.com/github/shioyama/mobility
+
 # Mobility
-![Build Status](https://travis-ci.org/shioyama/mobility.svg?branch=master)
 
+[![Gem Version](https://badge.fury.io/rb/mobility.svg)][gem]
+[![Build Status](https://travis-ci.org/shioyama/mobility.svg?branch=master)][travis]
+[![Dependency Status](https://gemnasium.com/shioyama/mobility.svg)][gemnasium]
+[![Code Climate](https://codeclimate.com/github/shioyama/mobility/badges/gpa.svg)][codeclimate]
 
 Mobility is a gem for storing and retrieving localized data through attributes
 on a class. A variety of different storage strategies are supported through
@@ -39,18 +47,23 @@ features, including:
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'mobility', '~> 0.1.0'
+gem 'mobility', '~> 0.1.3'
 ```
 
 To translate attributes on a model, you must include (or extend) `Mobility`,
-then call `translates` specifying the backend to use and any backend-specific
-options.
+then call `translates` passing in one or more attributes as well as a hash of
+options, including the backend to use. (See [Defining Backend
+Attributes](#attributes) below.)
 
 ### ActiveRecord (Rails)
 
 Requirements:
 - ActiveRecord >= 5.0
 
+(Support for some backends is also supported with ActiveRecord/Rails 4.2, see
+the [active_record-4.2
+branch](https://github.com/shioyama/mobility/tree/active_record_4.2).)
+
 If using Mobility in a Rails project, you can run the generator to create an
 initializer and (optionally) a migration to create shared tables for the
 default key-value backend:
@@ -74,25 +87,36 @@ Mobility.config.default_backend = :key_value
 ```
 
 To set a different default backend, set `default_backend` to another value (see
-possibilities below). Other configuration options can be set using the
+possibilities [below](#backend)). Other configuration options can be set using the
 `configure` method, see: {Mobility::Configuration} for details.
 
-The default key-value backend, which stores attributes and their translations
-as key/value pairs on shared tables, can be included in a model with the
-following two lines:
+To get started quickly, run the generator with tables, and add the following to
+a class to add translated attributes:
 
 ```ruby
 class Post < ActiveRecord::Base
-  include Mobility
-  translates :title, :author, backend: :key_value, type: :string
-  translates :content,        backend: :key_value, type: :text
+  translates :title,   type: :string
+  translates :content, type: :content
 end
 ```
 
-You can now store translations of `title`, `author` and `content` on shared
-translation tables (a string-valued translation table for the first two, and a
-text-valued translation table for the last one). For more information on
-backends, see [Choosing a Backend](#backend).
+You now have translated attributes `title` and `content` on the model:
+
+```ruby
+I18n.locale = :en
+post = Post.create(title: "foo")
+post.title                         #=> "Mobility"
+I18n.locale = :ja
+post.title                         #=> nil
+post.title = "モビリティ"
+post.save
+post.title                         #=> "モビリティ"
+I18n.locale = :en
+post.title                         #=> "Mobility"
+```
+
+Congratulations! Now have a look at the [Usage](#usage) section to see what
+else Mobility can do.
 
 ### Sequel
 
@@ -101,22 +125,65 @@ Requirements:
 
 Essentially identical to ActiveRecord, with the exception that there is no
 equivalent to a Rails generator (so you will need to create the migration for
-the translation table(s) yourself, see the API docs for details).
+any translation table(s) yourself, see the API docs for details).
 
-To include translations on a model, simply call `translates`:
+## Usage
+
+### <a name="attributes"></a>Defining Backend Attributes
+
+In order to use Mobility on a class, you will need to `extend` the {Mobility}
+module and call `translates`, passing in one or more attribute names as well as
+a hash of options.
+
+The options hash is used to generate the backend, and has several reserved keys:
+
+- **`backend`** (Symbol or Class)<br>
+  The backend to use (defaults to the value of `Mobility.default_backend`). If
+  its value is a symbol it will be converted to CamelCase and appended to the
+  `Mobility::Backend` module name to get the backend class (so `key_value` will
+  be converted to {Mobility::Backend::KeyValue}). See the list of [backends](#backend).
+- **`cache`** (Boolean)<br>
+  Whether to use a [cache](#cache).
+- **`fallbacks`** (Boolean or Hash)<br>
+  Enable [fallbacks](#fallbacks), and optionally configure them.
+- **`dirty`** (Boolean)<br>
+  Whether to enable [dirty tracking](#dirty).
+- **`accessor_locales`** (Boolean or Array)<br>
+  Enable [locale accessors](#locale_accessors) and optionally configure them.
+
+In addition to these, each backend may have specific configuration options. For
+example, the default key-value backend, which stores attributes and their
+translations as key/value pairs on shared tables, has a `type` option which
+specifies which type of column (string or text) to use for storing
+translations.
+
+Here is an example defining three attributes on an ActiveRecord model:
 
 ```ruby
-class Post < Sequel::Model
+class Post < ActiveRecord::Base
   include Mobility
-  translates :title, :author, backend: :key_value, type: :string
-  translates :content,        backend: :key_value, type: :text
+  translates :title, :author, backend: :key_value, type: :string, cache: false
+  translates :content,        backend: :key_value, type: :text, fallbacks: true
 end
 ```
 
-Note that Mobility will detect the parent class and use an ORM-specific
-backend, in this case the {Mobility::Backend::Sequel::KeyValue} backend.
+`title`, `author` and `content` will use the `KeyValue` backend, which stores
+translations on two shared translation tables (one for string-valued
+translations and one for text-valued translations). The cache (enabled by
+default) is disabled for `title` and `author` (but not `content`).
+[Fallbacks](#fallbacks) are enabled for `content` (but not `title` or
+`author`).
 
-## Usage
+Finally, `title` and `author` store their translations as string columns
+(`type: :string`) whereas `content` stores its values as text columns (`type:
+:text`). The `type` key is a backend-specific option used by the `KeyValue`
+backend.
+
+Note that Mobility will detect the model class and use this to determine which
+ORM-specific backend to use. In the example above, it will use
+{Mobility::Backend::ActiveRecord::KeyValue}; if the class were a
+`Sequel::Model`, it would have used {Mobility::Backend::Sequel::KeyValue}. In
+general options to configure the backend are ORM-independent.
 
 ### Setting the Locale
 
@@ -232,35 +299,34 @@ backend ([below](#backend)).
 
 Mobility supports six different (database) backends:
 
-- **{Mobility::Backend::Column}**<br>
+- **`:column`** ({Mobility::Backend::Column})<br>
   Store translations as columns on a table with locale as a postfix, of the
   form `title_en`, `title_fr`, etc. for an attribute `title`.
-- **{Mobility::Backend::Table}**<br>
+- **`:table`** ({Mobility::Backend::Table})<br>
   Store translations on a model-specific table, e.g. for a model `Post` with
   table `posts`, store translations on a table `post_translations`, and join
   the translation table when fetching translated values.
-- **{Mobility::Backend::KeyValue}**<br>
+- **`:key_value`** ({Mobility::Backend::KeyValue})<br>
   Store translations on a shared table of locale/attribute translation pairs,
   associated through a polymorphic relation with multiple models.
-- **{Mobility::Backend::Serialized}**<br>
+- **`:serialized`** ({Mobility::Backend::Serialized})<br>
   Store translations as serialized YAML or JSON on a text column.
-- **{Mobility::Backend::Hstore}**<br>
+- **`:hstore`** ({Mobility::Backend::Hstore})<br>
   Store translations as values of a hash stored as a PostgreSQL hstore column.
-- **{Mobility::Backend::Jsonb}**<br>
+- **`:jsonb`** ({Mobility::Backend::Jsonb})<br>
   Store translations as values of a hash stored as a PostgreSQL jsonb column.
 
 Each backend has strengths and weaknesses. If you're unsure of which backend to
 use, a rule of thumb would be:
 
-- If you're using PostgreSQL as your database, use {Mobility::Backend::Jsonb}.
+- If you're using PostgreSQL as your database, use `:jsonb`.
 - If you have a fixed, small set of locales that are not likely to increase,
-  and have a small number of models to translate, consider
-  {Mobility::Backend::Column}.
+  and have a small number of models to translate, consider `:column`.
 - If you have a small set of models to be translated but translation to
-  potentially many different languages, consider {Mobility::Backend::Table}.
+  potentially many different languages, consider `:table`.
 - For all other cases (many locales, many translated models), or if you're just
-  not sure, the recommended solution is {Mobility::Backend::KeyValue} for
-  maximum flexibility and minimum database migrations.
+  not sure, the recommended solution is `:key_value` for maximum flexibility
+  and minimum database migrations.
 
 
 ### <a name="locale-accessors"></a>Locale Accessors
@@ -501,7 +567,7 @@ To this end, Mobility backends strictly enforce the rule that *no backend
 should modify a parent class in any way which would interfere with other
 backends operating on the same class*. This is done using a heavy dose of
 metaprogramming, details of which can be found in the [API
-documentation](http://www.rubydoc.info/gems/mobility/0.1.1) and in the actual code.
+documentation](http://www.rubydoc.info/gems/mobility/0.1.3) and in the actual code.
 
 In practice, this means that you can use different backends for different
 attributes *on the same class* without any conflict, e.g. (assuming we
@@ -581,7 +647,7 @@ end
 
 For details on how to define a backend class, see the {Mobility::Backend}
 module and other classes defined in the [API
-documentation](http://www.rubydoc.info/gems/mobility/0.1.1).
+documentation](http://www.rubydoc.info/gems/mobility/0.1.3).
 
 ### Testing Backends
 
@@ -626,7 +692,7 @@ particular implementations.
 ## More Information
 
 - [Github repository](https://www.github.com/shioyama/mobility)
-- [API documentation](http://www.rubydoc.info/gems/mobility/0.1.1)
+- [API documentation](http://www.rubydoc.info/gems/mobility/0.1.3)
 
 ## License
 

data/lib/mobility/translates.rb

@@ -7,14 +7,14 @@ passed to accessors to configure backend (see example below).
 @example Defining backend on a class
   class MyClass
     extend Translates
-    mobility_accessor :foo, option1: :value
+    mobility_accessor :foo, option: :value
   end
 
 @example Passing backend to a block
   class MyClass
     extend Translates
-    mobility_accessor :foo, option1: :value do |backend|
-      # do something with backend
+    mobility_accessor :foo, option: :value do
+      # add custom code to backend class for this attribute only
     end
   end
 
@@ -44,25 +44,25 @@ passed to accessors to configure backend (see example below).
     # Defines mobility accessor on model class.
     # @param [Array<String>] attributes
     # @param [Hash] options
-    # @yield [Object] Backend
+    # @yield Yields to block with backend as context
     # @!method mobility_accessor(*attributes, **options)
 
     # Defines mobility reader and presence method on model class.
     # @param [Array<String>] attributes
     # @param [Hash] options
-    # @yield [Object] Backend
+    # @yield Yields to block with backend as context
     # @!method mobility_reader(*attributes, **options)
 
     # Defines mobility writer on model class.
     # @param [Array<String>] attributes
     # @param [Hash] options
-    # @yield [Object] Backend
+    # @yield Yields to block with backend as context
     # @!method mobility_writer(*attributes, **options)
     %w[accessor reader writer].each do |method|
       class_eval <<-EOM, __FILE__, __LINE__ + 1
-        def mobility_#{method}(*args, **options)
+        def mobility_#{method}(*args, **options, &block)
           attributes = Attributes.new(:#{method}, *args, options.merge(model_class: self))
-          yield(attributes.backend) if block_given?
+          attributes.backend.instance_eval &block if block_given?
           attributes.each do |attribute|
             alias_method "\#{attribute}_before_mobility",  attribute        if method_defined?(attribute)        && #{%w[accessor reader].include? method}
             alias_method "\#{attribute}_before_mobility=", "\#{attribute}=" if method_defined?("\#{attribute}=") && #{%w[accessor writer].include? method}

data/lib/mobility/version.rb

@@ -1,3 +1,3 @@
 module Mobility
-  VERSION = "0.1.2"
+  VERSION = "0.1.3"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mobility
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Chris Salzberg
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-02-23 00:00:00.000000000 Z
+date: 2017-02-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: request_store
@@ -213,7 +213,7 @@ files:
 - lib/mobility/translates.rb
 - lib/mobility/version.rb
 - lib/mobility/wrapper.rb
-homepage: 
+homepage: https://github.com/shioyama/mobility
 licenses:
 - MIT
 metadata: {}