Macros and where to go next chapters

Author: José Valim

_layouts/getting_started.html

@@ -32,6 +32,8 @@ <h3 class="widget-title">Index</h3>
 <li><aclass="spec" href="/getting_started/19.html">Sigils</a></li>
 <li><aclass="spec" href="/getting_started/20.html">Quote and unquote</a></li>
 <li><aclass="spec" href="/getting_started/21.html">Macros</a></li>
+<li><aclass="spec" href="/getting_started/22.html">Domain Specific Languages</a></li>
+<li><aclass="spec" href="/getting_started/23.html">Where to go next</a></li>
 </ol>
 </div>
 <divclass="widget">

getting_started/20.markdown

@@ -5,3 +5,140 @@ guide: 20
 ---
 
 # {{page.title }}
+
+An Elixir program can be represented by its own data structures. In this chapter, we will learn how those structures look like and how to compose them. The concepts learned in this chapter are the building blocks for macros, which we are going to take a deeper look at the next chapter.
+
+## 20.1 Quoting
+
+The building block of an Elixir program is a tuple with three elements. For example, the function call `sum(1,2,3)` is represented internally as:
+
+```elixir
+{:sum, [], [1, 2, 3]}
+```
+
+You can get the representation of any expression by using the `quote` macro:
+
+```iex
+iex> quote do: sum(1, 2, 3)
+{:sum, [], [1, 2, 3]}
+```
+
+The first element is the function name, the second is a keyword list containing metadata and the third is the arguments list.
+
+Operators are also represented as such tuples:
+
+```iex
+iex> quote do: 1 + 2
+{:+, [context: Elixir, import: Kernel], [1, 2]}
+```
+
+Even a map is represented as a call to `%{}`:
+
+```iex
+iex> quote do: %{1 => 2}
+{:%{}, [], [{1, 2}]}
+```
+
+Variables are also represented using such triplets, except the last element is an atom, instead of a list:
+
+```iex
+iex> quote do: x
+{:x, [], Elixir }
+```
+
+When quoting more complex expressions, we can see the code is represented in such tuples, often nested inside each other resembling a tree. Many languages would call those representations the Abstract Syntax Tree (AST). Elixir calls them quoted expressions:
+
+```iex
+iex> quote do: sum(1, 2 + 3, 4)
+{:sum, [], [1,{:+, [context: Elixir, import: Kernel], [2, 3]}, 4]}
+```
+
+Sometimes when working with quoted expressions, it may be useful to get the textual code representation back. This can be done with `Macro.to_string/1`:
+
+```iex
+iex> Macro.to_string(quote do: sum(1, 2 + 3, 4))
+"sum(1, 2 + 3, 4)"
+```
+
+In general, the tuples above follow the following format:
+
+```elixir
+{tuple | atom, list, list | atom }
+```
+
+* The first element is an atom or another tuple in the same representation;
+* The second element is a keyword list containing information like metadata like numbers and contexts;
+* The third element is either a list of arguments for the function call or an atom. When an atom, it means the tuple represents a variable.
+
+Besides the tuple defined above, there are five Elixir literals that when quoted return themselves (and not a tuple). They are:
+
+```elixir
+:sum#=> Atoms
+1.0#=> Numbers
+[1,2] #=> Lists
+"strings"#=> Strings
+{key, value} #=> Tuples with two elements
+```
+
+Most of Elixir code has straight-forward translation to its underlying quoted expression. We recommend you to try out different code samples and see what gets out of it. For example, what `String.upcase("foo")` expands to? We have also learned that `if(true, do: this, else: that)` is the same as `if true do this else that end`. How does this affirmation hold with quoted expressions?
+
+## 20.2 Unquoting
+
+Quote is about retrieving the inner representation of some particular chunk of code. However, sometimes it may be necessary to inject some other particular chunk of code inside the representation we want to retrieve.
+
+For example, imagine you have a variable `number` which contains the number you want to inject inside a quoted expression. The number can be injected into the quoted representation by using `unquote`:
+
+```iex
+iex> number = 13
+iex> Macro.to_string(quote do: 11 + unquote(number))
+"11 + 13"
+```
+
+`unquote` can even be used to inject function names:
+
+```iex
+iex> fun = :hello
+iex> Macro.to_string(quote do: unquote(hello)(:world))
+"hello(:world)"
+```
+
+In some cases, it may be necessary to inject many values inside a list. For example, imagine you have a list containing `[1, 2, 6]` and we want to inject `[3, 4, 5]` into it. Using `unquote` won't yield the desired result:
+
+```iex
+iex> inner = [3, 4, 5]
+iex> Macro.to_string(quote do: [1, 2, unquote(inner), 6])
+[1, 2, [3, 4, 5], 6]
+```
+
+That's when `unquote_splicing` becomes handy:
+
+```iex
+iex> inner = [3, 4, 5]
+iex> Macro.to_string(quote do: [1, 2, unquote_splicing(inner), 6])
+[1, 2, 3, 4, 5, 6]
+```
+
+Unquoting is very useful when working with macros. When writing macros, developers are able to receive code chunks and inject them inside other code chunks, being able to transform code or write code that generates code during compilation.
+
+## 20.3 Escaping
+
+As we have seen at the beginning of this chapter, only some values are valid quoted expressions. For example, a map is not a valid quoted expression. Nor a tuple with three elements. However, we have seen before those values *can* be expressed as a quoted expression:
+
+```iex
+iex> quote do: %{1 => 2}
+{:%{}, [], [{1, 2}]}
+```
+
+In some cases, you may need to inject such *values* into *quoted expressions*. To do that, we need to first escape those values into quoted expressions with the help of `Macro.escape/1`:
+
+```iex
+iex> map = %{hello: :world}
+iex> Macro.escape(map)
+{%{}, [], [hello: :world]}
+```
+
+In other words, it is important to make a distinction in between a regular Elixir value (like a list, a map, a process, a reference, etc) and a quoted expression. Some values like integers, atoms and strings have a quoted expression equal to the value itself. Other values like maps needs to be explicitly converted. Finally, some values like functions and references cannot be converted to a quoted expression at all.
+
+Macros receive quoted expressions and must return quoted expressions. However, sometimes during the function of a macro, you may need to work with values and making a distinction in between them may be required.
+
+With this introduction we have laid the ground to finally write out first macro, so let's move to the next chapter.