Advanced

defmodule Counter do
  use GenServer

  # Client API (public interface)
  def start_link(initial_value \\ 0) do
    GenServer.start_link(__MODULE__, initial_value, name: __MODULE__)  # => {:ok, #PID<...>} (starts GenServer process)
  end

  def increment do
    GenServer.cast(__MODULE__, :increment)  # => :ok (asynchronous, returns immediately)
  end

  def get do
    GenServer.call(__MODULE__, :get)  # => waits for reply from server
  end

  def add(value) do
    GenServer.call(__MODULE__, {:add, value})  # => returns new value after addition
  end

  # Server Callbacks (private implementation)
  @impl true
  def init(initial_value) do
    {:ok, initial_value}  # => {:ok, 0} (returns initial state to GenServer)
  end

  @impl true
  def handle_cast(:increment, state) do
    {:noreply, state + 1}  # => {:noreply, 1} (updates state asynchronously, no reply to caller)
  end

  @impl true
  def handle_call(:get, _from, state) do
    {:reply, state, state}  # => {:reply, 2, 2} (returns current state, state unchanged)
  end

  @impl true
  def handle_call({:add, value}, _from, state) do
    new_state = state + value  # => new_state is 7 (2 + 5)
    {:reply, new_state, new_state}  # => {:reply, 7, 7} (returns new value and updates state)
  end
end

{:ok, _pid} = Counter.start_link(0)  # Start with state = 0
Counter.increment()  # State becomes 1
Counter.increment()  # State becomes 2
Counter.get()  # => 2
Counter.add(5)  # => 7 (returns new value)
Counter.get()  # => 7

defmodule UserRegistry do
  use GenServer

  # Client API
  def start_link(_opts) do
    GenServer.start_link(__MODULE__, %{}, name: __MODULE__)
  end

  def register(name, data) do
    GenServer.call(__MODULE__, {:register, name, data})
  end

  def lookup(name) do
    GenServer.call(__MODULE__, {:lookup, name})
  end

  def list_all do
    GenServer.call(__MODULE__, :list_all)
  end

  # Server callbacks
  @impl true
  def init(_initial_state) do
    {:ok, %{}}  # => {:ok, %{}} (empty map as initial state)
  end

  @impl true
  def handle_call({:register, name, data}, _from, state) do
    new_state = Map.put(state, name, data)  # => %{"alice" => %{age: 30, ...}}
    {:reply, :ok, new_state}  # => {:reply, :ok, new_state} (confirms registration)
  end

  @impl true
  def handle_call({:lookup, name}, _from, state) do
    result = Map.get(state, name, :not_found)  # => %{age: 30, ...} or :not_found
    {:reply, result, state}  # => {:reply, result, state} (state unchanged)
  end

  @impl true
  def handle_call(:list_all, _from, state) do
    {:reply, state, state}  # => {:reply, %{"alice" => ..., "bob" => ...}, state}
  end
end

{:ok, _pid} = UserRegistry.start_link([])
UserRegistry.register("alice", %{age: 30, email: "alice@example.com"})
UserRegistry.register("bob", %{age: 25, email: "bob@example.com"})
UserRegistry.lookup("alice")  # => %{age: 30, email: "alice@example.com"}
UserRegistry.lookup("charlie")  # => :not_found
UserRegistry.list_all()  # => %{"alice" => %{...}, "bob" => %{...}}

defmodule Account do
  use GenServer

  # Struct to represent state
  defstruct balance: 0, transactions: []

  # Client API
  def start_link(initial_balance) do
    GenServer.start_link(__MODULE__, initial_balance)  # => {:ok, #PID<...>}
  end

  def deposit(pid, amount) when amount > 0 do
    GenServer.call(pid, {:deposit, amount})
  end

  def withdraw(pid, amount) when amount > 0 do
    GenServer.call(pid, {:withdraw, amount})
  end

  def balance(pid) do
    GenServer.call(pid, :balance)
  end

  def transaction_history(pid) do
    GenServer.call(pid, :transactions)
  end

  # Server callbacks
  @impl true
  def init(initial_balance) do
    state = %__MODULE__{balance: initial_balance}  # => %Account{balance: 1000, transactions: []}
    {:ok, state}  # => {:ok, %Account{...}}
  end

  @impl true
  def handle_call({:deposit, amount}, _from, state) do
    new_balance = state.balance + amount  # => 1500 (1000 + 500)
    transaction = {:deposit, amount, DateTime.utc_now()}  # => {:deposit, 500, ~U[...]}
    new_state = %{state | balance: new_balance, transactions: [transaction | state.transactions]}  # => %Account{balance: 1500, transactions: [{:deposit, 500, ...}]}
    {:reply, {:ok, new_balance}, new_state}  # => {:reply, {:ok, 1500}, new_state}
  end

  @impl true
  def handle_call({:withdraw, amount}, _from, state) do
    if state.balance >= amount do
      new_balance = state.balance - amount  # => 1300 (1500 - 200)
      transaction = {:withdrawal, amount, DateTime.utc_now()}  # => {:withdrawal, 200, ~U[...]}
      new_state = %{state | balance: new_balance, transactions: [transaction | state.transactions]}  # => %Account{balance: 1300, transactions: [{:withdrawal, 200, ...}, ...]}
      {:reply, {:ok, new_balance}, new_state}  # => {:reply, {:ok, 1300}, new_state}
    else
      {:reply, {:error, :insufficient_funds}, state}  # => {:reply, {:error, :insufficient_funds}, state} (state unchanged)
    end
  end

  @impl true
  def handle_call(:balance, _from, state) do
    {:reply, state.balance, state}  # => {:reply, 1300, state} (state unchanged)
  end

  @impl true
  def handle_call(:transactions, _from, state) do
    {:reply, Enum.reverse(state.transactions), state}  # => {:reply, [{:deposit, 500, ...}, {:withdrawal, 200, ...}], state}
  end
end

{:ok, account} = Account.start_link(1000)
Account.deposit(account, 500)  # => {:ok, 1500}
Account.withdraw(account, 200)  # => {:ok, 1300}
Account.withdraw(account, 2000)  # => {:error, :insufficient_funds}
Account.balance(account)  # => 1300
Account.transaction_history(account)  # => [{:deposit, 500, ...}, {:withdrawal, 200, ...}]

defmodule TodoList do
  use GenServer

  defstruct items: [], next_id: 1

  def start_link do
    GenServer.start_link(__MODULE__, [])
  end

  def add_item(pid, description) do
    GenServer.call(pid, {:add, description})
  end

  def complete_item(pid, id) do
    GenServer.call(pid, {:complete, id})
  end

  def list_items(pid) do
    GenServer.call(pid, :list)
  end

  @impl true
  def init(_) do
    {:ok, %__MODULE__{}}
  end

  @impl true
  def handle_call({:add, description}, _from, state) do
    item = %{id: state.next_id, description: description, completed: false}
    new_items = [item | state.items]
    new_state = %{state | items: new_items, next_id: state.next_id + 1}
    {:reply, {:ok, item.id}, new_state}
  end

  @impl true
  def handle_call({:complete, id}, _from, state) do
    new_items = Enum.map(state.items, fn item ->
      if item.id == id, do: %{item | completed: true}, else: item
    end)
    new_state = %{state | items: new_items}
    {:reply, :ok, new_state}
  end

  @impl true
  def handle_call(:list, _from, state) do
    {:reply, Enum.reverse(state.items), state}
  end
