wikiapi.js

  1. /**
  2.  * @name Wikiapi.js
  3.  * 
  4.  * @fileoverview Main codes of module wikiapi (class Wikiapi)
  5.  */
  7. 'use strict';
  9. /**
  10.  * @description CeJS controller
  11.  * 
  12.  * @type Function
  13.  * 
  14.  * @ignore
  15.  * @inner
  16.  * 
  17.  * @see https://github.com/kanasimi/CeJS
  18.  */
  19. let CeL;
  21. try {
  22. 	// Load CeJS library.
  23. 	CeL = require('cejs');
  24. 	if (typeof CeL.then === 'function' && typeof window === "object" && window.CeL) {
  25. 		// assert: @Snowpack
  26. 		CeL = window.CeL;
  27. 	}
  29. } catch (e) /* istanbul ignore next: Only for debugging locally */ {
  30. 	// https://github.com/gotwarlost/istanbul/blob/master/ignoring-code-for-coverage.md
  31. 	// const Wikiapi = require('./wikiapi.js');
  32. 	require('./_CeL.loader.nodejs.js');
  33. 	CeL = globalThis.CeL;
  34. }
  35. // assert: typeof CeL === 'function'
  37. // Load modules.
  38. // @see `wiki loader.js`:
  39. // https://github.com/kanasimi/wikibot/blob/master/wiki%20loader.js
  40. CeL.run(['interact.DOM', 'application.debug',
  41. 	// 載入不同地區語言的功能 for wiki.work()。
  42. 	'application.locale',
  43. 	// 載入操作維基百科的主要功能。
  44. 	'application.net.wiki',
  45. 	// Optional 可選功能
  46. 	'application.net.wiki.data', 'application.net.wiki.admin',
  47. 	// Add color to console messages. 添加主控端報告的顏色。
  48. 	'interact.console',
  49. 	// for 'application.platform.nodejs': CeL.env.arg_hash, wiki_API.cache(),
  50. 	// CeL.fs_mkdir(), wiki_API.read_dump()
  51. 	'application.storage']);
  53. // --------------------------------------------------------
  55. /**
  56.  * @description syntactic sugar for CeJS MediaWiki module. CeL.net.wiki === CeL.wiki
  57.  * 
  58.  * @ignore
  59.  * @inner
  60.  */
  61. const wiki_API = CeL.net.wiki;
  62. /**
  63.  * key to get {@link wiki_API} operator when using {@link wiki_API}.
  64.  * 
  65.  * @type Symbol
  66.  * 
  67.  * @ignore
  68.  * @inner
  69.  */
  70. const KEY_SESSION = wiki_API.KEY_SESSION;
  72. // Set default language. 改變預設之語言。
  73. wiki_API.set_language('en');
  75. /**
  76.  * @description key to get {@link wiki_API} operator inside {@link Wikiapi}.
  77.  * <code>this[KEY_wiki_session]</code> inside module code will get {@link wiki_API} operator.
  78.  * 
  79.  * @type Symbol
  80.  * 
  81.  * @ignore
  82.  * @inner
  83.  */
  84. const KEY_wiki_session = Symbol('wiki_API session');
  85. // for debug
  86. // Wikiapi.KEY_wiki_session = KEY_wiki_session;
  88. /**
  89.  * @description main Wikiapi operator 操作子.
  90.  * 
  91.  * @param {String|Object} [API_URL]	- language code or service endpoint of MediaWiki project.<br />
  92.  *            Input {Object} will be treat as options.
  93.  * 
  94.  * @class
  95.  */
  96. function Wikiapi(API_URL) {
  97. 	const wiki_session = new wiki_API(null, null, API_URL);
  98. 	// this[KEY_wiki_session] = new wiki_API(null, null, API_URL);
  99. 	setup_wiki_session.call(this, wiki_session);
  100. }
  102. // --------------------------------------------------------
  104. /**
  105.  * @description Bind {@link wiki_API} instance to {@link Wikiapi} instance
  106.  * 
  107.  * @param {wiki_API} wiki_session	- wiki_API session
  108.  * 
  109.  * @ignore
  110.  * @inner
  111.  */
  112. function setup_wiki_session(wiki_session) {
  113. 	Object.defineProperty(this, KEY_wiki_session, {
  114. 		value: wiki_session,
  115. 		writable: true,
  116. 	});
  117. }
  119. /**
  120.  * @alias login
  121.  * @description login into the target MediaWiki API using the provided username and password.
  122.  * For bots, see [[Special:BotPasswords]] on your wiki.
  123.  * 
  124.  * @param {String} user_name	- Account username.
  125.  * @param {String} password		- Account's password.
  126.  * @param {String} [API_URL]	- API URL of target wiki site.
  127.  *
  128.  * @returns {Promise} Promise object represents {String} login_name
  129.  *
  130.  * @example <caption><span id="example__Login to wiki site 1">Login to wiki site method 1 (recommend).</span></caption>
  131. // <code>
  132. const wiki = new Wikiapi;
  133. const login_options = {
  134. 	user_name: '', password: '', API_URL: 'en',
  135. 	// e.g., lingualibre. @see https://github.com/kanasimi/wikibot/blob/master/wiki%20configuration.sample.js
  136. 	//data_API_URL: 'https://lingualibre.org/api.php',
  137. 	//SPARQL_API_URL: 'https://lingualibre.org/bigdata/namespace/wdq/sparql',
  138. 	// Calling in another domain
  139. 	origin: '*'
  140. };
  141. await wiki.login(login_options);
  142. // </code>
  143.  *
  144.  * @example <caption><span id="example__Login to wiki site 2">Login to wiki site method 2.</span></caption>
  145. // <code>
  146. const wiki = new Wikiapi;
  147. await wiki.login('user_name', 'password', 'en');
  148. // </code>
  149.  *
  150.  * @memberof Wikiapi.prototype
  151.  */
  152. function Wikiapi_login(user_name, password, API_URL) {
  153. 	let options;
  154. 	if (!password && !API_URL && CeL.is_Object(user_name)) {
  155. 		options = user_name;
  156. 	} else if (CeL.is_Object(API_URL)) {
  157. 		options = { ...API_URL, user_name, password };
  158. 	} else {
  159. 		options = { user_name, password, API_URL };
  160. 	}
  162. 	function Wikiapi_login_executor(resolve, reject) {
  163. 		const wiki_session = wiki_API.login({
  164. 			preserve_password: true,
  165. 			...options,
  167. 			API_URL: options.API_URL || this[KEY_wiki_session].API_URL,
  168. 			callback(login_name, error) {
  169. 				if (error) {
  170. 					reject(error);
  171. 				} else {
  172. 					resolve(login_name);
  173. 				}
  174. 			},
  175. 			// task_configuration_page: 'page title',
  176. 		});
  177. 		setup_wiki_session.call(this, wiki_session);
  178. 	}
  180. 	return new Promise(Wikiapi_login_executor.bind(this));
  181. }
  183. // --------------------------------------------------------
  185. /**
  186.  * @description attributes of {Object} page_data, will setup by {@link set_page_data_attributes}.
  187.  * 
  188.  * @type Object
  189.  * 
  190.  * @ignore
  191.  * @inner
  192.  */
  193. const page_data_attributes = {
  194. 	/**
  195. 	 * @description get {String}page content, maybe undefined.
  196. 	 * 條目/頁面內容 = wiki_API.revision_content(revision)
  197. 	 *
  198. 	 * @type String
  199. 	 */
  200. 	wikitext: {
  201. 		get() {
  202. 			// console.trace(this);
  203. 			// console.log(wiki_API.content_of(this, 0));
  204. 			return wiki_API.content_of(this, 0);
  205. 		}
  206. 	},
  207. 	/**
  208. 	 * @description get {Object}revisions
  209. 	 *
  210. 	 * @type Object
  211. 	 */
  212. 	revision: {
  213. 		value: function revision(revision_NO) {
  214. 			return wiki_API.content_of(this, revision_NO);
  215. 		}
  216. 	},
  217. 	/**
  218. 	 * @description get {Attay} parsed data of page_data
  219. 	 *
  220. 	 * @type Array
  221. 	 */
  222. 	parse: {
  223. 		value: function parse(options) {
  224. 			// this === page_data
  226. 			// options = { ...options, [KEY_SESSION]: this[KEY_wiki_session] };
  227. 			options = Wikiapi.prototype.append_session_to_options.call(this, options);
  229. 			// using function parse_page(options) @ wiki_API
  230. 			return wiki_API.parser(this, options).parse();
  231. 			// return {Array}parsed
  232. 		}
  233. 	},
  234. };
  236. /**
  237.  * @description Bind {@link page_data_attributes} to <code>page_data</code>
  238.  * 
  239.  * @param {Object} page_data	- page data
  240.  * @param {wiki_API} wiki		- wiki_API session
  241.  * 
  242.  * @returns {Promise} Promise object represents {Object} page's data
  243.  * 
  244.  * @ignore
  245.  * @inner
  246.  */
  247. function set_page_data_attributes(page_data, wiki) {
  248. 	// `page_data` maybe non-object when error occurres.
  249. 	if (page_data) {
  250. 		page_data[KEY_wiki_session] = wiki;
  251. 		Object.defineProperties(page_data, page_data_attributes);
  252. 	}
  253. 	return page_data;
  254. }
  256. /**
  257.  * @alias page
  258.  * @description Given a title, returns the page's data.
  259.  * 
  260.  * @param {String} title		- page title
  261.  * @param {Object} [options]	- options to run this function
  262.  *
  263.  * @returns {Promise} Promise object represents {Object} page's data
  264.  *
  265.  * @example <caption>load page</caption>
  266. // <code>
  267. // on Wikipedia...
  268. const wiki = new Wikiapi('en');
  269. // ...or other MediaWiki websites
  270. //const wiki = new Wikiapi('https://awoiaf.westeros.org/api.php');
  271. let page_data = await wiki.page('Universe', {
  272. 	// You may also set rvprop.
  273. 	//rvprop: 'ids|content|timestamp|user',
  274. });
  275. console.log(page_data.wikitext);
  276. // </code>
  277.  *
  278.  * @example <caption>Get multi revisions</caption>
  279. // <code>
  280. const wiki = new Wikiapi;
  281. let page_data = await wiki.page('Universe', {
  282. 	// Get multi revisions
  283. 	revisions: 2
  284. });
  285. console.log(page_data.wikitext);
  286. // </code>
  287.  *
  288.  * @example <caption>parse wiki page (The parser is more powerful than the example. Please refer to link of wikitext parser examples showing in "Features" section of README.md.)</caption>
  289. // <code>
  290. // Usage with other language
  291. const zhwiki = new Wikiapi('zh');
  292. await zhwiki.login('user', 'password');
  293. let page_data = await zhwiki.page('Universe');
  295. // `page_data.parse(options)` will startup the parser process, create page_data.parsed. After .parse(), we can use parsed.each().
  296. const parsed = page_data.parse();
  298. // See all type in wiki_toString @ https://github.com/kanasimi/CeJS/tree/master/application/net/wiki/parser/wikitext.js
  299. // List all template name.
  300. parsed.each('template', token => console.log(token.name));
  301. // List all [[Template:Tl]] token.
  302. parsed.each('Template:Tl', token => console.log(token));
  303. // </code>
  304.  *
  305.  * @example <caption>Get information from Infobox template</caption>
  306. // <code>
  307. const wiki = new Wikiapi('en');
  308. const page_data = await wiki.page('JavaScript');
  309. const parsed = page_data.parse();
  310. let infobox;
  311. // Read [[w:en:MOS:INFOBOX|Infobox templates]], convert to JSON.
  312. parsed.each('template', template_token => {
  313. 	if (template_token.name.startsWith('Infobox')) {
  314. 		infobox = template_token.parameters;
  315. 		return parsed.each.exit;
  316. 	}
  317. });
  318. for (const [key, value] of Object.entries(infobox))
  319. 	infobox[key] = value.toString();
  320. // print json of the infobox
  321. console.log(infobox);
  322. // </code>
  323.  *
  324.  * @memberof Wikiapi.prototype
  325.  */
  326. function Wikiapi_page(title, options) {
  327. 	function Wikiapi_page_executor(resolve, reject) {
  328. 		const wiki = this[KEY_wiki_session];
  329. 		wiki.page(title, (page_data, error) => {
  330. 			if (error) {
  331. 				reject(error);
  332. 			} else {
  333. 				resolve(set_page_data_attributes(page_data, wiki));
  334. 			}
  335. 		}, {
  336. 			// node.js v12.22.7: Cannot use "?."
  337. 			rvlimit: options && options.revisions,
  338. 			...options
  339. 		});
  340. 	}
  342. 	return new Promise(Wikiapi_page_executor.bind(this));
  343. }
  345. // --------------------------------------------------------
  347. /**
  348.  * @alias tracking_revisions
  349.  * @description tracking revisions to lookup what revision had added / removed <code>to_search</code>.
  350.  * 
  351.  * @param {String} title		- page title
  352.  * @param {String} to_search	- filter / text to search. to_search(diff, revision, old_revision): `diff` 為從舊的版本 `old_revision` 改成 `revision` 時的差異。
  353.  * @param {Object} [options]	- options to run this function
  354.  * 
  355.  * @returns {Promise} Promise object represents {Object} newer_revision,
  356.  *          newer_revision.page: page_data
  357.  * 
  358.  * @memberof Wikiapi.prototype
  359.  */
  360. function Wikiapi_tracking_revisions(title, to_search, options) {
  361. 	function Wikiapi_tracking_revisions_executor(resolve, reject) {
  362. 		const wiki = this[KEY_wiki_session];
  363. 		wiki.tracking_revisions(title, to_search, (revision, page_data, error) => {
  364. 			if (error) {
  365. 				reject(error);
  366. 			} else {
  367. 				if (!revision)
  368. 					revision = Object.create(null);
  369. 				revision.page = page_data;
  370. 				resolve(revision);
  371. 			}
  372. 		}, options);
  373. 	}
  375. 	return new Promise(Wikiapi_tracking_revisions_executor.bind(this));
  376. }
  378. // --------------------------------------------------------
  380. /**
  381.  * @description Handle the result of MediaWiki API when executing edit operation.
  382.  * 
  383.  * @param {Function} reject	- reject function
  384.  * @param {any} error		- error object / message
  385.  * @param {any} [result]	- result of MediaWiki API
  386.  *
  387.  * @returns {Boolean} Return <code>true</code> if the edit operation failed.
  388.  * 
  389.  * @ignore
  390.  * @inner
  391.  */
  392. function reject_edit_error(reject, error, result) {
  393. 	// skip_edit is not error
  394. 	if (!error
  395. 		// e.g., set options.skip_nochange
  396. 		// @see function do_batch_work_summary @ CeL.application.net.wiki.task
  397. 		|| error === 'nochange' || error === 'skip'
  398. 		// @see wiki_API_edit.check_data
  399. 		|| Array.isArray(error) && error[0] === Wikiapi.skip_edit[0]) {
  400. 		return;
  401. 	}
  403. 	if (Array.isArray(error) && typeof error[1] === 'string') {
  404. 		// console.log('' + reject);
  405. 		// console.trace(error);
  406. 		error = error[1];
  407. 		const error_object = new Error(error);
  408. 		error_object.from_string = error;
  409. 		error = error_object
  410. 		// console.log(error);
  411. 	}
  413. 	if (result && error && typeof error === 'object')
  414. 		error.result = result;
  415. 	reject(error);
  416. 	return true;
  417. }
  419. /**
  420.  * @alias edit_page
  421.  * @description edits content of target page.<br />
  422.  * Note: for multiple pages, you should use {@link Wikiapi#for_each_page}.<br />
  423.  * Note: The function will check sections of [[User talk:user name/Stop]] if somebody tells us needed to stop edit. See <a href="https://en.wikipedia.org/wiki/User:Cewbot/Stop">mechanism to stop operations</a>.
  424.  * 
  425.  * @param {String} title			- page title
  426.  * @param {String|Function} content	- 'wikitext page content' || page_data => 'wikitext'
  427.  * @param {Object} [options]		- options to run this function. e.g., { summary: '', bot: 1, nocreate: 1, minor: 1 }
  428.  * 
  429.  * @returns {Promise} Promise object represents {Object} result of MediaWiki API
  430.  *
  431.  * @example <caption>edit page: method 1: basic operation</caption>
  432. // <code>
  433. const enwiki = new Wikiapi;
  434. await enwiki.login('bot name', 'password', 'en');
  436. const SB_page_data = await enwiki.page('Wikipedia:Sandbox');
  437. // You may do some operations on SB_page_data
  438. const parsed = SB_page_data.parse();
  439. parsed.each('template', template_token => {
  440. 	// modify template token
  441. });
  442. // and then edit it. ** You MUST call enwiki.page() before enwiki.edit()! **
  443. await enwiki.edit(parsed.toString(), { bot: 1, minor: 1, nocreate: 1 });
  445. // exmaple 2: append text in the tail of page content
  446. await enwiki.edit(page_data => {
  447. 	return page_data.wikitext
  448. 		+ '\nTest edit using {{GitHub|kanasimi/wikiapi}}.';
  449. }, { bot: 1 });
  451. // exmaple 3: replace page content
  452. await enwiki.edit('Just replace by this wikitext', { bot: 1, minor: 1, nocreate: 1, summary: 'test edit' });
  454. // exmaple 4: append a new section
  455. await enwiki.edit('section content', {
  456. 	section: 'new',
  457. 	sectiontitle: 'section title',
  458. 	nocreate : 1,
  459. 	summary: 'test edit',
  460. });
  461. // </code>
  462.  *
  463.  * @example <caption>edit page: method 2: modify summary inside function</caption>
  464. // <code>
  465. const enwiki = new Wikiapi;
  466. await enwiki.login('bot name', 'password', 'en');
  467. await enwiki.edit_page('Wikipedia:Sandbox', function (page_data) {
  468. 	this.summary += ': You may set additional summary inside the function';
  469. 	delete this.minor;
  470. 	return page_data.wikitext
  471. 		+ '\nTest edit using {{GitHub|kanasimi/wikiapi}}.';
  472. }, { bot: 1, nocreate: 1, minor: 1, redirects: 1, summary: 'test edit' });
  473. // </code>
  474.  *
  475.  * @memberof Wikiapi.prototype
  476.  */
  477. function Wikiapi_edit_page(title, content, options) {
  478. 	function Wikiapi_edit_page_executor(resolve, reject) {
  479. 		const wiki = this[KEY_wiki_session];
  481. 		// console.trace([title, content]);
  482. 		// console.trace(`Wikiapi_edit_page 1: ${wiki_API.title_link_of(title)}, ${wiki.actions.length} actions, ${wiki.running}/${wiki.thread_count}/${wiki.actions[wiki_API.KEY_waiting_callback_result_relying_on_this]}.`);
  483. 		// console.trace(title);
  484. 		// CeL.set_debug(6);
  485. 		if (title) {
  486. 			// console.trace(wiki);
  487. 			options = { ...options, error_with_symbol: true };
  488. 			if (false && options.page_to_edit && wiki_API.title_of(options.page_to_edit) !== wiki_API.title_of(title)) {
  489. 				console.trace('delete options.page_to_edit!');
  490. 				delete options.page_to_edit;
  491. 			}
  492. 			// 預防 page 本身是非法的頁面標題。當 session.page() 出錯時，將導致沒有 .last_page。
  493. 			if (wiki_API.content_of.had_fetch_content(title)) {
  494. 				options.page_to_edit = title;
  495. 			} else {
  496. 				options.page_title_to_edit = title;
  497. 				options.page_to_edit = wiki_API.VALUE_set_page_to_edit;
  498. 				// 設定個僅 debug 用、無功能的註記。
  499. 				//options[Symbol('page title to edit')] = title;
  500. 			}
  501. 			// call wiki_API_prototype_method() @ CeL.application.net.wiki.list
  502. 			wiki.page(title, (page_data, error) => {
  503. 				// console.trace(`Set .page_to_edit: ${wiki_API.title_link_of(page_data)} (${title}) (${wiki_API.title_link_of(options.page_to_edit)})`);
  504. 				// console.trace(options);
  505. 				// console.log([page_data, error]);
  506. 				// console.log(wiki.actions[0]);
  507. 				// if (!page_data) console.trace(page_data);
  509. 				// 手動指定要編輯的頁面。避免多執行續打亂 wiki.last_page。
  510. 				// Will set at wiki_API.prototype.next
  511. 				//options.page_to_edit = page_data;
  512. 			}, options);
  513. 		}
  514. 		// console.trace(`Wikiapi_edit_page 2: ${wiki_API.title_link_of(title)}, ${wiki.actions.length} actions, ${wiki.running}/${wiki.thread_count}/${wiki.actions[wiki_API.KEY_waiting_callback_result_relying_on_this]}.`);
  515. 		// console.trace(wiki);
  516. 		// console.trace(wiki.last_page);
  518. 		// wiki.edit(page contents, options, callback)
  519. 		wiki.edit(typeof content === 'function' ? function (page_data) {
  520. 			// console.trace(`Get page_data of ${wiki_API.title_link_of(page_data)} (${title})`);
  521. 			return content.call(this, set_page_data_attributes(page_data, wiki));
  522. 		} : content, options, (title, error, result) => {
  523. 			// console.trace(`Wikiapi_edit_page: callbacked: ${wiki_API.title_link_of(title)} (${wiki.running})`);
  524. 			// CeL.set_debug(6);
  526. 			if (!reject_edit_error(reject, error, result)) {
  527. 				// console.log('Wikiapi_edit_page: resolve');
  528. 				resolve(title);
  529. 			}
  530. 			// console.log('Wikiapi_edit_page: callback() return');
  531. 		});
  533. 		// console.trace(`Wikiapi_edit_page 3: ${wiki_API.title_link_of(title)}, ${wiki.actions.length} actions, ${wiki.running}/${wiki.thread_count}/${wiki.actions[wiki_API.KEY_waiting_callback_result_relying_on_this]}.`);
  534. 	}
  536. 	return new Promise(Wikiapi_edit_page_executor.bind(this));
  537. }
  539. // <code>return Wikiapi.skip_edit;</code> as a symbol to skip this edit, do not generate
  540. // warning message.
  541. // 可以利用 ((return [ wiki_API.edit.cancel, 'reason' ];)) 來回傳 reason。
  542. // ((return [ wiki_API.edit.cancel, 'skip' ];)) 來跳過 (skip) 本次編輯動作，不特別顯示或處理。
  543. // 被 skip/pass 的話，連警告都不顯現，當作正常狀況。
  544. /**
  545.  * @description Return <code>Wikiapi.skip_edit</code> when we running edit function, but do not want to edit current page.
  546.  * 
  547.  * @memberof Wikiapi
  548.  */
  549. Wikiapi.skip_edit = [wiki_API.edit.cancel, 'skip'];
  551. // --------------------------------------------------------
  553. /**
  554.  * @alias move_page
  555.  * @description Move page <code>move_from_title</code> to <code>move_to_title</code>.
  556.  *
  557.  * @param {Object|String} move_from_title	- move from title
  558.  * @param {Object|String} move_to_title		- move to title
  559.  * @param {Object} [options]				- options to run this function
  560.  *
  561.  * @returns {Promise} Promise object represents {String} result of MediaWiki API
  562.  *
  563.  * @example <caption>Move <code>move_from_title</code> to <code>move_to_title</code>.</caption>
  564. // <code>
  565. await wiki.move_page(move_from_title, move_to_title, { reason, noredirect: true, movetalk: true });
  566. // </code>
  567.  *
  568.  * @memberof Wikiapi.prototype
  569.  */
  570. function Wikiapi_move_page(move_from_title, move_to_title, options) {
  571. 	function Wikiapi_move_page_executor(resolve, reject) {
  572. 		const wiki = this[KEY_wiki_session];
  573. 		// using wiki_API.prototype.move_page()
  574. 		wiki.move_page(move_from_title, move_to_title, options, (data, error) => {
  575. 			if (error) {
  576. 				/**
  577. 				 * <code>
  579. 				e.g., { code: 'articleexists', info: 'A page of that name already exists, or the name you have chosen is not valid. Please choose another name.', '*': '...' }
  580. 				e.g., { code: 'missingtitle', info: "The page you specified doesn't exist.", '*': '...' }
  582. 				</code>
  583. 				 */
  584. 				reject(error);
  585. 			} else {
  586. 				/**
  587. 				 * <code>
  589. 				e.g., { from: 'from', to: 'to', reason: 'move', redirectcreated: '', moveoverredirect: '' }
  591. 				</code>
  592. 				 */
  593. 				resolve(data);
  594. 			}
  595. 		}, options);
  596. 	}
  598. 	return new Promise(Wikiapi_move_page_executor.bind(this));
  600. }
  602. /**
  603.  * @alias move_to
  604.  * @description Move to <code>move_to_title</code>. <em>Must call {@link Wikiapi#page} first!</em>
  605.  * 
  606.  * @param {Object|String} move_to_title	- move to title
  607.  * @param {Object} [options]			- options to run this function
  608.  *
  609.  * @returns {Promise} Promise object represents {String} result of MediaWiki API
  610.  *
  611.  * @example <caption>Move <code>move_from_title</code> to <code>move_to_title</code>.</caption>
  612. // <code>
  613. page_data = await wiki.page(move_from_title);
  614. await wiki.move_to(move_to_title, { reason: reason, noredirect: true, movetalk: true });
  615. // </code>
  616.  * 
  617.  * @memberof Wikiapi.prototype
  618.  */
  619. function Wikiapi_move_to(move_to_title, options) {
  620. 	function Wikiapi_move_to_executor(resolve, reject) {
  621. 		const wiki = this[KEY_wiki_session];
  622. 		if (!wiki.last_page) {
  623. 			reject(new Error(Wikiapi_move_to.name + ': Must call .page() first! '
  624. 				// gettext_config:{"id":"cannot-move-to-$1"}
  625. 				+ CeL.gettext('Cannot move to %1', wiki_API.title_link_of(move_to_title))));
  626. 			return;
  627. 		}
  629. 		// using wiki_API.prototype.move_to()
  630. 		wiki.move_to(move_to_title, options, (data, error) => {
  631. 			if (error) {
  632. 				/**
  633. 				 * <code>
  635. 				e.g., { code: 'articleexists', info: 'A page of that name already exists, or the name you have chosen is not valid. Please choose another name.', '*': '...' }
  636. 				e.g., { code: 'missingtitle', info: "The page you specified doesn't exist.", '*': '...' }
  638. 				</code>
  639. 				 */
  640. 				reject(error);
  641. 			} else {
  642. 				/**
  643. 				 * <code>
  645. 				e.g., { from: 'from', to: 'to', reason: 'move', redirectcreated: '', moveoverredirect: '' }
  647. 				</code>
  648. 				 */
  649. 				resolve(data);
  650. 			}
  651. 		}, options);
  652. 	}
  654. 	return new Promise(Wikiapi_move_to_executor.bind(this));
  655. }
  658. // --------------------------------------------------------
  660. /**
  661.  * @alias query
  662.  * @description query MediaWiki API manually
  663.  * 
  664.  * @param {Object} parameters	- parameters to call MediaWiki API
  665.  * @param {Object} [options]	- options to run this function
  666.  *
  667.  * @returns {Promise} Promise object represents {Object} result of MediaWiki API
  668.  *
  669.  * @example <caption>query flow-parsoid-utils</caption>
  670. // <code>
  671. const wiki = new Wikiapi('mediawiki');
  672. const results = await wiki.query({
  673. 	action: "flow-parsoid-utils",
  674. 	content: "<b>bold</b> &amp; <i>italic</i>",
  675. 	title: "MediaWiki", from: "html", to: "wikitext"
  676. });
  677. // </code>
  678.  * 
  679.  * @memberof Wikiapi.prototype
  680.  */
  681. function Wikiapi_query(parameters, options) {
  682. 	function Wikiapi_query_executor(resolve, reject) {
  683. 		const wiki = this[KEY_wiki_session];
  684. 		wiki.query_API(parameters, (data, error) => {
  685. 			if (error) {
  686. 				reject(error);
  687. 			} else {
  688. 				resolve(data);
  689. 			}
  690. 		}, {
  691. 			post_data_only: true,
  692. 			...options
  693. 		});
  694. 	}
  696. 	return new Promise(Wikiapi_query_executor.bind(this));
  697. }
  699. // --------------------------------------------------------
  701. /**
  702.  * @alias purge
  703.  * @description Purge the cache for the given title.
  704.  * 
  705.  * @param {Object} title		- page title
  706.  * @param {Object} [options]	- options to run this function
  707.  *
  708.  * @returns {Promise} Promise object represents {Object} page_data
  709.  *
  710.  * @example <caption>query flow-parsoid-utils</caption>
  711. // <code>
  712. const metawiki = new Wikiapi('meta');
  713. let page_data = await metawiki.purge('Project:Sandbox');
  714. // </code>
  715.  * 
  716.  * @memberof Wikiapi.prototype
  717.  */
  718. function Wikiapi_purge(title, options) {
  719. 	if (CeL.is_Object(title) && !options) {
  720. 		// shift arguments.
  721. 		[title, options] = [null, title];
  722. 	}
  724. 	function Wikiapi_purge_executor(resolve, reject) {
  725. 		const wiki = this[KEY_wiki_session];
  726. 		if (title) {
  727. 			wiki.page(title);
  728. 		}
  729. 		// using wiki_API.purge
  730. 		wiki.purge((data, error) => {
  731. 			if (error) {
  732. 				reject(error);
  733. 			} else {
  734. 				resolve(data);
  735. 			}
  736. 		}, options);
  737. 	}
  739. 	return new Promise(Wikiapi_purge_executor.bind(this));
  740. }
  742. // --------------------------------------------------------
  744. /**
  745.  * @description Bind properties to {@link wiki_API} data entity.
  746.  * 設定 wikidata entity object，讓我們能直接操作 entity.modify()，並且避免洩露 wiki_API session。
  747.  * 
  748.  * @param {Object} data_entity	- wiki_API data entity
  749.  * 
  750.  * @ignore
  751.  * @inner
  752.  */
  753. function setup_data_entity(data_entity) {
  754. 	if (!data_entity)
  755. 		return;
  756. 	// assert: data_entity[KEY_SESSION].host === this
  757. 	// console.trace(data_entity[KEY_SESSION].host === this);
  758. 	delete data_entity[KEY_SESSION];
  760. 	Object.defineProperties(data_entity, {
  761. 		[KEY_wiki_session]: { value: this },
  762. 		modify: { value: modify_data_entity },
  763. 	});
  764. }
  766. /**
  767.  * @description Modify data entity
  768.  * 
  769.  * @param {Object} data_entity	- wiki_API data entity
  770.  * @param {Object} [options]	- options to run this function
  771.  * 
  772.  * @returns {Promise} Promise object represents {Object} result data entity
  773.  * 
  774.  * @ignore
  775.  * @inner
  776.  */
  777. function modify_data_entity(data_to_modify, options) {
  778. 	function modify_data_entity_executor(resolve, reject) {
  779. 		const wiki = this[KEY_wiki_session];
  780. 		// console.trace(wiki);
  782. 		// using function wikidata_edit() @
  783. 		// https://github.com/kanasimi/CeJS/blob/master/application/net/wiki/data.js
  784. 		// wiki.edit_data(id, data, options, callback)
  785. 		wiki.data(this).edit_data(data_to_modify || this, options, (data_entity, error) => {
  786. 			// console.trace([data_entity, error]);
  787. 			if (error) {
  788. 				reject(error);
  789. 			} else {
  790. 				setup_data_entity.call(wiki, data_entity);
  791. 				resolve(data_entity);
  792. 			}
  793. 		});
  794. 	}
  796. 	return new Promise(modify_data_entity_executor.bind(this));
  797. }
  799. /**
  800.  * @alias data
  801.  * @description Get wikidata entity / property
  802.  *
  803.  * @param {Object} data_entity	- wiki_API data entity
  804.  * @param {Object} [options]	- options to run this function
  805.  *
  806.  * @returns {Promise} Promise object represents {Object} wikidata entity / property
  807.  *
  808.  * @example <caption>Get wikidata entity method 1</caption>
  809. // <code>
  810. const wiki = new Wikiapi;
  811. const data_entity = await wiki.data('Q1');
  812. // Work with other language
  813. console.assert(CeL.wiki.data.value_of(data_entity.labels.zh) === '宇宙');
  814. // </code>
  815.  *
  816.  * @example <caption>Get wikidata entity of [[Human]]</caption>
  817. // <code>
  818. const wiki = new Wikiapi;
  819. const page_data = await wiki.page('Human');
  820. const data_entity = await wiki.data(page_data);
  821. console.assert(CeL.wiki.data.value_of(data_entity.labels.zh) === '人類');
  822. // </code>
  823.  *
  824.  * @example <caption>Get wikidata entity method 2: Get P1419 of wikidata entity: 'Universe'</caption>
  825. // <code>
  826. const wiki = new Wikiapi;
  827. // Read, access by title (English), access property P1419
  828. let data = await wiki.data('Universe', 'P1419');
  829. // assert: {Array}data = [ 'shape of the universe', '', ... ]
  830. console.assert(data.includes('shape of the universe'));
  831. // </code>
  832.  *
  833.  * @example <caption>update wikidata</caption>
  834. // <code>
  835. // Just for test
  836. delete CeL.wiki.query.default_maxlag;
  837. const wiki = new Wikiapi;
  838. await wiki.login('user', 'password', 'test');
  840. // Get https://test.wikidata.org/wiki/Q7
  841. let entity = await wiki.data('Q7');
  842. // search [ language, label ]
  843. //entity = await wiki.data(['en', 'Earth']);
  845. // Reset claim
  846. entity = await wiki.data('Q1841');
  847. await entity.modify({ claims: [{ P3: "old.wav", remove: true }] }, { bot: 1, summary: 'test edit: Remove specific value' });
  848. // Warning: If you want to perform multiple operations on the same property, you need to get the entity again!
  849. entity = await wiki.data('Q1841');
  850. await entity.modify({ claims: [{ P3: "new.wav" }] }, { bot: 1, summary: 'test edit: Add value' });
  852. // Update claim
  853. await entity.modify({ claims: [{ P17: 'Q213280' }] }, { bot: 1, summary: 'test edit: Update claim' });
  855. // Update claim: set country (P17) to 'Test Country 1' (Q213280) ([language, label] as entity)
  856. await entity.modify({ claims: [{ language: 'en', country: [, 'Test Country 1'] }] }, { summary: '' });
  858. // Remove country (P17) : 'Test Country 1' (Q213280)
  859. await entity.modify({ claims: [{ language: 'en', country: [, 'Test Country 1'], remove: true }] }, { summary: '' });
  861. // Update label
  862. await entity.modify({ labels: [{ language: 'zh-tw', value: '地球' }] }, { summary: '' });
  863. // </code>
  864.  *
  865.  * @memberof Wikiapi.prototype
  866.  */
  867. function Wikiapi_data(key, property, options) {
  868. 	if (CeL.is_Object(property) && !options) {
  869. 		// shift arguments.
  870. 		[property, options] = [null, property];
  871. 	}
  873. 	function Wikiapi_data_executor(resolve, reject) {
  874. 		const wiki = this[KEY_wiki_session];
  875. 		if (false && wiki_API.is_page_data(key)) {
  876. 			// get entity (wikidata item) of page_data: key
  877. 			// .page(key): 僅僅設定 .last_page，不會真的再獲取一次頁面內容。
  878. 			wiki.page(key);
  879. 		}
  880. 		if (key.title && !key.site) {
  881. 			// @see function wikidata_entity() @ CeL.application.net.wiki.data
  882. 			// 確保引用到的是本 wiki session，不會引用到其他 site。
  883. 			key = { ...key, site: this.site_name() };
  884. 		}
  885. 		// using wikidata_entity() → wikidata_datavalue()
  886. 		wiki.data(key, property, (data_entity, error) => {
  887. 			if (error) {
  888. 				reject(error);
  889. 			} else {
  890. 				setup_data_entity.call(wiki, data_entity);
  891. 				resolve(data_entity);
  892. 			}
  893. 		}, options);
  894. 	}
  896. 	return new Promise(Wikiapi_data_executor.bind(this));
  897. }
  900. /**
  901.  * @alias new_data_entity
  902.  * @description Create new entity or property
  903.  *
  904.  * @param {Object} data_to_modify	- Initial data.
  905.  * @param {Object} [options]		- options to run this function
  906.  *
  907.  * @returns {Promise} Promise object represents {Object} new entity or property.
  908.  *
  909.  * @example <caption>Create new entity</caption>
  910. // <code>
  911. const new_entity = await wiki.new_data_entity({ labels: { en: "Evolution in Mendelian Populations" }, P698: "17246615", P932: "1201091" }, { new: 'item' });
  912. // </code>
  913.  *
  914.  * @memberof Wikiapi.prototype
  915.  */
  916. function Wikiapi_new_data_entity(data_to_modify, options) {
  917. 	function Wikiapi_new_data_entity_executor(resolve, reject) {
  918. 		options = { new: 'item', ...options };
  919. 		const wiki = this[KEY_wiki_session];
  920. 		wiki.edit_data({}, options, (data_entity, error) => {
  921. 			if (error) {
  922. 				reject(error);
  923. 			} else if (data_to_modify) {
  924. 				delete options.new;
  925. 				//console.trace([data_entity, options]);
  926. 				wiki.edit_data(data_entity, data_to_modify, options, (result, error) => {
  927. 					if (error) {
  928. 						reject(error);
  929. 					} else if (false && options.retrieve_entity) {
  930. 						// reget modified data
  931. 						this.data(data_entity.id, options).then(resolve, reject);
  932. 					} else {
  933. 						//console.trace([data_entity, result]);
  934. 						//data_entity.latest_result = result;
  935. 						// data_entity: e.g.,
  936. 						// {"type":"item","id":"Q123456","labels":{},"descriptions":{},"aliases":{},"claims":{},"sitelinks":{},"lastrevid":123456}
  937. 						resolve(data_entity);
  938. 					}
  939. 				});
  940. 			} else {
  941. 				setup_data_entity.call(wiki, data_entity);
  942. 				resolve(data_entity);
  943. 			}
  944. 		});
  945. 	}
  947. 	return new Promise(Wikiapi_new_data_entity_executor.bind(this));
  948. }
  950. // --------------------------------------------------------
  952. /**
  953.  * @alias SPARQL
  954.  * @description Query wikidata via SPARQL
  955.  *
  956.  * @param {Object} SPARQL		- SPARQL to query. Please test it on <a href="https://query.wikidata.org/">Wikidata Query Service</a> first.
  957.  * @param {Object} [options]	- options to run this function
  958.  *
  959.  * @returns {Promise} Promise object represents {Array} query result of `SPARQL`.
  960.  *
  961.  * @example <caption>Get cats</caption>
  962. // <code>
  963. const wikidata_item_list = await wiki.SPARQL(`
  964. SELECT ?item ?itemLabel WHERE {
  965.   ?item wdt:P31 wd:Q146.
  966.   SERVICE wikibase:label { bd:serviceParam wikibase:language "[AUTO_LANGUAGE],en". }
  967. }
  968. `);
  969. // </code>
  970.  *
  971.  * @example <caption>Get specific DOI</caption>
  972. // <code>
  973. // for case-insensitive DOI
  974. const wikidata_item_list = await wiki.search('haswbstatement:' + JSON.stringify('P356=10.1371/journal.pone.0029797'), { namespace: 0 });
  975. //wikidata_item_list.map(item => item.title)
  977. // for case-sensitive DOI
  978. const wikidata_item_list = await wiki.SPARQL(`
  979. SELECT ?doi ?item ?itemLabel WHERE {
  980. 	VALUES ?doi { "10.1371/JOURNAL.PONE.0029797" }
  981. 	?item wdt:P356 ?doi.
  982. 	SERVICE wikibase:label { bd:serviceParam wikibase:language "en". }
  983. }`, {
  984. 	// options.API_URL: custom SPARQL endpoint
  985. 	API_URL: ''
  986. });
  987. //wikidata_item_list.id_list()
  988. // </code>
  989.  *
  990.  * @memberof Wikiapi.prototype
  991.  */
  992. function Wikiapi_SPARQL(SPARQL, options) {
  993. 	function Wikiapi_SPARQL_executor(resolve, reject) {
  994. 		wiki_API.SPARQL(SPARQL, (result, error) => {
  995. 			if (error) {
  996. 				reject(error);
  997. 			} else {
  998. 				resolve(result);
  999. 			}
  1000. 		}, this.append_session_to_options(options));
  1001. 	}
  1003. 	return new Promise(Wikiapi_SPARQL_executor.bind(this));
  1004. }
  1007. // --------------------------------------------------------
  1009. /**
  1010.  * @description Tool function to access page list.<br />
  1011.  * Please refer to <a href="https://github.com/kanasimi/CeJS/blob/master/application/net/wiki/list.js#:~:text=get_list.type%20=">all supported types</a> (search "get_list.type =").
  1012.  * 
  1013.  * @example <caption>get list of [[w:en:Category:Chemical_elements]]</caption>
  1014. // <code>
  1015. const wiki = new Wikiapi;
  1016. let page_list = await wiki.categorymembers('Chemical elements');
  1017. console.log(page_list);
  1018. // Working on multiple pages
  1019. await wiki.for_each_page(
  1020. 	// {Array} title liat / page data list
  1021. 	page_list,
  1022. 	page_data => {
  1023. 		// ...
  1024. 	});
  1025. // </code>
  1026.  *
  1027.  * @example <caption>get pages transcluding {{w:en:Periodic table}}</caption>
  1028. // <code>
  1029. const wiki = new Wikiapi;
  1030. let page_list = await wiki.embeddedin('Template:Periodic table');
  1031. console.log(page_list);
  1032. // </code>
  1033.  *
  1034.  * @example <caption>Process each page of the category.</caption>
  1035. // <code>
  1036. // Get the list of all pages at once first.
  1037. const page_list = await wiki.categorymembers('Category:Articles not listed in the vital article list');
  1038. await page_list.each((page_data) => { }, options);
  1040. // Imperative code, for huge pages. 用於巨量的頁面。
  1041. for await (const page_data of wiki.categorymembers('Category:Articles not listed in the vital article list')) {
  1042. 	console.trace(`page_data #${count}:`, page_data);
  1043. }
  1045. // Declarative code(?), for huge pages.
  1046. await wiki.categorymembers('Category:Articles not listed in the vital article list', {
  1047. 	for_each_page(page_data) {
  1048. 		console.log('page_data:', page_data);
  1049. 	}
  1050. });
  1052. await wiki.allpages({
  1053. 	async for_each_slice(page_list) {
  1054. 	}
  1055. });
  1057. // </code>
  1058.  *
  1059.  * @example <caption>Process all pages.</caption>
  1060. // <code>
  1061. let count = 0;
  1062. for await (const page_data of wiki.allpages({ namespace: 'Talk', apfrom: wiki.remove_namespace('ABC') })) {
  1063. 	console.trace(`page_data #${count}:`, page_data);
  1064. 	if (++count > 5) break;
  1065. }
  1066. console.log('Done.');
  1067. // </code>
  1068.  *
  1069.  * @example <caption>Process all pages with batch_size.</caption>
  1070. // <code>
  1071. let count = 0;
  1072. for await (const page_list of wiki.allpages({ namespace: 'Talk', apfrom: wiki.remove_namespace('ABC'), batch_size: 5 })) {
  1073. 	console.trace('page_list:', page_list);
  1074. 	if (++count > 2) break;
  1075. }
  1076. console.log('Done.');
  1077. // </code>
  1078.  *
  1079.  */
  1081. // Warning: Won't throw if title is not existed!
  1082. // @inner
  1083. function Wikiapi_list(list_type, title, options) {
  1084. 	function Wikiapi_list_executor(resolve, reject) {
  1085. 		options = CeL.setup_options(options);
  1086. 		// console.trace(options.for_each_page);
  1087. 		// const wiki = this[KEY_wiki_session];
  1088. 		//console.trace([ list_type, title ]);
  1089. 		wiki_API.list(title, (list/* , target, options */) => {
  1090. 			// console.trace(list);
  1091. 			if (list.error) {
  1092. 				reject(list.error);
  1093. 			} else {
  1094. 				resolve(list);
  1095. 			}
  1096. 		}, this.append_session_to_options({
  1097. 			type: list_type,
  1098. 			// namespace: '0|1',
  1099. 			...options
  1100. 		}));
  1102. 		/**
  1103. 		 * <code>
  1105. 		// method 2: 使用循環取得資料版:
  1106. 		wiki.cache({
  1107. 			// Do not write cache file to disk.
  1108. 			cache: false,
  1109. 			type: list_type,
  1110. 			list: title
  1111. 		}, (list, error) => {
  1112. 			if (error) {
  1113. 				reject(error);
  1114. 			} else {
  1115. 				resolve(list);
  1116. 			}
  1117. 		},
  1118. 			// default options === this
  1119. 			//{ namespace : '0|1' }
  1120. 			options);
  1122. 		// NG: 不應使用單次版
  1123. 		wiki[list_type](title, (list, error) => {
  1124. 			if (error) {
  1125. 				reject(error);
  1126. 			} else {
  1127. 				resolve(list);
  1128. 			}
  1129. 		}, {
  1130. 				limit: 'max', ...options
  1131. 			});
  1133. 		</code>
  1134. 		 */
  1135. 	}
  1137. 	return new Promise(Wikiapi_list_executor.bind(this));
  1138. }
  1141. /**
  1142.  * @alias for_each_page_in_list
  1143.  * @description Syntactic sugar for several kinds of lists.
  1144.  * 
  1145.  * @param {String} type				- list type
  1146.  * @param {String} [title]			- page title if necessary.
  1147.  * @param {Function} for_each_page	- Executing for each page.
  1148.  * @param {Object} [options]		- options to run this function.
  1149.  * @returns {Promise}
  1150.  *
  1151.  * @deprecated Please use {@link Wikiapi_list}.
  1152.  * 
  1153.  * @example <caption>List all redirected categories</caption>
  1154. // <code>
  1155. await wiki.for_each_page_in_list('allredirects', page_data => console.log('page_data: ', page_data), { namespace: 'Category' });
  1156. // </code>
  1157.  */
  1158. function Wikiapi_for_each_page_in_list(type, title, for_each_page, options) {
  1159. 	if (options === undefined && typeof title === 'function') {
  1160. 		// shift arguments
  1161. 		options = for_each_page;
  1162. 		for_each_page = title;
  1163. 		title = undefined;
  1164. 	}
  1166. 	return Wikiapi_list.call(this, type, title, {
  1167. 		for_each_page: for_each_page,
  1168. 		...options
  1169. 	});
  1170. }
  1173. // wrapper for sync functions
  1174. for (const function_name of ('namespace|remove_namespace|is_article|is_namespace|to_namespace|is_talk_namespace|to_talk_page|talk_page_to_main|normalize_title|redirect_target_of|aliases_of_page|is_template'
  1175. 	// CeL.run('application.net.wiki.featured_content');
  1176. 	// [].map(wiki.to_talk_page.bind(wiki))
  1177. 	+ '|get_featured_content_configurations').split('|')) {
  1178. 	Wikiapi.prototype[function_name] = function wrapper() {
  1179. 		const wiki = this[KEY_wiki_session];
  1180. 		return wiki[function_name].apply(wiki, arguments);
  1181. 	};
  1182. }
  1184. const default_list_wait_size = 100;
  1185. // assert: default_list_wait_size >= 1
  1187. // @see get_list.type @
  1188. // https://github.com/kanasimi/CeJS/blob/master/application/net/wiki/list.js
  1189. for (const type of wiki_API.list.type_list) {
  1190. 	// Cannot use `= (title, options) {}` !
  1191. 	// arrow function expression DO NOT has this, arguments, super, or
  1192. 	// new.target keywords.
  1193. 	Wikiapi.prototype[type] = Wikiapi_get_page_list_of_type;
  1195. 	function Wikiapi_get_page_list_of_type(title, options) {
  1196. 		if (options === undefined && CeL.is_Object(title) && !wiki_API.is_page_data(title)) {
  1197. 			// shift arguments
  1198. 			options = title;
  1199. 			title = undefined;
  1200. 		}
  1201. 		const _this = this;
  1202. 		//console.trace(arguments);
  1204. 		let done, page_queue = [], resolve_queue, waiting_resolve;
  1205. 		// 餵頁面資料給 resolve()
  1206. 		function feed_page_data() {
  1207. 			//console.trace([resolve_queue.length, done, page_queue.length, options.batch_size]);
  1208. 			if (resolve_queue.length === 0)
  1209. 				return;
  1211. 			if (!done && !(page_queue.length >= (options.batch_size >= 1 ? options.batch_size : 1))) {
  1212. 				//CeL.info(`${feed_page_data.name}: 尚未累積足夠的頁面資料。 (${page_queue.length},${options.batch_size})`);
  1213. 				//CeL.set_debug(6);
  1214. 				return;
  1215. 			}
  1217. 			const feed_done = page_queue.abort || page_queue.length === 0;
  1218. 			// 由最早的開始給。
  1219. 			const value = options.batch_size >= 1 ? page_queue.splice(0, options.batch_size) : page_queue.shift();
  1221. 			// .shift(): 由最早的開始餵。
  1222. 			resolve_queue.shift()(feed_done ? { done } : { value });
  1223. 		}
  1225. 		function for_each_page(page_data) {
  1226. 			if (page_queue.abort)
  1227. 				return CeL.wiki.list.exit;
  1229. 			//console.trace(page_data, done, page_queue, resolve_queue);
  1230. 			const return_value = original_for_each_page?.apply(this, arguments);
  1232. 			if (resolve_queue) {
  1233. 				if (return_value === CeL.wiki.list.exit) {
  1234. 					page_queue.abort = done = true;
  1235. 					page_queue.truncate();
  1237. 					if (waiting_resolve) {
  1238. 						//CeL.info(`${for_each_page.name}: 清掉前面累積的。例如 wiki_API.list 剎不住。`);
  1239. 						waiting_resolve();
  1240. 					}
  1242. 				} else {
  1243. 					page_queue.push(page_data);
  1245. 					//console.trace(page_queue.length, 'pages in queue');
  1246. 					feed_page_data();
  1248. 					// assert: default_list_wait_size >= 1
  1249. 					const wait_size = options.batch_size > default_list_wait_size ? options.batch_size : default_list_wait_size;
  1250. 					if (page_queue.length > wait_size) {
  1251. 						if (waiting_resolve) {
  1252. 							//CeL.info(`${for_each_page.name}: 清掉前面累積的。例如 wiki_API.list 剎不住。`);
  1253. 							waiting_resolve();
  1254. 						}
  1255. 						//CeL.info(`${for_each_page.name}: 已經累積太多頁面資料(${page_queue.length} > ${wait_size})，該緩緩了。`);
  1256. 						return new Promise(resolve => { waiting_resolve = resolve; });
  1257. 					}
  1258. 				}
  1259. 			}
  1261. 			return return_value;
  1262. 		}
  1264. 		const original_for_each_page = options?.for_each_page;
  1265. 		options = { ...options, for_each_page, get_list: options?.get_list || !original_for_each_page };
  1267. 		/**
  1268. 		 * @example <code>
  1269. 		
  1270. 		const page_list = await wiki.embeddedin(template_name, options);
  1271. 		await page_list.each((page_data) => { }, options);
  1272. 	
  1273. 		 * </code>
  1274. 		 */
  1275. 		const promise = Wikiapi_list.call(this, type, title, options)
  1276. 			.then((page_list) => {
  1277. 				// console.trace(page_list);
  1278. 				// console.trace(page_list.length, 'pages');
  1279. 				// console.trace(page_queue, resolve_queue);
  1280. 				if (resolve_queue) {
  1281. 					done = true;
  1282. 					while (resolve_queue.length > 0)
  1283. 						feed_page_data();
  1284. 				}
  1285. 				page_list.each = Wikiapi_for_each_page.bind(_this, page_list);
  1286. 				return page_list;
  1287. 			});
  1289. 		// Imperative code, for huge pages.
  1290. 		// 依照標準實作，會先執行一次 next()。之後待 for_each_page() 將此 betch 全 push 進 page_queue 後，再依序 call next()。因此 resolve_queue.length <= 1。
  1291. 		// @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols
  1292. 		promise[Symbol.asyncIterator] = () => {
  1293. 			resolve_queue = [];
  1295. 			return {
  1296. 				next() {
  1297. 					//console.trace(done, page_queue, resolve_queue);
  1298. 					if (done && page_queue.length === 0)
  1299. 						return { done };
  1300. 					return new Promise( /* executor */ function (resolve, reject) {
  1301. 						//console.trace(done, page_queue, resolve_queue);
  1302. 						// 依照標準實作， resolve_queue.length === 0。
  1303. 						resolve_queue.push(resolve);
  1304. 						feed_page_data();
  1306. 						if (waiting_resolve) {
  1307. 							// 可以繼續接收頁面資料了。
  1308. 							waiting_resolve();
  1309. 							waiting_resolve = null;
  1310. 						}
  1311. 					});
  1312. 				},
  1313. 				return() {
  1314. 					// e.g., break loop
  1315. 					page_queue.abort = done = true;
  1316. 					return { done };
  1317. 				},
  1318. 				throw(error) {
  1319. 					CeL.error('Wikiapi list TODO: Not yet tested');
  1320. 					page_queue.abort = done = true;
  1321. 					return { done };
  1322. 				}
  1323. 			};
  1324. 		};
  1326. 		return promise;
  1327. 	}
  1329. }
  1332. // --------------------------------------------------------
  1334. /**
  1335.  * @alias category_tree
  1336.  * @description Get structural category tree with sub-categories of <code>root_category</code>. This is powerful than categorymembers. Get sub-categories with {@link Wikiapi.KEY_subcategories}.
  1337.  *
  1338.  * @param {String} root_category	- category name
  1339.  * @param {Object} [options]		- options to run this function.
  1340.  *
  1341.  * @returns {Promise} Promise object represents {Array} category_tree.
  1342.  *
  1343.  * @example <caption>Checking if [[Category:Countries in North America]] including [[Mexico]].</caption>
  1344. // <code>
  1345. const enwiki = new Wikiapi('en');
  1346. const page_list = await enwiki.category_tree('Countries in North America', 1);
  1347. assert(page_list.some(page_data => page_data.title === 'United States'), 'list category tree: [[Category:Countries in North America]] must includes [[United States]]');
  1348. assert('Mexico' in page_list[Wikiapi.KEY_subcategories], 'list category tree: [[Category:Mexico]] is a subcategory of [[Category:Countries in North America]]');
  1349. // </code>
  1350.  *
  1351.  * @example <caption>Get all sub-categories of [[Category:Echinodermata]] with depth=2.</caption>
  1352. // <code>
  1353. const wiki = new Wikiapi('commons');
  1354. const all_sub_categories = (await wiki.category_tree('Echinodermata', { depth: 2, cmtype: 'subcat', get_flat_subcategories: true })).flat_subcategories;
  1355. // </code>
  1356.  *
  1357.  * @memberof Wikiapi.prototype
  1358.  */
  1359. function Wikiapi_category_tree(root_category, options) {
  1360. 	function Wikiapi_category_tree_executor(resolve, reject) {
  1361. 		const wiki = this[KEY_wiki_session];
  1362. 		// using wiki_API.prototype.category_tree
  1363. 		wiki.category_tree(root_category, (list, error) => {
  1364. 			if (error) {
  1365. 				reject(error);
  1366. 			} else {
  1367. 				resolve(list);
  1368. 			}
  1369. 		}, options);
  1370. 	}
  1372. 	return new Promise(Wikiapi_category_tree_executor.bind(this));
  1373. }
  1375. /**
  1376.  * export key for subcategory 子分類 used in {@link Wikiapi#category_tree}
  1377.  *
  1378.  * @example
  1379. // <code>
  1380. const KEY_subcategories = Wikiapi.KEY_subcategories;
  1381. // </code>
  1382.  */
  1383. Wikiapi.KEY_subcategories = wiki_API.KEY_subcategories;
  1385. // --------------------------------------------------------
  1387. /**
  1388.  * @alias search
  1389.  * @description search pages include <code>key</code>
  1390.  *
  1391.  * @param {String} key			- key to search
  1392.  * @param {Object} [options]	- options to run this function.
  1393.  *
  1394.  * @returns {Promise} Promise object represents {Array} page_list.
  1395.  *
  1396.  * @example <caption>search pages include key: 霍金</caption>
  1397. // <code>
  1398. const zhwikinews = new Wikiapi('zh.wikinews');
  1399. const page_list = await zhwikinews.search('"霍金"');
  1400. // </code>
  1401.  *
  1402.  * @memberof Wikiapi.prototype
  1403.  */
  1404. function Wikiapi_search(key, options) {
  1405. 	function Wikiapi_search_executor(resolve, reject) {
  1406. 		const wiki = this[KEY_wiki_session];
  1407. 		// using wiki_API.search
  1408. 		wiki.search(key, (list, error) => {
  1409. 			if (error) {
  1410. 				reject(error);
  1411. 			} else {
  1412. 				resolve(list);
  1413. 			}
  1414. 		}, options);
  1415. 	}
  1417. 	return new Promise(Wikiapi_search_executor.bind(this));
  1418. }
  1420. // --------------------------------------------------------
  1422. /**
  1423.  * @alias redirects_root
  1424.  * @description Get redirects target of <code>title</code>.
  1425.  * 
  1426.  * @param {String} title		- page title
  1427.  * @param {Object} [options]	- options to run this function
  1428.  *
  1429.  * @returns {Promise} Promise object represents {String} page title or {Object} page data
  1430.  *
  1431.  * @example <caption>Get redirects target of [[WP:SB]]</caption>
  1432. // <code>
  1433. const redirects_taregt = await enwiki.redirects_root('WP:SB', { get_page_data: true });
  1434. // </code>
  1435.  * 
  1436.  * @memberof Wikiapi.prototype
  1437.  */
  1438. function Wikiapi_redirects_root(title, options) {
  1439. 	function Wikiapi_redirects_root_executor(resolve, reject) {
  1440. 		// const wiki = this[KEY_wiki_session];
  1441. 		// using wiki_API.redirects_root
  1442. 		wiki_API.redirects_root(title, (_title, page_data, error) => {
  1443. 			if (error) {
  1444. 				reject(error);
  1445. 			} else if (options && options.get_page_data) {
  1446. 				page_data.query_title = title;
  1447. 				resolve(page_data);
  1448. 			} else {
  1449. 				resolve(_title);
  1450. 			}
  1451. 		}, this.append_session_to_options(options));
  1452. 	}
  1454. 	return new Promise(Wikiapi_redirects_root_executor.bind(this));
  1455. }
  1457. // --------------------------------------------------------
  1459. /**
  1460.  * @alias redirect_to
  1461.  * @description Get the page that <code>title</code> redirects to.
  1462.  * 
  1463.  * @param {String} title		- page title
  1464.  * @param {Object} [options]	- options to run this function
  1465.  *
  1466.  * @returns {Promise} Promise object represents {Array} redirect_list
  1467.  *
  1468.  * @example <caption>Get the page that [[WP:SB]] redirects to.</caption>
  1469. // <code>
  1470. const redirects_list = await enwiki.redirect_to('WP:SB');
  1471. // </code>
  1472.  * 
  1473.  * @memberof Wikiapi.prototype
  1474.  */
  1475. function Wikiapi_redirect_to(title, options) {
  1476. 	function Wikiapi_redirect_to_executor(resolve, reject) {
  1477. 		// const wiki = this[KEY_wiki_session];
  1478. 		// using wiki_API.redirect_to
  1479. 		wiki_API.redirect_to(title, (redirect_data, page_data, error) => {
  1480. 			if (error) {
  1481. 				reject(error);
  1482. 			} else {
  1483. 				//console.trace(redirect_data);
  1484. 				//console.trace(page_data);
  1485. 				resolve(page_data || redirect_data);
  1486. 			}
  1487. 		}, this.append_session_to_options(options));
  1488. 	}
  1490. 	return new Promise(Wikiapi_redirect_to_executor.bind(this));
  1491. }
  1493. // --------------------------------------------------------
  1495. /**
  1496.  * @alias redirects_here
  1497.  * @description Get all pages redirects to <code>title</code>.
  1498.  * 
  1499.  * @param {String} title		- page title
  1500.  * @param {Object} [options]	- options to run this function
  1501.  *
  1502.  * @returns {Promise} Promise object represents {Array} redirect_list
  1503.  *
  1504.  * @example <caption>Get all pages redirects to [[Wikipedia:Sandbox]]</caption>
  1505. // <code>
  1506. const redirects_list = await enwiki.redirects_here('Wikipedia:Sandbox');
  1507. // </code>
  1508.  * 
  1509.  * @memberof Wikiapi.prototype
  1510.  */
  1511. function Wikiapi_redirects_here(title, options) {
  1512. 	function Wikiapi_redirects_here_executor(resolve, reject) {
  1513. 		// const wiki = this[KEY_wiki_session];
  1514. 		// using wiki_API.redirects_here
  1515. 		wiki_API.redirects_here(title, (root_page_data, redirect_list, error) => {
  1516. 			if (error) {
  1517. 				reject(error);
  1518. 			} else {
  1519. 				//console.trace(root_page_data);
  1520. 				//console.trace(redirect_list);
  1521. 				//console.assert(!redirect_list || redirect_list === root_page_data.redirect_list);
  1522. 				resolve(redirect_list || root_page_data);
  1523. 			}
  1524. 		}, this.append_session_to_options({
  1525. 			// Making .redirect_list[0] the redirect target.
  1526. 			include_root: true,
  1527. 			...options
  1528. 		}));
  1529. 	}
  1531. 	return new Promise(Wikiapi_redirects_here_executor.bind(this));
  1532. }
  1534. // --------------------------------------------------------
  1536. /**
  1537.  * @alias register_redirects
  1538.  * @description register page alias. usually used for templates
  1539.  * 
  1540.  * @param {Array|String} page_title_list	- list of page titles
  1541.  * @param {Object} [options]				- options to run this function.
  1542.  *
  1543.  * @returns {Promise} Promise object represents the operations are done.
  1544.  *
  1545.  * @example <caption>Do something for categories embedded in template `template_name`.</caption>
  1546. // <code>
  1547. const wiki_session = new Wikiapi;
  1548. const redirect_target_page_data = await wiki_session.register_redirects(template_name, { namespace: 'Template' });
  1549. // Do NOT use `await wiki_session.embeddedin(template_name)`: `template_name` may redirect to redirect_target_page_data.title. We need all categories embedded in redirect_target_page_data.title, not just `template_name`.
  1550. const category_list = await wiki_session.embeddedin(redirect_target_page_data.title, { namespace: 'Category' });
  1551. await wiki_session.for_each_page(category_list, for_category);
  1552. // </code>
  1553.  *
  1554.  * @example <caption>Register template redirects and get tokens of the templates.</caption>
  1555. // <code>
  1556. const wiki_session = new Wikiapi;
  1557. // e.g., await wiki_session.register_redirects(['Section link', 'Broken anchors'], { namespace: 'Template' });
  1558. await wiki_session.register_redirects([template_name_1, template_name_2, template_name_3], { namespace: 'Template' });
  1560. // ...
  1562. const page_data = await wiki_session.page(page_title);
  1563. // {Array} parsed page content 頁面解析後的結構。
  1564. const parsed = page_data.parse();
  1566. parsed.each('Template:' + template_name_1, function (token, index, parent) {
  1567. 	// ...
  1568. });
  1570. parsed.each('template', function (token, index, parent) {
  1571. 	if (wiki_session.is_template(template_name_1, token)) {
  1572. 		// ...
  1573. 		return;
  1574. 	}
  1575. 	if (wiki_session.is_template(template_name_2, token)) {
  1576. 		// ...
  1577. 		return;
  1578. 	}
  1580. 	// alternative method:
  1581. 	switch (wiki_session.redirect_target_of(token)) {
  1582. 		case wiki_session.redirect_target_of(template_name_1):
  1583. 			break;
  1584. 		case wiki_session.redirect_target_of(template_name_2):
  1585. 			break;
  1586. 		case wiki_session.redirect_target_of(template_name_3):
  1587. 			break;
  1588. 	}
  1589. });
  1590. // </code>
  1591.  *
  1592.  * @memberof Wikiapi.prototype
  1593.  */
  1594. function Wikiapi_register_redirects(page_title_list, options) {
  1595. 	function Wikiapi_register_redirects_executor(resolve, reject) {
  1596. 		const wiki = this[KEY_wiki_session];
  1597. 		wiki.register_redirects(page_title_list, (redirect_list, error) => {
  1598. 			if (error) {
  1599. 				reject(error);
  1600. 			} else {
  1601. 				// console.trace( redirect_list);
  1602. 				resolve(redirect_list);
  1603. 			}
  1604. 		}, options);
  1605. 	}
  1607. 	return new Promise(Wikiapi_register_redirects_executor.bind(this));
  1608. }
  1610. // --------------------------------------------------------
  1612. /**
  1613.  * @alias upload
  1614.  * @description Upload specified local file to the target wiki.
  1615.  *
  1616.  * @param {Object} file_data	- Upload configurations.<br />
  1617.  * Warning: When you are update a file, only the file content will changed. The <code>comment</code> will only show in the file page. The <code>text</code>, ... till <code>categories</code> will <em>all ignored</em>. If you want to update the content of file page, please consider <code>Variable_Map</code> as mentioned in the sample code.<br />
  1618. {<br />
  1619. <ul>
  1620. <li><code>file_path</code>: string - Local path.</li>
  1621. <li><code>media_url</code>: string - URL path. Alternative to <code>file_path</code>.</li>
  1622. <li><code>comment</code>: string - Upload comment.</li>
  1624. <li><code>text</code>: string or {Object} - Either {String}wikitext to fill the file's page,<br />
  1625.  or {Object}parameters of <a href="https://commons.wikimedia.org/wiki/Template:Information" target="_blank">{{Information}}</a>:<br />
  1626. {<br />
  1627. <ul>
  1628. <li><code>description</code>: string - File description.</li>
  1629. <li><code>date</code>: date string - YYYY-MM-DD, e.g., <code>new Date()</code> || <code>'2021-01-01'</code>.</li>
  1630. <li><code>source_url</code>: string - Source where the file comes from, typically an URL.</li>
  1631. <li><code>author</code>: string - Author's name or username in wikicode, e.g., URL or <code>'[[User:Yoda|Yoda]]'</code>.</li>
  1632. <li><code>permission</code>: string - License and other usage limitations and warnings, e.g., <code>'{{cc-by-sa-2.5}}'</code>.</li>
  1633. <li><code>other_versions</code>: string - Wikicode links to files with very similar content or derived files.</li>
  1634. <li><code>other_fields</code>: string - Additional table fields added on the bottom of the template.</li>
  1635. </ul>
  1636. }
  1637. </li>
  1639. <li><code>license</code>: array of strings - License under which the file is uploaded, e.g., <code>['{{cc-by-sa-2.5}}']</code>.</li>
  1640. <li><code>additional_text</code>: string - Additional wikitext to place before <code>categories</code>.</li>
  1641. <li><code>categories</code>: array of strings - Categories for this file, e.g., <code>['[[Category:test images]]']</code>.</li>
  1643. <li><code>ignorewarnings</code>: boolean - Set to 1 will overwrite existing files.</li>
  1644. </ul>
  1645. }<br />
  1646. <br />
  1647. See <a href="https://github.com/kanasimi/CeJS/blob/master/application/net/wiki/edit.js" target="_blank">edit.js</a> and search for <q>file_data</q> for other <code>file_data</code> options.
  1648.  *
  1649.  * @returns {Promise} Promise object represents {String} result of MediaWiki API
  1650.  *
  1651.  * @example <caption><span id="example__Upload file / media">Upload file / media</span></caption>
  1652. // <code>
  1653. const wiki = new Wikiapi;
  1654. await wiki.login('user', 'password', 'test');
  1655. // Upload a local file directly:
  1656. //let result = await wiki.upload({ file_path: '/local/file/path', comment: '', text: '' || {description: '', ...} });
  1657. let result = await wiki.upload({
  1658. 	file_path: '/local/file/path', comment: '',
  1659. 	filename: 'Will set via .file_path or .media_url if not settled.',
  1660. 	description: '', date: new Date() || '2021-01-01', source_url: 'https://github.com/kanasimi/wikiapi', author: '[[User:user]]', permission: '{{cc-by-sa-2.5}}', other_versions: '', other_fields: '',
  1661. 	license: ['{{cc-by-sa-2.5}}'], categories: ['[[Category:test images]]'],
  1662. 	bot: 1, tags: "tag1|tag2",
  1663. 	// To overwrite existing file
  1664. 	ignorewarnings: 1,
  1665. });
  1666. // Upload file from URL:
  1667. result = await wiki.upload({ media_url: 'https://media.url/name.jpg', comment: '', text: '' });
  1668. // </code>
  1669.  *
  1670.  * @example <caption>Upload file and then update content of file page</caption>
  1671. // <code>
  1672. const wiki = new Wikiapi;
  1673. await wiki.login('user', 'password', 'test');
  1675. const variable_Map = new CeL.wiki.Variable_Map();
  1676. variable_Map.set('description', '...');
  1677. //variable_Map.set('date', '...');
  1678. // ...
  1679. //variable_Map.set('other_fields', '...');
  1681. let result = await wiki.upload({
  1682. 	file_path: '/local/file/path',
  1683. 	// The <code>comment</code> will only show in the file page when updating file. It is read-only and cannot be modified.
  1684. 	comment: '',
  1686. 	// <code>CeL.wiki.Variable_Map</code> is used to update content when update pages or files. It will insert comments around the value, prevent others from accidentally editing the text that will be overwritten.
  1687. 	// <code>description</code> till <code>other_fields</code> will be auto-setted as values assigned above.
  1688. 	// The code to do the conversion is in <code>wiki_API.upload</code> @ https://github.com/kanasimi/CeJS/blob/master/application/net/wiki/edit.js
  1689. 	// There are some examples: https://github.com/kanasimi/wikibot/blob/master/routine/20181016.import_earthquake_shakemap.js https://github.com/kanasimi/wikibot/blob/master/routine/20190629.import_hurricane_track_maps.js
  1690. 	// More examples to use <code>CeL.wiki.Variable_Map</code>: https://github.com/kanasimi/wikibot/blob/master/routine/20191129.check_language_convention.js
  1691. 	variable_Map,
  1692. 	// When set .variable_Map, after successful update, the content of file page will be auto-updated too.
  1694. 	// To overwrite existing file
  1695. 	ignorewarnings: 1,
  1696. });
  1697. // </code>
  1698.  *
  1699.  * @memberof Wikiapi.prototype
  1700.  */
  1701. function Wikiapi_upload(file_data) {
  1702. 	// 2021/3/25 renamed from old name: Wikiapi_upload_file(),
  1703. 	// Wikiapi_upload_file_executor()
  1704. 	function Wikiapi_upload_executor(resolve, reject) {
  1705. 		const wiki = this[KEY_wiki_session];
  1706. 		wiki.upload(file_data, (result, error) => {
  1707. 			if (error) {
  1708. 				reject(error);
  1709. 			} else {
  1710. 				resolve(result);
  1711. 			}
  1712. 		});
  1713. 	}
  1715. 	return new Promise(Wikiapi_upload_executor.bind(this));
  1716. }
  1718. // --------------------------------------------------------
  1720. /**
  1721.  * @alias download
  1722.  * @description Download file to local path.
  1723.  *
  1724.  * @param {String} file_title	- file title starts with "File:"
  1725.  * @param {Object} [options]	- options to run this function. Refer to example codes.
  1726.  *
  1727.  * @returns {Promise} Promise object represents [ {Object}file informations ]
  1728.  *
  1729.  * @example <caption>Download original file / media to current directory.</span></caption>
  1730. // <code>
  1731. const wiki = new Wikiapi('commons');
  1732. await wiki.download('File:Example.svg');
  1733. // </code>
  1734.  *
  1735.  * @example <caption>Download file / media with options</span></caption>
  1736. // <code>
  1737. const wiki = new Wikiapi('commons');
  1739. // Download non-vector version of .svg
  1740. await wiki.download('File:Example.svg', { width: 80 });
  1742. // Change width / height
  1743. await wiki.download('File:Example.png', {
  1744. 	file_name: 'example.png', directory: '/tmp/',
  1745. 	// reget and overwrite existed file.
  1746. 	reget: true,
  1747. 	width: 80,// height: 80
  1748. });
  1750. // Download all files from a (Commons) category and its subcategories WITH directory structure.
  1751. const file_data_list = await wiki.download('Category:name', {
  1752. 	directory: './',
  1753. 	max_threads: 4,
  1754. 	// depth of categories
  1755. 	depth: 4,
  1756. 	// Only download files with these formats.
  1757. 	//download_derivatives : ['wav', 'mp3', 'ogg'],
  1758. 	// Warning: Will skip downloading if there is no new file!
  1759. 	download_derivatives : 'mp3',
  1760. 	// A function to filter result pages. Return `true` if you want to keep the element.
  1761. 	page_filter(page_data) {
  1762. 		return page_data.title.includes('word');
  1763. 	}
  1764. });
  1766. // Download all files from a (Commons) category WITHOUT directory structure.
  1767. for (const page_data of await wiki.categorymembers('Category:name', { namespace: 'File' })) {
  1768. 	try {
  1769. 		//if (wiki.is_namespace(page_data, 'File'))
  1770. 		const file_data = await wiki.download(page_data, { directory: './' });
  1771. 	} catch (e) { console.error(e); }
  1772. }
  1773. // also
  1774. const categorymembers = await wiki.categorymembers('Category:name', { namespace: 'File' });
  1775. const file_data_list = await wiki.download(categorymembers, { directory: './', no_category_tree: true });
  1776. // </code>
  1777.  *
  1778.  * @memberof Wikiapi.prototype
  1779.  */
  1780. function Wikiapi_download(file_title, options) {
  1781. 	function Wikiapi_download_executor(resolve, reject) {
  1782. 		const wiki = this[KEY_wiki_session];
  1783. 		wiki.download(file_title, options, (result, error) => {
  1784. 			if (error) {
  1785. 				// return result.error_titles
  1786. 				reject(result && result.error_titles && result || error);
  1787. 			} else {
  1788. 				resolve(result);
  1789. 			}
  1790. 		});
  1791. 	}
  1793. 	return new Promise(Wikiapi_download_executor.bind(this));
  1794. }
  1796. // --------------------------------------------------------
  1798. /**
  1799.  * @alias for_each_page
  1800.  * @description Edit / process pages listing in <code>page_list</code>. Will get the content of multiple pages at once to save transmission times. 一次取得多個頁面內容，以節省傳輸次數。<br />
  1801.  * <b>You might be interested in {@link Wikiapi_list}</b>.
  1802.  * 
  1803.  * @param {Array} page_list			- title list or page_data list
  1804.  * @param {Function} for_each_page	- processor for each page. for_each_page(page_data with contents)
  1805.  * @param {Object} [options]		- options to run this function. Refer to example codes.
  1806.  *
  1807.  * @returns {Promise} Promise object represents the operations are done.
  1808.  *
  1809.  * @example <caption>read / edit multiple pages</caption>
  1810. // <code>
  1811. const enwiki = new Wikiapi('en');
  1812. const link_from = await wiki.redirects_here('ABC');
  1813. await wiki.for_each_page(link_from, page_data => {
  1814. 	// Return `Wikiapi.skip_edit` if you just want to get the page data.
  1815. 	return Wikiapi.skip_edit;
  1816. 	return 'You may also modify page contents for each page';
  1817. }, {
  1818. 	// The options below are sample, not default configuration.
  1820. 	// denotes we do not edit pages
  1821. 	no_edit: true,
  1823. 	// Only needed if you want to modify page.
  1824. 	summary: 'test edit',
  1825. 	// Allow content to be emptied. 允許內容被清空。白紙化。
  1826. 	allow_blanking: true,
  1827. 	// If the content is not changed, using `skip_nochange` will skip the actual edit. Otherwise, a null edit will be made.
  1828. 	skip_nochange: true,
  1829. 	tags: 'bot trial',
  1830. 	// prevent creating new pages
  1831. 	// Throw an error if the page doesn't exist.
  1832. 	// 若頁面不存在/已刪除，則產生錯誤。
  1833. 	nocreate: 1,
  1834. 	// denotes this is a bot edit. 標記此編輯為機器人編輯。
  1835. 	bot: 1,
  1836. 	minor: 1,
  1838. 	// options to get page revisions
  1839. 	page_options: { redirects: 1, rvprop: 'ids|content|timestamp|user' }
  1841. 	// <code>.for_each_page()</code> will generate a report. It can be written to the specified page.
  1842. 	log_to: 'log to this page',
  1843. 	// no warning messages on console. e.g., hide "wiki_API_page: No contents: [[title]]" messages
  1844. 	no_warning: true,
  1845. 	// no warning messages and debug messages on console
  1846. 	no_message: true,
  1847. 	// For `{{bots|optout=n1,n2}}`
  1848. 	notification_name: 'n1|n2',
  1849. });
  1850. // </code>
  1851.  *
  1852.  * @memberof Wikiapi.prototype
  1853.  */
  1854. function Wikiapi_for_each_page(page_list, for_each_page, options) {
  1855. 	function Wikiapi_for_each_page_executor(resolve, reject) {
  1856. 		options = typeof options === 'string' ? { summary: options } : CeL.setup_options(options);
  1858. 		const wiki = this[KEY_wiki_session];
  1859. 		const append_to_this = Array.isArray(for_each_page) && for_each_page[1];
  1860. 		if (Array.isArray(for_each_page))
  1861. 			for_each_page = for_each_page[0];
  1862. 		// console.trace(for_each_page);
  1863. 		const work_config = {
  1864. 			log_to: null,
  1865. 			no_message: options.no_edit,
  1867. 			...options,
  1869. 			//is_async_each: CeL.is_async_function(for_each_page),
  1870. 			each: [function each(page_data/* , messages, config */) {
  1871. 				// assert: arguments[2] === work_config && work_config === config
  1872. 				// assert: config.initial_target_length > 0
  1873. 				set_page_data_attributes(page_data, wiki);
  1875. 				return for_each_page.apply(this, arguments);
  1876. 			}, append_to_this],
  1877. 			// Run after all list items (pages) processed.
  1878. 			last(error) {
  1879. 				// this === options
  1880. 				// console.trace('last(error)');
  1881. 				// console.error(error);
  1882. 				// console.trace('Wikiapi_for_each_page_executor finish:');
  1883. 				// console.log(options);
  1885. 				// 提早執行 resolve(), reject() 的話，可能導致後續的程式碼 `options.last`
  1886. 				// 延後執行，程式碼順序錯亂。
  1887. 				if (typeof options.last === 'function')
  1888. 					options.last.call(this, error);
  1889. 				if (error) {
  1890. 					if (options.throw_error) {
  1891. 						reject(error);
  1892. 						return;
  1893. 					}
  1894. 					console.error(typeof error === 'object' ? error : new Error(error));
  1895. 				}
  1896. 				resolve(this);
  1897. 			}
  1898. 		};
  1899. 		//console.trace([ options, work_config, ]);
  1901. 		wiki.work(work_config, page_list);
  1902. 	}
  1904. 	return new Promise(Wikiapi_for_each_page_executor.bind(this));
  1905. }
  1908. // --------------------------------------------------------
  1910. /**
  1911.  * @alias convert_Chinese
  1912.  * @description convert text to traditional Chinese / simplified Chinese.
  1913.  * 
  1914.  * @param {String|Array|Object} text	- text or objects to convert. Will convert to {String} using JSON.stringify().
  1915.  * @param {Object} [options]			- options to run this function
  1916.  *
  1917.  * @returns {Promise} Promise object represents the converted text.
  1918.  *
  1919.  * @example <caption>繁簡轉換</caption>
  1920. // <code>
  1921. const wiki = new Wikiapi('en');
  1922. const converted_text = await wiki.convert_Chinese('中国', { uselang: 'zh-hant' });
  1923. const converted_text = await wiki.convert_Chinese('中國', { uselang: 'zh-hans' });
  1924. const converted_list = await wiki.convert_Chinese(['繁體', '簡體'], { uselang: 'zh-hans' });
  1925. // </code>
  1926.  * 
  1927.  * @memberof Wikiapi.prototype
  1928.  */
  1929. function Wikiapi_convert_Chinese(text, options) {
  1930. 	function Wikiapi_convert_Chinese(resolve, reject) {
  1931. 		if (typeof options === 'string') {
  1932. 			options = { uselang: options };
  1933. 		}
  1934. 		const site_name = this.site_name({ get_all_properties: true });
  1935. 		// node.js v12.22.7: Cannot use "?."
  1936. 		if (site_name && site_name.language === 'zh') {
  1937. 			// 不用再重新造出一個實體。
  1938. 			options = this.append_session_to_options(options);
  1939. 		}
  1941. 		// using wiki_API.search
  1942. 		wiki_API.convert_Chinese(text, (text, error) => {
  1943. 			if (error) {
  1944. 				reject(error);
  1945. 			} else {
  1946. 				resolve(text);
  1947. 			}
  1948. 		}, options);
  1949. 	}
  1951. 	return new Promise(Wikiapi_convert_Chinese.bind(this));
  1952. }
  1954. // --------------------------------------------------------
  1956. // May only test in the [https://tools.wmflabs.org/ Wikimedia Toolforge]
  1957. function Wikiapi_run_SQL(SQL, for_each_row/* , options */) {
  1958. 	function Wikiapi_run_SQL_executor(resolve, reject) {
  1959. 		const wiki = this[KEY_wiki_session];
  1960. 		function run_callback() {
  1961. 			wiki.SQL_session.SQL(SQL, (error, rows/* , fields */) => {
  1962. 				if (error) {
  1963. 					reject(error);
  1964. 				} else {
  1965. 					rows.forEach(for_each_row);
  1966. 				}
  1967. 			});
  1968. 			resolve();
  1969. 		}
  1970. 		if (wiki.SQL_session) {
  1971. 			run_callback();
  1972. 			return;
  1973. 		}
  1974. 		wiki.SQL_session = new wiki_API.SQL((error, rows, fields) => {
  1975. 			if (error) {
  1976. 				reject(error);
  1977. 			} else {
  1978. 				run_callback();
  1979. 			}
  1980. 		}, wiki);
  1981. 	}
  1983. 	return new Promise(Wikiapi_run_SQL_executor.bind(this));
  1984. }
  1986. // --------------------------------------------------------
  1988. /**
  1989.  * @alias setup_layout_element_to_insert
  1990.  * @description Setup layout element to insert before  insert layout element.
  1991.  * 
  1992.  * @example <caption>insert layout element</caption>
  1993. // <code>
  1994. const layout_element = CeL.wiki.parse('{{Authority control}}');
  1995. await wiki_session.setup_layout_element_to_insert(layout_element);
  1997. const page_data = await wiki.page(page_data);
  1998. const parsed = page_data.parse();
  1999. parsed.insert_layout_element(layout_element);
  2000. parsed.toString();
  2001. // </code>
  2002.  *
  2003.  * @memberof Wikiapi.prototype
  2004.  */
  2005. function Wikiapi_setup_layout_element_to_insert(layout_element, options) {
  2006. 	function Wikiapi_setup_layout_element_to_insert_executor(resolve, reject) {
  2007. 		const wiki = this[KEY_wiki_session];
  2008. 		wiki.setup_layout_element_to_insert(layout_element, (location, error) => {
  2009. 			if (error)
  2010. 				reject(error);
  2011. 			else
  2012. 				resolve(location);
  2013. 		}, options);
  2014. 	}
  2016. 	return new Promise(Wikiapi_setup_layout_element_to_insert_executor.bind(this));
  2017. }
  2019. // --------------------------------------------------------
  2021. /**
  2022.  * @alias get_featured_content
  2023.  * @description Get featured content.
  2024.  * 
  2025.  * @param {String|Object} [options]	- options to run this function.
  2026.  *            {String}type (FFA|GA|FA|FL)
  2027.  *            || {type,on_conflict(FC_title, {from,to})}
  2028.  *
  2029.  * @returns {Promise} Promise object represents {Object} featured content data hash
  2030.  *
  2031.  * @example <caption>Get featured content of current wiki site.</caption>
  2032. // <code>
  2033. // MUST including wiki.featured_content first to get featured content!
  2034. CeL.run('application.net.wiki.featured_content');
  2036. // ...
  2038. const FC_data_hash = await wiki.get_featured_content();
  2039. console.assert(FC_data_hash === wiki.FC_data_hash);
  2040. // </code>
  2041.  * 
  2042.  * @memberof Wikiapi.prototype
  2043.  */
  2044. function Wikiapi_get_featured_content(options) {
  2045. 	if (!options || !options.type) {
  2046. 		const session = this;
  2047. 		return Wikiapi_get_featured_content.default_types
  2048. 			.reduce((promise, type) => promise.then(Wikiapi_get_featured_content.bind(session, { ignore_missed: true, ...options, type, })), Promise.resolve());
  2049. 		if (false) {
  2050. 			let promise = Promise.resolve();
  2051. 			Wikiapi_get_featured_content.default_types.forEach(type => {
  2052. 				promise = promise.then(Wikiapi_get_featured_content.bind(session, { ...options, type }));
  2053. 			});
  2054. 			return promise;
  2055. 		}
  2056. 	}
  2058. 	function Wikiapi_get_featured_content_executor(resolve, reject) {
  2059. 		const wiki = this[KEY_wiki_session];
  2060. 		wiki.get_featured_content(options, FC_data_hash => {
  2061. 			try {
  2062. 				this.FC_data_hash = FC_data_hash;
  2063. 				resolve(FC_data_hash);
  2064. 			} catch (e) {
  2065. 				reject(e);
  2066. 			}
  2067. 		});
  2068. 	}
  2070. 	return new Promise(Wikiapi_get_featured_content_executor.bind(this));
  2071. }
  2073. Wikiapi_get_featured_content.default_types = 'FFA|GA|FA|FL'.split('|');
  2075. // --------------------------------------------------------
  2077. /**
  2078.  * @alias site_name
  2079.  * @description Get site name / project name of this {@link Wikiapi} instance.
  2080.  * 
  2081.  * @param {String} [language]	- language code of wiki session
  2082.  * @param {Object} [options]	- options to run this function
  2083.  *
  2084.  * @returns {String}site name
  2085.  * 
  2086.  * @example <caption>Get site name of {@link Wikiapi} instance.</caption>
  2087. // <code>
  2088. console.log(Wikiapi.site_name('zh', { get_all_properties: true }));
  2090. const wiki = new Wikiapi('en');
  2091. console.assert(wiki.site_name() === 'enwiki');
  2092. console.log(wiki.site_name({ get_all_properties: true }));
  2093. console.assert(wiki.site_name({ get_all_properties: true }).language === 'en');
  2094. // </code>
  2095.  * 
  2096.  * @memberof Wikiapi.prototype
  2097.  */
  2098. function Wikiapi_site_name(language, options) {
  2099. 	return wiki_API.site_name(language, options);
  2100. }
  2102. Wikiapi.site_name = Wikiapi_site_name;
  2104. // --------------------------------------------------------
  2105. // administration functions 管理功能。
  2107. /**
  2108.  * @alias delete
  2109.  * @description delete page
  2110.  *
  2111.  * @param {String} title		- page title
  2112.  * @param {Object} [options]	- options to run this function
  2113.  *
  2114.  * @returns {Promise} Promise object represents response of delete.
  2115.  *
  2116.  * @example <caption>delete page [[Page to delete]]</caption>
  2117. // <code>
  2118. const testwiki = new Wikiapi('test');
  2119. await testwiki.delete('Page to delete', { reason: 'test' });
  2120. // { title: 'Page to delete', reason: 'test', logid: 00000 }
  2121. // </code>
  2122.  *
  2123.  * @memberof Wikiapi.prototype
  2124.  */
  2125. function Wikiapi_delete(title, options) {
  2126. 	function Wikiapi_delete_executor(resolve, reject) {
  2127. 		const wiki = this[KEY_wiki_session];
  2128. 		// using wiki_API.delete
  2129. 		wiki.page(title).delete(options, (response, error) => {
  2130. 			if (error) {
  2131. 				reject(error);
  2132. 			} else {
  2133. 				resolve(response);
  2134. 			}
  2135. 		}, options);
  2136. 	}
  2138. 	return new Promise(Wikiapi_delete_executor.bind(this));
  2139. }
  2141. // --------------------------------------------------------
  2142. // exports
  2144. Object.assign(Wikiapi.prototype, {
  2145. 	append_session_to_options(options) {
  2146. 		// Object.assign({ [KEY_SESSION]: wiki }, options)
  2147. 		// return { ...options, [KEY_SESSION]: this[KEY_wiki_session] };
  2148. 		return wiki_API.add_session_to_options(this[KEY_wiki_session], options);
  2149. 	},
  2151. 	site_name(options) {
  2152. 		return Wikiapi_site_name(this[KEY_wiki_session], options);
  2153. 	},
  2154. 	login: Wikiapi_login,
  2156. 	query: Wikiapi_query,
  2157. 	page: Wikiapi_page,
  2158. 	tracking_revisions: Wikiapi_tracking_revisions,
  2159. 	edit_page: Wikiapi_edit_page,
  2160. 	/**
  2161. 	 * @description edits content of target page.<br />
  2162. 	 * <em>MUST using directly after {@link Wikiapi#page} without any complicated operation! Or rather, the {@link Wikiapi#edit_page} should be used instead.</em><br />
  2163. 	 * Note: for multiple pages, you should use {@link Wikiapi#for_each_page}.<br />
  2164. 	 * Note: The function will check sections of [[User talk:user name/Stop]] if somebody tells us needed to stop edit. See <a href="https://en.wikipedia.org/wiki/User:Cewbot/Stop">mechanism to stop operations</a>.
  2165. 	 * 
  2166. 	 * @param {String|Function} content	- 'wikitext page content' || page_data => 'wikitext'
  2167. 	 * @param {Object} [options]		- options to run this function. e.g., { summary: '', bot: 1, nocreate: 1, minor: 1 }
  2168. 	 * 
  2169. 	 * @returns {Promise} Promise object represents {Object} result of MediaWiki API
  2170. 	 *
  2171. 	 * @memberof Wikiapi.prototype
  2172. 	 */
  2173. 	edit(content, options) {
  2174. 		return this.edit_page(null, content, options);
  2175. 	},
  2176. 	move_to: Wikiapi_move_to,
  2177. 	move_page: Wikiapi_move_page,
  2178. 	purge: Wikiapi_purge,
  2180. 	/**
  2181. 	 * @description Find comment by talk page title and anchor.
  2182. 	 * 
  2183. 	 * @example <code>
  2185. 	const comment_list = await wiki.find_comment(token);
  2187. 	</code>
  2188. 	 * 
  2189. 	 * @param {String|Array}talk_page_and_anchor
  2190. 	 *            talk page and anchor: "title#anchor" | [title,anchor]
  2191. 	 * @param {Object}[options]
  2192. 	 *            附加參數/設定選擇性/特殊功能與選項
  2193. 	 * 
  2194. 	 * @returns {Promise|Undefined} resolve({Array}comment_list)
  2195. 	 * 
  2196. 	 * @memberof Wikiapi.prototype
  2197. 	 */
  2198. 	find_comment(talk_page_and_anchor, options) {
  2199. 		const wiki = this[KEY_wiki_session];
  2200. 		return wiki.find_comment.apply(wiki, arguments);
  2201. 	},
  2203. 	/**
  2204. 	 * @description Listen to page modification. 監視最近更改的頁面。<br />
  2205. 	 * wrapper for {@link wiki_API}#listen
  2206. 	 *
  2207. 	 * @param {Function} listener	- function(page_data) { return quit_listening; }
  2208. 	 * @param {Object} [options]	- options to run this function. e.g., { summary: '', bot: 1, nocreate: 1, minor: 1 }
  2209. 	 *
  2210. 	 * @example <caption>listen to new edits</caption>
  2211. // <code>
  2212. const wiki = new Wikiapi;
  2213. wiki.listen(function for_each_row() {
  2214. 	// ...
  2215. }, {
  2216. 	// 檢查的延遲時間。
  2217. 	delay: '2m',
  2218. 	filter: function filter_row(row) {
  2219. 		// The format of `row` is basically the same as page_data.
  2220. 	},
  2221. 	// also get diff
  2222. 	with_diff: { LCS: true, line: true },
  2223. 	// only for articles (0:main namespace) and talk pages
  2224. 	namespace: '0|talk',
  2225. });
  2226. // </code>
  2227. 	 *
  2228. 	 * @memberof Wikiapi.prototype
  2229. 	 */
  2230. 	listen(listener, options) {
  2231. 		const wiki = this[KEY_wiki_session];
  2232. 		wiki.listen(listener, options);
  2233. 	},
  2235. 	category_tree: Wikiapi_category_tree,
  2236. 	search: Wikiapi_search,
  2238. 	redirects_root: Wikiapi_redirects_root,
  2239. 	redirect_to: Wikiapi_redirect_to,
  2240. 	// Warning: 採用 wiki_API.redirects_here(title) 才能追溯重新導向的標的。
  2241. 	// wiki.redirects() 無法追溯重新導向的標的！
  2242. 	redirects_here: Wikiapi_redirects_here,
  2243. 	register_redirects: Wikiapi_register_redirects,
  2245. 	upload: Wikiapi_upload,
  2246. 	download: Wikiapi_download,
  2248. 	get_featured_content: Wikiapi_get_featured_content,
  2250. 	for_each_page: Wikiapi_for_each_page,
  2252. 	for_each_page_in_list: Wikiapi_for_each_page_in_list,
  2254. 	delete: Wikiapi_delete,
  2256. 	data: Wikiapi_data,
  2257. 	new_data_entity: Wikiapi_new_data_entity,
  2258. 	SPARQL: Wikiapi_SPARQL,
  2260. 	convert_Chinese: Wikiapi_convert_Chinese,
  2262. 	run_SQL: Wikiapi_run_SQL,
  2264. 	setup_layout_element_to_insert: Wikiapi_setup_layout_element_to_insert,
  2265. });
  2267. // wrapper for properties
  2268. for (const property_name of ('task_configuration|latest_task_configuration').split('|')) {
  2269. 	Object.defineProperty(Wikiapi.prototype, property_name, {
  2270. 		get() {
  2271. 			const wiki = this[KEY_wiki_session];
  2272. 			return wiki[property_name];
  2273. 		}
  2274. 	});
  2275. }
  2277. module.exports = Wikiapi;
  2279. // export default Wikiapi;