feat: add source hyperlinks + remove thin from-source.md

Every source reference now links to elixir-lang/elixir at commit f4e1b34.
122 hyperlinks across 11 topic files. Added PATTERN_COMPLETE sentinels.
Removed from-source.md (326 lines, shallow) — covered by existing files.
This commit is contained in:
Rodin
2026-04-30 14:43:56 -07:00
parent 9ff22d2eed
commit 5f62dd0bf1
13 changed files with 146 additions and 480 deletions
+16 -14
View File
@@ -6,7 +6,7 @@ Patterns extracted from Elixir's standard library source code.
## 1. The `with` Macro — Normalized Error Clauses
**Source:** `lib/elixir/lib/kernel/special_forms.ex` lines 16001715 (docs + definition)
**Source:** [lib/elixir/lib/kernel/special_forms.ex#L1600](https://github.com/elixir-lang/elixir/blob/f4e1b34617ef92052b65781f18eae5b88a490098/lib/elixir/lib/kernel/special_forms.ex#L1600) (docs + definition)
**What it does:** The `with` macro chains pattern-matched steps where each `<-` clause returns a normalized error shape. When a step fails to match, the non-matched value falls through (or hits `else`).
@@ -107,7 +107,7 @@ Repo.get_user(id)
## 2. Real-World `with` — Multi-Step Fallible Operations
**Source:** `lib/elixir/lib/exception.ex` lines 251285 (`blame_mfa/4`)
**Source:** [lib/elixir/lib/exception.ex#L251](https://github.com/elixir-lang/elixir/blob/f4e1b34617ef92052b65781f18eae5b88a490098/lib/elixir/lib/exception.ex#L251) (`blame_mfa/4`)
**What it does:** Uses `with` to chain 5+ fallible steps where any failure should produce `:error`. Each step's pattern is an exact match.
@@ -222,7 +222,7 @@ def process_payment(order) do
## 3. Another `with` — Error Info Extraction
**Source:** `lib/elixir/lib/exception.ex` lines 26952720 (`error_info/3` in ErlangError)
**Source:** [lib/elixir/lib/exception.ex#L2695](https://github.com/elixir-lang/elixir/blob/f4e1b34617ef92052b65781f18eae5b88a490098/lib/elixir/lib/exception.ex#L2695) (`error_info/3` in ErlangError)
**What it does:** Chains pattern matching on a stacktrace and error_info map to extract formatted error details.
@@ -322,7 +322,7 @@ def extract_user_preference(_user, _key), do: {:error, :no_preferences}
## 4. `{:ok, value}` / `:error` Convention (Map.fetch)
**Source:** `lib/elixir/lib/map.ex` lines 290309
**Source:** [lib/elixir/lib/map.ex#L290](https://github.com/elixir-lang/elixir/blob/f4e1b34617ef92052b65781f18eae5b88a490098/lib/elixir/lib/map.ex#L290)
**What it does:** `Map.fetch/2` returns `{:ok, value}` on success and bare `:error` on failure. No reason atom, because the failure mode is obvious (key not found).
@@ -413,7 +413,7 @@ end
## 5. Bang Functions: Raise on Error (`fetch!` vs `fetch`)
**Source:** `lib/elixir/lib/map.ex` lines 311380
**Source:** [lib/elixir/lib/map.ex#L311](https://github.com/elixir-lang/elixir/blob/f4e1b34617ef92052b65781f18eae5b88a490098/lib/elixir/lib/map.ex#L311)
**What it does:** The `!` suffix convention means "raises on failure instead of returning an error tuple." The non-bang version is for when the caller wants to handle the error.
@@ -507,7 +507,7 @@ end
## 6. Exception Structure: `defexception` Fields
**Source:** `lib/elixir/lib/exception.ex` lines 22502500 (exception definitions)
**Source:** [lib/elixir/lib/exception.ex#L2250](https://github.com/elixir-lang/elixir/blob/f4e1b34617ef92052b65781f18eae5b88a490098/lib/elixir/lib/exception.ex#L2250) (exception definitions)
**What it does:** Exceptions carry meaningful fields beyond just `:message`. The `message/1` callback generates a human-readable string from those fields.
@@ -605,7 +605,7 @@ raise "expected state in #{inspect(expected)}, got #{inspect(actual)}"
## 7. Custom `exception/1` Callback for Ergonomic Raising
**Source:** `lib/elixir/lib/exception.ex` lines 22552270 (UnicodeConversionError)
**Source:** [lib/elixir/lib/exception.ex#L2255](https://github.com/elixir-lang/elixir/blob/f4e1b34617ef92052b65781f18eae5b88a490098/lib/elixir/lib/exception.ex#L2255) (UnicodeConversionError)
**What it does:** Override `exception/1` to accept raw values (not just keyword lists) and build the struct with a meaningful message.
@@ -710,7 +710,7 @@ end
## 8. `raise` Macro Internals: Compile-Time Type Resolution
**Source:** `lib/elixir/lib/kernel.ex` lines 22462294
**Source:** [lib/elixir/lib/kernel.ex#L2246](https://github.com/elixir-lang/elixir/blob/f4e1b34617ef92052b65781f18eae5b88a490098/lib/elixir/lib/kernel.ex#L2246)
**What it does:** The `raise` macro inspects the argument at compile time to determine if it's a string, binary expression, atom (module), or existing exception struct, generating optimized code for each case.
@@ -815,7 +815,7 @@ end
## 9. Error Normalization: Erlang → Elixir Exception Translation
**Source:** `lib/elixir/lib/exception.ex` lines 25302680 (`ErlangError.normalize/2`)
**Source:** [lib/elixir/lib/exception.ex#L2530](https://github.com/elixir-lang/elixir/blob/f4e1b34617ef92052b65781f18eae5b88a490098/lib/elixir/lib/exception.ex#L2530) (`ErlangError.normalize/2`)
**What it does:** Translates raw Erlang error reasons (atoms and tuples) into proper Elixir exception structs with helpful messages.
@@ -913,7 +913,7 @@ end
## 10. `blame/2` Callback: Enriching Exceptions After the Fact
**Source:** `lib/elixir/lib/exception.ex` lines 22002215 (KeyError.blame)
**Source:** [lib/elixir/lib/exception.ex#L2200](https://github.com/elixir-lang/elixir/blob/f4e1b34617ef92052b65781f18eae5b88a490098/lib/elixir/lib/exception.ex#L2200) (KeyError.blame)
**What it does:** The optional `blame/2` callback enriches an exception with additional context that's expensive to compute (like "did you mean?" suggestions).
@@ -1008,7 +1008,7 @@ end
## 11. Guards for Type Dispatch in Error Handling
**Source:** `lib/elixir/lib/exception.ex` lines 25302550, `lib/elixir/lib/map.ex` lines 586594
**Source:** [lib/elixir/lib/exception.ex#L2530](https://github.com/elixir-lang/elixir/blob/f4e1b34617ef92052b65781f18eae5b88a490098/lib/elixir/lib/exception.ex#L2530), [lib/elixir/lib/map.ex#L586](https://github.com/elixir-lang/elixir/blob/f4e1b34617ef92052b65781f18eae5b88a490098/lib/elixir/lib/map.ex#L586)
**What it does:** Guards (`when is_map(term)`, `when is_list(term)`) dispatch to different error handling or normalization logic without using conditionals.
@@ -1101,7 +1101,7 @@ end
## 12. The `:error` / `{:error, reason}` Convention Split
**Source:** `lib/elixir/lib/map.ex` (Map.fetch → `:error`), `lib/elixir/lib/exception.ex` lines 26952720 (`error_info``{:ok, ...} | :error`)
**Source:** `lib/elixir/lib/map.ex` (Map.fetch → `:error`), [lib/elixir/lib/exception.ex#L2695](https://github.com/elixir-lang/elixir/blob/f4e1b34617ef92052b65781f18eae5b88a490098/lib/elixir/lib/exception.ex#L2695) (`error_info``{:ok, ...} | :error`)
**What it does:** Elixir has two error return conventions:
1. **`:error`** alone — when there's only one failure mode (Map.fetch, Access)
@@ -1197,7 +1197,7 @@ end
## 13. `reduce_while` — Early Exit Without Exceptions
**Source:** `lib/elixir/lib/enum.ex` lines 26602676
**Source:** [lib/elixir/lib/enum.ex#L2660](https://github.com/elixir-lang/elixir/blob/f4e1b34617ef92052b65781f18eae5b88a490098/lib/elixir/lib/enum.ex#L2660)
**What it does:** `reduce_while` uses `{:cont, acc}` / `{:halt, acc}` tuples as the reducer's return value to signal continuation or early termination.
@@ -1291,7 +1291,7 @@ Enum.find(users, & &1.admin?)
## 14. Three-Tier Error Strategy in Map Operations
**Source:** `lib/elixir/lib/map.ex` lines 290430
**Source:** [lib/elixir/lib/map.ex#L290](https://github.com/elixir-lang/elixir/blob/f4e1b34617ef92052b65781f18eae5b88a490098/lib/elixir/lib/map.ex#L290)
**What it does:** Map provides three variants for key operations, each with different error semantics:
@@ -1399,3 +1399,5 @@ end
```
**Why:** The three-tier pattern only makes sense when failure is a real possibility and different callers genuinely need different responses to that failure. Don't cargo-cult it onto functions that always succeed or have a single calling context.
<!-- PATTERN_COMPLETE -->