end

{:ok, todo} = TodoList.start_link()
{:ok, id1} = TodoList.add_item(todo, "Buy groceries")
{:ok, id2} = TodoList.add_item(todo, "Write code")
TodoList.complete_item(todo, id1)
TodoList.list_items(todo)  # => [%{id: 1, description: "Buy groceries", completed: true}, ...]

defmodule ResilientServer do
  use GenServer

  def start_link do
    GenServer.start_link(__MODULE__, [])  # => {:ok, #PID<...>}
  end

  def do_work(pid) do
    GenServer.call(pid, :work, 10_000)  # => 10 second timeout, returns :done
  end

  def slow_work(pid) do
    GenServer.call(pid, :slow_work, 1_000)  # => 1 second timeout (will raise timeout error)
  end

  def crash_me(pid) do
    GenServer.cast(pid, :crash)  # => :ok (async, server will crash)
  end

  @impl true
  def init(_) do
    {:ok, %{}}  # => {:ok, %{}} (empty map as state)
  end

  @impl true
  def handle_call(:work, _from, state) do
    # Simulate work
    :timer.sleep(500)  # => sleep 500ms
    {:reply, :done, state}  # => {:reply, :done, state} (completes within timeout)
  end

  @impl true
  def handle_call(:slow_work, _from, state) do
    # Too slow, will timeout
    :timer.sleep(2_000)  # => sleep 2s (exceeds 1s timeout)
    {:reply, :done, state}  # => never reached (timeout occurs first)
  end

  @impl true
  def handle_cast(:crash, _state) do
    raise "Server crashed!"  # => raises error, server terminates
  end

  # Handle unexpected messages
  @impl true
  def handle_info(msg, state) do
    Logger.warn("Unexpected message: #{inspect(msg)}")  # => logs warning
    {:noreply, state}  # => {:noreply, state} (ignores message, continues)
  end

  # Stop callback
  @impl true
  def terminate(reason, _state) do
    Logger.info("Server terminating: #{inspect(reason)}")  # => logs termination reason
    :ok  # => :ok (cleanup complete)
  end
end

{:ok, pid} = ResilientServer.start_link()
ResilientServer.do_work(pid)  # => :done

try do
  ResilientServer.slow_work(pid)  # Timeout after 1 second
rescue
  e in RuntimeError -> IO.puts("Caught timeout: #{inspect(e)}")
end

defmodule SafeServer do
  use GenServer

  def start_link do
    GenServer.start_link(__MODULE__, [])  # => {:ok, #PID<...>}
  end

  def divide(pid, a, b) do
    GenServer.call(pid, {:divide, a, b})  # => calls division handler
  end

  @impl true
  def init(_) do
    {:ok, %{}}  # => {:ok, %{}}
  end

  @impl true
  def handle_call({:divide, a, b}, _from, state) do
    try do
      result = a / b  # => 5.0 or raises ArithmeticError
      {:reply, {:ok, result}, state}  # => {:reply, {:ok, 5.0}, state}
    rescue
      ArithmeticError ->  # => catches division by zero
        {:reply, {:error, :division_by_zero}, state}  # => {:reply, {:error, :division_by_zero}, state}
    end
  end

  # Alternative: return error tuple without exceptions
  def handle_call_safe({:divide, _a, 0}, _from, state) do
    {:reply, {:error, :division_by_zero}, state}  # => pattern matches zero divisor
  end
  def handle_call_safe({:divide, a, b}, _from, state) do
    {:reply, {:ok, a / b}, state}  # => {:reply, {:ok, result}, state}
  end
end

{:ok, pid} = SafeServer.start_link()  # => {:ok, #PID<...>}
SafeServer.divide(pid, 10, 2)  # => {:ok, 5.0}
SafeServer.divide(pid, 10, 0)  # => {:error, :division_by_zero}

# Named GenServer - Singleton pattern (one instance per application)
defmodule Cache do
  use GenServer  # => imports GenServer behavior

  # Start with name registration
  def start_link(_opts) do
    GenServer.start_link(__MODULE__, %{}, name: __MODULE__)  # => {:ok, #PID<...>} with name: Cache
    # => name: __MODULE__ registers process globally as Cache atom
    # => Now can reference as Cache instead of PID
  end

  # Client API uses module name, not PID
  def put(key, value) do
    GenServer.cast(__MODULE__, {:put, key, value})  # => :ok (sends async message to Cache process)
    # => __MODULE__ resolves to Cache atom (finds PID via process registry)
    # => No need to pass PID around!
  end

  def get(key) do
    GenServer.call(__MODULE__, {:get, key})  # => returns value or nil
    # => Synchronous call to Cache process (found by name)
  end

  def delete(key) do
    GenServer.cast(__MODULE__, {:delete, key})  # => :ok (async delete)
  end

  # Server Callbacks
  @impl true
  def init(_) do
    {:ok, %{}}  # => {:ok, %{}} (starts with empty map)
    # => State is in-memory cache (key-value pairs)
  end

  @impl true
  def handle_cast({:put, key, value}, state) do
    {:noreply, Map.put(state, key, value)}  # => {:noreply, %{user_1: %{name: "Alice"}}}
    # => Updates state with new key-value pair
  end

  @impl true
  def handle_cast({:delete, key}, state) do
    {:noreply, Map.delete(state, key)}  # => {:noreply, %{}} (removes key)
    # => State updated, key removed
  end

  @impl true
  def handle_call({:get, key}, _from, state) do
    {:reply, Map.get(state, key), state}  # => {:reply, %{name: "Alice"}, state}
    # => Returns value from cache, state unchanged
  end
end

# Usage: Singleton cache (one instance for whole application)
{:ok, _pid} = Cache.start_link([])  # => {:ok, #PID<...>} (Cache registered globally)
Cache.put(:user_1, %{name: "Alice"})  # => :ok (stores in cache)
# => State now: %{user_1: %{name: "Alice"}}
Cache.get(:user_1)  # => %{name: "Alice"} (retrieves from cache)
Cache.delete(:user_1)  # => :ok (removes from cache)
# => State now: %{}
Cache.get(:user_1)  # => nil (key not found)

# Named GenServer - Multiple instances with different names
defmodule Worker do
  use GenServer

  def start_link(name) do
    GenServer.start_link(__MODULE__, [], name: name)  # => {:ok, #PID<...>} with name: :worker_1, :worker_2, etc.
    # => Each instance has unique name (passed as argument)
    # => Can start multiple Workers with different names
  end

  def ping(name) do
    GenServer.call(name, :ping)  # => :pong (calls specific worker by name)
    # => name is :worker_1 or :worker_2 (looks up PID by name)
  end

  @impl true
  def init(_) do
    {:ok, []}  # => {:ok, []} (empty list as state)
  end

  @impl true
  def handle_call(:ping, _from, state) do
    {:reply, :pong, state}  # => {:reply, :pong, []} (simple ping response)
  end
end

# Usage: Multiple named workers (each with unique name)
{:ok, _} = Worker.start_link(:worker_1)  # => {:ok, #PID<...>} (worker_1 registered)
{:ok, _} = Worker.start_link(:worker_2)  # => {:ok, #PID<...>} (worker_2 registered)
# => Two separate Worker processes, each with unique name
Worker.ping(:worker_1)  # => :pong (pings worker_1 by name)
Worker.ping(:worker_2)  # => :pong (pings worker_2 by name)
# => Each worker responds independently

