Finished Chapter 1

Author: shmink

README.md

@@ -17,6 +17,11 @@ Moreover, don't expect direct quotes, changing the sentences vocbulary helps me
     -   [What are Macros?](#what-are-macros)
     -   [The Abstract Syntax Tree](#the-abstract-syntax-tree)
     -   [Trying It All Together](#trying-it-all-together)
+    -   [Macro Rules](#macro-rules)
+    -   [The Abstract Syntax Tree - Demystified](#the-abstract-syntax-tree-demystified)
+    -   [High-Level Syntax vs. Low-level AST](#high-level-syntax-vs-low-level-ast)
+    -   [AST Literals](#ast-literals)
+    -   [Macros: The Building Blocks of Elixir](#macros-the-building-blocks-of-elixir)
 
 ### Chapter 1 - The Language of Macros
 
@@ -71,7 +76,7 @@ iex> quote do: div(10, 2)
 In most languages, we would have to parse a string expression into something digestible by our program. With Elixir, we can access
 the representation of expressions directly with macros."
 
-[First macro - `math.exs`](math.exs) 
+[First macro - `math.exs`](math/math.exs) 
 
 <details>
 <summary>math.exs</summary>
@@ -144,7 +149,168 @@ Which is not the expected result. For this, we use unquote:
 I assume from this then when you pass variables to a macro they need to be `unqoute`-d, incontrast to passing a value directly.
 Which I'm not following as Elixir is pass-by-value so wouldn't the value just be known?
 
-Yes that's correct because we are dealing with ASTs not the data it represents; therefore the pass-by-value argument doesn't hold.
+Turns out that yes that's correct because we are dealing with ASTs not the data it represents; therefore the pass-by-value argument doesn't hold.
 Much like interpolation from Ecto and the difference between `"Hello world"` and `"Hello #{world}`.
 
-Back to the `math.exs`example. 
+-   We know that macros receive the AST representation of the arguments.
+-   "To complete the macro, we used `quote` to return an AST for the caller to replace out `Math.say` invocations." I'm assuming by this that every macro needs some form of `quote`.
+
+#### Macro Rules
+
+-   **Rule 1: Don't write macros.**  We have to remember that writing code to produce code require special care. It's easy to get caught in a web of your own code generation. Too many macros can make debugging more difficult.
+
+-   **Rule: 2 Use macros gratuitously.** Metaprogramming is sometimes framed as complex and fragile as well as offering productive advantages in a fraction of the required code. It's important to keep this duality in mind when writing macros.
+
+#### The Abstract Syntax Tree - Demystified
+
+-   Every expression you write in Elixir breaks down to a three-element tuple in the AST.
+-   This uniform format makes pattern matching arguments a lot easier.
+-   Quoting a couple more complex expressions to see how entire Elixir prograns are structure in the AST.
+
+<details>
+<summary>(5 * 2 - 1 + 7)</summary>
+
+```elixir
+iex(1)> quote do: (5 * 2) - 1 + 7
+{:+, [context: Elixir, import: Kernel],
+ [
+   {:-, [context: Elixir, import: Kernel],
+    [{:*, [context: Elixir, import: Kernel], [5, 2]}, 1]},
+   7
+ ]}
+```
+
+</details>
+
+<details>
+<summary>MyModule</summary>
+
+```elixir
+iex(1)> quote do
+...(1)>   defmodule MyModule do
+...(1)>     def hello, do: "World"
+...(1)>   end
+...(1)> end
+{:defmodule, [context: Elixir, import: Kernel],
+ [
+   {:__aliases__, [alias: false], [:MyModule]},
+   [
+     do: {:def, [context: Elixir, import: Kernel],
+      [{:hello, [context: Elixir], Elixir}, [do: "World"]]}
+   ]
+ ]}
+```
+
+</details>
+
+-   A stacking tuple was produced from each quoted exoression. The first example shows the familiar structures used by our `Math.say` macro, but multiple tuples are stacked into an embedded tree to represent the entire expression. The result of the second example shows how an entire Eliir module represented by a simple AST.
+
+-   **All elixir code is represented as a series of three-element tuples with the following format:**
+
+    -   **The first element** is an atom denoting the funcation call, or another tuple, representing a nested node in the AST.
+    -   **The second element** represents metadata about the expression.
+    -   **The third element** is a list of arguments for the function call.
+
+-   Applying this to the AST of `(5 * 2) - 1 + 7` from before
+
+```elixir
+iex(1)> quote do: (5 * 2) - 1 + 7
+{:+, [context: Elixir, import: Kernel],
+ [
+   {:-, [context: Elixir, import: Kernel],
+    [{:*, [context: Elixir, import: Kernel], [5, 2]}, 1]},
+   7
+ ]}
+```
+
+-   An AST tree strunction of functions and arguments has been made. If we were to format this output into a more readable tree:
+
+```bash
++
+├── -
+│   ├── *
+│   │   ├── 5
+│   │   └── 7
+│   └── 1
+└── 7
+```
+
+-   It seems easiest to start from the end of the AST and work up. The root AST node is the `+` operator, and its arguments are
+    the number 7 combined with another nested node in the tree. We can see that the nested nodes contain out `(5 * 2)` expression,
+    whose results are applied to the `- 1` branch.
+-   `5 * 2` is syntactic sugar for `Kernel.*(5, 2)`. This means the `:*` atom is just a function call from the import of `Kernel` as
+    you can see from the AST output from before.
+
+#### High-Level Syntax vs. Low-level AST
+
+Comparing the AST from elixir to the source of Lisp. If you look closely, you can see how elixir operates at a layer just above this format.
+
+For example, Lisp source code:
+
+```lisp
+(+ (* 2 3) 1)
+```
+
+And Elixir from source to generated AST:
+
+```elixir
+quote do: 2 * 3 + 1
+{:+, _, [{:*, _, [2, 3]}, 1]}
+```
+
+If we compare the both you can see that the structure itself is nearly identical with only the syntax being different. The beauty here is that
+the transformation from high-level source to low-level AST requires only a `quote` invocation. On the contrary, with Lisp you have all the power
+of a programmable AST at the cost of a less natural and flexible syntax. José seperated the AST from the syntax, meaning we get the best of both worlds.
+
+#### AST Literals
+
+-   Playing with elixir source, sometimes the results of quoted expressions can appear confusing and irregular. This is because of literals. Literals
+    have the same representation within the AST and at high-lvel source. This includes atoms, ints, floats, lists, strings and any two-element tuples
+    containing the former types. Such as the following:
+
+```elixir
+iex> quote do: :atom
+:atom
+
+iex> quote do: 123
+123
+
+iex> quote do: [1, 2, 3]
+
+iex> quote do: {:ok, [1, 2, 3]}
+{:ok, [1, 2, 3]}
+```
+
+If you pass any of the example to a macro, the macro receives the literal arguments instead of an abstract representation.
+
+```elixir
+quoute do: %{a: 1, b: 2}
+{:%{}, [], [a: 1, b: 2]}
+
+iex> quoute do: Enum
+{:__aliases__, [alias: false], [:Enum]}
+```
+
+In these two examples we see that there are two different ways in which elixir types are represented in the AST. Some values are passed through as
+is, while more complex tuples are returned as a quoted expression. It's useful to keep literals in mind when writing macros to avoid confusion.
+
+#### Macros: The Building Blocks of Elixir
+
+-   Let's imagine that `unless` does not exist in the elixir language. `unless` is essentially the same as a negated if statement, e.g. unless(1 + 1 = 5) would return true.
+
+[Second macro](unless/unless.exs) - `unless.exs`
+
+<details>
+<summary>unless.exs</summary>
+
+```elixir
+defmodule ControlFlow do
+  defmacro unless(expression, do: block) do
+    quote do
+      if !unquote(expression), do: unquote(block)
+    end
+  end
+end
+```
+
+</details>

callers-context/.iex.exs

@@ -0,0 +1 @@
+c("callers_context.exs")

callers-context/callers_context.exs

@@ -0,0 +1,21 @@
+defmodule Mod do
+  defmacro definfo do
+    IO.puts("In macro's context (#{__MODULE__}).")
+
+    quote do
+      IO.puts("In caller's context (#{__MODULE__}).")
+
+      def friendly_info do
+        IO.puts("""
+        My name is #{__MODULE__}
+        My functions are #{inspect(__info__(:functions))}
+        """)
+      end
+    end
+  end
+end
+
+defmodule MyModule do
+  require Mod
+  Mod.definfo()
+end

.iex.exs renamed to math/.iex.exs

@@ -0,0 +1,2 @@
+c("unless.exs")
+require ControlFlow

math.exs renamed to math/math.exs

@@ -0,0 +1,7 @@
+defmodule ControlFlow do
+  defmacro unless(expression, do: block) do
+    quote do
+      if !unquote(expression), do: unquote(block)
+    end
+  end
+end