@wdprlib/parser 1.0.0 → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -1,33 +1,80 @@
1
1
  import { Position as Position2, Point, Version as Version2, Element as Element6, SyntaxTree as SyntaxTree4, ContainerType, ContainerData, AttributeMap, VariableMap, Alignment, LinkType, LinkLocation, LinkLabel, PageRef as PageRef2, ImageSource, FloatAlignment, ListType, ListItem, ListData, CodeBlockData as CodeBlockData2, TabData, TableCell, TableRow, TableData, DefinitionListItem, Module as Module4, CollapsibleData, ClearFloat, AnchorTarget, HeaderType, AlignType, HeadingLevel, Heading, DateItem, Embed, TocEntry as TocEntry2 } from "@wdprlib/ast";
2
2
  import { createPoint, createPosition, text, container, paragraph, bold, italics, heading, lineBreak, horizontalRule, link, list, listItemElements, listItemSubList } from "@wdprlib/ast";
3
+ import { WikitextMode, WikitextSettings as WikitextSettings4 } from "@wdprlib/ast";
4
+ import { createSettings, DEFAULT_SETTINGS } from "@wdprlib/ast";
3
5
  import { Position } from "@wdprlib/ast";
4
6
  /**
5
- * Token types for Wikidot markup
7
+ * Every distinct lexeme the Wikidot lexer can produce.
8
+ *
9
+ * Each value corresponds to a fixed character sequence (or class of
10
+ * sequences) in Wikidot markup. The inline comments show the literal
11
+ * text that produces each token type.
12
+ *
13
+ * @group Lexer
6
14
  */
7
15
  type TokenType = "EOF" | "TEXT" | "IDENTIFIER" | "NEWLINE" | "WHITESPACE" | "BLOCK_OPEN" | "BLOCK_CLOSE" | "BLOCK_END_OPEN" | "BOLD_MARKER" | "ITALIC_MARKER" | "UNDERLINE_MARKER" | "STRIKE_MARKER" | "SUPER_MARKER" | "SUB_MARKER" | "MONO_MARKER" | "MONO_CLOSE" | "HEADING_MARKER" | "HR_MARKER" | "LIST_BULLET" | "LIST_NUMBER" | "BLOCKQUOTE_MARKER" | "TABLE_MARKER" | "TABLE_HEADER" | "TABLE_LEFT" | "TABLE_CENTER" | "TABLE_RIGHT" | "CODE_OPEN" | "CODE_CLOSE" | "LINK_OPEN" | "LINK_CLOSE" | "BRACKET_OPEN" | "BRACKET_CLOSE" | "BRACKET_ANCHOR" | "BRACKET_STAR" | "PIPE" | "EQUALS" | "COLON" | "SLASH" | "STAR" | "HASH" | "AT" | "AMPERSAND" | "BACKSLASH" | "QUOTED_STRING" | "RAW_OPEN" | "RAW_CLOSE" | "RAW_BLOCK_OPEN" | "RAW_BLOCK_CLOSE" | "COLOR_MARKER" | "UNDERSCORE" | "BACKSLASH_BREAK" | "COMMENT_OPEN" | "COMMENT_CLOSE" | "CLEAR_FLOAT" | "CLEAR_FLOAT_LEFT" | "CLEAR_FLOAT_RIGHT" | "LEFT_DOUBLE_ANGLE" | "RIGHT_DOUBLE_ANGLE";
8
16
  /**
9
- * Token
17
+ * A single lexical token produced by the `Lexer`.
18
+ *
19
+ * Tokens are the input to the parser stage. Each token carries its
20
+ * literal text (`value`), source location (`position`), and a flag
21
+ * indicating whether it appeared at the beginning of a line — which
22
+ * matters because several Wikidot constructs (headings, lists,
23
+ * blockquotes, horizontal rules) are only valid at line start.
24
+ *
25
+ * @group Lexer
10
26
  */