# Naming comparison:
# PID-based (without names):
#   {:ok, pid} = GenServer.start_link(Worker, [])  # => must store/pass pid everywhere
#   GenServer.call(pid, :ping)  # => pass pid to every call
#
# Name-based (with names):
#   GenServer.start_link(Worker, [], name: :worker_1)  # => register with name once
#   GenServer.call(:worker_1, :ping)  # => reference by name anywhere
#
# Benefits of naming:
# ✅ No need to pass PIDs around (cleaner API)
# ✅ Process discovery (find by name)
# ✅ Singleton pattern (one instance per name)
# ⚠️ Names are global atoms (limited to ~1 million atoms)
# ⚠️ Name conflicts cause crashes (can't register same name twice)

# Best Practice 1: Separate client API from server callbacks
defmodule BestPractices do
  use GenServer  # => imports GenServer behavior

  # ✅ CLIENT API - Public interface (synchronous functions)
  # Users call these functions (they DON'T call handle_call directly)
  def start_link(opts \\ []) do
    GenServer.start_link(__MODULE__, opts, name: __MODULE__)  # => {:ok, #PID<...>}
  end

  def create_user(name, email) do
    GenServer.call(__MODULE__, {:create_user, name, email})  # => {:ok, user} or {:error, reason}
    # => Blocks until server replies
  end

  def get_user(id) do
    GenServer.call(__MODULE__, {:get_user, id})  # => user map or nil
  end
  # => Client API is CLEAN - no process details, just business operations

  # ✅ SERVER CALLBACKS - Private implementation (handle_* functions)
  # These run inside GenServer process, users never call them directly

  # Best Practice 2: Use @impl for callback clarity
  @impl true  # => ✅ declares this is GenServer.init/1 callback (compiler verifies signature)
  def init(_opts) do
    # Initialize state
    state = %{users: %{}, next_id: 1}  # => initial state structure
    {:ok, state}  # => {:ok, %{users: %{}, next_id: 1}}
  end
  # => @impl ensures callback signature matches behavior (compile-time check)

  @impl true
  def handle_call({:create_user, name, email}, _from, state) do
    # ✅ Best Practice 3: Keep callbacks simple - delegate to private helpers
    {reply, new_state} = do_create_user(name, email, state)  # => delegates business logic
    {:reply, reply, new_state}  # => {:reply, {:ok, user}, new_state}
  end
  # => Callback is THIN - just message routing, no business logic

  @impl true
  def handle_call({:get_user, id}, _from, state) do
    user = Map.get(state.users, id)  # => retrieves user or nil
    {:reply, user, state}  # => {:reply, %{id: 1, name: "Alice", ...}, state}
  end

  # ✅ Best Practice 4: Extract complex logic to private functions
  defp do_create_user(name, email, state) do
    if valid_email?(email) do  # => validation check
      user = %{id: state.next_id, name: name, email: email}  # => creates user map
      new_users = Map.put(state.users, state.next_id, user)  # => adds to users map
      new_state = %{state | users: new_users, next_id: state.next_id + 1}  # => updates state immutably
      {{:ok, user}, new_state}  # => returns success tuple + new state
    else
      {{:error, :invalid_email}, state}  # => returns error tuple + unchanged state
    end
  end
  # => Private helper is TESTABLE - pure function (no side effects)

  defp valid_email?(email), do: String.contains?(email, "@")  # => simple validation

  # ✅ Best Practice 5: Use typespec for documentation
  @spec create_user(String.t(), String.t()) :: {:ok, map()} | {:error, atom()}
  # => Documents function signature and return types (Dialyzer can verify)
end

# Testing GenServer with callbacks
defmodule BestPracticesTest do
  use ExUnit.Case  # => imports ExUnit test DSL

  setup do  # => runs before each test
    {:ok, _pid} = BestPractices.start_link()  # => starts GenServer for test
    :ok  # => return :ok (no context needed)
  end
  # => Each test gets fresh GenServer instance

  test "creates user with valid email" do
    assert {:ok, user} = BestPractices.create_user("Alice", "alice@example.com")  # => calls client API
    # => GenServer.call → handle_call → do_create_user → validation → success
    assert user.name == "Alice"  # => verifies user data
  end

  test "rejects invalid email" do
    assert {:error, :invalid_email} = BestPractices.create_user("Bob", "invalid")  # => validation fails
    # => GenServer.call → handle_call → do_create_user → validation fails → error
  end

  test "retrieves created user" do
    {:ok, user} = BestPractices.create_user("Charlie", "charlie@example.com")  # => creates user
    assert BestPractices.get_user(user.id) == user  # => retrieves created user
    # => State persists between calls (same GenServer process)
  end
end

# ✅ Best Practice 6: Extract business logic to pure modules (advanced pattern)
defmodule UserLogic do
  # Pure functions - NO side effects (no GenServer, no state, no I/O)
  # Easy to test without processes

  def create_user(users, next_id, name, email) do
    # => Takes explicit arguments (not hidden state)
    if valid_email?(email) do
      user = %{id: next_id, name: name, email: email}  # => creates user
      new_users = Map.put(users, next_id, user)  # => updates users map
      {{:ok, user}, new_users, next_id + 1}  # => returns result, new users, new ID
    else
      {{:error, :invalid_email}, users, next_id}  # => error with unchanged state
    end
  end
  # => PURE function: same inputs always produce same outputs
  # => Can test with simple assertions (no process spawning)

  defp valid_email?(email), do: String.contains?(email, "@")
end

# GenServer as thin wrapper around pure business logic
defmodule UserServer do
  use GenServer

  # Client API
  def start_link(_), do: GenServer.start_link(__MODULE__, %{}, name: __MODULE__)  # => {:ok, #PID<...>}
  def create_user(name, email), do: GenServer.call(__MODULE__, {:create, name, email})  # => calls server

  # Server callbacks
  @impl true
  def init(_), do: {:ok, %{users: %{}, next_id: 1}}  # => initial state

  @impl true
  def handle_call({:create, name, email}, _from, state) do
    # ✅ Delegate to pure business logic (UserLogic module)
    {reply, new_users, new_next_id} = UserLogic.create_user(state.users, state.next_id, name, email)
    # => UserLogic is PURE - takes values, returns values (no process magic)
    new_state = %{state | users: new_users, next_id: new_next_id}  # => reconstructs state from pure results
    {:reply, reply, new_state}  # => returns to caller
  end
  # => GenServer handles ONLY concurrency and state management
  # => UserLogic handles ONLY business rules and validation
  # => Clear separation of concerns!
end

# Benefits of this pattern:
# ✅ Test UserLogic without spawning processes (fast, simple unit tests)
# ✅ Test UserServer for concurrency bugs (slow, complex integration tests)
# ✅ Reuse UserLogic in other contexts (web controller, CLI, background job)
# ✅ Clear separation: GenServer = concurrency, Pure modules = business logic

