@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.cjs +65 -25
- package/dist/index.d.cts +277 -62
- package/dist/index.d.ts +277 -62
- package/dist/index.js +50 -10
- package/package.json +2 -2
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
|
-
*
|
|
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
|
-
*
|
|
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
|
-
/**
|
|
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
|
-
*
|
|
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
|
|
54
|
+
* Configuration for the {@link Lexer}.
|
|
55
|
+
*
|
|
56
|
+
* @group Lexer
|
|
24
57
|
*/
|
|
25
58
|
interface LexerOptions {
|
|
26
|
-
/**
|
|
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
|
|
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
|
-
*
|
|
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
|
|
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
|
-
/**
|
|
146
|
+
/** Markup dialect. Currently only `"wikidot"` is supported. */
|
|
88
147
|
version?: "wikidot";
|
|
89
|
-
/**
|
|
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
|
|
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
|
|
131
|
-
*
|
|
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
|
-
*
|
|
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
|
-
*
|
|
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
|
-
*
|
|
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
|
-
*
|
|
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
|
|
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
|
|
672
|
+
* Callback to retrieve the current page's tags during the resolve phase.
|
|
527
673
|
*
|
|
528
|
-
* Called
|
|
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
|
-
*
|
|
681
|
+
* Callback bag for supplying external data during module resolution.
|
|
535
682
|
*
|
|
536
|
-
*
|
|
537
|
-
*
|
|
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
|
-
*
|
|
688
|
+
* @group Module Resolution
|
|
540
689
|
*/
|
|
541
690
|
interface DataProvider {
|
|
542
691
|
/**
|
|
543
|
-
* Fetch data for ListPages
|
|
544
|
-
* Called during resolve phase with query parameters
|
|
692
|
+
* Fetch page data for `[[module ListPages]]` expansion.
|
|
545
693
|
*
|
|
546
|
-
*
|
|
547
|
-
*
|
|
548
|
-
*
|
|
549
|
-
*
|
|
550
|
-
*
|
|
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
|
|
555
|
-
*
|
|
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
|
-
*
|
|
560
|
-
*
|
|
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
|
-
*
|
|
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
|
|
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
|
-
*
|
|
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
|
|
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
|
-
*
|
|
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
|
-
*
|
|
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
|
|
928
|
+
/** Parser function used to re-parse expanded template markup into AST nodes */
|
|
720
929
|
parse: ParseFunction;
|
|
721
|
-
/** Pre-compiled templates
|
|
930
|
+
/** Pre-compiled ListPages body templates, keyed by requirement ID */
|
|
722
931
|
compiledListPagesTemplates: Map<number, CompiledTemplate>;
|
|
723
|
-
/** Pre-compiled templates
|
|
932
|
+
/** Pre-compiled ListUsers body templates, keyed by requirement ID */
|
|
724
933
|
compiledListUsersTemplates?: Map<number, ListUsersCompiledTemplate>;
|
|
725
|
-
/**
|
|
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
|
|
732
|
-
*
|
|
733
|
-
*
|
|
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 };
|