Merge branch 'releases/2.0.0'

Author: crbelaus

.travis.yml

@@ -1,24 +1,17 @@
 language: elixir
 elixir:
-  - 1.2.5
   - 1.3.2
   - 1.3.3
   - 1.3.4
   - 1.4.0
   - 1.4.1
+  - 1.4.2
 otp_release:
   - 18.3
   - 19.0
   - 19.1
   - 19.2
-matrix:
-  exclude:
-    - otp_release: 19.0
-      elixir: 1.2.5
-    - otp_release: 19.1
-      elixir: 1.2.5
-    - otp_release: 19.2
-      elixir: 1.2.5
+  - 19.3
 addons:
   postgresql: "9.4"
 before_script:

CHANGELOG.md

@@ -4,23 +4,28 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
+## 2.0.0 - 2017-04-11
+- Rewrite the `Trans` module to use underscore functions to store configuration.
+- Rewrite the `QueryBuilder` module to unify previous functions into a single macro with compile time checks. Translations can now be used directly when building queries and are compatible with functions and macros provided by `Ecto.Query` and `Ecto.Query.Api`.
+- Update the `Translator` module to use the new underscore functions.
+- Update documentation and improve the tests.
+
+## 1.1.0 - 2017-02-28
+- Make `Ecto` an optional dependency. If `Ecto` is not available the `QueryBuilder` module will not be compiled.
+
 ## 1.0.2 - 2017-02-19
-### Added
 - Remove `earmark` as a direct dependency since it is already required by `ex_doc`.
 - Remove warnings when compiling with Elixir 1.4.
 - Adds contribution guidelines detailed in `CONTRIBUTING.md`.
 
 ## 1.0.1 - 2016-10-22
-### Added
 - New testing environments for Travis CI.
 - The project has now a changelog.
 - Improved documentation.
 - Improved README.
 
 ## 1.0.0 - 2016-07-30
-### Added
 - Support for Ecto 2.0.
 
 ## 0.1.0 - 2016-06-04
-### Added
 - Initial release with basic functionality and documentation.

README.md

@@ -22,7 +22,7 @@ use the `Trans.Translator` component without those dependencies though.
 - PostgreSQL 9.4 or higher (since `Trans` leverages the JSONB datatype)
 
 Support for MySQL JSON type (introduced in MySQL 5.7) will come also, but right
-now it is not yet implemented.
+now it is not yet implemented at the database adapter level.
 
 ## Why Trans?
 
@@ -46,9 +46,9 @@ translatable schema has an extra column that contains all of its translations.
 This approach drastically reduces the number of required JOINs when filtering or
 fetching records.
 
-Trans is lightweight and modularized. The main functionality is provided by the
-`Trans.Translator` and the `Trans.QueryBuilder` modules, while the `Trans` module
-simplifies the calls to translator and query builder functions from a schema.
+`Trans` is lightweight and modularized. The `Trans` module provides metadata
+that is used by the `Trans.Translator` and `Trans.QueryBuilder` modules, which
+implement the main functionality of this library.
 
 ## Making a schema translatable
 
@@ -84,6 +84,22 @@ defmodule Article do
 end
 ```
 
+Then we must use `Trans` from our schema module to indicate which fields will
+be translated.
+
+```elixir
+defmodule Article do
+  use Ecto.Schema
+  use Trans, translates: [:title, :body]
+
+  schema "articles" do
+    field :title, :string
+    field :body, :string
+    field :translations, :map
+  end
+end
+```
+
 ## Storing translations
 
 Translations are stored as a map of maps in the *translation container* of our
@@ -111,45 +127,44 @@ iex> article = Repo.insert!(changeset)
 ## Filtering queries by translations
 
 We may want to fetch articles that are translated into a certain language.  To
-do this we may use the `with_translations/3` function of the `Trans.QueryBuilder`
-module:
+do this we use the `Trans.QueryBuilder.translated/3` macro, which generates the
+required SQL fragment for us.
 
 ```elixir
-iex> Article
-...> |> Trans.QueryBuilder.with_translations(:es)
-...> |> Repo.all
-[debug] SELECT a0."id", a0."title", a0."body", a0."translations"
-        FROM "articles" AS a0
-        WHERE ((a0."translations"->>$1) is not null) ["es"]
-[debug] OK query=4.7ms queue=0.1ms
+iex> Repo.all(from a in Article,
+...>   where: not is_nil(translated(Article, a, :es)))
+# SELECT a0."id", a0."title", a0."body", a0."translations"
+# FROM "articles" AS a0
+# WHERE (NOT ((a0."translations"->"es") IS NULL))
 ```
 
 We can also get more specific and fetch only those articles for which their
-Spanish title contains the word "Trans".
+Spanish title matches "Elixir".
 
 ```elixir