defmodule Worker do
  use GenServer  # => imports GenServer behavior

  # Client API
  def start_link(id) do
    GenServer.start_link(__MODULE__, id, name: via_tuple(id))  # => {:ok, #PID<...>} (registers worker with Registry)
  end

  def crash(id) do
    GenServer.cast(via_tuple(id), :crash)  # => :ok (async crash request)
  end

  def ping(id) do
    GenServer.call(via_tuple(id), :ping)  # => {:pong, 1} (synchronous ping)
  end

  defp via_tuple(id), do: {:via, Registry, {WorkerRegistry, id}}  # => {:via, Registry, {WorkerRegistry, 1}} (name registration via Registry)

  # Server Callbacks
  @impl true
  def init(id) do
    IO.puts("Worker #{id} starting...")  # => prints "Worker 1 starting..." to console
    {:ok, id}  # => {:ok, 1} (returns worker ID as initial state)
  end

  @impl true
  def handle_call(:ping, _from, id) do
    {:reply, {:pong, id}, id}  # => {:reply, {:pong, 1}, 1} (replies with worker ID, state unchanged)
  end

  @impl true
  def handle_cast(:crash, _state) do
    raise "Worker crashed!"  # => raises RuntimeError, GenServer terminates (supervisor will restart)
  end
end

defmodule MySupervisor do
  use Supervisor  # => imports Supervisor behavior

  def start_link(_opts) do
    Supervisor.start_link(__MODULE__, :ok, name: __MODULE__)  # => {:ok, #PID<...>} (starts supervisor with name MySupervisor)
  end

  @impl true
  def init(:ok) do
    # Start Registry for worker names
    children = [
      {Registry, keys: :unique, name: WorkerRegistry},  # => Registry child spec (started first)
      # Worker children
      {Worker, 1},  # => starts Worker with id=1
      {Worker, 2},  # => starts Worker with id=2
      {Worker, 3}   # => starts Worker with id=3
    ]

    # :one_for_one strategy - restart only crashed child
    Supervisor.init(children, strategy: :one_for_one)  # => {:ok, {supervisor_flags, children}} (configures restart strategy)
    # => :one_for_one means if Worker 2 crashes, only Worker 2 restarts (Workers 1 and 3 unaffected)
  end
end

# Start supervision tree
{:ok, _pid} = MySupervisor.start_link([])  # => {:ok, #PID<...>} (supervisor starts all children)
# => Prints:
# => Worker 1 starting...
# => Worker 2 starting...
# => Worker 3 starting...

Worker.ping(1)  # => {:pong, 1} (Worker 1 is alive)
Worker.crash(2)  # => :ok (Worker 2 crashes and supervisor restarts it)
# => Supervisor detects crash, restarts Worker 2
# => Prints: Worker 2 starting... (restart message)
:timer.sleep(100)  # => wait for restart to complete
Worker.ping(2)  # => {:pong, 2} (Worker 2 alive again with clean state!)
# => Demonstrates fault tolerance: crashed worker automatically recovers

# Child specification structure
child_spec = %{
  id: Worker,  # => unique identifier for child (used to identify which child crashed)
  start: {Worker, :start_link, [1]},  # => {Module, function, args} tuple for starting child
  restart: :permanent,  # => :permanent (always restart), :temporary (never restart), :transient (restart only on abnormal exit)
  shutdown: 5000,       # => 5000ms wait for graceful shutdown before force kill
  type: :worker         # => :worker or :supervisor (for supervision tree organization)
}
# => This spec defines HOW supervisor manages this child (restart policy, shutdown timeout, etc.)

# :one_for_one - Independent workers, restart crashed child only
defmodule OneForOneSupervisor do
  use Supervisor  # => imports Supervisor behavior

  def start_link(_opts) do
    Supervisor.start_link(__MODULE__, :ok)  # => {:ok, #PID<...>}
  end

  @impl true
  def init(:ok) do
    children = [
      {Worker, 1},  # => Worker 1 (independent)
      {Worker, 2},  # => Worker 2 (independent)
      {Worker, 3}   # => Worker 3 (independent)
    ]
    # => Workers are INDEPENDENT - Worker 2 crash doesn't affect Workers 1 or 3

    Supervisor.init(children, strategy: :one_for_one)  # => {:ok, {supervisor_flags, children}}
    # => :one_for_one means: if Worker 2 crashes, ONLY Worker 2 restarts
    # => Workers 1 and 3 keep running with their current state
    # => Use case: stateless workers, connection pool workers, task processors
  end
end

# :one_for_all - Tightly coupled workers, restart ALL on any crash
defmodule OneForAllSupervisor do
  use Supervisor

  def start_link(_opts) do
    Supervisor.start_link(__MODULE__, :ok)  # => {:ok, #PID<...>}
  end

  @impl true
  def init(:ok) do
    children = [
      {DatabaseConnection, []},  # => Must be up for Cache and APIServer
      {Cache, []},               # => Depends on database (caches DB queries)
      {APIServer, []}            # => Depends on cache (serves cached data)
    ]
    # => Workers are TIGHTLY COUPLED - if any crashes, ALL must restart for consistency

    Supervisor.init(children, strategy: :one_for_all)  # => {:ok, {supervisor_flags, children}}
    # => :one_for_all means: if DatabaseConnection crashes, ALL THREE restart in order
    # => Why? Cache has stale DB state, APIServer has stale cache state
    # => Restart order: DatabaseConnection → Cache → APIServer (clean slate for all)
    # => Use case: workers with shared mutable state, game sessions, synchronized protocols
  end
end

# :rest_for_one - Startup-order dependencies, restart crashed child + later siblings
defmodule RestForOneSupervisor do
  use Supervisor

  def start_link(_opts) do
    Supervisor.start_link(__MODULE__, :ok)  # => {:ok, #PID<...>}
  end

  @impl true
  def init(:ok) do
    children = [
      {DatabaseConnection, []},  # => Position 1: Started first
      {Cache, []},               # => Position 2: Depends on DatabaseConnection
      {APIServer, []}            # => Position 3: Depends on Cache
    ]
    # => STARTUP ORDER MATTERS - later children depend on earlier children

    Supervisor.init(children, strategy: :rest_for_one)  # => {:ok, {supervisor_flags, children}}
    # => :rest_for_one means: restart crashed child + all LATER siblings
    # => If DatabaseConnection (pos 1) crashes: restart DatabaseConnection, Cache, APIServer
    # => If Cache (pos 2) crashes: restart Cache, APIServer (DatabaseConnection unaffected)
    # => If APIServer (pos 3) crashes: restart APIServer only (nothing depends on it)
    # => Use case: initialization pipelines, dependent services, layered architectures
  end
end

# Supervisor with restart limits (prevent crash loops)
defmodule ConfiguredSupervisor do
  use Supervisor

  def start_link(_opts) do
    Supervisor.start_link(__MODULE__, :ok)  # => {:ok, #PID<...>}
  end

  @impl true
  def init(:ok) do
    children = [{Worker, 1}]  # => single worker child

    Supervisor.init(children,
      strategy: :one_for_one,  # => restart only crashed child
      max_restarts: 3,         # => allow MAX 3 restarts...
      max_seconds: 5           # => ...within 5 second window
    )
    # => Restart budget: 3 restarts per 5 seconds
    # => Example timeline:
    # => t=0s: Worker crashes (1st restart) ✓
    # => t=2s: Worker crashes (2nd restart) ✓
    # => t=4s: Worker crashes (3rd restart) ✓
    # => t=5s: Worker crashes (4th restart in 5s) ✗ SUPERVISOR CRASHES
    # => Supervisor crashes → escalates to parent supervisor (up supervision tree)
    # => Prevents infinite crash loops from depleting system resources
    # => If limit exceeded, supervisor itself crashes (escalates to parent)
  end
