Token (EN)

Table of Contents

• Introduction
• Properties
  • type ✅
  • images
  • links
  • embeds
• Methods
  • safeReplaceWith
  • createComment
  • createElement
  • createTextNode
  • createRange
  • caretPositionFromIndex
  • caretPositionFromPoint
  • elementFromIndex
  • elementFromPoint
  • elementsFromIndex
  • elementsFromPoint
  • isInterwiki
  • cloneNode
  • sections
  • section
  • findEnclosingHtml
  • getCategories
  • expand
  • solveConst
  • flatten
  • toHtml

Other Languages

• 简体中文

Introduction

This is the parent class of all specific nodes corresponding to different wiki syntax. The parent class of the Token class, AstElement, is modeled after the HTMLElement class. This page only describes the unique properties and methods of the Token class.

✅ Available in the Mini and Browser versions.

Properties

type

✅ Expand

type: string
The type of the node.

// type
assert.strictEqual(Parser.parse('').type, 'root');

images

Expand

type: Token[]
All image nodes, read-only.

// images (main)
var root = Parser.parse('[[file:a]]'),
	{firstChild} = root;
assert.equal(firstChild, '[[file:a]]');
assert.deepStrictEqual(root.images, [firstChild]);

links

Expand

type: Token[]
All internal links, external links, free external links and image links, read-only.

