#!/usr/bin/env python3
"""Add When to Use / When NOT to Use sections to macros.md
Parts: 0=preamble, 1=section1, 2=section2, ..., 12=section12"""

with open("patterns/macros.md", "r") as f:
    content = f.read()

separator = "\n\n---\n\n"
parts = content.split(separator)
assert len(parts) == 13, f"Expected 13 parts, got {len(parts)}"

# Index 1-12 maps to sections 1-12
when_sections = {
    1: '''
### When to Use

**Triggers:**
- A macro must behave differently in guards vs normal code
- You're writing an operator-like macro that users will put in guard clauses
- The same syntax needs different compilation strategies per context

**Example — before:**
```elixir
# Macro that only works in normal code, crashes in guards
defmacro my_or(left, right) do
  quote do
    case unquote(left) do
      x when x in [false, nil] -> unquote(right)
      x -> x
    end
  end
end
```

**Example — after:**
```elixir
defmacro my_or(left, right) do
  case __CALLER__.context do
    nil -> quote do
      case unquote(left) do
        x when x in [false, nil] -> unquote(right)
        x -> x
      end
    end
    :guard -> quote(do: :erlang.orelse(unquote(left), unquote(right)))
    :match -> raise ArgumentError, "cannot use or/2 in match"
  end
end
```

### When NOT to Use

**Don't use this when:**
- Your macro will never be used in guards (most macros)
- A simple `defguard` would suffice for guard-only usage

**Over-application example:**
```elixir
# Checking __CALLER__.context in a macro that just generates module-level code
defmacro define_schema(fields) do
  case __CALLER__.context do
    nil -> generate_schema(fields)
    :guard -> raise "can't use in guard"  # Unnecessary
    :match -> raise "can't use in match"  # Unnecessary
  end
end
```

**Better alternative:**
```elixir
defmacro define_schema(fields) do
  generate_schema(fields)
end
```

**Why:** Context-checking adds complexity. Only use it when there's a legitimate code path for guards or matches. Module-level macros like schema definitions will never appear in guard context.''',

    2: '''
### When to Use

**Triggers:**
- You need a guard-safe check that combines multiple guard expressions
- Multiple modules share the same guard condition
- The guard logic is complex enough to warrant a name

**Example — before:**
```elixir
# Repeating guard logic everywhere
def process(n) when is_integer(n) and rem(n, 2) == 0 do
  # handle even...
end

def validate(n) when is_integer(n) and rem(n, 2) == 0 do
  # validate even...
end
```

**Example — after:**
```elixir
defmodule Guards do
  defguard is_even(n) when is_integer(n) and rem(n, 2) == 0
end

import Guards

def process(n) when is_even(n), do: # ...
def validate(n) when is_even(n), do: # ...
```

### When NOT to Use

**Don't use this when:**
- The check isn't guard-safe (calls functions, uses try/rescue, etc.)
- The guard is used in one place and is already readable
- You need runtime logic like database lookups in the check

**Over-application example:**
```elixir
# Trying to use defguard for something that needs runtime state
defguard is_admin(user_id) when user_id in @admin_ids
# @admin_ids is a module attribute — frozen at compile time!
```

**Better alternative:**
```elixir
def admin?(user_id), do: user_id in load_admin_ids()

def process(request) do
  if admin?(request.user_id), do: # ...
end
```

**Why:** `defguard` expressions are evaluated at compile time with only BIF access. If your "guard" needs runtime data, config, or database state, it's not a guard — it's a function.''',

    3: '''
### When to Use

**Triggers:**
- A macro receives arguments that should be evaluated once in the expansion
- You're generating code that interpolates compile-time values into runtime code
- The macro argument has side effects or is expensive to compute

**Example — before:**
```elixir
# unquote(fields) evaluated twice
defmacro setup(fields) do
  quote do
    validated = validate(unquote(fields))
    @fields unquote(fields)  # fields expression runs again!
  end
end
```

**Example — after:**
```elixir
defmacro setup(fields) do
  quote bind_quoted: [fields: fields] do
    validated = validate(fields)
    @fields fields  # Same bound value, no double-evaluation
  end
end
```

### When NOT to Use

**Don't use this when:**
- You need to unquote into a pattern match position (bind_quoted can't do this)
- The expression is a simple literal or variable with no side effects
- You're building complex AST where you need fine-grained unquote placement

**Over-application example:**
```elixir
# bind_quoted fails in pattern positions
defmacro match_field(field, value) do
  quote bind_quoted: [field: field, value: value] do
    def handle(%{field => result}) when result == value do
      result
    end
  end
end
```

**Better alternative:**
```elixir
defmacro match_field(field, value) do
  quote do
    def handle(%{unquote(field) => result}) when result == unquote(value) do
      result
    end
  end
end
```

**Why:** `bind_quoted` wraps values in regular variable bindings, which can't appear in pattern match positions. When you need to inject into patterns or guards, use direct `unquote`.''',

    4: '''
### When to Use

**Triggers:**
- A macro must inject code that references a variable from the caller's scope
- Building test/assertion macros where you need access to the test binding
- Module-level macros that accumulate into a module attribute the caller defines

**Example — before:**
```elixir
# Hygienic variable — creates a NEW binding, doesn't access caller's
defmacro assert_stored(key) do
  quote do
    assert store[unquote(key)]  # 'store' is hygienic — undefined in caller!
  end
end
```

**Example — after:**
```elixir
defmacro assert_stored(key) do
  quote do
    assert var!(store)[unquote(key)]  # Accesses caller's 'store' variable
  end
end
```

### When NOT to Use

**Don't use this when:**
- You can pass the value as a macro argument instead
- The macro doesn't need to reference caller-scope variables
- You're creating new bindings (just let hygiene work naturally)

**Over-application example:**
```elixir
# Using var! when the value could just be passed as an argument
defmacro double_it do
  quote do
    var!(x) * 2  # Assumes caller has 'x' — fragile!
  end
end

# Caller must have 'x' defined
x = 5
double_it()  # => 10
```

**Better alternative:**
```elixir
defmacro double_it(value) do
  quote do
    unquote(value) * 2
  end
end

double_it(5)  # => 10, explicit, no hidden dependencies
```

**Why:** Every `var!` creates an invisible contract between macro and caller. Prefer explicit arguments. Reserve `var!` for cases where the contract is part of the documented API (like ExUnit's test context).''',

    5: '''
### When to Use

**Triggers:**
- Your macro receives user input that could be an alias, module attribute, or compile-time expression
- You need to make compile-time decisions based on what type of thing was passed
- Distinguishing between module names and runtime expressions in macro arguments

**Example — before:**
```elixir
# Trying to pattern-match on the raw AST — breaks with aliases
defmacro wrap_error(module) when is_atom(module) do
  # Never matches! Aliases are {:__aliases__, _, [...]} in AST
  quote do: %{__exception__: true, __struct__: unquote(module)}
end
```

**Example — after:**
```elixir
defmacro wrap_error(module_or_msg) do
  case Macro.expand(module_or_msg, __CALLER__) do
    atom when is_atom(atom) ->
      quote do: unquote(atom).exception([])
    _ ->
      quote do: RuntimeError.exception(unquote(module_or_msg))
  end
end
```

### When NOT to Use

**Don't use this when:**
- The macro argument is always a literal (string, number)
- You don't need compile-time branching on the argument's type
- The argument should remain unevaluated (lazy evaluation semantics)

**Over-application example:**
```elixir
# Expanding an argument that's meant to be a runtime expression
defmacro log(message) do
  expanded = Macro.expand(message, __CALLER__)
  quote do
    Logger.info(unquote(expanded))
  end
end
```

**Better alternative:**
```elixir
defmacro log(message) do
  quote do
    Logger.info(unquote(message))  # Let it evaluate at runtime
  end
end
```

**Why:** `Macro.expand` resolves compile-time constructs (aliases, module attributes). Expanding function calls or complex expressions can produce confusing results. Only expand when you need to determine the *type* of the argument at compile time.''',

    6: '''
### When to Use

**Triggers:**
- Your macro defines module-level constructs (functions, types, modules)
- The macro makes no sense inside a guard or pattern match
- Early failure with a clear message prevents confusing downstream errors

**Example — before:**
```elixir
# No context validation — weird error deep in expansion
defmacro defroute(path, handler) do
  quote do
    @routes [{unquote(path), unquote(handler)} | @routes]
  end
end

# User accidentally writes:
def check(x) when defroute("/foo", Foo), do: x  # Cryptic error
```

**Example — after:**
```elixir
defmacro defroute(path, handler) do
  assert_no_match_or_guard_scope(__CALLER__.context, "defroute/2")
  quote do
    @routes [{unquote(path), unquote(handler)} | @routes]
  end
end

# Now gives: "cannot invoke defroute/2 inside a guard"
```

### When NOT to Use

**Don't use this when:**
- Your macro IS designed to work in guards (use `defguard` or handle context)
- Your macro is designed to work in match context (like custom patterns)
- The macro is simple enough that misuse produces a clear error naturally

**Over-application example:**
```elixir
# Adding guard assertion to a macro that could legitimately work anywhere
defmacro debug(expr) do
  assert_no_match_or_guard_scope(__CALLER__.context, "debug/1")
  quote do
    IO.inspect(unquote(expr), label: unquote(Macro.to_string(expr)))
  end
end
```

**Better alternative:**
```elixir
# Let it work anywhere it naturally can
defmacro debug(expr) do
  quote do
    IO.inspect(unquote(expr), label: unquote(Macro.to_string(expr)))
  end
end
```

**Why:** Only add context assertions when misuse would produce confusing errors. If your macro naturally fails with a clear error in the wrong context, the assertion adds noise without value.''',

    7: '''
### When to Use

**Triggers:**
- You're building a type system or dispatch mechanism that operates on open-ended types
- Users need to add behavior for their own types without modifying your library
- You need dynamic dispatch based on the data type with compile-time consolidation

**Example — before:**
```elixir
# Manual dispatch via case — closed, must modify to extend
def serialize(data) do
  case data do
    %User{} -> serialize_user(data)
    %Post{} -> serialize_post(data)
    _ -> raise "don't know how to serialize"
  end
end
```

**Example — after:**
```elixir
defprotocol Serializable do
  @doc "Converts a data structure to a wire format"
  def serialize(data)
end

defimpl Serializable, for: User do
  def serialize(%User{name: name, email: email}), do: %{name: name, email: email}
end

# Anyone can add implementations for their own types
```

### When NOT to Use

**Don't use this when:**
- You have a closed set of types that won't be extended by users
- Simple pattern matching or behaviours solve the problem
- The dispatch doesn't depend on the first argument's type

**Over-application example:**
```elixir
# Protocol for internal types that will never be extended
defprotocol InternalFormat do
  def format(thing)
end

defimpl InternalFormat, for: [Map, List, BitString] do
  # Only ever these three types, controlled by us
end
```

**Better alternative:**
```elixir
# Simple function with pattern matching — less machinery
def format(%{} = map), do: # ...
def format(list) when is_list(list), do: # ...
def format(binary) when is_binary(binary), do: # ...
```

**Why:** Protocols add indirection and compilation complexity (consolidation). If the type set is closed and you control all implementations, pattern matching is simpler, faster, and easier to understand.''',

    8: '''
### When to Use

**Triggers:**
- A protocol should handle ANY value rather than crashing on unknown types
- The generic behavior is genuinely useful (inspect, encode, display)
- You want a safe default that users can override for specific types

**Example — before:**
```elixir
defprotocol Displayable do
  def display(term)
end

# Every new struct crashes until someone adds an implementation:
# ** (Protocol.UndefinedError) protocol Displayable not implemented for %MyStruct{}
```

**Example — after:**
```elixir
defprotocol Displayable do
  @fallback_to_any true
  def display(term)
end

defimpl Displayable, for: Any do
  def display(term), do: inspect(term)  # Reasonable fallback
end
```

### When NOT to Use

**Don't use this when:**
- The protocol operation doesn't make sense for arbitrary types
- Silently returning a default would hide bugs
- You want to force implementors to think about their implementation

**Over-application example:**
```elixir
defprotocol Saveable do
  @fallback_to_any true
  def save(data, repo)
end

defimpl Saveable, for: Any do
  def save(_data, _repo), do: :ok  # Silently does nothing!
end

# Dangerous: %UnknownStruct{} |> Saveable.save(repo) succeeds but saves nothing
```

**Better alternative:**
```elixir
defprotocol Saveable do
  # No fallback — forces explicit implementation
  def save(data, repo)
end

# Clear error on missing implementation:
# ** (Protocol.UndefinedError) protocol Saveable not implemented for %Foo{}
```

**Why:** Fallbacks that silently succeed are a bug factory. Use `@fallback_to_any` only when the default behavior is *genuinely useful* (like `Inspect`), not when "do nothing" masks errors.''',

    9: '''
### When to Use

**Triggers:**
- Your module needs to inject behaviours, default function implementations, or compile hooks
- Users need a one-line "opt in" that sets up complex module infrastructure
- The setup requires `@behaviour`, `@before_compile`, `defoverridable`, or module attributes

**Example — before:**
```elixir
# User must remember all the boilerplate
defmodule MyWorker do
  @behaviour GenServer

  def child_spec(init_arg) do
    %{id: __MODULE__, start: {__MODULE__, :start_link, [init_arg]}}
  end

  def init(state), do: {:ok, state}
  # ... more defaults ...
end
```

**Example — after:**
```elixir
defmodule MyWorker do
  use GenServer

  # All boilerplate injected, just implement what you need
  def init(state), do: {:ok, state}
end
```

### When NOT to Use

**Don't use this when:**
- `import` or `alias` is all you need (no module attributes, no callbacks)
- The module doesn't need to inject code — just provides functions
- You're using `use` to inject large amounts of invisible code that surprises users

**Over-application example:**
```elixir
# use for something that should just be import
defmodule MyHelpers do
  defmacro __using__(_opts) do
    quote do
      import MyHelpers  # That's literally all it does
    end
  end
end

# User writes: use MyHelpers
# When they could just write: import MyHelpers
```

**Better alternative:**
```elixir
# Just tell users to import directly
defmodule MyHelpers do
  def format_date(date), do: # ...
  def format_money(amount), do: # ...
end

# In user's module:
import MyHelpers
```

**Why:** `use` implies "this module needs setup that goes beyond importing functions." If all you're doing is importing, `use` adds a layer of indirection that obscures what's happening. Reserve `use` for genuine module setup.''',

    10: '''
### When to Use

**Triggers:**
- You have compile-time-known literal values that benefit from validation at compile time
- A domain has a specific syntax for literals (dates, regex, URIs, colors)
- You want zero runtime parsing cost for constant values

**Example — before:**
```elixir
# Runtime parsing — fails at runtime, no compile-time validation
def deadline do
  Date.from_iso8601!("2024-13-45")  # Explodes at runtime
end
```

**Example — after:**
```elixir
def deadline do
  ~D[2024-13-45]  # Compile error! Invalid date caught immediately
end
```

### When NOT to Use

**Don't use this when:**
- Values come from runtime input (user data, config files, databases)
- The syntax doesn't provide meaningful compile-time validation
- A regular function or struct literal is equally clear

**Over-application example:**
```elixir
# Sigil for something with no compile-time validation benefit
defmacro sigil_u({:<<>>, _, [string]}, []) do
  quote do: String.upcase(unquote(string))
end

name = ~u"hello"  # Just uppercases a string... why not String.upcase("hello")?
```

**Better alternative:**
```elixir
name = String.upcase("hello")
```

**Why:** Sigils shine when they validate or transform at compile time in ways that prevent runtime errors. A sigil that just wraps a function call without validation adds syntax without value.''',

    11: '''
### When to Use

**Triggers:**
- You want a zero-cost syntactic transformation (no runtime dispatch)
- The transformation is purely structural (rewriting argument positions)
- An operator or DSL benefits from left-to-right readability

**Example — before:**
```elixir
# Deeply nested function calls — read inside-out
String.trim(String.downcase(String.replace(input, "_", " ")))
```

**Example — after:**
```elixir
input
|> String.replace("_", " ")
|> String.downcase()
|> String.trim()
```

### When NOT to Use

**Don't use this when:**
- The pipe has only one step (just call the function directly)
- The piped value isn't the first argument (requires anonymous function wrappers)
- You're piping into a macro that needs special AST handling

**Over-application example:**
```elixir
# Single-step pipe — adds noise
user
|> Map.get(:name)

# Piping where the value isn't first argument
data
|> Jason.encode!()
|> send_to(socket)  # Is this send_to(encoded, socket)? Unclear.
```

**Better alternative:**
```elixir
# Single step — just call it
name = Map.get(user, :name)

# When argument position is unclear, break the pipe
encoded = data |> build_map() |> Jason.encode!()
send_to(socket, encoded)  # Clear which arg is which
```

**Why:** Pipes optimize for readability of *sequential transformations*. When the data doesn't flow naturally as the first argument, or there's only one step, the pipe adds syntactic overhead without improving clarity.''',

    12: '''
### When to Use

**Triggers:**
- Your macro generates variable bindings in quoted code
- You need `n` variables for a generated function clause or pattern
- The macro expands in user code where variable names could clash

**Example — before:**
```elixir
# Hardcoded variable names — can clash with caller's variables
defmacro curry(fun, arity) do
  args = Enum.map(1..arity, fn i -> Macro.var(:"arg\#{i}", __MODULE__) end)
  quote do
    fn unquote_splicing(args) -> unquote(fun).(unquote_splicing(args)) end
  end
end
```

**Example — after:**
```elixir
defmacro curry(fun, arity) do
  args = Macro.generate_unique_arguments(arity, __CALLER__.module)
  quote do
    fn unquote_splicing(args) -> unquote(fun).(unquote_splicing(args)) end
  end
end
```

### When NOT to Use

**Don't use this when:**
- You're using `bind_quoted` (it handles hygiene for you)
- The variable is accessed via `var!` (intentionally unhygienic)
- You only need one variable (a simple `quote do: var = ... end` is hygienic by default)

**Over-application example:**
```elixir
# Using generate_unique_arguments for a single binding
defmacro time_it(expr) do
  [start] = Macro.generate_unique_arguments(1, __CALLER__.module)
  quote do
    unquote(start) = System.monotonic_time()
    result = unquote(expr)
    IO.puts("Took \#{System.monotonic_time() - unquote(start)}")
    result
  end
end
```

**Better alternative:**
```elixir
# Regular quote hygiene handles single variables fine
defmacro time_it(expr) do
  quote do
    start = System.monotonic_time()
    result = unquote(expr)
    IO.puts("Took \#{System.monotonic_time() - start}")
    result
  end
end
```

**Why:** Variables created in `quote` are already hygienic by default — they can't clash with caller variables. `generate_unique_arguments` is needed when you're generating *multiple* variables dynamically (e.g., function parameters for a generated clause) where you need distinct names that also interoperate correctly.''',
}

for i in range(len(parts)):
    if i in when_sections:
        parts[i] = parts[i].rstrip() + "\n\n" + when_sections[i].strip()

output = separator.join(parts) + "\n"

with open("patterns/macros.md", "w") as f:
    f.write(output)

print(f"Done! {len(output)} chars")