end

# Example usage comparison
{:ok, one_for_one} = OneForOneSupervisor.start_link([])  # => starts 3 independent workers
# => Worker 2 crashes → only Worker 2 restarts

{:ok, one_for_all} = OneForAllSupervisor.start_link([])  # => starts 3 dependent workers
# => DatabaseConnection crashes → ALL 3 restart (DatabaseConnection → Cache → APIServer)

{:ok, rest_for_one} = RestForOneSupervisor.start_link([])  # => starts 3 workers with startup dependencies
# => Cache crashes → Cache and APIServer restart (DatabaseConnection keeps running)

defmodule DynamicWorker do
  use GenServer  # => imports GenServer behavior

  def start_link(id) do
    GenServer.start_link(__MODULE__, id)  # => {:ok, #PID<...>} (starts worker with id as state)
  end

  def get_id(pid) do
    GenServer.call(pid, :get_id)  # => synchronous call to retrieve worker ID
  end

  @impl true
  def init(id) do
    IO.puts("DynamicWorker #{id} started")  # => prints "DynamicWorker 1 started"
    {:ok, id}  # => {:ok, 1} (stores id as state)
  end

  @impl true
  def handle_call(:get_id, _from, id) do
    {:reply, id, id}  # => {:reply, 1, 1} (returns id, state unchanged)
  end
end

defmodule MyDynamicSupervisor do
  use DynamicSupervisor  # => imports DynamicSupervisor behavior

  def start_link(_opts) do
    DynamicSupervisor.start_link(__MODULE__, :ok, name: __MODULE__)  # => {:ok, #PID<...>} (starts supervisor with NO children initially)
  end
  # => Unlike static Supervisor, DynamicSupervisor starts with ZERO children

  def start_worker(id) do
    child_spec = {DynamicWorker, id}  # => child spec: {module, arg}
    DynamicSupervisor.start_child(__MODULE__, child_spec)  # => {:ok, #PID<...>} (starts child on demand)
  end
  # => Spawns NEW worker process at runtime (not compile time)

  def stop_worker(pid) do
    DynamicSupervisor.terminate_child(__MODULE__, pid)  # => :ok (stops specific child by PID)
  end
  # => Gracefully stops worker, supervisor removes it from child list

  def count_workers do
    DynamicSupervisor.count_children(__MODULE__)  # => %{active: 3, specs: 3, supervisors: 0, workers: 3}
  end
  # => Returns count of currently supervised children

  @impl true
  def init(:ok) do
    DynamicSupervisor.init(strategy: :one_for_one)  # => {:ok, supervisor_flags}
  end
  # => Configured but starts with ZERO children (children added via start_child)
end

# Start supervisor (zero children initially)
{:ok, _sup} = MyDynamicSupervisor.start_link([])  # => {:ok, #PID<...>} (supervisor running, no children)

# Add workers dynamically at runtime
{:ok, worker1} = MyDynamicSupervisor.start_worker(1)  # => {:ok, #PID<0.123.0>} (worker 1 started)
# => Prints: DynamicWorker 1 started
{:ok, worker2} = MyDynamicSupervisor.start_worker(2)  # => {:ok, #PID<0.124.0>} (worker 2 started)
# => Prints: DynamicWorker 2 started
{:ok, worker3} = MyDynamicSupervisor.start_worker(3)  # => {:ok, #PID<0.125.0>} (worker 3 started)
# => Prints: DynamicWorker 3 started
# => Now supervisor has 3 children (added at runtime, not init time)

DynamicWorker.get_id(worker1)  # => 1 (retrieves worker 1's ID)
DynamicWorker.get_id(worker2)  # => 2 (retrieves worker 2's ID)

MyDynamicSupervisor.count_workers()  # => %{active: 3, specs: 3, supervisors: 0, workers: 3}
# => 3 workers currently supervised

MyDynamicSupervisor.stop_worker(worker2)  # => :ok (terminates worker 2)
# => Worker 2 process stopped and removed from supervisor
MyDynamicSupervisor.count_workers()  # => %{active: 2, specs: 2, supervisors: 0, workers: 2}
# => Now only 2 workers (worker1 and worker3)

# Connection Pool Example - Practical Use Case
defmodule Connection do
  use GenServer

  def start_link(url) do
    GenServer.start_link(__MODULE__, url)  # => {:ok, #PID<...>}
  end

  @impl true
  def init(url) do
    # Simulate connection establishment
    {:ok, %{url: url, connected: true}}  # => {:ok, %{url: "db://localhost", connected: true}}
  end
  # => In real pool: connect to database, open socket, authenticate
end

defmodule ConnectionPool do
  use DynamicSupervisor

  def start_link(_opts) do
    DynamicSupervisor.start_link(__MODULE__, :ok, name: __MODULE__)  # => {:ok, #PID<...>} (pool starts with zero connections)
  end

  def add_connection(url) do
    DynamicSupervisor.start_child(__MODULE__, {Connection, url})  # => {:ok, #PID<...>} (adds connection to pool)
  end
  # => Spawns new connection process on demand (e.g., high load)

  def remove_connection(pid) do
    DynamicSupervisor.terminate_child(__MODULE__, pid)  # => :ok (removes idle connection)
  end
  # => Reduces pool size when load decreases

  @impl true
  def init(:ok) do
    DynamicSupervisor.init(
      strategy: :one_for_one,  # => restart crashed connection only (others unaffected)
      max_restarts: 5,         # => allow 5 connection failures...
      max_seconds: 10          # => ...within 10 seconds before pool crashes
    )
    # => Prevents cascading failures: if DB unreachable, pool crashes (supervisor restarts pool with fresh state)
  end
end

# Usage: Dynamic connection pool
{:ok, _} = ConnectionPool.start_link([])  # => {:ok, #PID<...>} (pool starts with zero connections)
{:ok, conn1} = ConnectionPool.add_connection("db://localhost")  # => {:ok, #PID<...>} (connection 1 added)
# => Connection to local DB established
{:ok, conn2} = ConnectionPool.add_connection("db://remote")  # => {:ok, #PID<...>} (connection 2 added)
# => Connection to remote DB established
# => Pool now has 2 active connections
ConnectionPool.remove_connection(conn1)  # => :ok (closes local connection)
# => Pool now has 1 active connection (remote only)
# => Use case: scale pool up/down based on traffic, remove idle connections to save resources

# Mix Project - Defines application metadata
defmodule MyApp.MixProject do
  use Mix.Project  # => imports Mix.Project behavior

  def project do
    [
      app: :my_app,  # => application name (atom, must match module name)
      version: "0.1.0"  # => semantic version
    ]
  end
  # => Defines build metadata for mix (dependencies, compilers, paths)

  # Application callback - defines OTP application
  def application do
    [
      extra_applications: [:logger],  # => include Logger app (built-in Elixir app)
      mod: {MyApp.Application, []}    # => {Module, args} - application starts by calling Module.start/2 with args
    ]
  end
  # => When you run "mix run", OTP starts MyApp.Application.start(:normal, [])
  # => extra_applications ensures Logger starts BEFORE MyApp
