Модуль:Escape/документація

Використання

Цей модуль розроблений з метою забезпечення екранування рядків налаштовувальним і ефективним способом. Він працює за допомогою заміни символів, що передують вашому символу (або фразі) екранування. Є два варіанти виклику цього модуля:

З іншого модуля:

local esc = require('Module:Escape')
esc:char(символ (або послідовність символів) екранування)
local to_escape = esc:text(рядок)
код, що замінює або видаляє неекрановані символи
local result = esc:undo(to_escape)

З шаблону:

{{invoke:Escape|main|mode=функція|char=символ (або послідовність символів) екранування|текст}}

В шаблоні, найкориснішою функцією є kill.

Цей модуль в основному призначений для використання в інших модулях. Однак, всі функції можуть бути викликані в просторі шаблону, використовуючи |mode=функція, яку ви хочете викликати після чого йдуть аргументи функції.

Усі функції модуля (тобто будь-яка функція крім main()) повинні бути викликані через використання дві крапки (:), наприклад, esc:char('%') або esc:kill{'{{example|\\}}}', '}'} == '{{example|}'

escape:text() escape:text()	Ця функція приймає лише один аргумент: Рядок. Усі символи в цьому рядку, що передують набору послідовності в escape:char(), будуть замінені на символи-заповнювачі (placeholders), що можуть бути перетворені назад в ті символи функцією escape:undo()
escape:undo() escape:undo()	Приймає два аргументи: Рядок, що може містити символи-заповнювачі, що встановленні функцією escape:text() Додатково, символ, що буде розміщено попереду будь-якого символу, що було виведено з екранування. (тобто, якщо ви хочете повторно екранувати ці рядки з іншими символами)
escape:kill() escape:kill()	Це, в основному, відповідає виклику string.gsub() над рядком, який повернула функція escape:text(), та передача цього результату в функцію escape:undo() в один етап. Приймає три аргументи: Рядок Послідовність символів, що будуть вилучені з рядка. (Може використовувати шаблони string.gsub) Додатково, символ, що буде розміщено попереду будь-якого символу, що було виведено з екранування.
escape:char() escape:char()	Основне використання цієї функції є ініціалізація шаблонів для пошуку рядка на наявність послідовності екранування. Вона приймає два аргументи, першим є символ екранування, а другий — таблиця аргументів (додатково). Стандартно, цей модуль використовує \ як символ екранування. Щоб замінити символ екранування на {, ви можете зробити require('Module:Escape'):char('{') (або esc:char('{') (припускаючи, що ви зберігаєте таблицю, повернути цим модулем, в локальній змінній esc). Коли викликається без другого аргументу, то char() поверне таблицю, що мітить функції. Це дозволяє наступне: наприклад, escape:char('*'):kill('1*23', '%d'), що поверне «2». Для більшості випадків, мало причин, щоб встановлювати |mode= в просторі шаблону, бо патерни, які він зберігає, не використовуються з іншими викликами цього модуля. Натомість шаблони повинні використовувати |char=, якщо потрібно нова послідовність екранування. Скорочення Якщо надано другий аргумент, який є таблицею, що містить пару {ключ = значення}, де ключ є text, undo або kill, а значення є таблицею з аргументами, які були б передані цим функціям, то можна використати скорочення. Наприклад, escape:char('\\', {text = 'string'}) відповідає escape:char('\\'):text('string'). Зверніть увагу, що якщо надано кілька пар ключ—значення, то лише один можна буде виконати. kill буде проігноровано, якщо наявно text або undo. undo буде проігноровано, якщо наявно text.

Застереження

• Коли використовується послідовність екранування, що складається з кількох символів, то цей модуль лише позначає їх, використовуючи байтове значення першого символу. Тому, escape:undo() виведе з екранування, наприклад, всі символи, що екрановані через «e» та «esc», якщо використано обидві послідовності. На практиці, однак це не є проблемою, бо кілька послідовностей екранування є дуже рідкісним випадком, окрім, коли ви переходите між кількома мовними кодами. (У будь-якому разі, кілька послідовностей екранування з кількох символів, що починаються з одного символу, є просто поганою практикою .)
• Через те, що байтові значення зберігаються як числа, то не рекомендуються використовувати числа як послідовність екранування (хоча вони можуть нормально працювати).
• Байтові значення заповнювачів розділяються символами повернення ('\r'), які вибрані, тому, що вони взагалі рідко використовуються, та практично ніколи не використовують окремо від '\n'; до того ж він відрізняється від маркерів, що створюються <nowiki>...</nowiki> або mw.text.nowiki() (які використовують символ видалення). Щоб встановити інший символ розділення, то включіть пару ключ—значення {safeChr = альтернативний символ} в таблиці, що ви передаєте до escape:char().

Швидкість

Нижче наведено тести продуктивності...

коли виконується наступна функція модуля:

 function p.test_kill500(frame)
  local esc = require('Module:Escape')
  for k = 1, 500 do
   local v = esc:kill(p.test_string2(), 'test')
  end
  return os.clock(esc)
 end

0.05882

коли повторюється наступний рядок 500 разів у шаблоні:

{{#invoke:Escape|main|mode=kill|{{#invoke:Escape/тести|test_string2}}|test}}

0.767

Весь час в секундах. Час тесту (x500) з модулем обраховується, коли ви завантажує цю сторінку документації (зазвичай, результат між 0.02 та 0.07). Час тесту (x500) з шаблоном був записаний 15 січня 2015 в англійській Вікіпедії.

Приклади

Шаблон

Оригінал:

test { test {\{ test, \test, \{,test\ \ \ {\

Використовуючи внутрішній метод для видалення {:

{{#invoke:Escape|main|mode=kill|test { test {\{ test, \test, \{,test\ \ \ {\|{}}test test { test, test, {,test \

Використовуючи {{replace}} для видалення {:

{{#invoke:Escape|main|mode=undo|{{replace|{{#invoke:Escape|main|mode=text|test { test {\{ test, \test, \{,test\ \ \ {\}}|{|}}}}test test { test, test, {,test \

Без видалення { між екранованою/неекранованою (символ екранування не відновлено) частиною:

{{#invoke:Escape|main|mode=undo |{{#invoke:Escape|main|mode=text|test { test {\{ test, \test, \{,test\ \ \ {\}} }}test { test {{ test, test, {,test {\

Відновлення до оринігалу пілся екранування

{{#invoke:Escape|main|mode=undo |{{#invoke:Escape|main|mode=text|test { test {\{ test, \test, \{,test\ \ \ {\}} |\ }}test { test {\{ test, \test, \{,test\ \ \ {\

Видалення слова test, якщо воно не екрановане, а потім розміщення іншого символу екранування на місці старого символу екранування (для використання чогось іншого):

Зверніть увагу: Символ '%' є спеціальним в Lua, тому використовуйте '%%', якщо хочете його використати як символ екранування. В інших випадках, достатньо одного символа (чи слова). {{#invoke:Escape|main|mode=kill |test { test {\{ test, \test, \{,test\ \ \ {\ |test |%% }} { {%{ , %test, %{,% % % {\

Модуль

Ось декілька прикладів виводу з консолі налагодження під редактором модуля:

local escape = require('Module:Escape') test = 'test, \\test, \\{,test\\\\ \\\\ \\\\\\\\' test2 = escape:char('{'):text(test) =test2 test, \test, \7b 044 7btest\\ \\ \\\\ test3 = escape:char('\\'):text(test2) =test3 test, 5c 0116 5cest, 5c 055 5cb 044 7btest5c 092 5c 5c 092 5c 5c 092 5c5c 092 5c test4 = escape:char('{', {undo = test3}) =test4 test, 5c 0116 5cest, 5c 055 5cb 044 7btest5c 092 5c 5c 092 5c 5c 092 5c5c 092 5c test4 = escape:char('\\', {undo = test3}) =test4 test, test, 7b 044 7btest\ \ \\ test5 = escape:char('{', {undo = test4}) =test5 == test true =escape:undo(test3)--не працює, бо символ екранування досі встановлено як '{' в поточній сесії test, 5c 0116 5cest, 5c 055 5cb 044 7btest5c 092 5c 5c 092 5c 5c 092 5c5c 092 5c =escape:undo(test4) test, \test, \,test\\ \\ \\\\ =escape:char('\\'):undo(test3) test, test, 7b 044 7btest\ \ \\ =escape:char('{', {undo = escape:char('\\'):undo(test3)}) test, test, {,test\ \ \\ =test == escape:char('{', {undo = escape:char('\\'):undo(test3)}) false =test == escape:char('{', {undo = escape:char('\\'):undo(test3, '\\')}) true local t = 'test { test {\\{ test, \\test, \\{,test\\ \\ \\ {\\' =t test { test {\{ test, \test, \{,test\ \ \ {\ local e = require('Module:Escape') local t2 = escape:text(t) local t3 = string.gsub(t2, '{', ) local t4 = escape:undo(t3) =t4 test test { test, test, {,test \ local tk0 = escape:kill(t, '{') =tk0 == t4 true