wikiparser-node 0.3.0 → 0.4.0

package/lib/ranges.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const /** @type {Parser} */ Parser = require('..');
+const Parser = require('..');
 
 /** 模拟Python的Range对象。除`step`至少为`1`外，允许负数、小数或`end < start`的情形。 */
 class Range {
@@ -8,7 +8,12 @@ class Range {
 	end;
 	step;
 
-	/** @param {string|Range} str */
+	/**
+	 * @param {string|Range} str 表达式
+	 * @throws `RangeError` 起点、终点和步长均应为整数
+	 * @throws `RangeError` n的系数不能为0
+	 * @throws `RangeError` 应使用CSS选择器或Python切片的格式
+	 */
 	constructor(str) {
 		if (str instanceof Range) {
 			Object.assign(this, str);
@@ -32,7 +37,7 @@ class Range {
 				throw new RangeError(`步长 ${this.step} 应为整数！`);
 			}
 		} else {
-			const mt = str.match(/^([+-])?(\d+)?n(?:([+-])(\d+))?$/);
+			const mt = /^([+-])?(\d+)?n(?:([+-])(\d+))?$/u.exec(str);
 			if (mt) {
 				const [, sgnA = '+', a = 1, sgnB = '+'] = mt,
 					b = Number(mt[4] ?? 0);
@@ -56,19 +61,20 @@ class Range {
 	}
 
 	/**
-	 * 将Range转换为针对特定Array的下标集
-	 * @param {number|any[]} arr
+	 * 将Range转换为针对特定数组的下标集
+	 * @param {number|any[]} arr 参考数组
 	 * @complexity `n`
 	 */
 	applyTo(arr) {
 		return new Array(typeof arr === 'number' ? arr : arr.length).fill().map((_, i) => i)
-			.slice(this.start, this.end).filter((_, j) => j % this.step === 0);
+			.slice(this.start, this.end)
+			.filter((_, j) => j % this.step === 0);
 	}
 }
 
 /** @extends {Array<number|Range>} */
 class Ranges extends Array {
-	/** @param {number|string|Range|(number|string|Range)[]} arr */
+	/** @param {number|string|Range|(number|string|Range)[]} arr 表达式数组 */
 	constructor(arr) {
 		super();
 		if (arr === undefined) {
@@ -94,24 +100,27 @@ class Ranges extends Array {
 
 	/**
 	 * 将Ranges转换为针对特定Array的下标集
-	 * @param {number|any[]} arr
+	 * @param {number|any[]} arr 参考数组
 	 * @complexity `n`
 	 */
 	applyTo(arr) {
 		const length = typeof arr === 'number' ? arr : arr.length;
-		return [...new Set(
-			Array.from(this).flatMap(ele => {
-				if (typeof ele === 'number') {
-					return ele < 0 ? ele + length : ele;
-				}
-				return ele.applyTo(length);
-			}),
-		)].filter(i => i >= 0 && i < length).sort();
+		return [
+			...new Set(
+				[...this].flatMap(ele => {
+					if (typeof ele === 'number') {
+						return ele < 0 ? ele + length : ele;
+					}
+					return ele.applyTo(length);
+				}),
+			),
+		].filter(i => i >= 0 && i < length).sort();
 	}
 
 	/**
-	 * @param {string} str
-	 * @param {number} i
+	 * 检查某个下标是否符合表达式
+	 * @param {string} str 表达式
+	 * @param {number} i 待检查的下标
 	 */
 	static nth(str, i) {
 		return new Ranges(str.split(',')).applyTo(i + 1).includes(i);

package/lib/text.js

@@ -0,0 +1,146 @@
+'use strict';
+
+const AstNode = require('./node'),
+	Parser = require('..');
+
+/** 文本节点 */
+class AstText extends AstNode {
+	type = 'text';
+	/** @type {string} */ data;
+
+	/** 文本长度 */
+	get length() {
+		return this.data.length;
+	}
+
+	/** @param {string} text 包含文本 */
+	constructor(text = '') {
+		super();
+		Object.defineProperties(this, {
+			data: {value: text, writable: false},
+			childNodes: {enumerable: false, configurable: false},
+			type: {enumerable: false, writable: false, configurable: false},
+		});
+	}
+
+	/** 复制 */
+	cloneNode() {
+		return new AstText(this.data);
+	}
+
+	/**
+	 * @override
+	 * @template {string} T
+	 * @param {T} key 属性键
+	 * @returns {TokenAttribute<T>}
+	 */
+	getAttribute(key) {
+		return key === 'verifyChild'
+			? () => {
+				throw new Error('文本节点没有子节点！');
+			}
+			: super.getAttribute(key);
+	}
+
+	/** 输出字符串 */
+	toString() {
+		return this.data;
+	}
+
+	/** @override */
+	text() {
+		return this.data;
+	}
+
+	/**
+	 * 修改内容
+	 * @param {string} text 新内容
+	 */
+	#setData(text) {
+		text = String(text);
+		const {data} = this,
+			e = new Event('text', {bubbles: true});
+		this.setAttribute('data', text);
+		if (data !== text) {
+			this.dispatchEvent(e, {oldText: data, newText: text});
+		}
+		return this;
+	}
+
+	/**
+	 * 在后方添加字符串
+	 * @param {string} text 添加的字符串
+	 * @throws `Error` 禁止外部调用
+	 */
+	appendData(text) {
+		this.#setData(this.data + text);
+	}
+
+	/**
+	 * 删减字符串
+	 * @param {number} offset 起始位置
+	 * @param {number} count 删减字符数
+	 * @throws `RangeError` 错误的删减位置
+	 * @throws `Error` 禁止外部调用
+	 */
+	deleteData(offset, count) {
+		this.#setData(this.data.slice(0, offset) + this.data.slice(offset + count));
+	}
+
+	/**
+	 * 插入字符串
+	 * @param {number} offset 插入位置
+	 * @param {string} text 待插入的字符串
+	 * @throws `RangeError` 错误的插入位置
+	 * @throws `Error` 禁止外部调用
+	 */
+	insertData(offset, text) {
+		this.#setData(this.data.slice(0, offset) + text + this.data.slice(offset));
+	}
+
+	/**
+	 * 替换字符串
+	 * @param {string} text 替换的字符串
+	 * @throws `Error` 禁止外部调用
+	 */
+	replaceData(text = '') {
+		this.#setData(text);
+	}
+
+	/**
+	 * 提取子串
+	 * @param {number} offset 起始位置
+	 * @param {number} count 字符数
+	 */
+	substringData(offset, count) {
+		return this.data.slice(offset, offset + count);
+	}
+
+	/**
+	 * 将文本子节点分裂为两部分
+	 * @param {number} offset 分裂位置
+	 * @throws `RangeError` 错误的断开位置
+	 * @throws `Error` 没有父节点
+	 */
+	splitText(offset) {
+		if (typeof offset !== 'number') {
+			this.typeError('splitText', 'Number');
+		} else if (offset > this.length || offset < -this.length || !Number.isInteger(offset)) {
+			throw new RangeError(`错误的断开位置！${offset}`);
+		}
+		const {parentNode, data} = this;
+		if (!parentNode) {
+			throw new Error('待分裂的文本节点没有父节点！');
+		}
+		const newText = new AstText(data.slice(offset)),
+			childNodes = [...parentNode.childNodes];
+		this.setAttribute('data', data.slice(0, offset));
+		childNodes.splice(childNodes.indexOf(this) + 1, 0, newText);
+		newText.setAttribute('parentNode', parentNode);
+		parentNode.setAttribute('childNodes', childNodes);
+		return newText;
+	}
+}
+
+Parser.classes.AstText = __filename;
+module.exports = AstText;

package/lib/title.js

@@ -1,8 +1,8 @@
 'use strict';
 
-const {ucfirst} = require('../util/string'),
-	/** @type {Parser} */ Parser = require('..');
+const Parser = require('..');
 
+/** MediaWiki页面标题对象 */
 class Title {
 	title = '';
 	main = '';
@@ -12,7 +12,10 @@ class Title {
 	fragment = '';
 	valid = true;
 
-	/** @param {string} title */
+	/**
+	 * @param {string} title 标题（含或不含命名空间前缀）
+	 * @param {number} defaultNs 命名空间
+	 */
 	constructor(title, defaultNs = 0, config = Parser.getConfig()) {
 		const {namespaces, nsid} = config;
 		let namespace = namespaces[defaultNs];
@@ -50,10 +53,15 @@ class Title {
 			this.fragment ||= fragment;
 			title = title.slice(0, i).trim();
 		}
-		this.main = ucfirst(title);
+		this.main = title && `${title[0].toUpperCase()}${title.slice(1)}`;
 		this.prefix = `${namespace}${namespace && ':'}`;
 		this.title = `${iw ? `${this.interwiki}:` : ''}${this.prefix}${this.main}`;
-		this.valid = Boolean(this.main) && !/\x00\d+[eh!+-]\x7f|[<>[\]{}|]/.test(this.title);
+		this.valid = Boolean(this.main || this.fragment) && !/\0\d+[eh!+-]\x7F|[<>[\]{}|]/u.test(this.title);
+	}
+
+	/** @override */
+	toString() {
+		return `${this.title}${this.fragment && '#'}${this.fragment}`;
 	}
 }
 

package/mixin/attributeParent.js

@@ -1,65 +1,111 @@
 'use strict';
 
-const /** @type {Parser} */ Parser = require('..'),
+const Parser = require('..'),
 	AttributeToken = require('../src/attribute');
 
 /**
+ * 子节点含有AttributeToken的类
  * @template T
- * @param {T} constructor
+ * @param {T} Constructor 基类
+ * @param {number} i AttributeToken子节点的位置
  * @returns {T}
  */
-const attributeParent = (ct, i = 0) => class extends ct {
+const attributeParent = (Constructor, i = 0) => class extends Constructor {
 	/**
-	 * @this {{children: AttributeToken[]}}
-	 * @param {string} key
+	 * getAttr()方法的getter写法
+	 * @returns {Record<string, string|true>}
+	 */
+	get attributes() {
+		return this.getAttr();
+	}
+
+	/** 以字符串表示的class属性 */
+	get className() {
+		const attr = this.getAttr('class');
+		return typeof attr === 'string' ? attr : '';
+	}
+
+	set className(className) {
+		this.setAttr('class', className);
+	}
+
+	/** 以Set表示的class属性 */
+	get classList() {
+		return new Set(this.className.split(/\s/u));
+	}
+
+	/** id属性 */
+	get id() {
+		const attr = this.getAttr('id');
+		return typeof attr === 'string' ? attr : '';
+	}
+
+	set id(id) {
+		this.setAttr('id', id);
+	}
+
+	/**
+	 * AttributeToken子节点是否具有某属性
+	 * @this {{childNodes: AttributeToken[]}}
+	 * @param {string} key 属性键
 	 */
 	hasAttr(key) {
-		return this.children.at(i).hasAttr(key);
+		return this.childNodes.at(i).hasAttr(key);
 	}
 
 	/**
-	 * @this {{children: AttributeToken[]}}
+	 * 获取AttributeToken子节点的属性
+	 * @this {{childNodes: AttributeToken[]}}
 	 * @template {string|undefined} T
-	 * @param {T} key
+	 * @param {T} key 属性键
 	 */
 	getAttr(key) {
-		return this.children.at(i).getAttr(key);
+		return this.childNodes.at(i).getAttr(key);
 	}
 
-	/** @this {{children: AttributeToken[]}} */
+	/**
+	 * 列举AttributeToken子节点的属性键
+	 * @this {{childNodes: AttributeToken[]}}
+	 */
 	getAttrNames() {
-		return this.children.at(i).getAttrNames();
+		return this.childNodes.at(i).getAttrNames();
 	}
 
-	/** @this {{children: AttributeToken[]}} */
+	/**
+	 * AttributeToken子节点是否具有任意属性
+	 * @this {{childNodes: AttributeToken[]}}
+	 */
 	hasAttrs() {
-		return this.children.at(i).hasAttrs();
+		return this.childNodes.at(i).hasAttrs();
 	}
 
 	/**
-	 * @this {{children: AttributeToken[]}}
-	 * @param {string} key
-	 * @param {string|boolean} value
+	 * 对AttributeToken子节点设置属性
+	 * @this {{childNodes: AttributeToken[]}}
+	 * @param {string} key 属性键
+	 * @param {string|boolean} value 属性值
 	 */
 	setAttr(key, value) {
-		return this.children.at(i).setAttr(key, value);
+		return this.childNodes.at(i).setAttr(key, value);
 	}
 
 	/**
-	 * @this {{children: AttributeToken[]}}
-	 * @param {string} key
+	 * 移除AttributeToken子节点的某属性
+	 * @this {{childNodes: AttributeToken[]}}
+	 * @param {string} key 属性键
 	 */
 	removeAttr(key) {
-		this.children.at(i).removeAttr(key);
+		this.childNodes.at(i).removeAttr(key);
 	}
 
 	/**
-	 * @this {{children: AttributeToken[]}}
-	 * @param {string} key
-	 * @param {boolean|undefined} force
+	 * 开关AttributeToken子节点的某属性
+	 * @this {{childNodes: AttributeToken[]}}
+	 * @param {string} key 属性键
+	 * @param {boolean|undefined} force 强制开启或关闭
 	 */
 	toggleAttr(key, force) {
-		this.children.at(i).toggleAttr(key, force);
+		this.childNodes.at(i).toggleAttr(key, force);
 	}
 };
 

package/mixin/fixedToken.js

@@ -1,23 +1,31 @@
 'use strict';
 
-const /** @type {Parser} */ Parser = require('..');
+const Parser = require('..'),
+	Token = require('../src');
 
 /**
+ * 不可增删子节点的类
  * @template T
- * @param {T} constructor
+ * @param {T} Constructor 基类
  * @returns {T}
  */
-const fixedToken = ct => class extends ct {
+const fixedToken = Constructor => class extends Constructor {
 	static fixed = true;
 
+	/**
+	 * 移除子节点
+	 * @throws `Error`
+	 */
 	removeAt() {
 		throw new Error(`${this.constructor.name} 不可删除元素！`);
 	}
 
 	/**
-	 * @template {string|Token} T
-	 * @param {T} token
-	 * @param {number} i
+	 * 插入子节点
+	 * @template {Token} T
+	 * @param {T} token 待插入的子节点
+	 * @param {number} i 插入位置
+	 * @throws `Error`
 	 */
 	insertAt(token, i = this.childNodes.length) {
 		if (!Parser.running) {

package/mixin/hidden.js

@@ -1,14 +1,16 @@
 'use strict';
 
-const /** @type {Parser} */ Parser = require('..');
+const Parser = require('..');
 
 /**
+ * 解析后不可见的类
  * @template T
- * @param {T} constructor
+ * @param {T} Constructor 基类
  * @returns {T}
  */
-const hidden = ct => class extends ct {
-	text() {
+const hidden = Constructor => class extends Constructor {
+	/** 没有可见部分 */
+	text() { // eslint-disable-line class-methods-use-this
 		return '';
 	}
 };

package/mixin/sol.js

@@ -1,39 +1,56 @@
 'use strict';
 
-const /** @type {Parser} */ Parser = require('..'),
+const Parser = require('..'),
 	Token = require('../src');
 
 /**
+ * 只能位于行首的类
  * @template T
- * @param {T} constructor
+ * @param {T} Constructor 基类
  * @returns {T}
  */
-const sol = ct => class extends ct {
-	/** @this {Token} */
+const sol = Constructor => class extends Constructor {
+	/**
+	 * 在前方插入newline
+	 * @this {Token}
+	 */
 	prependNewLine() {
 		const {previousVisibleSibling = '', parentNode} = this;
-		return (previousVisibleSibling || parentNode?.type !== 'root') && !String(previousVisibleSibling).endsWith('\n')
+		return (previousVisibleSibling || parentNode?.type !== 'root') && String(previousVisibleSibling).at(-1) !== '\n'
 			? '\n'
 			: '';
 	}
 
-	/** @this {Token} */
+	/**
+	 * 在后方插入newline
+	 * @this {Token}
+	 */
 	appendNewLine() {
 		const {nextVisibleSibling = '', parentNode} = this;
-		return (nextVisibleSibling || parentNode?.type !== 'root') && !String(nextVisibleSibling ?? '').startsWith('\n')
+		return (nextVisibleSibling || parentNode?.type !== 'root') && String(nextVisibleSibling ?? '')[0] !== '\n'
 			? '\n'
 			: '';
 	}
 
-	toString(ownLine = false) {
-		return `${this.prependNewLine()}${super.toString()}${ownLine ? this.appendNewLine() : ''}`;
+	/**
+	 * 还原为wikitext
+	 * @param {string} selector
+	 * @param {boolean} ownLine 是否独占一行
+	 */
+	toString(selector, ownLine) {
+		return `${this.prependNewLine()}${super.toString(selector)}${ownLine ? this.appendNewLine() : ''}`;
 	}
 
+	/** 获取padding */
 	getPadding() {
 		return this.prependNewLine().length;
 	}
 
-	text(ownLine = false) {
+	/**
+	 * 可见部分
+	 * @param {booean} ownLine 是否独占一行
+	 */
+	text(ownLine) {
 		return `${this.prependNewLine()}${super.text()}${ownLine ? this.appendNewLine() : ''}`;
 	}
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wikiparser-node",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "A Node.js parser for MediaWiki markup with AST",
   "keywords": [
     "mediawiki",
@@ -18,11 +18,17 @@
     "url": "git+https://github.com/bhsd-harry/wikiparser-node.git"
   },
   "scripts": {
-    "test": "echo 'Error: no test specified' && exit 1"
+    "test": "node test/test.js",
+    "real": "node test/real.js"
   },
   "devDependencies": {
     "@types/node": "^17.0.23",
-    "eslint": "^8.30.0"
+    "eslint": "^8.30.0",
+    "eslint-plugin-n": "^15.6.0",
+    "eslint-plugin-regexp": "^1.11.0",
+    "eslint-plugin-unicorn": "^45.0.2",
+    "eslint-plugin-jsdoc": "^1.0.0",
+    "request": "^2.88.2"
   },
   "engines": {
     "node": "^18.4.0"

package/parser/brackets.js

@@ -1,35 +1,42 @@
 'use strict';
 
 const {removeComment} = require('../util/string'),
-	/** @type {Parser} */ Parser = require('..');
+	Parser = require('..');
 
 /**
- * @param {string} text
+ * 解析花括号
+ * @param {string} text wikitext
  * @param {accum} accum
+ * @throws TranscludeToken.constructor()
  */
 const parseBrackets = (text, config = Parser.getConfig(), accum = []) => {
-	const source = '(?<=^(?:\x00\\d+c\x7f)*)={1,6}|\\[\\[|{{2,}|-{(?!{)',
+	const source = '^(\0\\d+c\x7F)*={1,6}|\\[\\[|\\{{2,}|-\\{(?!\\{)',
 		/** @type {BracketExecArray[]} */ stack = [],
-		closes = {'=': '\n', '{': '}{2,}|\\|', '-': '}-', '[': ']]'},
+		closes = {'=': '\n', '{': '\\}{2,}|\\|', '-': '\\}-', '[': '\\]\\]'},
 		/** @type {Record<string, string>} */ marks = {'!': '!', '!!': '+', '(!': '{', '!)': '}', '!-': '-', '=': '~'};
-	let regex = new RegExp(source, 'gm'),
+	let regex = new RegExp(source, 'gmu'),
 		/** @type {BracketExecArray} */ mt = regex.exec(text),
 		moreBraces = text.includes('}}'),
 		lastIndex;
 	while (mt || lastIndex <= text.length && stack.at(-1)?.[0]?.[0] === '=') {
+		if (mt?.[1]) {
+			const [, {length}] = mt;
+			mt[0] = mt[0].slice(length);
+			mt.index += length;
+		}
 		const {0: syntax, index: curIndex} = mt ?? {0: '\n', index: text.length},
 			/** @type {BracketExecArray} */ top = stack.pop() ?? {},
-			{0: open, index, parts} = top,
-			innerEqual = syntax === '=' && top.findEqual;
-		if ([']]', '}-'].includes(syntax)) { // 情形1：闭合内链或转换
+			{0: open, index, parts, findEqual: topFindEqual, pos: topPos} = top,
+			innerEqual = syntax === '=' && topFindEqual;
+		if (syntax === ']]' || syntax === '}-') { // 情形1：闭合内链或转换
 			lastIndex = curIndex + 2;
 		} else if (syntax === '\n') { // 情形2：闭合标题
 			lastIndex = curIndex + 1;
 			const {pos, findEqual} = stack.at(-1) ?? {};
 			if (!pos || findEqual || removeComment(text.slice(pos, index)) !== '') {
-				const rmt = text.slice(index, curIndex).match(/^(={1,6})(.+)\1((?:\s|\x00\d+c\x7f)*)$/);
+				const rmt = /^(={1,6})(.+)\1((?:\s|\0\d+c\x7F)*)$/u.exec(text.slice(index, curIndex));
 				if (rmt) {
-					text = `${text.slice(0, index)}\x00${accum.length}h\x7f${text.slice(curIndex)}`;
+					text = `${text.slice(0, index)}\0${accum.length}h\x7F${text.slice(curIndex)}`;
 					lastIndex = index + 4 + String(accum.length).length;
 					const HeadingToken = require('../src/heading');
 					new HeadingToken(rmt[1].length, rmt.slice(2), config, accum);
@@ -37,7 +44,7 @@ const parseBrackets = (text, config = Parser.getConfig(), accum = []) => {
 			}
 		} else if (syntax === '|' || innerEqual) { // 情形3：模板内部，含行首单个'='
 			lastIndex = curIndex + 1;
-			parts.at(-1).push(text.slice(top.pos, curIndex));
+			parts.at(-1).push(text.slice(topPos, curIndex));
 			if (syntax === '|') {
 				parts.push([]);
 			}
@@ -49,9 +56,8 @@ const parseBrackets = (text, config = Parser.getConfig(), accum = []) => {
 				rest = open.length - close.length,
 				{length} = accum;
 			lastIndex = curIndex + close.length; // 这不是最终的lastIndex
-			parts.at(-1).push(text.slice(top.pos, curIndex));
-			/* 标记{{!}}等 */
-			const ch = close.length === 2 ? marks[removeComment(parts[0][0])] ?? 't' : 't';
+			parts.at(-1).push(text.slice(topPos, curIndex));
+			const ch = close.length === 2 ? marks[removeComment(parts[0][0])] ?? 't' : 't'; // 标记{{!}}等
 			let skip = false;
 			if (close.length === 3) {
 				const ArgToken = require('../src/arg');
@@ -70,8 +76,7 @@ const parseBrackets = (text, config = Parser.getConfig(), accum = []) => {
 				}
 			}
 			if (!skip) {
-				/* 标记{{!}}结束 */
-				text = `${text.slice(0, index + rest)}\x00${length}${ch}\x7f${text.slice(lastIndex)}`;
+				text = `${text.slice(0, index + rest)}\0${length}${ch}\x7F${text.slice(lastIndex)}`;
 				lastIndex = index + rest + 3 + String(length).length;
 				if (rest > 1) {
 					stack.push({0: open.slice(0, rest), index, pos: index + rest, parts: [[]]});
@@ -96,7 +101,7 @@ const parseBrackets = (text, config = Parser.getConfig(), accum = []) => {
 		regex = new RegExp(source + (curTop
 			? `|${closes[curTop[0][0]]}${curTop.findEqual ? '|=' : ''}`
 			: ''
-		), 'gm');
+		), 'gmu');
 		regex.lastIndex = lastIndex;
 		mt = regex.exec(text);
 	}