// links (main)
var root = Parser.parse([[a]][//b]http://c[[file:d|link=e]]'),
	{childNodes: [link, extLink, magicLink, {lastChild}]} = root;
assert.equal(link, '[[a]]');
assert.equal(extLink, '[//b]');
assert.equal(magicLink, 'http://c');
assert.equal(lastChild, 'link=e');
assert.deepStrictEqual(root.links, [
	link,
	extLink,
	magicLink,
	lastChild,
]);

embeds

Expand

type: Token[]
All embedded templates and modules, read-only.

// embeds (main)
var root = Parser.parse('{{a}}{{#invoke:b|c}}'),
	{firstChild, lastChild} = root;
assert.equal(firstChild, '{{a}}');
assert.equal(lastChild, '{{#invoke:b|c}}');
assert.deepStrictEqual(root.embeds, [firstChild, lastChild]);

Methods

safeReplaceWith

Expand

param: this New node
Some nodes with special syntax can only be replaced by nodes of the same type. Note that the use of this method generally requires the use of the AstElement.prototype.destroy method.

// safeReplaceWith (main)
var {firstChild, lastChild: {lastChild}} = Parser.parse('<p><p lang="zh">'),
	attrs = lastChild.cloneNode();
assert.equal(firstChild, '<p>');
assert.equal(lastChild, ' lang="zh"');
assert.equal(attrs, ' lang="zh"');
try {
	firstChild.lastChild.replaceWith(attrs);
} catch (e) {
	assert(e instanceof Error);
	assert.equal(e.message, 'HtmlToken cannot insert child nodes!');
}
firstChild.lastChild.safeReplaceWith(attrs);

createComment

Expand

param: string Text content of the comment
returns: CommentToken
Create an HTML comment.

// createComment (main)
var {firstChild} = Parser.parse('<!--a-->');
assert.equal(firstChild, '<!--a-->');
assert.deepStrictEqual(firstChild.createComment('a'), firstChild);

createElement

Expand

param: string Tag name
param: {closing?: boolean, selfClosing?: boolean} Options
returns: Token
Create an HTML tag or extension tag.

// createElement (main)
var root = Parser.parse('</p><ref/>'),
	{firstChild, lastChild} = root;
assert.equal(firstChild, '</p>');
assert.equal(lastChild, '<ref/>');
assert.deepStrictEqual(
	root.createElement('p', {closing: true}),
	firstChild,
);
assert.deepStrictEqual(
	root.createElement('ref', {selfClosing: true}),
	lastChild,
);

createTextNode

Expand

param: string
returns: AstText
Create a text node.

// createTextNode (main)
var root = Parser.parse('text');
assert.deepStrictEqual(root.createTextNode('text'), root.firstChild);

createRange

Expand

returns: AstRange
Create an AstRange object.

// createRange (main)
var root = Parser.parse('text'),
	{firstChild} = root,
	range = root.createRange();
range.setStart(firstChild, 1);
range.setEnd(firstChild, 3);
assert.strictEqual(range.toString(), 'ex');

caretPositionFromIndex

Expand

param: number Character position
returns: {offsetNode: AstNode, offset: number}
Find the given position.

// caretPositionFromIndex (main)
var root = Parser.parse('[[a]]'),
	{firstChild} = root;
assert.equal(firstChild, '[[a]]');
assert.deepStrictEqual(root.caretPositionFromIndex(1), {
	offsetNode: firstChild,
	offset: 1,
});

caretPositionFromPoint

Expand

param: number Character column
param: number Character row
returns: {offsetNode: AstNode, offset: number}
Find the given position.

// caretPositionFromPoint (main)
var root = Parser.parse('[[a]]'),
	{firstChild} = root;
assert.equal(firstChild, '[[a]]');
assert.deepStrictEqual(root.caretPositionFromPoint(1, 0), {
	offsetNode: firstChild,
	offset: 1,
});

elementFromIndex

Expand

param: number Character position
returns: AstNode
Find the outermost node at the given position.

// elementFromIndex (main)
var root = Parser.parse('[[a]]'),
	{firstChild} = root;
assert.equal(firstChild, '[[a]]');
assert.strictEqual(root.elementFromIndex(1), firstChild);

elementFromPoint

Expand

param: number Character column
param: number Character row
returns: AstNode
Find the outermost node at the given position.

// elementFromPoint (main)
var root = Parser.parse('[[a]]'),
	{firstChild} = root;
assert.equal(firstChild, '[[a]]');
assert.strictEqual(root.elementFromPoint(1, 0), firstChild);

elementsFromIndex

Expand

param: number Character position
returns: AstNode[]
Find all nodes at the given position.

// elementsFromIndex (main)
var root = Parser.parse('[[a]]'),
	{firstChild} = root;
assert.equal(firstChild, '[[a]]');
assert.deepStrictEqual(root.elementsFromIndex(1), [root, firstChild]);

elementsFromPoint

Expand

param: number Character column
param: number Character row
returns: AstNode[]
Find all nodes at the given position.

// elementsFromPoint (main)
var root = Parser.parse('[[a]]'),
	{firstChild} = root;
assert.equal(firstChild, '[[a]]');
assert.deepStrictEqual(root.elementsFromPoint(1, 0), [root, firstChild]);

isInterwiki

Expand

param: string Title
returns: RegExpExecArray | null
Similar to Parser.isInterwiki, but using the same parsing configurations as the current node.

cloneNode

Expand

returns: this
Deep clone the node. Different types of nodes use different algorithms.

sections

Expand

returns: AstRange[]
Get all sections (including the prelude), each of which is an array. Only available for root nodes.

// sections (main)
var root = Parser.parse('a\n==b==\nc'),
	[s1, s2] = root.sections(),
	{childNodes: [a, b, c]} = root;
assert.equal(a, 'a\n');
assert.equal(b, '==b==');
assert.equal(c, '\nc');
assert.deepStrictEqual(s1.startContainer, root);
assert.deepStrictEqual(s1.endContainer, root);
assert.equal(s1.startOffset, 0);
assert.equal(s1.endOffset, 1);
assert.deepStrictEqual(s2.startContainer, root);
assert.deepStrictEqual(s2.endContainer, root);
assert.equal(s2.startOffset, 1);
assert.equal(s2.endOffset, 3);

section

Expand

param: number Number of the section
returns: AstRange
Get the specified section. Only available for root nodes.

// section (main)
var root = Parser.parse('a\n==b==\nc'),
	section = root.section(1),
	{childNodes: [, b, c]} = root;
assert.equal(b, '==b==');
assert.equal(c, '\nc');
assert.deepStrictEqual(section.startContainer, root);
assert.deepStrictEqual(section.endContainer, root);
assert.equal(section.startOffset, 1);
assert.equal(section.endOffset, 3);

findEnclosingHtml

Expand

param: string Tag name (optional)
returns: [HtmlToken, HtmlToken]
Get the specified outer HTML tag. Note that text nodes cannot use this method.

// findEnclosingHtml (main)
var {childNodes: [start, link, end]} = Parser.parse('<p>[[a]]</p>'),
	range = link.createRange();
assert.equal(start, '<p>');
assert.equal(link, '[[a]]');
assert.equal(end, '</p>');
range.setStartBefore(start);
range.setEndAfter(end);
assert.deepStrictEqual(link.findEnclosingHtml(), range);

getCategories

Expand

returns: [string, string | undefined][]
Get all categories and their sort keys.

// getCategories (main)
assert.deepStrictEqual(
	Parser.parse([[category:a]][[category:b|c]]').getCategories(),
	[
		['Category:A', undefined],
		['Category:B', 'c'],
	],
);

expand

Expand

version added: 1.10.0

returns: Token
Expand templates and some magic words.

// expand (main)
var root, copy;
Parser.templates.set(
	'Template:Link_start',
	`[[{{{1|<noinclude>Template:Link start]]</noinclude>}}}<noinclude>
{{doc}}</noinclude>`,
);
root = Parser.parse('{{link start|a}}b|c]]');
copy = root.expand();
assert.deepStrictEqual(copy.childNodes.map(({type}) => type), ['link']);
assert.equal(copy, '[[ab|c]]');

solveConst

Expand

returns: Token
Parse template parameters and some magic words.

// solveConst (main)
var root = Parser.parse(
		`{{{null}}}{{{|[[a]]}}}{{#if:||[//b]}}{{#switch:|#default={{c}}}}{{#switch:d|d|e=}}`,
	),
	copy = root.solveConst();
assert.deepStrictEqual(
	copy.childNodes.map(({type}) => type),
	['text', 'link', 'ext-link', 'template'],
);
assert.deepStrictEqual(
	copy.childNodes.map(String),
	['{{{null}}}', '[[a]]', '[//b]', '{{c}}'],
);

flatten

Expand

Merge the plain child nodes of the current plain node.

// flatten (main)
var root = Parser.parse(''),
	plain = Parser.parse('a'),
	{firstChild} = plain;
root.append(plain);
root.flatten();
assert.strictEqual(root.lastChild, firstChild);

toHtml

Expand

version added: 1.10.0

param: boolean Whether to disable line breaks
returns: string
Convert to HTML.

// toHtml (main)
var root;
Parser.templates.set('Template:Dt', ';');
root = Parser.parse('{{dt}}{{dt}}a:b');
assert.strictEqual(
	root.toHtml(),
	`<dl><dt></dt>\n<dt>a</dt>\n<dd>b</dd></dl>`,
);