-iex> Article
-...> |> Trans.QueryBuilder.with_translation(:es, :title, "Trans")
-...> |> Repo.all
-[debug] SELECT a0."id", a0."title", a0."body", a0."translations"
-        FROM "articles" AS a0
-        WHERE (a0."translations"->$1->>$2 = $3) ["es", "title", "Trans"]
-[debug] OK query=2.6ms queue=0.1ms
+iex> Repo.all(from a in Article,
+...>   where: translated(Article, a.title, :es) == "Elixir")
+# SELECT a0."id", a0."title", a0."body", a0."translations"
+# FROM "articles" AS a0
+# WHERE ((a0."translations"->"fr"->>"title") = "Elixir")
 ```
 
-By default `Trans` looks for an exact match when we add a condition.  We may
-also perform a LIKE or ILIKE comparison and use wilcards like this:
+The SQL fragment generated by the `Trans.QueryBuilder.translated/3` macro is
+compatible with the rest of functions and macros provided by `Ecto.Query` and
+`Ecto.Query.Api`.
 
 ```elixir
-iex> Article
-...> |> Trans.QueryBuilder.with_translation(:es, :title, "%Trans%", type: :like)
-...> |> Repo.all
-[debug] SELECT a0."id", a0."title", a0."body", a0."translations"
-        FROM "articles" AS a0
-        WHERE (a0."translations"->$1->>$2 LIKE $3) ["es", "title", "%Trans%"]
-[debug] OK query=2.1ms queue=0.1ms
+iex> Repo.all(from a in Article,
+...> where: ilike(translated(Article, a.body, :es), "%elixir%"))
+# SELECT a0."id", a0."title", a0."body", a0."translations"
+# FROM "articles" AS a0
+# WHERE ((a0."translations"->"es"->>"body") ILIKE "%elixir%")
 ```
 
+More complex queries such as adding conditions to joined schemas can be easily
+generated in the same way. Take a look at the documentation and tests for more
+examples.
+
 ## Obtaining translations from a struct
 
 In those examples we will be referring to this article:
@@ -171,20 +186,20 @@ iex> article = %Article{
 ...> }
 ```
 
-Once we have already loaded a struct, we may use the `Trans.Translator.translate/4`
-function to easily access a translation for a certain field.
+Once we have already loaded a struct, we may use the `Trans.Translator.translate/3`
+function to easily access a translation of a certain field.
 
 ```elixir
-iex> Article.translate(article, :es, :body)
+iex> Trans.Translator.translate(article, :title, :es)
 "Cómo escribir un corrector ortográfico"
 ```
 
-The `Trans.Translator.translate/4` function also provides a fallback mechanism
+The `Trans.Translator.translate/3` function also provides a fallback mechanism
 that activates when the required translation does not exist:
 
 ```elixir
-iex> Article.translate(article, :de, :title)
-"How to Write a Spelling Corrector" # Fallback to untranslated value
+iex> Trans.Translator.translate(article, :title, :de)
+"How to Write a Spelling Corrector"
 ```
 
 ## Using a different *translation container*
@@ -193,42 +208,13 @@ In the previous examples we have used `translations` as the name of the
 *translation container* and `Trans` looks automatically for translations into this
 field.
 
-We can also give the *translation container* a different name:
-
-```elixir
-defmodule Article do
-  use Ecto.Schema
-
-  schema "articles" do
-    field :title, :string
-    field :body, :string
-    field :article_translations, :map # this is our translation container
-  end
-end
-```
-
-We can call the same functions as in previous examples, but we have to specify
-the name of the *translation container* to override the default:
-
-```elixir
-iex> Article
-...> |> Trans.QueryBuilder.with_translation(:es, :title, "Trans", container: :article_translations)
-...> |> Repo.all
-[debug] SELECT a0."id", a0."title", a0."body", a0."translations"
-        FROM "articles" AS a0
-        WHERE (a0."article_translations"->$1->>$2 = $3) ["es", "title", "Trans"]
-[debug] OK query=2.6ms queue=0.1ms
-```
-
-Having to specify the name of the *translation container* everytime is error
-prone and can become tiresome.  Instead we can use the `Trans` module in our
-schema and have this option specified automatically for us:
+We can also give the *translation container* a different name, for example
+**article_translations**:
 
 ```elixir
 defmodule Article do
   use Ecto.Schema
-  use Trans, defaults: [container: :article_translations],
-    translates: [:title, :body]
+  use Trans, translates: [:title, :body], container: :article_translations
 
   schema "articles" do
     field :title, :string
@@ -238,14 +224,13 @@ defmodule Article do
 end
 ```
 
-Now we can do:
+We can call the same functions as in previous examples and both `Trans.Translator`
+and `Trans.QueryBuilder` will automatically look for translations in the correct field.
 
 ```elixir
-iex> Article
-...> |> Article.with_translation(:es, :title, "Trans")
-...> |> Repo.all
-[debug] SELECT a0."id", a0."title", a0."body", a0."translations"
-        FROM "articles" AS a0
-        WHERE (a0."article_translations"->$1->>$2 = $3) ["es", "title", "Trans"]
-[debug] OK query=2.6ms queue=0.1ms
-```
+iex> Repo.all(from a in Article,
+...>   where: not is_nil(translated(Article, a, :es)))
+# SELECT a0."id", a0."title", a0."body", a0."article_translations"
+# FROM "articles" AS a0
+# WHERE (NOT ((a0."article_translations"->"es") IS NULL))
+```