New concept exercise dancing-dots (use and behaviour) (#1103)

Co-authored-by: Victor Goff <[email protected]>
Co-authored-by: Jie <[email protected]>

Author: 3 people

concepts/behaviours/.meta/config.json

@@ -0,0 +1,9 @@
+{
+  "blurb": "Behaviours allow us to define interfaces in a behaviour module that can be later implemented by different callback modules.",
+  "authors": [
+    "angelikatyborska"
+  ],
+  "contributors": [
+    "jiegillet"
+  ]
+}

concepts/behaviours/about.md

@@ -0,0 +1,66 @@
+# About
+
+Behaviours allow us to define interfaces (sets of functions and macros) in a _behaviour module_ that can be later implemented by different _callback modules_. Thanks to the shared interface, those callback modules can be used interchangeably.
+
+~~~~exercism/note
+Note the British spelling of "behaviours".
+~~~~
+
+## Defining behaviours
+
+To define a behaviour, we need to create a new module and specify a list of functions that are part of the desired interface. Each function needs to be defined using the `@callback` module attribute. The syntax is identical to a [function typespec][concept-typespecs] (`@spec`). We need to specify a function name, a list of argument types, and all the possible return types.
+
+```elixir
+defmodule Countable do
+  @callback count(collection :: any) :: pos_integer
+end
+```
+
+## Implementing behaviours
+
+To add an existing behaviour to our module (create a callback module) we use the `@behaviour` module attribute. Its value should be the name of the behaviour module that we're adding.
+
+Then, we need to define all the functions (callbacks) that are required by that behaviour module. If we're implementing somebody else's behaviour, like Elixir's built-in `Access` or `GenServer` behaviours, we would find the list of all the behaviour's callbacks in the documentation on [hexdocs.pm][hexdocs].
+
+A callback module is not limited to implementing only the functions that are part of its behaviour. It is also possible for a single module to implement multiple behaviours.
+
+To mark which function comes from which behaviour, we should use the module attribute `@impl` before each function. Its value should be the name of the behaviour module that defines this callback.
+
+```elixir
+defmodule BookCollection do
+  @behaviour Countable
+
+  defstruct :list, :owner
+
+  @impl Countable
+  def count(collection) do
+    Enum.count(collection.list)
+  end
+
+  def mark_as_read(collection, book) do
+    # other function unrelated to the Countable behaviour
+  end
+end
+```
+
+## Default callback implementations
+
+When defining a behaviour, it is possible to provide a default implementation of a callback. This implementation should be defined in the quoted expression of the `__using__/1` macro. To make it possible for users of the behaviour module to override the default implementation, call the `defoverridable/1` macro after the function implementation. It accepts a keyword list of function names as keys and function arities as values.
+
+```elixir
+defmodule Countable do
+  @callback count(collection :: any) :: pos_integer
+
+  defmacro __using__(_) do
+    quote do
+      @behaviour Countable
+      def count(collection), do: Enum.count(collection)
+      defoverridable count: 1
+    end
+  end
+end
+```
+
+Note that defining functions inside of `__using__/1` is discouraged for any other purpose than defining default callback implementations, but you can always define functions in another module and import them in the  `__using__/1` macro.
+
+[concept-typespecs]: https://exercism.org/tracks/elixir/concepts/typespecs

concepts/behaviours/introduction.md

@@ -0,0 +1,66 @@
+# Introduction
+
+Behaviours allow us to define interfaces (sets of functions and macros) in a _behaviour module_ that can be later implemented by different _callback modules_. Thanks to the shared interface, those callback modules can be used interchangeably.
+
+~~~~exercism/note
+Note the British spelling of "behaviours".
+~~~~
+
+## Defining behaviours
+
+To define a behaviour, we need to create a new module and specify a list of functions that are part of the desired interface. Each function needs to be defined using the `@callback` module attribute. The syntax is identical to a [function typespec][concept-typespecs] (`@spec`). We need to specify a function name, a list of argument types, and all the possible return types.
+
+```elixir
+defmodule Countable do
+  @callback count(collection :: any) :: pos_integer
+end
+```
+
+## Implementing behaviours
+
+To add an existing behaviour to our module (create a callback module) we use the `@behaviour` module attribute. Its value should be the name of the behaviour module that we're adding.
+
+Then, we need to define all the functions (callbacks) that are required by that behaviour module. If we're implementing somebody else's behaviour, like Elixir's built-in `Access` or `GenServer` behaviours, we would find the list of all the behaviour's callbacks in the documentation on [hexdocs.pm][hexdocs].
+
+A callback module is not limited to implementing only the functions that are part of its behaviour. It is also possible for a single module to implement multiple behaviours.
+
+To mark which function comes from which behaviour, we should use the module attribute `@impl` before each function. Its value should be the name of the behaviour module that defines this callback.
+
+```elixir
+defmodule BookCollection do
+  @behaviour Countable
+
+  defstruct :list, :owner
+
+  @impl Countable
+  def count(collection) do
+    Enum.count(collection.list)
+  end
+
+  def mark_as_read(collection, book) do
+    # other function unrelated to the Countable behaviour
+  end
+end
+```
+
+## Default callback implementations
+
+When defining a behaviour, it is possible to provide a default implementation of a callback. This implementation should be defined in the quoted expression of the `__using__/1` macro. To make it possible for users of the behaviour module to override the default implementation, call the `defoverridable/1` macro after the function implementation. It accepts a keyword list of function names as keys and function arities as values.
+
+```elixir
+defmodule Countable do
+  @callback count(collection :: any) :: pos_integer
+
+  defmacro __using__(_) do
+    quote do
+      @behaviour Countable
+      def count(collection), do: Enum.count(collection)
+      defoverridable count: 1
+    end
+  end
+end
+```
+
+Note that defining functions inside of `__using__/1` is discouraged for any other purpose than defining default callback implementations, but you can always define functions in another module and import them in the  `__using__/1` macro.
+
+[concept-typespecs]: https://exercism.org/tracks/elixir/concepts/typespecs

concepts/behaviours/links.json

@@ -0,0 +1,14 @@
+[
+  {
+    "url": "https://elixir-lang.org/getting-started/typespecs-and-behaviours.html#behaviours",
+    "description": "Getting Started - Behaviours"
+  },
+  {
+    "url": "https://hexdocs.pm/elixir/typespecs.html#behaviours",
+    "description": "Documentation - Behaviours"
+  },
+  {
+    "url": "https://elixirschool.com/en/lessons/advanced/behaviours",
+    "description": "Elixir School - Behaviours"
+  }
+]

concepts/use/.meta/config.json

@@ -0,0 +1,9 @@
+{
+  "blurb": "The use macro allows us to quickly extend our module with functionally provided by another module.",
+  "authors": [
+    "angelikatyborska"
+  ],
+  "contributors": [
+    "jiegillet"
+  ]
+}

concepts/use/about.md

@@ -0,0 +1,33 @@
+# About
+
+The `use` macro allows us to quickly extend our module with functionally provided by another module. When we `use` a module, that module can inject code into our module - it can for example define functions, `import` or `alias` other modules, or set module attributes.
+
+If you ever looked at the test files of some of the Elixir exercises here on Exercism, you most likely noticed that they all start with `use ExUnit.Case`. This single line of code is what makes the macros `test` and `assert` available in the test module.
+
+```elixir
+defmodule LasagnaTest do
+  use ExUnit.Case
+
+  test "expected minutes in oven" do
+    assert Lasagna.expected_minutes_in_oven() === 40
+  end
+end
+```
+
+## `__using__/1` macro
+
+What exactly happens when you `use` a module is dictated by that module's `__using__/1` macro. It takes one argument, a keyword list with options, and it returns a [quoted expression][concept-ast]. The code in this quoted expression is inserted into our module when calling `use`.
+
+```elixir
+defmodule ExUnit.Case do
+  defmacro __using__(opts) do
+    # some real-life ExUnit code omitted here
+    quote do
+      import ExUnit.Assertions
+      import ExUnit.Case, only: [describe: 2, test: 1, test: 2, test: 3]
+    end
+  end
+end
+```
+
+The options can be given as a second argument when calling `use`, e.g. `use ExUnit.Case, async: true`. When not given explicitly, they default to an empty list.

concepts/use/introduction.md

@@ -0,0 +1,33 @@
+# Introduction
+
+The `use` macro allows us to quickly extend our module with functionally provided by another module. When we `use` a module, that module can inject code into our module - it can for example define functions, `import` or `alias` other modules, or set module attributes.
+
+If you ever looked at the test files of some of the Elixir exercises here on Exercism, you most likely noticed that they all start with `use ExUnit.Case`. This single line of code is what makes the macros `test` and `assert` available in the test module.
+
+```elixir
+defmodule LasagnaTest do
+  use ExUnit.Case
+
+  test "expected minutes in oven" do
+    assert Lasagna.expected_minutes_in_oven() === 40
+  end
+end
+```
+
+## `__using__/1` macro
+
+What exactly happens when you `use` a module is dictated by that module's `__using__/1` macro. It takes one argument, a keyword list with options, and it returns a [quoted expression][concept-ast]. The code in this quoted expression is inserted into our module when calling `use`.
+
+```elixir
+defmodule ExUnit.Case do
+  defmacro __using__(opts) do
+    # some real-life ExUnit code omitted here
+    quote do
+      import ExUnit.Assertions
+      import ExUnit.Case, only: [describe: 2, test: 1, test: 2, test: 3]
+    end
+  end
+end
+```
+
+The options can be given as a second argument when calling `use`, e.g. `use ExUnit.Case, async: true`. When not given explicitly, they default to an empty list.

concepts/use/links.json

@@ -0,0 +1,10 @@
+[
+  {
+    "url": "https://elixir-lang.org/getting-started/alias-require-and-import.html#use",
+    "description": "Getting Started - Use"
+  },
+  {
+    "url": "https://hexdocs.pm/elixir/Kernel.html#use/2",
+    "description": "Documentation - Use"
+  }
+]

config.json

@@ -614,6 +614,23 @@
           "enum"
         ],
         "status": "active"