11
27
  interface Token {
28
+ /** The lexeme category */
12
29
  type: TokenType;
30
+ /** The literal source text that produced this token */
13
31
  value: string;
32
+ /** Start/end location in the original source string */
14
33
  position: Position;
15
- /** Whether this token appears at the start of a line */
34
+ /**
35
+ * `true` when this token is the first non-whitespace token on its
36
+ * line. Block-level rules (headings, lists, blockquotes) check this
37
+ * flag before attempting to match.
38
+ */
16
39
  lineStart: boolean;
17
40
  }
18
41
  /**
19
- * Create a token
42
+ * Construct a {@link Token} value.
43
+ *
44
+ * @param type - The lexeme category
45
+ * @param value - Literal source text
46
+ * @param position - Source location range
47
+ * @param lineStart - Whether the token starts a new line
48
+ * @returns A new token object
49
+ *
50
+ * @group Lexer
20
51
  */
21
52
  declare function createToken(type: TokenType, value: string, position: Position, lineStart?: boolean): Token;
22
53
  /**
23
- * Lexer options
54
+ * Configuration for the {@link Lexer}.
55
+ *
56
+ * @group Lexer
24
57
  */
25
58
  interface LexerOptions {
26
- /** Track position information */
59
+ /**
60
+ * When `true` (default), every token carries accurate line/column/offset
61
+ * data. Set to `false` to skip position tracking for faster tokenisation
62
+ * when source-map information is not needed.
63
+ */
27
64
  trackPositions?: boolean;
28
65
  }
29
66
  /**
30
- * Wikidot markup lexer
67
+ * Converts a Wikidot markup source string into a flat array of {@link Token}s.
68
+ *
69
+ * The lexer is single-pass and greedy: it tries the longest-matching
70
+ * multi-character pattern first (e.g. `[[[` before `[[`, `**` before `*`).
71
+ * Context-sensitive constructs (line-start headings, blockquote markers)
72
+ * are disambiguated via the `lineStart` state flag.
73
+ *
74
+ * For convenience, use the standalone {@link tokenize} function instead
75
+ * of constructing a `Lexer` directly.
76
+ *
77
+ * @group Lexer
31
78
  */