end

# Application Module - OTP application behavior
defmodule MyApp.Application do
  use Application  # => imports Application behavior (requires start/2 and stop/1 callbacks)

  @impl true
  def start(_type, _args) do
    # => _type is :normal (regular start), :takeover (distributed failover), or :failover (node takeover)
    # => _args is [] (from mod: {MyApp.Application, []})

    # Define supervision tree children
    children = [
      {Registry, keys: :unique, name: MyApp.Registry},  # => Registry child spec (process registry)
      MyApp.Cache,  # => shorthand for {MyApp.Cache, []} (assumes start_link/1 function exists)
      {MyApp.Worker, 1},  # => Worker with arg=1
      {MyApp.Worker, 2}   # => Worker with arg=2
    ]
    # => Children start in ORDER: Registry → Cache → Worker 1 → Worker 2

    opts = [strategy: :one_for_one, name: MyApp.Supervisor]  # => supervisor options
    Supervisor.start_link(children, opts)  # => {:ok, #PID<...>} (starts root supervisor)
    # => This PID is the APPLICATION's root supervisor (if it crashes, application crashes)
  end
  # => start/2 MUST return {:ok, pid} or {:error, reason}
  # => The pid is the supervision tree root (OTP monitors it for application health)

  @impl true
  def stop(_state) do
    # => Called when application stops (before supervision tree shutdown)
    # => _state is the PID returned from start/2
    # Cleanup logic (close file handles, flush logs, graceful degradation)
    IO.puts("Application stopping...")  # => cleanup example
    :ok  # => must return :ok
  end
  # => After stop/1, OTP terminates supervision tree (children stop in reverse order)
  # => Shutdown order: Worker 2 → Worker 1 → Cache → Registry
end

# Application Configuration Access
defmodule MyApp.Config do
  def api_key, do: Application.get_env(:my_app, :api_key)  # => retrieves :api_key from :my_app config
  # => Returns nil if not configured (use pattern matching to handle)

  def timeout, do: Application.get_env(:my_app, :timeout, 3000)  # => returns :timeout or default 3000ms
  # => Third argument is DEFAULT value (returned if :timeout not configured)
end
# => Access config set in config/config.exs:
# => config :my_app, api_key: "secret", timeout: 5000

# Application Dependencies (in mix.exs)
def application do
  [
    mod: {MyApp.Application, []},  # => application module and start args
    extra_applications: [:logger, :crypto],  # => built-in Erlang/Elixir apps to start BEFORE MyApp
    # => :logger (Elixir), :crypto (Erlang) start first
    applications: [:httpoison]  # => third-party dependencies to start BEFORE MyApp
    # => :httpoison must start before MyApp (declared dependency)
  ]
  # => Start order: :logger → :crypto → :httpoison → :my_app
  # => OTP ensures dependency order automatically
end
# => If :httpoison fails to start, MyApp NEVER starts (dependency failure)

# Example usage of application lifecycle
# 1. Developer runs: mix run
#    => OTP reads mix.exs application/0
#    => Starts dependencies: Logger → Crypto → HTTPoison
#    => Calls MyApp.Application.start(:normal, [])
#    => Supervision tree starts (Registry → Cache → Workers)
#    => Application running ✓

# 2. Application stops (Ctrl+C or System.stop())
#    => OTP calls MyApp.Application.stop(pid)
#    => Cleanup logic runs (stop/1 callback)
#    => Supervision tree terminates (children shutdown in reverse)
#    => Dependencies stop in reverse: MyApp → HTTPoison → Crypto → Logger
#    => Application stopped ✓

# config/config.exs - Base configuration (COMPILE TIME)
import Config  # => imports Config module for config/2 macro

# Application-level configuration
config :my_app,  # => :my_app is the application name (atom)
  api_url: "https://api.example.com",  # => default API URL
  timeout: 5000,  # => 5000ms timeout
  max_retries: 3  # => retry failed requests 3 times
# => These values are READ AT COMPILE TIME and baked into release

# Module-specific configuration (nested under application)
config :my_app, MyApp.Repo,  # => config for MyApp.Repo module
  database: "my_app_dev",  # => database name
  username: "postgres",  # => ❌ BAD: hardcoded credentials (OK for dev, NOT for prod)
  password: "postgres",  # => ❌ SECURITY RISK: never commit production passwords
  hostname: "localhost"  # => database host
# => This config is for DEVELOPMENT only (overridden in prod.exs)

# Import environment-specific config
import_config "#{config_env()}.exs"  # => loads dev.exs, test.exs, or prod.exs based on MIX_ENV
# => config_env() returns :dev, :test, or :prod
# => Files loaded in order: config.exs → {env}.exs (env-specific overrides base)

# config/dev.exs - Development environment (COMPILE TIME)
import Config

config :my_app,
  debug: true,  # => enable debug logging in dev
  api_url: "http://localhost:4000"  # => override to use local API
# => These values OVERRIDE config.exs settings
# => Evaluated at compile time when MIX_ENV=dev

# config/prod.exs - Production environment (COMPILE TIME)
import Config

config :my_app,
  debug: false,  # => disable debug in production
  api_url: System.get_env("API_URL") || raise "API_URL not set"  # => ❌ PROBLEM: System.get_env at COMPILE time
# => This evaluates when building release (not at runtime!)
# => If API_URL not set during build, release fails to compile
# => ✅ SOLUTION: Use runtime.exs instead

# config/runtime.exs - Runtime configuration (APPLICATION STARTUP)
import Config

if config_env() == :prod do  # => only in production
  config :my_app,
    api_key: System.get_env("API_KEY") || raise "API_KEY not set",  # => ✅ GOOD: reads ENV at runtime
    # => Application CRASHES on startup if API_KEY missing (fail fast)
    database_url: System.get_env("DATABASE_URL") || raise "DATABASE_URL not set"  # => reads DATABASE_URL at startup
  # => runtime.exs evaluates when APPLICATION STARTS (not when building release)
  # => Perfect for secrets: API keys, DB URLs, etc.
end
# => Runtime config enables SAME release binary for different environments
# => Just change environment variables, no recompilation needed

# Accessing configuration in code
defmodule MyApp.API do
  def url, do: Application.get_env(:my_app, :api_url)  # => retrieves :api_url from :my_app config
  # => Returns "https://api.example.com" (or overridden value)

  def timeout, do: Application.get_env(:my_app, :timeout, 3000)  # => returns :timeout or default 3000ms
  # => Third argument is fallback if key not found

  def debug?, do: Application.get_env(:my_app, :debug, false)  # => returns boolean, defaults to false
  # => Useful for conditional logging

  def call_api do
    if debug?() do  # => check debug mode
      IO.puts("Calling #{url()} with timeout #{timeout()}")  # => log API call in debug mode
      # => Prints: "Calling https://api.example.com with timeout 5000"
    end
    # Make API call...
  end
end

# Accessing nested configuration
repo_config = Application.get_env(:my_app, MyApp.Repo)  # => retrieves MyApp.Repo config
# => repo_config = [database: "my_app_dev", username: "postgres", ...]
database = Keyword.get(repo_config, :database)  # => extracts :database from keyword list
# => database = "my_app_dev"

