From 3519e177d60e8931ca805f6c77f29afd83f61d32 Mon Sep 17 00:00:00 2001 From: "@mpyw" Date: Tue, 18 Aug 2026 21:39:25 +0900 Subject: [PATCH] docs: note that an @include fragment owns its leading connector Add a TIP to the Fragment inclusion section. Because @include rides the parser-comment channel it disappears when a template is pasted verbatim, so the surrounding SQL must be valid without the fragment: the including template places a bare directive after a fixed anchor, and the fragment supplies the connector with its predicate. Moving the connector onto the including side would leave a dangling AND (or empty parentheses when wrapped), so the fragment's leading AND is load-bearing, not stylistic. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01YAydPGeSHjZvJv22oz4P6d --- README.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/README.md b/README.md index b65dfb6..ce48302 100644 --- a/README.md +++ b/README.md @@ -411,6 +411,26 @@ unbounded depth. Because the directive is carried on the parser-comment channel, that references a fragment still executes verbatim in a client (the base statement runs without the fragment). +> [!TIP] +> A fragment owns its own leading connector; the including template must not. Because the +> `@include` directive rides the parser-comment channel, it disappears when the template is +> pasted verbatim into a client, so the surrounding SQL has to be valid without it. The +> including template therefore places a bare directive after a fixed anchor, and the fragment +> supplies the connector together with its predicate: +> +> ```sql +> -- including template +> where 1 = 1 /*%! @include active */ +> -- fragment "active" +> /*%if activeOnly*/and status = /*status*/'active'/*%end*/ +> ``` +> +> Moving the connector onto the including side — `where 1 = 1 and /*%! @include active */` — +> would leave a dangling `and` when the fragment is absent, and wrapping the directive as +> `and (/*%! @include active */)` would leave empty parentheses. The fragment's leading `and` +> is therefore load-bearing, not stylistic, and the same holds for `or` chains and any other +> connector. + Fragment resolution is delegated to an implementation of the `Loader` interface: ```go