+      },
+      {
+        "slug": "dancing-dots",
+        "name": "Dancing Dots",
+        "uuid": "cf9e346b-d809-4c0c-9801-8f59461ece95",
+        "concepts": [
+          "behaviours",
+          "use"
+        ],
+        "prerequisites": [
+          "typespecs",
+          "structs",
+          "ast",
+          "enum",
+          "import"
+        ],
+        "status": "beta"
       }
     ],
     "practice": [
@@ -2905,6 +2922,11 @@
       "slug": "basics",
       "name": "Basics"
     },
+    {
+      "uuid": "8cee26b5-2f55-4b6d-9902-64d10e96a7b6",
+      "slug": "behaviours",
+      "name": "Behaviours"
+    },
     {
       "uuid": "d291ca4b-7163-43e4-ab02-383904f19c34",
       "slug": "binaries",
@@ -3145,6 +3167,11 @@
       "slug": "typespecs",
       "name": "Typespecs"
     },
+    {
+      "uuid": "399e6943-dd79-4de5-a7a6-5df95ee35a85",
+      "slug": "use",
+      "name": "Use"
+    },
     {
       "uuid": "870a9af1-9354-451c-a0ab-6deada59254a",
       "slug": "with",

exercises/concept/dancing-dots/.docs/hints.md

@@ -0,0 +1,52 @@
+# Hints
+
+## General
+
+- Read about behaviours in the official [Getting Started guide][getting-started-behaviours].
+- Read about behaviours on [elixirschool.com][elixir-school-behaviours].
+- Read about behaviours in the [documentation][doc-behaviours].
+- Read about `use` in the official [Getting Started guide][getting-started-use].
+- Read about `use` in the [documentation][doc-use].
+
+## 1. Define the animation behaviour
+
+- Use the `@callback` module attribute to define the desired functions.
+- Each callback must specify the function name, list of arguments (their types) and the return value (its type).
+- Use the given custom types `dot`, `opts`, `error`, and `frame_number` in the callbacks' definitions.
+- Refresh your knowledge of [typespecs][typespec] to help with defining callbacks.
+
+## 2. Provide a default implementation of the `init/1` callback
+
+- Define a `__using__/1` macro in the `DacingDots.Animation` module.
+- The macros' argument can be ignored.
+- The macro must return a [quoted expression][quote].
+- In the quoted expression, use `@behaviour` so that calling `use DacingDots.Animation` sets `DacingDots.Animation` as the using module's behaviour.
+- In the quoted expression, implement the `init/1` function.
+- The default implementation of the `init/1` function should wrap the given `opts` argument in `:ok` tuple.
+- There is [a macro][defoverridable] that can mark a function as overridable.
+
+## 3. Implement the `Flicker` animation
+
+- Make use of `DancingDots.Animation` `__using__/1` macro by calling [this one special macro][doc-use] in the `DancingDots.Flicker` module.
+- You do not need to implement the `init/1` function. Its default implementation is enough.
+- You need to implement the `handle_frame/3` function.
+- To detect "every 4th frame", you can check if the [remainder][rem] when dividing it by 4 is equal to 0.
+
+## 4. Implement the `Zoom` animation
+
+- Make use of `DancingDots.Animation` `__using__/1` macro by calling [this one special macro][doc-use] in the `DancingDots.Zoom` module.
+- You need to implement both the `init/1` function and the `handle_frame/3` function.
+- Use the [`Keyword`][keyword] module to work with the options keyword list.
+- There is [a built-in guard][is_number] for checking if a value is a number.
+
+[getting-started-behaviours]: https://elixir-lang.org/getting-started/typespecs-and-behaviours.html#behaviours
+[doc-behaviours]: https://hexdocs.pm/elixir/typespecs.html#behaviours
+[elixir-school-behaviours]: https://elixirschool.com/en/lessons/advanced/behaviours
+[doc-use]: https://hexdocs.pm/elixir/Kernel.html#use/2
+[getting-started-use]: https://elixir-lang.org/getting-started/alias-require-and-import.html#use
+[typespec]: https://hexdocs.pm/elixir/typespecs.html
+[defoverridable]: https://hexdocs.pm/elixir/Kernel.html#defoverridable/1
+[quote]: https://hexdocs.pm/elixir/Kernel.SpecialForms.html#quote/2
+[rem]: https://hexdocs.pm/elixir/Kernel.html#rem/2
+[is_number]: https://hexdocs.pm/elixir/Kernel.html#is_number/1
+[keyword]: https://hexdocs.pm/elixir/Keyword.html