# Modifying configuration at runtime (rare, usually for testing)
Application.put_env(:my_app, :debug, true)  # => sets :debug to true at runtime
# => ⚠️ Changes are NOT persisted (lost on restart)
# => Useful in tests to override config

# Getting all application config
Application.get_all_env(:my_app)  # => returns all config for :my_app
# => [api_url: "...", timeout: 5000, max_retries: 3, debug: true, ...]

# Configuration timeline:
# 1. Build time (mix compile):
#    - config.exs loaded → base settings
#    - dev.exs/test.exs/prod.exs loaded → environment overrides
#    - Values baked into compiled beam files
#
# 2. Application startup (mix run, release start):
#    - runtime.exs loaded → runtime overrides from ENV vars
#    - Application.get_env/2,3 retrieves values
#
# 3. Runtime (application running):
#    - Application.put_env/3 can modify (not persisted)
#    - Application.get_env/2,3 retrieves current values

# Best practices:
# ✅ config.exs: defaults, development settings
# ✅ dev.exs: development overrides (local URLs, debug mode)
# ✅ test.exs: test-specific settings (test database)
# ✅ prod.exs: production settings (no secrets!)
# ✅ runtime.exs: secrets from ENV vars (API keys, DB URLs)
# ❌ NEVER commit secrets to any .exs file
# ❌ AVOID System.get_env in config.exs/prod.exs (compile time)
# ✅ USE System.get_env in runtime.exs only (runtime)

# Create umbrella project structure
mix new my_app --umbrella  # => creates apps/ directory for child applications
# => Structure:
# => my_app/
# =>   apps/         (child applications go here)
# =>   config/       (shared configuration)
# =>   mix.exs       (umbrella project definition)

# Create child apps inside umbrella
cd my_app/apps
mix new my_app_core  # => creates my_app_core app (business logic)
mix new my_app_web --sup  # => creates my_app_web app (web interface) with supervision tree

# apps/my_app_core/mix.exs - Core business logic app
defmodule MyAppCore.MixProject do
  use Mix.Project

  def project do
    [
      app: :my_app_core,  # => application name (atom)
      version: "0.1.0",  # => version
      build_path: "../../_build",  # => ✅ shared build directory (umbrella root)
      config_path: "../../config/config.exs",  # => ✅ shared config
      deps_path: "../../deps",  # => ✅ shared dependencies (all apps use same versions)
      lockfile: "../../mix.lock"  # => ✅ shared lock file (dependency versions locked)
    ]
  end
  # => All umbrella apps share build artifacts and dependencies
  # => This enables: 1) consistent versions, 2) shared compilation, 3) faster builds
end

# apps/my_app_web/mix.exs - Web interface app
defmodule MyAppWeb.MixProject do
  use Mix.Project

  def project do
    [
      app: :my_app_web,  # => application name
      deps: deps()  # => dependencies for web app
    ]
  end

  defp deps do
    [
      {:my_app_core, in_umbrella: true},  # => ✅ depend on sibling app (in same umbrella)
      # => in_umbrella: true tells Mix to find :my_app_core in apps/ directory
      # => NOT from Hex (external package)
      {:phoenix, "~> 1.7"}  # => external dependency from Hex
    ]
  end
  # => Dependency order: Phoenix → my_app_core → my_app_web
  # => OTP starts apps in dependency order automatically
end

# apps/my_app_core/lib/my_app_core/users.ex - Business logic (core app)
defmodule MyAppCore.Users do
  def list_users do
    # Business logic (no web dependencies, pure Elixir)
    [%{id: 1, name: "Alice"}, %{id: 2, name: "Bob"}]  # => returns user list
  end
  # => Core app is INDEPENDENT - no Phoenix, no web concepts
  # => Can be used by: web app, CLI app, background workers, etc.
end

# apps/my_app_web/lib/my_app_web/controllers/user_controller.ex - Web layer
defmodule MyAppWeb.UserController do
  use MyAppWeb, :controller  # => imports Phoenix controller functionality

  def index(conn, _params) do
    users = MyAppCore.Users.list_users()  # => calls core app function
    # => Web app DEPENDS on core app (declared in deps)
    # => Core app is OBLIVIOUS to web app (no reverse dependency)
    render(conn, "index.html", users: users)  # => renders view with data from core
  end
end
# => Clear separation: Core = business logic, Web = presentation layer

# Running umbrella commands
# From umbrella root (my_app/):
# mix test                           # => runs tests in ALL apps
# mix test --only apps/my_app_core   # => tests specific app only
# mix compile                        # => compiles ALL apps
# mix deps.get                       # => fetches deps for ALL apps (shared deps/)
# mix run --no-halt                  # => runs ALL applications

# Benefits of umbrella architecture:
# ✅ Shared dependencies (single deps/ directory, consistent versions)
# ✅ Clear domain boundaries (core vs web vs workers)
# ✅ Independent testing (test core without Phoenix)
# ✅ Flexible deployment (deploy web separately from workers)
# ✅ Code reuse (CLI, web, workers all use same core)
# ❌ Complexity overhead (more mix.exs files, dependency management)
# ❌ Tight coupling risk (easy to create circular dependencies)

# Use umbrella when:
# ✅ Large system with distinct domains (auth, billing, notifications)
# ✅ Multiple deployment targets (web, workers, CLI)
# ✅ Shared business logic across apps
# ❌ Small projects (unnecessary complexity)
# ❌ Single deployment target (regular app is simpler)

# quote - captures code as AST (tuple representation)
quoted = quote do
  1 + 2  # => this code is NOT executed, it's captured as data structure
end
# => quoted = {:+, [context: Elixir, imports: [{1, Kernel}, {2, Kernel}]], [1, 2]}
# => AST format: {function_name, metadata, arguments}
# => {:+, metadata, [1, 2]} represents the + function called with args [1, 2]

{:+, _metadata, [1, 2]} = quoted  # => pattern matches AST tuple
# => Confirms structure: + operator with arguments 1 and 2

# Complex expressions also become AST
quoted = quote do
  if true, do: :yes, else: :no
end
# => {:if, [], [true, [do: :yes, else: :no]]}
# => if macro with condition true and keyword list of branches

# unquote - injects VALUES into quoted expressions
x = 5  # => x is a regular variable (not AST)
quoted = quote do
  1 + unquote(x)  # => unquote(x) evaluates x and injects value 5 into AST
end
# => {:+, [], [1, 5]}
# => Note: 5 is injected, NOT variable x
# => At quote time: x evaluated → 5 injected → AST contains literal 5

# WITHOUT unquote - variable name becomes AST variable reference
quoted = quote do
  1 + x  # => x is kept as variable reference (not evaluated)
end
# => {:+, [], [1, {:x, [], Elixir}]}
# => x becomes AST variable node, NOT value 5
# => If you eval_quoted this, it looks for variable x at eval time

# Evaluating quoted expressions
Code.eval_quoted(quote do: 1 + 2)  # => {3, []}
# => Returns {result, bindings}
# => result = 3 (evaluated expression)
# => bindings = [] (no variables bound)

# unquote with multiple values
a = 10  # => variable a
b = 20  # => variable b
quoted = quote do
  unquote(a) + unquote(b)  # => injects 10 and 20 into AST
end
# => {:+, [], [10, 20]}
# => Both values injected at quote time
Code.eval_quoted(quoted)  # => {30, []}
# => Evaluates 10 + 20 = 30

