from_clause_translate 0.2.6 → 0.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 61a7a0b83c04d5cc4e15a088c9a56ad2388700bc1a6de3c477860501fdcfd16e
-  data.tar.gz: 1fd848f0dda4626997dc32742616117b4fcc3017219a30133d3c585ec0408a2a
+  metadata.gz: e2a0a04072d1c8cb05f90443fa05aa74ffceaced4a714761abe83940b36a694a
+  data.tar.gz: 9c01576a7a7dcb5124bf82a0b8d88c61d67126bcbf41dc9dabec1d3c2878f2c4
 SHA512:
-  metadata.gz: 85e5ab0a94cd12927ed91ac819d4c4775374dbb217cf23d4511d9c4f292ba11ff5470c1d444b01fff500c51c737dc52904ff0a60f3dac75cdb695dfab8779c45
-  data.tar.gz: 4e032681587d35263fbae5bdf3f70b06f51f10104c3495ffa311d0fef8ec195759825d2b36a239c4a04a609fa19966376a9a14fbfe9f7fe4d0b479a642bb7b3a
+  metadata.gz: 4ad0b659cd25294a584f9bf293f74fbda4006b1f71bea76ba0cdd0abc293a6177dd027dc204a13173d8a4ca361b34c665f392e49fa59617828142f6731c6114c
+  data.tar.gz: 8437b273f89e0780289287f26cef363a56ffab850c2133226a49a73ca2c45597f38aaf8e982cbb175988d6f4872b9f8291e0d4442d4c0c3cb00203770a46ad81

data/README.md

@@ -1,8 +1,155 @@
 # FromClauseTranslate
-Short description and motivation.
+This gem extends ActiveRecord models for easy manipulations with multilanguage data. 
+
+The name of gem stands for way that it is doing its magic - SQL's `FROM` statement.
+
+The main idea is that you can have database columns `name_en`, `name_ru`, `name_fr` and you will still able to filter data with `WHERE name LIKE '%some name%'`, all `SQL` statements will be working with just `name` column.
+
+It allows making of complex `SQL` queries without need of interpolation of `I18n.locale` and without joining separate translation tables.
+
+## Requirements
+
+Activerecord.
+
+Postgresql, other databases were not tested.
 
 ## Usage
-How to use my plugin.
+Lets have translatable model `Post`:
+
+```ruby
+class CreatePosts < ActiveRecord::Migration[5.2]
+  def change
+    create_table :posts do |t|
+      %i[en ru uk de fr it es].each do |locale|
+        t.string "slug_#{locale}"
+        t.string "name_#{locale}"
+        t.string "title_#{locale}"
+        t.string "text_#{locale}"
+        t.boolean "translated_#{locale}", null: false, default: false
+      end
+    end
+  end
+end
+```
+
+In migration array of locales should be hardcoded, because when new language will be added in future, this migration will still be reversable.
+
+Then this `FromClauseTranslate` should be included in `AplicationRecord` or in the required model:
+
+```ruby
+class ApplicationRecord < ActiveRecord::Base
+  include FromClauseTranslate
+
+  self.abstract_class = true
+end
+```
+
+Make columns in the model translatable:
+
+```ruby
+class Post < ApplicationRecord
+  translates :name, :title, :text, :slug, :translated, plurals: %i[slugs translateds]
+end
+```
+
+About plurals will be down below, now this model supports getting and setting values:
+
+```ruby
+post = Post.new(name: 'Name for current locale')
+post.name == 'Name for current locale' # true
+post.name = 'New name'
+post.name_fr = 'French name of post' # real columns are still accessible
+```
+
+Such ActiveRecord column methods are supported (star for column name):
+`save_change_to_*`, `*_changed?`, `*_before_last_save`, `*_change_to_be_saved`, `*_in_database`, `saved_change_to_*?`, `will_save_change_to_*?`
+
+## Querying
+
+Following code will get posts just like they are in DB, with all of `name_en`, `title_de` columns:
+
+```ruby
+post = Post.take
+posts = Post.all
+```
+
+For receiving columns for current locale use `.translated` method with the list of required columns:
+
+```ruby
+post = Post.translated(:title, :name, :text)
+```
+
+It accepts symbols and `SQL` strings that will go to `SELECT` statement.
+
+After invoking `.translated` passed columns becomes available in querying methods:
+```ruby
+Post.translated(:title, :name)
+  .where(title: 'smth')
+  .where("name ILIKE '%name%'")
+  .order('title DESC, name ASC')
+```
+
+## Fallbacks
+
+Set up `I18n.fallbacks` in `application.rb`:
+
+```ruby
+I18n.fallbacks = {uk: [:ru, :en]}
+```
+
+Now ukrainian will fallback to russian and then to english.
+
+Lets take post record:
+
+```ruby
+Post.translated(:name).take
+```
+
+Fallback rule will be present in produced `SQL` statement:
+
+```sql
+COALESCE(COALESCE("posts"."name_uk", name_ru), name_en) AS name
+```
+
+Fallbacks could be set through option of `.translated` method in model:
+
+```ruby
+class Post
+  translates :name, fallback: {_: %i[name_en title_en]}
+end
+```
+
+Here `_` key means any locale.
+If current locale is `ru` and `name_ru` is `NULL` then `name_en` will be used.
+If it is `NULL` too then `title_en` will be received.
+If current locale is `en` then `name_en` fallback rule will be ignored and `title_en` will be received.
+
+## Plurals
+
+Described Post model has `slug` columns for human readable urls.
+Also it has `translated` boolean columns for hiding not translated posts from users.
+
+```ruby
+class Post < ApplicationRecord
+  translates :name, ..., plurals: %i[slugs translateds]
+end
+```
+
+Query for show page loads `slug` and `translated` columns for all locales:
+
+```ruby
+post = Post.translated(:slug, :slugs, :translateds).find_by(slug: params[:slug])
+```
+
+Now at the show page you can provide links to same post in different languages filtering out not translated:
+
+```erbruby
+<% I18n.available_locales.each do |locale| %>
+  <% if @post.send("translated_#{locale}") %>
+    <% link_to "Read in #{locale}", post_url(@post.send("slug_#{locale}")) %>
+  <% end %>
+<% end %>
+```
 
 ## Installation
 Add this line to your application's Gemfile:
@@ -21,8 +168,5 @@ Or install it yourself as:
 $ gem install from_clause_translate
 ```
 
-## Contributing
-Contribution directions go here.
-
 ## License
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/lib/from_clause_translate.rb

@@ -2,14 +2,9 @@ module FromClauseTranslate
   require 'active_record'
   require 'from_clause_translate/active_record_relation'
   require 'from_clause_translate/class_methods'
+  require 'from_clause_translate/translation_data'
 
-  def self.included model
-    model.instance_variable_set :@original_connection, model.connection
-    model.extend ClassMethods
-    model.const_set :TRANSLATED, {}
-    model.const_set :TRANSLATED_PLURALS, {}
-    model.const_set :TRANSLATED_SELECTION, Hash[
-      I18n.available_locales.map { |locale| [locale, {}] }
-    ]
+  def self.included(model)
+    model.extend FromClauseTranslate::ClassMethods
   end
 end

data/lib/from_clause_translate/active_record_relation.rb

@@ -1,33 +1,35 @@
 require 'from_clause_translate/translated_columns_builder'
 
 module ActiveRecord::Relation::Extended
-  def arel aliases = nil
+  def arel(aliases = nil)
+    arel = super
     apply_translates
-    super aliases
+    arel.instance_variable_get(:@ctx).source.left = @from_clause if @from_clause
+    arel
   end
 
-  def add_translated_columns columns
+  def add_translated_columns(columns)
     (@values[:translated] ||= []).concat columns
   end
 
-  def add_translated_column column
+  def add_translated_column(column)
     (@values[:translated] ||= []) << column
   end
 
   def apply_translates
-    return if @translates_applied || !@klass.const_defined?(:TRANSLATED)
+    return if @translates_applied || !@values[:translated]
 
     @translates_applied = true
 
     columns = translated_columns_build
     return unless columns
 
-    @arel = build_arel nil
-
     rel = unscoped.select(columns)
     rel.instance_variable_set(:@translates_applied, true)
     replace_plurals_in_projections
-    @arel.from("(#{rel.arel.to_sql}) #{@klass.table_name}")
+    @from_clause = Arel::Nodes::SqlLiteral.new(
+      "(#{rel.arel.to_sql}) #{@klass.table_name}"
+    )
   end
 
   def translated_columns_build
@@ -36,7 +38,7 @@ module ActiveRecord::Relation::Extended
     ).perform
   end
 
-  def perform_calculation operation, column_name
+  def perform_calculation(operation, column_name)
     return super operation, column_name if @without_projections
 
     rel = spawn
@@ -50,7 +52,7 @@ module ActiveRecord::Relation::Extended
       next unless column.is_a? String
 
       name = column[0] == '"' ? column[1...-1] : column
-      plural = @klass::TRANSLATED_PLURALS[name.to_sym]
+      plural = @klass._translation_data.plurals[name.to_sym]
       column.replace plural if plural
     end
   end

data/lib/from_clause_translate/class_methods.rb

@@ -1,106 +1,27 @@
-module ClassMethods
-  require 'from_clause_translate/class_methods/fallbacks'
-  include Fallbacks
-
-  def translates *columns
+module FromClauseTranslate::ClassMethods
+  def translates(*columns)
     options = columns.extract_options!
-    filter_translated_columns(
-      map_translated_columns(columns)
-    ).each do |hash|
-      column = hash[:name]
-      self::TRANSLATED[column] = true
-      define_translated_selection column, hash
-      define_translated_column_methods column
-    end
+    _translation_data.add_columns(columns)
     translates_plurals options[:plurals]
   end
 
-  def translates_plurals plurals
-    return unless plurals
-
-    plurals.each do |plural|
-      plural = plural.to_sym
-      self::TRANSLATED[plural] = true
-      column = plural.to_s.singularize.to_sym
-      selection = I18n.available_locales.map do |locale|
-        "#{quoted_table_name}.\"#{column}_#{locale}\""
-      end.join ','
-      self::TRANSLATED_PLURALS[plural] = selection
-      I18n.available_locales.each do |locale|
-        self::TRANSLATED_SELECTION[locale][plural] = selection
-      end
+  def translates_plurals(plurals)
+    plurals && plurals.each do |plural|
+      _translation_data.add_plural(plural)
     end
   end
 
-  def translates? column
-    self::TRANSLATED[column.to_sym]
+  def translates?(column)
+    _translation_data.translates? column
   end
 
-  def translated *columns
+  def translated(*columns)
     scope = current_scope || all
     scope.add_translated_columns columns
     scope
   end
 
-  private
-
-  def map_translated_columns columns
-    columns.map! do |column|
-      hash = column.is_a?(Hash) ? column : {name: column}
-      translated_fallbacks_set hash
-      hash
-    end
-  end
-
-  def filter_translated_columns columns
-    columns.keep_if do |hash|
-      !translates?(hash[:name]) &&
-        column_names.include?("#{hash[:name]}_#{I18n.locale}")
-    end
-  end
-
-  def define_translated_selection column, hash
-    fallback = hash[:fallback]
-    I18n.available_locales.each do |locale|
-      selection = "#{quoted_table_name}.\"#{column}_#{locale}\""
-      selection = translated_fallbacks_wrap selection, fallback[locale]
-      selection = translated_fallbacks_wrap selection, fallback[:_]
-      self::TRANSLATED_SELECTION[locale][column] = "#{selection} AS #{column}"
-    end
-  end
-
-  def define_translated_column_methods col
-    col = col.to_s
-    dashed = "#{col}_"
-    define_translated_column_getter_and_setter col, dashed
-    define_translated_column_changing_methods col, dashed
-  end
-
-  def define_translated_column_getter_and_setter col, dashed
-    define_method col do
-      @attributes.key?(col) ? self[col] : send("#{dashed}#{I18n.locale}")
-    end
-
-    define_method col + '=' do |val|
-      send "#{dashed}#{I18n.locale}=", val
-    end
-  end
-
-  def define_translated_column_changing_methods col, dashed
-    define_method 'saved_change_to_' + col do
-      send "saved_change_to_#{dashed}#{I18n.locale}"
-    end
-
-    %w[changed? before_last_save change_to_be_saved in_database].each do |suf|
-      define_method dashed + suf do
-        send "#{dashed}#{I18n.locale}_#{suf}"
-      end
-    end
-
-    %w[saved_change_to will_save_change_to].each do |prefix|
-      define_method "#{prefix}_#{col}?" do
-        send "#{prefix}_#{dashed}#{I18n.locale}?"
-      end
-    end
+  def _translation_data
+    @translation_data ||= FromClauseTranslate::TranslationData.new(self)
   end
 end

data/lib/from_clause_translate/fallback.rb

@@ -0,0 +1,53 @@
+class FromClauseTranslate::Fallback
+  attr_reader :model, :fallback
+
+  def initialize(model, hash)
+    @model = model
+    @fallback = hash[:fallback]
+
+    if fallback.nil?
+      create_fallback_from_i18n(hash[:name])
+    elsif !fallback.is_a? Hash
+      @fallback = {_: fallback}
+    end
+  end
+
+  def wrap(selection, column, locale)
+    wrap_with_fallbacks selection, fallback[locale], column, locale
+    wrap_with_fallbacks selection, fallback[:_], column, locale
+    selection
+  end
+
+  private
+
+  def wrap_with_fallbacks(selection, fallbacks, column, locale)
+    return unless fallbacks
+
+    if fallbacks.is_a? Array
+      fallbacks.each do |fallback|
+        wrap_with_fallbacks selection, fallback, column, locale
+      end
+      return
+    end
+
+    fallbacks = "#{model.table_name}.#{fallbacks}" if fallbacks.is_a? Symbol
+    return if fallbacks == "#{model.table_name}.#{column}_#{locale}"
+
+    selection.replace "COALESCE(#{selection}, #{fallbacks})"
+  end
+
+  def create_fallback_from_i18n(column)
+    if I18n.fallbacks.empty?
+      # invoke fallbacks generation
+      I18n.available_locales.each { |locale| I18n.fallbacks[locale] }
+    end
+    @fallback = {}
+    I18n.fallbacks.each do |locale, array|
+      result = []
+      fallback[locale] = result
+      array.each do |fallback|
+        result << "#{column}_#{fallback}" unless fallback == locale
+      end
+    end
+  end
+end

data/lib/from_clause_translate/translated_columns_builder.rb

@@ -79,9 +79,12 @@ class FromClauseTranslate::TranslatedColumnsBuilder
         next unless child.respond_to? :left
 
         left = child.left
-        next if left.relation.table_name != @klass.table_name
+        if left.respond_to?(:relation) &&
+           left.relation.table_name != @klass.table_name
+          next
+        end
 
-        translated_selection left.name
+        translated_selection child.left.name
       end
     end
   end
@@ -100,22 +103,24 @@ class FromClauseTranslate::TranslatedColumnsBuilder
 
   def add_translated_columns_from_orders
     @arel.ast.orders.each do |name|
-      name = name.respond_to?(:expr) ? name.expr.name : name
+      if name.respond_to?(:expr)
+        name = name.expr
+        name = name.name if name.respond_to?(:name)
+      end
       translated_selection name
     end
   end
 
   def translated_selection name, original = nil
     sym = name.to_sym
-    translates = @klass.translates? sym
+    translates = @klass.respond_to?(:translates?) && @klass.translates?(sym)
     @has_translated = true
     if translates
-      return @columns << @klass::TRANSLATED_SELECTION[I18n.locale][sym]
+      return @columns << @klass._translation_data.selections[I18n.locale][sym]
     end
 
-    @select_all = true if sym == :*
-    return if @select_all || !@klass.columns_hash[name.to_s]
+    return unless @klass.columns_hash[name.to_s]
 
-    @columns << (original || name)
+    @columns << (original ? original.to_sym : sym)
   end
 end

data/lib/from_clause_translate/translation_data.rb

@@ -0,0 +1,89 @@
+require 'from_clause_translate/fallback'
+
+class FromClauseTranslate::TranslationData
+  attr_reader :model, :translated, :plurals, :selections
+
+  def initialize(model)
+    @model = model
+    @translated = {}
+    @plurals = {}
+    @selections = I18n.available_locales.map { |locale| [locale, {}] }.to_h
+  end
+
+  def translates?(column)
+    @translated[column.to_sym] || false
+  end
+
+  def add_columns(columns)
+    columns.each(&method(:add_column))
+  end
+
+  def add_column(column)
+    hash = column.is_a?(Hash) ? column : {name: column}
+
+    return if translates?(hash[:name]) ||
+              !model.column_names.include?("#{hash[:name]}_#{I18n.locale}")
+
+    column = hash[:name]
+    translated[column] = true
+
+    define_translated_selection column, hash
+
+    column = column.to_s
+    dashed = "#{column}_"
+    define_translated_column_getter_and_setter column, dashed
+    define_translated_column_changing_methods column, dashed
+  end
+
+  def add_plural(plural)
+    plural = plural.to_sym
+    translated[plural] = true
+    column = plural.to_s.singularize.to_sym
+    selection = I18n.available_locales.map do |locale|
+      "#{model.quoted_table_name}.\"#{column}_#{locale}\""
+    end.join ','
+    plurals[plural] = selection
+    I18n.available_locales.each do |locale|
+      selections[locale][plural] = selection
+    end
+  end
+
+  private
+
+  def define_translated_selection(column, hash)
+    fallback = FromClauseTranslate::Fallback.new(model, hash)
+    I18n.available_locales.each do |locale|
+      selection = "#{model.quoted_table_name}.\"#{column}_#{locale}\""
+      selection = fallback.wrap selection, column, locale
+      selections[locale][column] = "#{selection} AS #{column}"
+    end
+  end
+
+  def define_translated_column_getter_and_setter col, dashed
+    model.define_method col do
+      @attributes.key?(col) ? self[col] : send("#{dashed}#{I18n.locale}")
+    end
+
+    model.define_method col + '=' do |val|
+      send "#{dashed}#{I18n.locale}=", val
+    end
+  end
+
+  def define_translated_column_changing_methods col, dashed
+    model.define_method 'saved_change_to_' + col do
+      send "saved_change_to_#{dashed}#{I18n.locale}"
+    end
+
+    %w[changed? before_last_save change_to_be_saved in_database].each do |suf|
+      model.define_method dashed + suf do
+        send "#{dashed}#{I18n.locale}_#{suf}"
+      end
+    end
+
+    %w[saved_change_to will_save_change_to].each do |prefix|
+      model.define_method "#{prefix}_#{col}?" do
+        send "#{prefix}_#{dashed}#{I18n.locale}?"
+      end
+    end
+  end
+end

data/lib/from_clause_translate/version.rb

@@ -1,3 +1,3 @@
 module FromClauseTranslate
-  VERSION = '0.2.6'.freeze
+  VERSION = '0.2.7'.freeze
 end

metadata

@@ -1,29 +1,85 @@
 --- !ruby/object:Gem::Specification
 name: from_clause_translate
 version: !ruby/object:Gem::Version
-  version: 0.2.6
+  version: 0.2.7
 platform: ruby
 authors:
 - Roman Kushin
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-12-10 00:00:00.000000000 Z
+date: 2019-08-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: rails
+  name: activerecord
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5'
+        version: '5.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5'
+        version: '5.2'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.8'
+- !ruby/object:Gem::Dependency
+  name: standalone_migrations
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.2'
+- !ruby/object:Gem::Dependency
+  name: database_cleaner
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
 description: Translates record using SQL from clause.
 email:
 - romadzao@gmail.com
@@ -36,10 +92,11 @@ files:
 - lib/from_clause_translate.rb
 - lib/from_clause_translate/active_record_relation.rb
 - lib/from_clause_translate/class_methods.rb
-- lib/from_clause_translate/class_methods/fallbacks.rb
+- lib/from_clause_translate/fallback.rb
 - lib/from_clause_translate/translated_columns_builder.rb
+- lib/from_clause_translate/translation_data.rb
 - lib/from_clause_translate/version.rb
-homepage: 
+homepage: https://gitlab.com/romikus/rails-from-clause-translate-gem
 licenses:
 - MIT
 metadata: {}
@@ -58,8 +115,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.6
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: For database record translations

data/lib/from_clause_translate/class_methods/fallbacks.rb

@@ -1,32 +0,0 @@
-module Fallbacks
-  private
-
-  def translated_fallbacks_set hash
-    fallback = hash[:fallback]
-    return hash[:fallback] = {} unless hash[:fallback]
-    return if fallback.is_a? Hash
-
-    hash[:fallback] = {_: fallback}
-  end
-
-  def translated_fallbacks_wrap selection, fallbacks
-    return selection unless fallbacks
-
-    if fallbacks.is_a?(String) || fallbacks.is_a?(Symbol)
-      translated_selection_fallback_wrap selection, fallbacks
-    else
-      fallbacks.each do |fallback|
-        selection = translated_selection_fallback_wrap selection, fallback
-      end
-      selection
-    end
-  end
-
-  def translated_selection_fallback_wrap selection, fallback
-    if fallback.is_a? String
-      "COALESCE(#{selection}, #{fallback})"
-    else
-      "COALESCE(#{selection}, #{table_name}.#{fallback})"
-    end
-  end
-end