32
79
  declare class Lexer {
33
80
  private state;
@@ -76,21 +123,59 @@ declare class Lexer {
76
123
  private isAlphanumeric;
77
124
  }
78
125
  /**
79
- * Tokenize source string
126
+ * Tokenise a Wikidot markup source string in one call.
127
+ *
128
+ * Shorthand for `new Lexer(source, options).tokenize()`.
129
+ *
130
+ * @param source - Raw Wikidot markup
131
+ * @param options - Optional lexer configuration
132
+ * @returns A flat array of tokens, ending with an `EOF` token
133
+ *
134
+ * @group Lexer
80
135
  */
81
136
  declare function tokenize(source: string, options?: LexerOptions): Token[];
82
- import { SyntaxTree } from "@wdprlib/ast";
137
+ import { SyntaxTree, WikitextSettings } from "@wdprlib/ast";
83
138
  /**
84
- * Parser options
139
+ * Configuration for the {@link Parser} and the {@link parse} function.
140
+ *
141
+ * All fields are optional; sensible defaults are applied when omitted.
142
+ *
143
+ * @group Parser
85
144
  */
86
145
  interface ParserOptions {
87
- /** Wikidot version */
146
+ /** Markup dialect. Currently only `"wikidot"` is supported. */
88
147
  version?: "wikidot";
89
- /** Track position information */
148
+ /**
149
+ * Propagate source-position data into every AST node.
150
+ * Defaults to `true`. Set to `false` for smaller output when positions
151
+ * are not needed.
152
+ */
90
153
  trackPositions?: boolean;
154
+ /**
155
+ * Context-dependent feature flags (page vs. forum-post, etc.).
156
+ * Defaults to {@link DEFAULT_SETTINGS} (full page mode).
157
+ */
158
+ settings?: WikitextSettings;
91
159
  }
92
160
  /**
93
- * Wikidot markup parser
161
+ * Converts a token stream into a Wikidot {@link SyntaxTree}.
162
+ *
163
+ * The parser consumes tokens produced by the `Lexer` and emits a
164
+ * tree of {@link Element} nodes. Block-level rules are tried in priority
165
+ * order; when none match, the fallback paragraph rule collects inline
166
+ * tokens until the next blank line.
167
+ *
168
+ * After the main parse pass, two post-processing steps run:
169
+ *
170
+ * 1. **Span-strip merging** — `[[span_]]` elements that set
171
+ * `_paragraphStrip` are merged with adjacent paragraphs.
172
+ * 2. **Internal-flag cleanup** — all `_`-prefixed bookkeeping fields
173
+ * are removed from the final AST.
174
+ *
175
+ * For most use-cases the standalone {@link parse} function is simpler
176
+ * than constructing a `Parser` directly.
177
+ *
178
+ * @group Parser
94
179
  */
95
180
  declare class Parser {
96
181
  private ctx;
@@ -127,58 +212,119 @@ declare class Parser {
127
212
  declare function parse(source: string, options?: ParserOptions): SyntaxTree;
128
213
  import { Element as Element2 } from "@wdprlib/ast";
129
214
  /**
130
- * Parser function type for re-parsing substituted templates
131
- * Used by ListPages and ListUsers modules
215
+ * Parser function type for re-parsing substituted template output as wikitext.
216
+ *
217
+ * Used by ListPages and ListUsers modules during the resolution phase. After
218
+ * template variables are substituted with actual data, the resulting string
219
+ * needs to be parsed as wikitext to produce AST elements.
220
+ *
221
+ * @param input - Wikitext string to parse
222
+ * @returns Object containing the parsed elements
132
223
  */
133
224
  type ParseFunction = (input: string) => {
134
225
  elements: Element2[];
135
226
  };
136
227
  /**
137
- * ListUsers module types
228
+ *
229
+ * Type definitions for the ListUsers module.
230
+ *
231
+ * The `[[module ListUsers users="."]]` block displays information about site
232
+ * members. Currently, only `users="."` (the logged-in user) is supported.
233
+ * The template body can reference three variables: `%%number%%`, `%%title%%`,
234
+ * and `%%name%%`.
235
+ *
236
+ * @module
138
237
  */
139
238
  /**
140
- * Supported template variables
239
+ * Supported template variables for ListUsers.
240
+ *
241
+ * - `number` - The user's numeric ID
242
+ * - `title` - The user's display title/nickname
243
+ * - `name` - The user's account name
141
244
  */
142
245
  type ListUsersVariable = "number" | "title" | "name";
143
246
  /**
144
- * User data provided by external source
247
+ * User data that must be provided by the external data source.
248
+ *
249
+ * Each field corresponds to a template variable of the same name.
145
250
  */
146
251
  interface ListUsersUserData {
252
+ /** The user's numeric ID, rendered by `%%number%%` */
147
253
  number: number;
254
+ /** The user's display title, rendered by `%%title%%` */
148
255
  title: string;
256
+ /** The user's account name, rendered by `%%name%%` */
149
257
  name: string;
150
258
  }
151
259
  /**
152
- * Data requirement for a single ListUsers module
260
+ * Data requirement for a single ListUsers module instance.
261
+ *
262
+ * Produced by the extraction phase and consumed by the application to
263
+ * determine what data to fetch.
153
264
  */
154
265
  interface ListUsersDataRequirement {
266
+ /** Unique identifier for this module instance (sequential, 0-based) */
155
267
  id: number;
268
+ /** The `users` attribute value (currently only `"."` is supported) */
156
269
  users: string;
270
+ /** Template variables that need data from the external source */
157
271
  neededVariables: ListUsersVariable[];
158
272
  }
159
273
  /**
160
- * External data for a single ListUsers module
161
- * Note: ListUsers returns only the logged-in user
274
+ * External data provided by the application for a single ListUsers module.
275
+ *
276
+ * Currently ListUsers only returns information about the logged-in user.
277
+ * Return null/undefined from the fetcher to indicate no user is logged in.
162
278
  */
163
279
  interface ListUsersExternalData {
280
+ /** Data for the logged-in user */
164
281
  user: ListUsersUserData;
165
282
  }
166
283
  /**
167
- * Callback to fetch data for a ListUsers module
284
+ * Callback to fetch user data for a ListUsers module.
285
+ *
286
+ * Called during the resolution phase for each ListUsers module in the AST.
287
+ * Return null/undefined to skip the module (outputs nothing, e.g., when
288
+ * no user is logged in).
289
+ *
290
+ * @param requirement - The data requirement describing what data is needed
291
+ * @returns User data, null/undefined to skip, or a Promise of the same
168
292
  */
169
293
  type ListUsersDataFetcher = (requirement: ListUsersDataRequirement) => ListUsersExternalData | null | undefined | Promise<ListUsersExternalData | null | undefined>;
170
294
  /**
171
- * Context passed to compiled template
295
+ * Context passed to a compiled ListUsers template function during rendering.
172
296
  */
173
297
  interface ListUsersVariableContext {
298
+ /** The user whose data is being rendered */
174
299
  user: ListUsersUserData;
175
300
  }
176
301
  /**
177
- * Compiled template function
302
+ * A compiled ListUsers template function.
303
+ *
304
+ * Accepts a variable context and returns the rendered wikitext string
305
+ * with all `%%variable%%` placeholders substituted.
306
+ *
307
+ * @param ctx - The variable context containing user data
308
+ * @returns Rendered wikitext string
178
309
  */
179
310
  type ListUsersCompiledTemplate = (ctx: ListUsersVariableContext) => string;
180
311
  /**
181
- * ListPages module types
312
+ *
313
+ * Type definitions for the ListPages module system.
314
+ *
315
+ * This file defines the complete type vocabulary for the ListPages lifecycle:
316
+ *
317
+ * - **Query types**: Raw and normalized representations of ListPages filter/sort parameters
318
+ * - **Variable types**: The `%%variable%%` names supported in ListPages templates
319
+ * - **Data requirement types**: What the parser tells the application it needs to fetch
320
+ * - **External data types**: What the application provides back (page data, user info, site context)
321
+ * - **Template types**: Compiled template function signatures and their execution context
322
+ * - **Normalized query types**: Structured representations of parsed query parameters
323
+ *
324
+ * Security note: Several fields contain untrusted user input from wikitext.
325
+ * See `ListPagesQuery` documentation for safe usage guidelines.
326
+ *
327
+ * @module
182
328
  */
183
329
  /**
184
330
  * ListPages query parameters for page selection
@@ -381,7 +527,7 @@ interface ListPagesExternalData {
381
527
  * Callback to fetch data for a ListPages module
382
528
  *
383
529
  * Called by resolveModules for each ListPages module in the AST.
384
- * Receives a normalized query with all @URL parameters resolved.
530
+ * Receives a normalized query with all `@URL` parameters resolved.
385
531
  * Return null/undefined to skip the module (outputs nothing).
386
532
  *
387
533
  * @param query - Normalized query with structured types (tags, category, order, etc.)
@@ -523,47 +669,60 @@ interface NormalizedListPagesQuery {
523
669
  reverse?: boolean;
524
670
  }
525
671
  /**
526
- * Callback to get current page's tags
672
+ * Callback to retrieve the current page's tags during the resolve phase.
527
673
  *
528
- * Called during resolve phase to evaluate [[iftags]] conditions.
674
+ * Called when evaluating `[[iftags]]` conditions. The application must provide
675
+ * this callback with access to the current page's tag list.
529
676
  *
530
677
  * @returns Array of tag names for the current page
531
678
  */
532
679
  type IfTagsResolver = () => string[];
533
680
  /**
534
- * Data provider interface for resolving modules that require external data
681
+ * Callback bag for supplying external data during module resolution.
535
682
  *
536
- * All callbacks are optional - if not provided, the corresponding
537
- * module/syntax will be output as-is in the AST without resolution.
683
+ * Pass an instance to `resolveModules()`. Every callback is optional:
684
+ * when a callback is missing the corresponding module node is kept as-is
685
+ * in the output AST — useful when you only need to resolve a subset of
686
+ * modules (e.g. only `[[iftags]]` on the client side).
538
687
  *
539
- * Note: Include resolution is handled separately via resolveIncludes().
688
+ * @group Module Resolution
540
689
  */
541
690
  interface DataProvider {
542
691
  /**
543
- * Fetch data for ListPages module
544
- * Called during resolve phase with query parameters
692
+ * Fetch page data for `[[module ListPages]]` expansion.
545
693
  *
546
- * @security `req.query` / `req.rawAttributes` are **untrusted user input** from wikitext.
547
- * When building database queries:
548
- * - **NEVER** interpolate them into SQL strings
549
- * - **ALWAYS** use parameterized queries / prepared statements
550
- * - For `order` (ORDER BY), use a whitelist of allowed column names
694
+ * Called once per ListPages instance in the AST with the normalised
695
+ * query parameters extracted from the module's wikitext attributes.
696
+ *
697
+ * @security The query fields originate from **untrusted user input**.
698
+ * When building database queries from the returned requirement:
699
+ * - **Never** interpolate `req.query` / `req.rawAttributes` into SQL
700
+ * - **Always** use parameterised queries or prepared statements
701
+ * - For `order` (ORDER BY), validate against a whitelist of column names
551
702
  */
552
703
  fetchListPages?: ListPagesDataFetcher;
553
704
  /**
554
- * Fetch data for ListUsers module
555
- * Called during resolve phase with user query parameters
705
+ * Fetch user data for `[[module ListUsers]]` expansion.
706
+ *
707
+ * Called once per ListUsers instance with the parsed query parameters.
556
708
  */
557
709
  fetchListUsers?: ListUsersDataFetcher;
558
710
  /**
559
- * Get current page's tags for iftags evaluation
560
- * Called during resolve phase to evaluate [[iftags]] conditions
711
+ * Return the current page's tags for `[[iftags]]` evaluation.
712
+ *
713
+ * If provided, `[[iftags]]` blocks are evaluated and either kept or
714
+ * discarded based on whether the page's tags satisfy the condition.
715
+ * If omitted, `[[iftags]]` blocks pass through unresolved.
561
716
  */
562
717
  getPageTags?: IfTagsResolver;
563
718
  }
564
719
  import { SyntaxTree as SyntaxTree2 } from "@wdprlib/ast";
565
720
  /**
566
- * Result of extraction including compiled templates
721
+ * Complete result of extracting data requirements from an AST.
722
+ *
723
+ * Contains everything needed to fetch external data and then resolve modules:
724
+ * the data requirements tell the application what to fetch, and the pre-compiled
725
+ * templates are used during the resolution phase to efficiently render results.
567
726
  */
568
727
  interface ExtractionResult {
569
728
  /** Data requirements for external fetching */
@@ -574,11 +733,29 @@ interface ExtractionResult {
574
733
  compiledListUsersTemplates: Map<number, ListUsersCompiledTemplate>;
575
734
  }
576
735
  /**
577
- * Extract data requirements from a parsed AST
736
+ * Extract all data requirements from a parsed AST.
737
+ *
738
+ * Walks the entire AST to find ListPages and ListUsers module elements,
739
+ * analyzes their templates to determine which variables are used, builds
740
+ * query objects from their attributes, and pre-compiles their templates.
741
+ *
742
+ * Each module is assigned a sequential ID (separate counters for ListPages
743
+ * and ListUsers) that is used to correlate requirements with fetched data
744
+ * and compiled templates during the resolution phase.
745
+ *
746
+ * @param ast - The parsed syntax tree to analyze
747
+ * @returns Extraction result containing requirements and compiled templates
578
748
  */
579
749
  declare function extractDataRequirements(ast: SyntaxTree2): ExtractionResult;
580
750
  /**
581
- * Compile a template string into an executable function
751
+ * Compile a ListPages template string into an executable function.
752
+ *
753
+ * The template is split into alternating static strings and dynamic getter
754
+ * functions. The returned function concatenates these parts with the getter
755
+ * functions evaluated against the provided variable context.
756
+ *
757
+ * @param template - The template string containing `%%variable%%` placeholders
758
+ * @returns A compiled function that accepts a `VariableContext` and returns the rendered string
582
759
  */
583
760
  declare function compileTemplate(template: string): CompiledTemplate;
584
761
  /**
@@ -655,7 +832,7 @@ declare function parseNumericSelector(value: string): NormalizedNumericSelector
655
832
  * @returns Normalized query with structured types
656
833
  */
657
834
  declare function normalizeQuery(query: ListPagesQuery): NormalizedListPagesQuery;
658
- import { PageRef } from "@wdprlib/ast";
835
+ import { PageRef, WikitextSettings as WikitextSettings3 } from "@wdprlib/ast";
659
836
  /**
660
837
  * Callback to fetch page content for include resolution.
661
838
  * Returns the wikitext source of the page, or null if the page does not exist.
@@ -671,6 +848,8 @@ type IncludeFetcher = (pageRef: PageRef) => string | null;
671
848
  interface ResolveIncludesOptions {
672
849
  /** Maximum recursion depth for nested includes (default: 5) */
673
850
  maxDepth?: number;
851
+ /** Wikitext settings. If enablePageSyntax is false, includes are not expanded. */
852
+ settings?: WikitextSettings3;
674
853
  }
675
854
  /**
676
855
  * Expand all [[include]] directives in the source text.
@@ -688,49 +867,85 @@ interface ResolveIncludesOptions {
688
867
  */
689
868
  declare function resolveIncludes(source: string, fetcher: IncludeFetcher, options?: ResolveIncludesOptions): string;
690
869
  /**
691
- * Compile a template string into an executable function
870
+ * Compile a ListUsers template string into an executable function.
871
+ *
872
+ * The template is split into alternating static strings and dynamic getter
873
+ * functions. The returned function concatenates these parts for each call.
874
+ *
875
+ * @param template - The template string containing `%%variable%%` placeholders
876
+ * @returns A compiled function that accepts a `ListUsersVariableContext` and returns rendered text
692
877
  */
693
878
  declare function compileListUsersTemplate(template: string): ListUsersCompiledTemplate;
694
879
  /**
695
- * Extract needed variables from a template string
880
+ * Extract the set of template variables referenced in a ListUsers template string.
881
+ *
882
+ * Scans for `%%variable%%` patterns and returns only those that match known
883
+ * ListUsers variables. Unknown variables are silently ignored.
884
+ *
885
+ * @param template - The template string from the module body
886
+ * @returns Deduplicated array of referenced variable names
696
887
  */
697
888
  declare function extractListUsersVariables(template: string): ListUsersVariable[];
698
889
  import { Element as Element5, Module as Module3 } from "@wdprlib/ast";
699
890
  /**
700
- * ListUsers module data type
891
+ * Narrowed type for the list-users variant of the Module discriminated union.
701
892
  */
702
893
  type ListUsersModuleData = Extract<Module3, {
703
894
  module: "list-users";
704
895
  }>;
705
896
  /**
706
- * Type guard for list-users module
897
+ * Type guard to check if a Module is a list-users module.
898
+ *
899
+ * @param module - A Module discriminated union value
900
+ * @returns true if the module is a list-users module
707
901
  */
708
902
  declare function isListUsersModule(module: Module3): module is ListUsersModuleData;
709
903
  /**
710
- * Resolve a single ListUsers module
711
- * Note: ListUsers returns only the logged-in user
904
+ * Resolve a single ListUsers module by substituting fetched user data into
905
+ * the pre-compiled template and re-parsing the result as wikitext.
906
+ *
907
+ * Currently ListUsers only renders the logged-in user (no iteration over
908
+ * multiple users), so the template is executed exactly once.
909
+ *
910
+ * @param _module - The list-users module data from the AST (unused, reserved for future use)
911
+ * @param data - External user data fetched by the application
912
+ * @param compiledTemplate - Pre-compiled template function from the extraction phase
913
+ * @param parse - Parser function for re-parsing the substituted template as wikitext
914
+ * @returns Array of AST elements produced by parsing the rendered template
712
915
  */
713
916
  declare function resolveListUsers(_module: ListUsersModuleData, data: ListUsersExternalData, compiledTemplate: ListUsersCompiledTemplate, parse: ParseFunction): Element5[];
714
917
  import { SyntaxTree as SyntaxTree3 } from "@wdprlib/ast";
715
918
  /**
716
- * Options for resolving modules
919
+ * Configuration for {@link resolveModules}.
920
+ *
921
+ * Callers must supply pre-extracted requirements and pre-compiled
922
+ * templates (obtained from `extractDataRequirements()` and
923
+ * `compileTemplate()` / `compileListUsersTemplate()`).
924
+ *
925
+ * @group Module Resolution
717
926
  */
718
927
  interface ResolveOptions {
719
- /** Parser function for re-parsing templates */
928
+ /** Parser function used to re-parse expanded template markup into AST nodes */
720
929
  parse: ParseFunction;
721
- /** Pre-compiled templates for ListPages */
930
+ /** Pre-compiled ListPages body templates, keyed by requirement ID */
722
931
  compiledListPagesTemplates: Map<number, CompiledTemplate>;
723
- /** Pre-compiled templates for ListUsers */
932
+ /** Pre-compiled ListUsers body templates, keyed by requirement ID */
724
933
  compiledListUsersTemplates?: Map<number, ListUsersCompiledTemplate>;
725
- /** Data requirements grouped by module type */
934
+ /**
935
+ * Data requirements grouped by module type.
936
+ * Obtained from `extractDataRequirements()`.
937
+ */
726
938
  requirements: {
727
939
  listPages?: ListPagesDataRequirement[];
728
940
  listUsers?: ListUsersDataRequirement[];
729
941
  };
730
942
  /**
731
- * URL path for @URL parameter resolution (HPC support)
732
- * Format: "/page-name/param/value/param/value"
733
- * Example: "/scp-001/offset/10/page2_limit/5"
943
+ * URL path for `@URL` parameter resolution (HPC / pagination support).
944
+ *
945
+ * Wikidot encodes pagination state in the URL path as key/value pairs
946
+ * after the page name, e.g. `"/scp-001/offset/10/page2_limit/5"`.
947
+ * When provided, `@URL` references in ListPages queries are replaced
948
+ * with the corresponding values from this path.
734
949
  */
735
950
  urlPath?: string;
736
951
  }
@@ -749,4 +964,4 @@ interface ResolveOptions {
749
964
  * @param options - Resolution options including requirements
750
965
  */
751
966
  declare function resolveModules(ast: SyntaxTree3, dataProvider: DataProvider, options: ResolveOptions): Promise<SyntaxTree3>;
752
- export { tokenize, text, resolveModules, resolveListUsers, resolveIncludes, parseTags, parseParent, parseOrder, parseNumericSelector, parseDateSelector, parseCategory, parse, paragraph, normalizeQuery, listItemSubList, listItemElements, list, link, lineBreak, italics, isListUsersModule, horizontalRule, heading, extractListUsersVariables, extractDataRequirements, createToken, createPosition, createPoint, container, compileTemplate, compileListUsersTemplate, bold, Version2 as Version, VariableMap, VariableContext, UserInfo, TokenType, Token, TocEntry2 as TocEntry, TableRow, TableData, TableCell, TabData, SyntaxTree4 as SyntaxTree, SiteContext, ResolveOptions, ResolveIncludesOptions, Position2 as Position, Point, ParserOptions, Parser, ParseFunction, PageRef2 as PageRef, PageData, NormalizedTags, NormalizedParent, NormalizedOrder, NormalizedNumericSelector, NormalizedListPagesQuery, NormalizedDateSelector, NormalizedCategory, Module4 as Module, ListUsersVariableContext, ListUsersVariable, ListUsersUserData, ListUsersExternalData, ListUsersDataRequirement, ListUsersDataFetcher, ListUsersCompiledTemplate, ListType, ListPagesVariable, ListPagesQuery, ListPagesExternalData, ListPagesDataRequirement, ListPagesDataFetcher, ListItem, ListData, LinkType, LinkLocation, LinkLabel, LexerOptions, Lexer, IncludeFetcher, ImageSource, HeadingLevel, Heading, HeaderType, FloatAlignment, ExtractionResult, Embed, Element6 as Element, DefinitionListItem, DateItem, DataRequirements, DataProvider, ContainerType, ContainerData, CompiledTemplate, CollapsibleData, CodeBlockData2 as CodeBlockData, ClearFloat, AttributeMap, AnchorTarget, Alignment, AlignType };
967
+ export { tokenize, text, resolveModules, resolveListUsers, resolveIncludes, parseTags, parseParent, parseOrder, parseNumericSelector, parseDateSelector, parseCategory, parse, paragraph, normalizeQuery, listItemSubList, listItemElements, list, link, lineBreak, italics, isListUsersModule, horizontalRule, heading, extractListUsersVariables, extractDataRequirements, createToken, createSettings, createPosition, createPoint, container, compileTemplate, compileListUsersTemplate, bold, WikitextSettings4 as WikitextSettings, WikitextMode, Version2 as Version, VariableMap, VariableContext, UserInfo, TokenType, Token, TocEntry2 as TocEntry, TableRow, TableData, TableCell, TabData, SyntaxTree4 as SyntaxTree, SiteContext, ResolveOptions, ResolveIncludesOptions, Position2 as Position, Point, ParserOptions, Parser, ParseFunction, PageRef2 as PageRef, PageData, NormalizedTags, NormalizedParent, NormalizedOrder, NormalizedNumericSelector, NormalizedListPagesQuery, NormalizedDateSelector, NormalizedCategory, Module4 as Module, ListUsersVariableContext, ListUsersVariable, ListUsersUserData, ListUsersExternalData, ListUsersDataRequirement, ListUsersDataFetcher, ListUsersCompiledTemplate, ListType, ListPagesVariable, ListPagesQuery, ListPagesExternalData, ListPagesDataRequirement, ListPagesDataFetcher, ListItem, ListData, LinkType, LinkLocation, LinkLabel, LexerOptions, Lexer, IncludeFetcher, ImageSource, HeadingLevel, Heading, HeaderType, FloatAlignment, ExtractionResult, Embed, Element6 as Element, DefinitionListItem, DateItem, DataRequirements, DataProvider, DEFAULT_SETTINGS, ContainerType, ContainerData, CompiledTemplate, CollapsibleData, CodeBlockData2 as CodeBlockData, ClearFloat, AttributeMap, AnchorTarget, Alignment, AlignType };