# unquote_splicing - injects list elements as separate arguments
args = [1, 2, 3]  # => list of arguments
quoted = quote do
  sum(unquote_splicing(args))  # => unquote_splicing expands [1, 2, 3] to separate args
end
# => {:sum, [], [1, 2, 3]}
# => Equivalent to: sum(1, 2, 3)
# => WITHOUT splicing: sum([1, 2, 3]) - would pass list as single arg

# Building function calls dynamically
defmodule Builder do
  def build_call(function, args) do
    quote do
      unquote(function)(unquote_splicing(args))  # => injects function name and spreads args
    end
  end
  # => function is injected as function reference
  # => args are spliced as separate arguments
end

quoted = Builder.build_call(:IO.puts, ["Hello"])  # => builds IO.puts("Hello")
# => Returns AST: {{:., [], [:IO, :puts]}, [], ["Hello"]}
Code.eval_quoted(quoted)  # => Prints: Hello
# => {nil, []} (IO.puts returns nil)

# Converting AST back to string
quote(do: 1 + 2) |> Macro.to_string()  # => "1 + 2"
# => AST → string representation (pretty print)
# => Useful for debugging macros (see generated code)

# Macro expansion - see how macros are transformed
Macro.expand(quote(do: unless true, do: :no), __ENV__)  # => expands unless macro
# => unless is a macro that rewrites to if with negated condition
# => Returns: {:if, [], [false, [do: :no, else: nil]]}
# => Shows underlying if implementation

# Key AST concepts:
# 1. Everything is a tuple: {function, metadata, arguments}
# 2. Literals (1, "hello", :atom) are kept as-is
# 3. Variables become {:var_name, metadata, context}
# 4. Function calls become {func, metadata, args}
# 5. quote captures code as AST (doesn't execute)
# 6. unquote injects values into AST at quote time
# 7. unquote_splicing expands lists as separate arguments

defmodule MyMacros do
  # Simple macro - no arguments
  defmacro say_hello do
    quote do  # => returns AST: {{:., [], [{:__aliases__, [alias: false], [:IO]}, :puts]}, [], ["Hello from macro!"]}
      IO.puts("Hello from macro!")  # => this code runs in CALLER's context at runtime
    end
  end
  # => defmacro receives NO arguments, returns AST that will be inserted at call site

  # Macro with arguments
  defmacro double(value) do
    # => value is AST of argument (e.g., for double(5), value = {:5, [], Elixir})
    quote do
      unquote(value) * 2  # => unquote injects value AST into multiplication expression
    end
    # => returns AST: {:*, [], [unquote(value), 2]}
    # => At compile time: double(5) becomes: 5 * 2
  end

  # Macro that generates function
  defmacro create_getter(name, value) do
    # => name is atom AST (e.g., :name), value is AST (e.g., "Alice")
    quote do
      def unquote(name)(), do: unquote(value)  # => generates function definition at compile time
    end
    # => creates: def name(), do: "Alice"
    # => unquote(name) injects atom as function name
    # => unquote(value) injects value as function body
  end

  # Macro for logging
  defmacro log(message) do
    quote do
      IO.puts("[LOG #{DateTime.utc_now()}] #{unquote(message)}")  # => DateTime.utc_now() evaluated at RUNTIME in caller context
    end
    # => unquote(message) injects message AST
    # => Timestamp generated when log executes, NOT when macro expands
  end

  # Macro with block (do...end)
  defmacro benchmark(name, do: block) do
    # => name is string AST, block is AST of entire do...end content
    quote do
      {time, result} = :timer.tc(fn -> unquote(block) end)  # => unquote(block) injects benchmarked code into anonymous function
      # => :timer.tc returns {microseconds, result} tuple
      IO.puts("#{unquote(name)} took #{time}μs")  # => prints benchmark name and duration
      result  # => returns result of benchmarked code
    end
    # => entire benchmark logic inserted at call site and executed at runtime
  end
end

defmodule Example do
  require MyMacros  # => makes macros available at compile time (REQUIRED for macro use)

  MyMacros.say_hello()  # => macro expands to: IO.puts("Hello from macro!")
  # => Prints: Hello from macro! (at runtime)

  x = MyMacros.double(5)  # => macro expands to: x = 5 * 2
  # => x = 10 (at runtime)

  MyMacros.create_getter(:name, "Alice")  # => generates function def at compile time
  # => Expands to: def name(), do: "Alice"
  # => Now name() function exists in Example module

  def demo do
    MyMacros.log("Starting demo")  # => expands to: IO.puts("[LOG #{DateTime.utc_now()}] Starting demo")
    # => Prints: [LOG 2024-01-15 10:30:45.123456Z] Starting demo (timestamp at runtime)

    result = MyMacros.benchmark "computation" do
      :timer.sleep(100)  # => sleep 100ms
      42  # => return value
    end
    # => Expands to:
    # => {time, result} = :timer.tc(fn -> :timer.sleep(100); 42 end)
    # => IO.puts("computation took #{time}μs")
    # => result
    # => Prints: computation took ~100000μs (100ms = 100,000 microseconds)
    # => Returns: 42
  end
end

# Macro Hygiene - variables don't leak by default
defmodule HygieneDemo do
  defmacro create_var do
    quote do
      x = 42  # => creates x in MACRO's context (hygienic), NOT caller's context
    end
  end
end

defmodule User do
  require HygieneDemo

  def test do
    HygieneDemo.create_var()  # => macro creates x in isolated scope
    x  # => ** (CompileError) undefined function x/0
    # => ERROR! Variable x from macro doesn't exist in test/0 scope
    # => This is HYGIENE - prevents accidental variable capture
  end
end

# Explicitly breaking hygiene with var!
defmodule UnhygieneDemo do
  defmacro create_var do
    quote do
      var!(x) = 42  # => var! explicitly creates variable in CALLER's context (unhygienic)
    end
  end
end

defmodule User2 do
  require UnhygieneDemo

  def test do
    UnhygieneDemo.create_var()  # => creates x in test/0 scope (intentional leak)
    x  # => 42 (works! variable explicitly leaked using var!)
    # => var! breaks hygiene when you WANT variable sharing between macro and caller
  end
end

# Pattern matching on AST
defmodule MiniTest do
  defmacro assert({:==, _, [left, right]}) do  # => pattern matches AST of == expression
    # => {:==, _, [left, right]} destructures: operator, metadata, [left_arg, right_arg]
    # => For assert(1 + 1 == 2), left = {:+, [], [1, 1]}, right = 2
    quote do
      left_val = unquote(left)  # => evaluates left expression at runtime
      # => left_val = 1 + 1 = 2
      right_val = unquote(right)  # => evaluates right expression at runtime
      # => right_val = 2
      if left_val != right_val do
        raise "Assertion failed: #{inspect(left_val)} != #{inspect(right_val)}"  # => raises on mismatch
      end
      # => If assertion passes, returns nil (no raise)
    end
    # => This shows how macros can inspect AST structure (pattern match on operator)
  end
end

require MiniTest  # => loads MiniTest macros
MiniTest.assert(1 + 1 == 2)  # => macro expands, evaluates 1+1, compares to 2, passes (no raise)
# => At compile time: pattern matches AST, generates assertion code
# => At runtime: evaluates expressions, performs comparison