saxes.d.ts
1 /** 2 * The list of supported events. 3 */ 4 export declare const EVENTS: readonly ["xmldecl", "text", "processinginstruction", "doctype", "comment", "opentagstart", "attribute", "opentag", "closetag", "cdata", "error", "end", "ready"]; 5 /** 6 * Event handler for the 7 * 8 * @param text The text data encountered by the parser. 9 * 10 */ 11 export declare type XMLDeclHandler = (decl: XMLDecl) => void; 12 /** 13 * Event handler for text data. 14 * 15 * @param text The text data encountered by the parser. 16 * 17 */ 18 export declare type TextHandler = (text: string) => void; 19 /** 20 * Event handler for processing instructions. 21 * 22 * @param data The target and body of the processing instruction. 23 */ 24 export declare type PIHandler = (data: { 25 target: string; 26 body: string; 27 }) => void; 28 /** 29 * Event handler for doctype. 30 * 31 * @param doctype The doctype contents. 32 */ 33 export declare type DoctypeHandler = (doctype: string) => void; 34 /** 35 * Event handler for comments. 36 * 37 * @param comment The comment contents. 38 */ 39 export declare type CommentHandler = (comment: string) => void; 40 /** 41 * Event handler for the start of an open tag. This is called as soon as we 42 * have a tag name. 43 * 44 * @param tag The tag. 45 */ 46 export declare type OpenTagStartHandler<O> = (tag: StartTagForOptions<O>) => void; 47 export declare type AttributeEventForOptions<O extends SaxesOptions> = O extends { 48 xmlns: true; 49 } ? SaxesAttributeNSIncomplete : O extends { 50 xmlns?: false | undefined; 51 } ? SaxesAttributePlain : SaxesAttribute; 52 /** 53 * Event handler for attributes. 54 */ 55 export declare type AttributeHandler<O> = (attribute: AttributeEventForOptions<O>) => void; 56 /** 57 * Event handler for an open tag. This is called when the open tag is 58 * complete. (We've encountered the ">" that ends the open tag.) 59 * 60 * @param tag The tag. 61 */ 62 export declare type OpenTagHandler<O> = (tag: TagForOptions<O>) => void; 63 /** 64 * Event handler for a close tag. Note that for self-closing tags, this is 65 * called right after ``opentag``. 66 * 67 * @param tag The tag. 68 */ 69 export declare type CloseTagHandler<O> = (tag: TagForOptions<O>) => void; 70 /** 71 * Event handler for a CDATA section. This is called when ending the 72 * CDATA section. 73 * 74 * @param cdata The contents of the CDATA section. 75 */ 76 export declare type CDataHandler = (cdata: string) => void; 77 /** 78 * Event handler for the stream end. This is called when the stream has been 79 * closed with ``close`` or by passing ``null`` to ``write``. 80 */ 81 export declare type EndHandler = () => void; 82 /** 83 * Event handler indicating parser readiness . This is called when the parser 84 * is ready to parse a new document. 85 */ 86 export declare type ReadyHandler = () => void; 87 /** 88 * Event handler indicating an error. 89 * 90 * @param err The error that occurred. 91 */ 92 export declare type ErrorHandler = (err: Error) => void; 93 export declare type EventName = (typeof EVENTS)[number]; 94 export declare type EventNameToHandler<O, N extends EventName> = { 95 "xmldecl": XMLDeclHandler; 96 "text": TextHandler; 97 "processinginstruction": PIHandler; 98 "doctype": DoctypeHandler; 99 "comment": CommentHandler; 100 "opentagstart": OpenTagStartHandler<O>; 101 "attribute": AttributeHandler<O>; 102 "opentag": OpenTagHandler<O>; 103 "closetag": CloseTagHandler<O>; 104 "cdata": CDataHandler; 105 "error": ErrorHandler; 106 "end": EndHandler; 107 "ready": ReadyHandler; 108 }[N]; 109 /** 110 * This interface defines the structure of attributes when the parser is 111 * processing namespaces (created with ``xmlns: true``). 112 */ 113 export interface SaxesAttributeNS { 114 /** 115 * The attribute's name. This is the combination of prefix and local name. 116 * For instance ``a:b="c"`` would have ``a:b`` for name. 117 */ 118 name: string; 119 /** 120 * The attribute's prefix. For instance ``a:b="c"`` would have ``"a"`` for 121 * ``prefix``. 122 */ 123 prefix: string; 124 /** 125 * The attribute's local name. For instance ``a:b="c"`` would have ``"b"`` for 126 * ``local``. 127 */ 128 local: string; 129 /** The namespace URI of this attribute. */ 130 uri: string; 131 /** The attribute's value. */ 132 value: string; 133 } 134 /** 135 * This is an attribute, as recorded by a parser which parses namespaces but 136 * prior to the URI being resolvable. This is what is passed to the attribute 137 * event handler. 138 */ 139 export declare type SaxesAttributeNSIncomplete = Exclude<SaxesAttributeNS, "uri">; 140 /** 141 * This interface defines the structure of attributes when the parser is 142 * NOT processing namespaces (created with ``xmlns: false``). 143 */ 144 export interface SaxesAttributePlain { 145 /** 146 * The attribute's name. 147 */ 148 name: string; 149 /** The attribute's value. */ 150 value: string; 151 } 152 /** 153 * A saxes attribute, with or without namespace information. 154 */ 155 export declare type SaxesAttribute = SaxesAttributeNS | SaxesAttributePlain; 156 /** 157 * This are the fields that MAY be present on a complete tag. 158 */ 159 export interface SaxesTag { 160 /** 161 * The tag's name. This is the combination of prefix and global name. For 162 * instance ``<a:b>`` would have ``"a:b"`` for ``name``. 163 */ 164 name: string; 165 /** 166 * A map of attribute name to attributes. If namespaces are tracked, the 167 * values in the map are attribute objects. Otherwise, they are strings. 168 */ 169 attributes: Record<string, SaxesAttributeNS> | Record<string, string>; 170 /** 171 * The namespace bindings in effect. 172 */ 173 ns?: Record<string, string>; 174 /** 175 * The tag's prefix. For instance ``<a:b>`` would have ``"a"`` for 176 * ``prefix``. Undefined if we do not track namespaces. 177 */ 178 prefix?: string; 179 /** 180 * The tag's local name. For instance ``<a:b>`` would 181 * have ``"b"`` for ``local``. Undefined if we do not track namespaces. 182 */ 183 local?: string; 184 /** 185 * The namespace URI of this tag. Undefined if we do not track namespaces. 186 */ 187 uri?: string; 188 /** Whether the tag is self-closing (e.g. ``<foo/>``). */ 189 isSelfClosing: boolean; 190 } 191 /** 192 * This type defines the fields that are present on a tag object when 193 * ``onopentagstart`` is called. This interface is namespace-agnostic. 194 */ 195 export declare type SaxesStartTag = Pick<SaxesTag, "name" | "attributes" | "ns">; 196 /** 197 * This type defines the fields that are present on a tag object when 198 * ``onopentagstart`` is called on a parser that does not processes namespaces. 199 */ 200 export declare type SaxesStartTagPlain = Pick<SaxesStartTag, "name" | "attributes">; 201 /** 202 * This type defines the fields that are present on a tag object when 203 * ``onopentagstart`` is called on a parser that does process namespaces. 204 */ 205 export declare type SaxesStartTagNS = Required<SaxesStartTag>; 206 /** 207 * This are the fields that are present on a complete tag produced by a parser 208 * that does process namespaces. 209 */ 210 export declare type SaxesTagNS = Required<SaxesTag> & { 211 attributes: Record<string, SaxesAttributeNS>; 212 }; 213 /** 214 * This are the fields that are present on a complete tag produced by a parser 215 * that does not process namespaces. 216 */ 217 export declare type SaxesTagPlain = Pick<SaxesTag, "name" | "attributes" | "isSelfClosing"> & { 218 attributes: Record<string, string>; 219 }; 220 /** 221 * An XML declaration. 222 */ 223 export interface XMLDecl { 224 /** The version specified by the XML declaration. */ 225 version?: string; 226 /** The encoding specified by the XML declaration. */ 227 encoding?: string; 228 /** The value of the standalone parameter */ 229 standalone?: string; 230 } 231 /** 232 * A callback for resolving name prefixes. 233 * 234 * @param prefix The prefix to check. 235 * 236 * @returns The URI corresponding to the prefix, if any. 237 */ 238 export declare type ResolvePrefix = (prefix: string) => string | undefined; 239 export interface CommonOptions { 240 /** Whether to accept XML fragments. Unset means ``false``. */ 241 fragment?: boolean; 242 /** Whether to track positions. Unset means ``true``. */ 243 position?: boolean; 244 /** 245 * A file name to use for error reporting. "File name" is a loose concept. You 246 * could use a URL to some resource, or any descriptive name you like. 247 */ 248 fileName?: string; 249 } 250 export interface NSOptions { 251 /** Whether to track namespaces. Unset means ``false``. */ 252 xmlns?: boolean; 253 /** 254 * A plain object whose key, value pairs define namespaces known before 255 * parsing the XML file. It is not legal to pass bindings for the namespaces 256 * ``"xml"`` or ``"xmlns"``. 257 */ 258 additionalNamespaces?: Record<string, string>; 259 /** 260 * A function that will be used if the parser cannot resolve a namespace 261 * prefix on its own. 262 */ 263 resolvePrefix?: ResolvePrefix; 264 } 265 export interface NSOptionsWithoutNamespaces extends NSOptions { 266 xmlns?: false; 267 additionalNamespaces?: undefined; 268 resolvePrefix?: undefined; 269 } 270 export interface NSOptionsWithNamespaces extends NSOptions { 271 xmlns: true; 272 } 273 export interface XMLVersionOptions { 274 /** 275 * The default XML version to use. If unspecified, and there is no XML 276 * encoding declaration, the default version is "1.0". 277 */ 278 defaultXMLVersion?: "1.0" | "1.1"; 279 /** 280 * A flag indicating whether to force the XML version used for parsing to the 281 * value of ``defaultXMLVersion``. When this flag is ``true``, 282 * ``defaultXMLVersion`` must be specified. If unspecified, the default value 283 * of this flag is ``false``. 284 */ 285 forceXMLVersion?: boolean; 286 } 287 export interface NoForcedXMLVersion extends XMLVersionOptions { 288 forceXMLVersion?: false; 289 } 290 export interface ForcedXMLVersion extends XMLVersionOptions { 291 forceXMLVersion: true; 292 defaultXMLVersion: Exclude<XMLVersionOptions["defaultXMLVersion"], undefined>; 293 } 294 /** 295 * The entire set of options supported by saxes. 296 */ 297 export declare type SaxesOptions = CommonOptions & NSOptions & XMLVersionOptions; 298 export declare type TagForOptions<O extends SaxesOptions> = O extends { 299 xmlns: true; 300 } ? SaxesTagNS : O extends { 301 xmlns?: false | undefined; 302 } ? SaxesTagPlain : SaxesTag; 303 export declare type StartTagForOptions<O extends SaxesOptions> = O extends { 304 xmlns: true; 305 } ? SaxesStartTagNS : O extends { 306 xmlns?: false | undefined; 307 } ? SaxesStartTagPlain : SaxesStartTag; 308 export declare class SaxesParser<O extends SaxesOptions = {}> { 309 private readonly fragmentOpt; 310 private readonly xmlnsOpt; 311 private readonly trackPosition; 312 private readonly fileName?; 313 private readonly nameStartCheck; 314 private readonly nameCheck; 315 private readonly isName; 316 private readonly ns; 317 private openWakaBang; 318 private text; 319 private name; 320 private piTarget; 321 private entity; 322 private q; 323 private tags; 324 private tag; 325 private topNS; 326 private chunk; 327 private chunkPosition; 328 private i; 329 private prevI; 330 private carriedFromPrevious?; 331 private forbiddenState; 332 private attribList; 333 private state; 334 private reportedTextBeforeRoot; 335 private reportedTextAfterRoot; 336 private closedRoot; 337 private sawRoot; 338 private xmlDeclPossible; 339 private xmlDeclExpects; 340 private entityReturnState?; 341 private processAttribs; 342 private positionAtNewLine; 343 private doctype; 344 private getCode; 345 private isChar; 346 private pushAttrib; 347 private _closed; 348 private currentXMLVersion; 349 private readonly stateTable; 350 private xmldeclHandler?; 351 private textHandler?; 352 private piHandler?; 353 private doctypeHandler?; 354 private commentHandler?; 355 private openTagStartHandler?; 356 private openTagHandler?; 357 private closeTagHandler?; 358 private cdataHandler?; 359 private errorHandler?; 360 private endHandler?; 361 private readyHandler?; 362 private attributeHandler?; 363 /** 364 * Indicates whether or not the parser is closed. If ``true``, wait for 365 * the ``ready`` event to write again. 366 */ 367 get closed(): boolean; 368 readonly opt: SaxesOptions; 369 /** 370 * The XML declaration for this document. 371 */ 372 xmlDecl: XMLDecl; 373 /** 374 * The line number of the next character to be read by the parser. This field 375 * is one-based. (The first line is numbered 1.) 376 */ 377 line: number; 378 /** 379 * The column number of the next character to be read by the parser. * 380 * This field is zero-based. (The first column is 0.) 381 * 382 * This field counts columns by *Unicode character*. Note that this *can* 383 * be different from the index of the character in a JavaScript string due 384 * to how JavaScript handles astral plane characters. 385 * 386 * See [[columnIndex]] for a number that corresponds to the JavaScript index. 387 */ 388 column: number; 389 /** 390 * A map of entity name to expansion. 391 */ 392 ENTITIES: Record<string, string>; 393 /** 394 * @param opt The parser options. 395 */ 396 constructor(opt?: O); 397 _init(): void; 398 /** 399 * The stream position the parser is currently looking at. This field is 400 * zero-based. 401 * 402 * This field is not based on counting Unicode characters but is to be 403 * interpreted as a plain index into a JavaScript string. 404 */ 405 get position(): number; 406 /** 407 * The column number of the next character to be read by the parser. * 408 * This field is zero-based. (The first column in a line is 0.) 409 * 410 * This field reports the index at which the next character would be in the 411 * line if the line were represented as a JavaScript string. Note that this 412 * *can* be different to a count based on the number of *Unicode characters* 413 * due to how JavaScript handles astral plane characters. 414 * 415 * See [[column]] for a number that corresponds to a count of Unicode 416 * characters. 417 */ 418 get columnIndex(): number; 419 /** 420 * Set an event listener on an event. The parser supports one handler per 421 * event type. If you try to set an event handler over an existing handler, 422 * the old handler is silently overwritten. 423 * 424 * @param name The event to listen to. 425 * 426 * @param handler The handler to set. 427 */ 428 on<N extends EventName>(name: N, handler: EventNameToHandler<O, N>): void; 429 /** 430 * Unset an event handler. 431 * 432 * @parma name The event to stop listening to. 433 */ 434 off(name: EventName): void; 435 /** 436 * Make an error object. The error object will have a message that contains 437 * the ``fileName`` option passed at the creation of the parser. If position 438 * tracking was turned on, it will also have line and column number 439 * information. 440 * 441 * @param message The message describing the error to report. 442 * 443 * @returns An error object with a properly formatted message. 444 */ 445 makeError(message: string): Error; 446 /** 447 * Report a parsing error. This method is made public so that client code may 448 * check for issues that are outside the scope of this project and can report 449 * errors. 450 * 451 * @param message The error to report. 452 * 453 * @returns this 454 */ 455 fail(message: string): this; 456 /** 457 * Write a XML data to the parser. 458 * 459 * @param chunk The XML data to write. 460 * 461 * @returns this 462 */ 463 write(chunk: string | {} | null): this; 464 /** 465 * Close the current stream. Perform final well-formedness checks and reset 466 * the parser tstate. 467 * 468 * @returns this 469 */ 470 close(): this; 471 /** 472 * Get a single code point out of the current chunk. This updates the current 473 * position if we do position tracking. 474 * 475 * This is the algorithm to use for XML 1.0. 476 * 477 * @returns The character read. 478 */ 479 private getCode10; 480 /** 481 * Get a single code point out of the current chunk. This updates the current 482 * position if we do position tracking. 483 * 484 * This is the algorithm to use for XML 1.1. 485 * 486 * @returns {number} The character read. 487 */ 488 private getCode11; 489 /** 490 * Like ``getCode`` but with the return value normalized so that ``NL`` is 491 * returned for ``NL_LIKE``. 492 */ 493 private getCodeNorm; 494 private unget; 495 /** 496 * Capture characters into a buffer until encountering one of a set of 497 * characters. 498 * 499 * @param chars An array of codepoints. Encountering a character in the array 500 * ends the capture. (``chars`` may safely contain ``NL``.) 501 * 502 * @return The character code that made the capture end, or ``EOC`` if we hit 503 * the end of the chunk. The return value cannot be NL_LIKE: NL is returned 504 * instead. 505 */ 506 private captureTo; 507 /** 508 * Capture characters into a buffer until encountering a character. 509 * 510 * @param char The codepoint that ends the capture. **NOTE ``char`` MAY NOT 511 * CONTAIN ``NL``.** Passing ``NL`` will result in buggy behavior. 512 * 513 * @return ``true`` if we ran into the character. Otherwise, we ran into the 514 * end of the current chunk. 515 */ 516 private captureToChar; 517 /** 518 * Capture characters that satisfy ``isNameChar`` into the ``name`` field of 519 * this parser. 520 * 521 * @return The character code that made the test fail, or ``EOC`` if we hit 522 * the end of the chunk. The return value cannot be NL_LIKE: NL is returned 523 * instead. 524 */ 525 private captureNameChars; 526 /** 527 * Skip white spaces. 528 * 529 * @return The character that ended the skip, or ``EOC`` if we hit 530 * the end of the chunk. The return value cannot be NL_LIKE: NL is returned 531 * instead. 532 */ 533 private skipSpaces; 534 private setXMLVersion; 535 private sBegin; 536 private sBeginWhitespace; 537 private sDoctype; 538 private sDoctypeQuote; 539 private sDTD; 540 private sDTDQuoted; 541 private sDTDOpenWaka; 542 private sDTDOpenWakaBang; 543 private sDTDComment; 544 private sDTDCommentEnding; 545 private sDTDCommentEnded; 546 private sDTDPI; 547 private sDTDPIEnding; 548 private sText; 549 private sEntity; 550 private sOpenWaka; 551 private sOpenWakaBang; 552 private sComment; 553 private sCommentEnding; 554 private sCommentEnded; 555 private sCData; 556 private sCDataEnding; 557 private sCDataEnding2; 558 private sPIFirstChar; 559 private sPIRest; 560 private sPIBody; 561 private sPIEnding; 562 private sXMLDeclNameStart; 563 private sXMLDeclName; 564 private sXMLDeclEq; 565 private sXMLDeclValueStart; 566 private sXMLDeclValue; 567 private sXMLDeclSeparator; 568 private sXMLDeclEnding; 569 private sOpenTag; 570 private sOpenTagSlash; 571 private sAttrib; 572 private sAttribName; 573 private sAttribNameSawWhite; 574 private sAttribValue; 575 private sAttribValueQuoted; 576 private sAttribValueClosed; 577 private sAttribValueUnquoted; 578 private sCloseTag; 579 private sCloseTagSawWhite; 580 private handleTextInRoot; 581 private handleTextOutsideRoot; 582 private pushAttribNS; 583 private pushAttribPlain; 584 /** 585 * End parsing. This performs final well-formedness checks and resets the 586 * parser to a clean state. 587 * 588 * @returns this 589 */ 590 private end; 591 /** 592 * Resolve a namespace prefix. 593 * 594 * @param prefix The prefix to resolve. 595 * 596 * @returns The namespace URI or ``undefined`` if the prefix is not defined. 597 */ 598 resolve(prefix: string): string | undefined; 599 /** 600 * Parse a qname into its prefix and local name parts. 601 * 602 * @param name The name to parse 603 * 604 * @returns 605 */ 606 private qname; 607 private processAttribsNS; 608 private processAttribsPlain; 609 /** 610 * Handle a complete open tag. This parser code calls this once it has seen 611 * the whole tag. This method checks for well-formeness and then emits 612 * ``onopentag``. 613 */ 614 private openTag; 615 /** 616 * Handle a complete self-closing tag. This parser code calls this once it has 617 * seen the whole tag. This method checks for well-formeness and then emits 618 * ``onopentag`` and ``onclosetag``. 619 */ 620 private openSelfClosingTag; 621 /** 622 * Handle a complete close tag. This parser code calls this once it has seen 623 * the whole tag. This method checks for well-formeness and then emits 624 * ``onclosetag``. 625 */ 626 private closeTag; 627 /** 628 * Resolves an entity. Makes any necessary well-formedness checks. 629 * 630 * @param entity The entity to resolve. 631 * 632 * @returns The parsed entity. 633 */ 634 private parseEntity; 635 }