نمایش مبدأ برای ویکی‌پدیا:لوآ

{{سرساز ویکی‌پروژه لوآ}}
{{صفحه اطلاعات|وپ:لوآ}}
{{جعبه فضای نام}}
[[لوآ (زبان برنامه‌نویسی)|لوآ]] یک زبان برنامه‌نویسی است که در مدیاویکی، افزونه [[mw:Extension:Scribunto|اسکریبونتو]] امکان استفاده از کدهای نوشته شده به آن را فراهم می‌کند. این امکان در ویکی‌پدیای فارسی نیز در دسترس است. کد لوآ را می‌توان داخل الگوهای ویکی با قابلیت اسکریبونتو بدین شکل «<nowiki>{{#invoke:}}</nowiki>» جاسازی کرد. این افزونه از لوآ ۵٫۱ {{از تاریخ|lc=y|2015|07}} پشتیبانی می‌کند.

[[کد منبع]] لوآ درون صفحاتی که به آنها پودمان می‌گوییم (مانند [[پودمان:Bananas]]) ذخیره می‌شود. این پودمان‌های منحصربه‌فرد سپس با کد <code><nowiki>{{#invoke:}}</nowiki></code> در صفحات الگو فراخوانی می‌شوند (مانند [[پودمان:Bananas/توضیحات]] از کد <code><nowiki>{{#invoke:Bananas|hello}}</nowiki></code> برای چاپ متن «سلام، دنیا!» استفاده می‌کند).

== اجرای پودمان ==
پودمان‌ها روی صفحه‌های عادی ویکی با تابع تجزیه‌کننده #invoke اجرا می‌شوند. سینتکس #invoke مشابه سینتکس الگو است، اما تفاوت‌هایی هم دارد. مهم‌ترین تفاوت این است که شما باید ''اسم یک تابع'' را مشخص کنید. تابع مجموعه‌ای از دستورالعمل‌ها و فرمان‌ها است که مقادیر ورودی می‌پذیرد، آنها را پردازش می‌کند و یک مقدار خروجی برمی‌گرداند.<ref>شما همچنین می‌توانید چندین مقدار خروجی داشته باشید، اما توابعی که اینکار را می‌کنند به‌طور عادی در صفحه‌های ویکی استفاده نمی‌شوند.</ref> درست مثل یک الگو: شما آرگومان می‌دهید، الگو آنها را پردازش می‌کند و یک نتیجه به شما برمی‌گرداند. البته شما می‌توانید چندین تابع در یک پودمان لوآ تعریف کنید درحالی که فقط یک الگو در یک صفحه تعریف می‌شود.

علاوه بر این، شما نمی‌توانید پودمان لوآ را مستقیماً اجرا کنید - فقط می‌توانید یکی از توابع پودمان را اجرا کنید. پودمان فقط نگهدارنده توابع است و کار خاصی انجام نمی‌دهد. پس دو دلیل هست که باید نام یک تابع را وارد کنیم: نمی‌توانیم خود پودمان را اجرا کنیم و دوم اینکه بدون مشخص کردن نام یک تابع، لوآ نخواهد فهمید کدام تابع را باید اجرا کند.

ساده‌ترین راه اجرای پودمان از صفحهٔ ویکی این شکلی است:

 &#123;{#invoke:''نام پودمان''|''نام تابع''}}

برای مثال، [[پودمان:Bananas]] را می‌توانیم به این شکل اجرا کنیم، که یک تابع به اسم «hello» دارد.
* <code><nowiki>{{#invoke:Bananas|hello}}</nowiki></code> → {{#invoke:Bananas|hello}}

=== استفاده از آرگومان‌ها ===
آرگومان همان‌طور که به الگوها ارسال می‌شود به پودمان نیز فرستاده می‌شود. توجه کنید که تنها تفاوت در این است که اولین آرگومان بعد از اولین کاراکتر {{!}} نام تابع است.

 &#123;{#invoke:''نام پودمان''|''نام تابع''|''اولین آرگومان''|''دومین آرگومان''|''آرگومان نام‌دار'' = ''مقدار''}}

برای مثال، در [[پودمان:BananasArgs]]، تابع «hello» به افراد گوناگون بسته به اولین آرگومان سلام می‌کند. این پودمان اینطوری کار می‌کند:
* <span dir=ltr><code><nowiki>{{#invoke:BananasArgs|hello|علیرضا}}</nowiki></code></span> ← {{#invoke:BananasArgs|hello|علیرضا}}
* <span dir=ltr><code><nowiki>{{#invoke:BananasArgs|hello|آتنا}}</nowiki></code></span> ← {{#invoke:BananasArgs|hello|آتنا}}

BananasArgs همچنین تابعی به اسم «count_fruit» دارد که از آرگومان‌های نام‌دار <code>bananas</code> و <code>apples</code> برای شمارش مقدار موزها و سیب‌هایی که داریم استفاده می‌کند. این پودمان اینطوری کار می‌کند:
* <span dir=ltr><code><nowiki>{{#invoke:BananasArgs|count_fruit|apples=3|bananas=4}}</nowiki></code></span> ← {{#invoke:BananasArgs|count_fruit|apples=3|bananas=4}}
* <span dir=ltr><code><nowiki>{{#invoke:BananasArgs|count_fruit|bananas=5|apples=2}}</nowiki></code></span> ← {{#invoke:BananasArgs|count_fruit|bananas=5|apples=2}}

بیشتر پودمان‌ها صفحهٔ مستنداتی دارند که آرگومان‌هایی که می‌توان استفاده کرد و تأثیر و استفاده‌شان را توضیح می‌دهد.

== نمونه پودمان‌ها ==
* [[پودمان:Bananas]]: ساده‌ترین اسکریپت ممکن، یک تابع بدون آرگومان را ارائه می‌کند.
* [[پودمان:BananasArgs]]: نشان می‌دهد چطور به پارامترها دسترسی و از آنها استفاده کنیم.

== درخواست اسکریپت ==
از '''[[ویکی‌پدیا:لوآ درخواست‌ها]]''' برای درخواست کمک در نوشتن یک اسکریپت لوآ تا اجرای وظیفه‌ای مشخص در ویکی‌پدیا یا دیگر پروژه بنیاد ویکی‌مدیا دیدن کنید.

== تاریخچه ==
اول از الگوی [[w:en:Template:qif|qif]] شروع شد، بعد [[mw:Help:Extension:ParserFunctions|توابع تجزیه‌گر (ParserFunctions)]] به ویکی افزوده شدند و پس از آن افزونهٔ [[mw:Extension:Lua|Lua]]، بعد بر روی اینکه زبان اسکریپتی ویکی جاوااسکریپت باشد یا لوآ مناقشه پیش آمد، بعد افزونهٔ [[mw:Extension:WikiScripts|WikiScripts]] ایجاد شد، و درنهایت [[mw:User:Tim Starling|Tim Starling]] افزونهٔ [[mw:Extension:Scribunto|Scribunto]] را با پشتیبانی اولیه از زبان لوآ ساخت. بعد از سال‌ها بحث، لوآ در سال ۲۰۱۲ برای آزمایش در [[test2wiki:|test2.wikipedia.org]] نصب شد، و از کاربران برای آزمایش آن از طریق ساخت پودمان‌های لوآ دعوت شد. بعد از آزمایش در mediawiki.org و دیگر ویکی‌های آزمایش ویکی‌مدیا، لوآ در فوریهٔ ۲۰۱۳ در همهٔ ویکی‌پدیاها فعال شد.

== دربارهٔ لوآ ==
:''همچنین ببینید [[:پرونده:WMF Tech Talk 2013-02-28 slides - Scribunto presentation.pdf|ارائه کوتاه براد جرش از نمونهٔ ساده چگونگی تبدیل الگوی ویکی‌متن به پودمان لوآ (پی‌دی‌اف، انگلیسی)]]''

لوآ یک [[پردازه‌نویسی|زبان اسکریپتی]] است که در آن می‌توان توابع یا [[برنامه‌نویسی شیءگرا]] را برای تحلیل داده‌ها، محاسبات، و قالب‌بندی نتایج به کار برد.

یکی از مهم‌ترین عبارت‌هایی که باعث کندتر عمل کردن الگوهای ویکی‌پدیا می‌شود دستور <code><nowiki>{{#switch:}}</nowiki></code> است که در هر صفحه‌ای معمولاً چندین بار فراخوانی می‌شود. با استفاده از جداول لوآ می‌توان به شدت بر کارایی این جستجوها افزود و تقریباً به درجهٔ پیچیدگی {{چر}}O(1){{چر}} دست یافت، این داده‌ها — حتی اگر چندین بار پودمان لوآ فراخوانی شده باشد — تنها یک بار فراخوانی می‌شوند. در یک آزمایش تبدیل یک دستور switch با ۱۵۰ آرگومان به یک پودمان لوآ باعث شد حدود ۵۰٪ در زمان تجزیهٔ صفحه صرفه‌جویی شود.<ref>{{یادکرد وب|نویسنده=Lua|عنوان=Lua templating/Converting Wikitext templates|وبگاه=Wikia Developers Wiki|تاریخ=2012-03-14|سال=2012|پیوند=http://dev.wikia.com/wiki/Lua_templating/Converting_Wikitext_templates|کد زبان=en|تاریخ بازبینی=2014-10-26}}‏</ref>

== آزمایش واحد ==
چارچوب آزمایش واحد برای اسکریپت‌های لوآ در ویکی‌پدیا با [[پودمان:UnitTests]] دردسترس است. این پودمان کمک می‌کند اسکریپت را با مجموعه‌ای از مقادیر ورودی اجرا کنیم و نهایتاً اعتبارسنجی کنیم که خروجی همان مقادیر مورد نظرمان باشد.
آزمایش‌های واحد بیشتر برای تشخیص پسرفت‌ها کاربرد کارد، و پسرفت‌ها همان تغییراتی هستند که به یک اسکریپت می‌دهیم و باعث مشکلات جدید یا قدیمی می‌شود.

بر اساس قرارداد، آزمایش‌های واحد برای پودمانی مثل [[پودمان:Bananas]] در زیرصفحهٔ [[پودمان:Bananas/testcases]] قرار می‌گیرند و در [[بحث پودمان:Bananas/testcases]] با چیزی مثل <code><nowiki>{{#invoke: Bananas/testcases | run_tests}}</nowiki></code> اجرا می‌شود. متدهای آزمایش با «test «شروع می‌شوند. نمونهٔ ساده از [[پودمان:Bananas/testcases]] در زیر آورده شده است.
<syntaxhighlight lang="lua">
-- Unit tests for [[پودمان:Bananas]]. Click talk page to run tests.
local p = require('Module:UnitTests')

function p:test_hello()
    self:preprocess_equals('{{#invoke:Bananas | hello}}', 'سلام، دنیا!')
end

return p
</syntaxhighlight>

برای مشاهدهٔ فهرستی از پودمان‌هایی که از آزمایش واحد بهره می‌برند، [[ویژه:پیوند به این صفحه/پودمان:UnitTests]] را ببینید.

یک چارچوب آزمایش واحد دیگری هم است به اسم [[پودمان:ScribuntoUnit]] که از ویکی‌پدیای مجارستان سرچشمه گرفته است. این چارچوب خیلی شبیه به [[پودمان:UnitTests]] است، اما شکل کدنویسی متفاوتی دارد و خطاهای واقعی که به‌واسطهٔ فراخوانی‌های حفاظت‌شده به دام افتاده‌اند را برمی‌گرداند. این چارچوب همچنین تابعی برای مقایسهٔ ممیزهای شناور با دقت تعیین‌شده دارد.

== بومی‌سازی پودمان ==
=== بومی‌سازی ارقام ===
[[پودمان:Numeral converter]] برای استفاده در پودمان کاربرد دارد. بیشترین کاربرد این پودمان برای بومی‌سازی ارقام و علائم نگارشی است، اما کاربردهای دیگر هم دارد. به زبان ساده، اگر در خروجی ارقام انگلیسی مشاهده کردید، این پودمان آنها را به فارسی برمی‌گرداند. استفاده از این پودمان بسیار راحت است و نمونه‌ای ساده از آن را در [[پودمان:BananasArgs]] در عمل می‌بینید و در ادامه نمونه ساده‌تری آماده شده است.

<syntaxhighlight lang="lua">
local p = {}
local converter = require("Module:Numeral converter")

function p.hello_world()
return "سلام " .. converter.convert("fa", 2) .. " دنیا!"
end

return p
</syntaxhighlight>

=== ترجمه و بومی‌سازی رشته‌ها ===
صحبت خاصی برای ترجمه و بومی‌سازی رشته‌ها وجود ندارد. فقط تجربه لازم است و ذکر چند نکته حیاتی. حتماً به‌دقت رشته‌ها را به فارسی برگردانید و ترجمه دقیقی داشته باشید. ممکن است بعضی رشته‌ها ظاهری مانند متنی نیازمند ترجمه داشته باشند اما کاربردی غیر از آن دارند که لازم است حواستان را جمع کنید و بهتر است در صفحهٔ تمرین پودمان اینکار را کنید و اگر همه‌چیز درست کار می‌کرد به پودمان منتقل کنید.

== ویژگی‌های مختص ویکی‌پدیا ==
Overall: Lua can only get input as text strings passed to the <code><nowiki>{{#invoke:}}</nowiki></code> and what can be fetched via mw.title.new(...):getContent() and frame:expandTemplate(). Lua output will not be preprocessed unless frame:preprocess() is explicitly called, meaning that template calls, parser functions, etc. in the output will not work correctly. Also, all Lua in the page is limited to 10 seconds CPU time (you can look in the source code of a rendered page to see how long a template or module took to parse). And relative to standard Lua, Scribunto's Lua lacks all sorts of functions (see {{Section link|mw:Extension:Scribunto/Lua reference manual|Differences from standard Lua}}).

=== محدودیت‌های ورودی لوآ ===
Lua code in Scribunto is only run when the page is being parsed. Therefore, the only user input that Lua can receive is by ''page editing'' - it cannot create a box that calculates the square root of a number you type in, or recalculate a piece of the Mandelbrot set depending on which part of the parent set you click on. The input Lua can receive includes any transcludeable text page on Wikipedia. This does ''not'' include graphics files (not even [[Wikipedia:SVG help|.SVG]] files, although they are actually text, unless you cut and paste it onto a Wiki text page), the list of pages listed in a [[راهنما:رده]]، nor the contents of [[ویکی‌پدیا:تراگنجانش]] [[راهنما:صفحات ویژه]].

=== ویکی‌متن ===
Transcluded Wikipedia headers frequently contain a hidden code such as "UNIQ5ae8f2aa414ff233-h-3--QINU" which may need to be stripped out in order for them to be parsed effectively.

Wikilinks of the [[Wikipedia:Pipe trick|type]] '''<nowiki>[[راهنما:فهرست]]</nowiki>''' won't work if returned as output - they need to be written explicitly as '''<nowiki>[[راهنما:فهرست]]</nowiki>'''. Other pre-save transforms, such as replacing <code>~~<nowiki/>~~</code> with signatures, will also fail to be processed. Template transclusions, parser function calls, and variable substitutions (i.e. anything with a <code><nowiki>{{...}}</nowiki></code>) will not be processed, nor will tags such as {{برچسب|ref|o}} or {{برچسب|nowiki|o}}.

== برچسب‌زدن الگوهای تبدیل‌شده ==
در صفحهٔ بحث الگوهایی که از پودمان‌های لوآ استفاده می‌کنند الگوی {{الگو|بحث لوآ}} را بیفزایید.

== جستارهای وابسته ==
; منابع مختص ویکی‌پدیای فارسی
* [[ویکی‌پدیا:لوآ راهنمای سبک]] – استانداردها برای بهبود خوانایی کد ازطریق توافق
* [[ویژه:نمایه پیشوندی/پودمان:]] – ردیابی پودمان‌های لوآ بااستفاده از [[ویژه:نمایه_پیشوندی]]
* [[راهنما:لوآ اشکال‌زدایی]] – راهنمای چگونگی دربارهٔ [[اشکال‌زدایی]] پودمان‌های لوآ
* [[پودمان:Sandbox]] یک شبه فضای نام برای آزمایش پودمان‌های لوآ فراهم می‌کند
* [[وپ:درخواست‌های لوآ]] – درخواست‌های الگو مبتنی بر لوآ یا وظایف
* [[:رده:الگو:مبتنی بر لوآ]] – گروه‌های الگوهای مبتنی بر لوآ
* [[:رده:فراپودمان‌های لوآ]] –

;مستندات لوآ در مدیاویکی
* [[mw:Extension:Scribunto/Lua reference manual]]

== پانویس ==
{{پانویس}}

{{راهنمای فنی ویکی‌پدیا|collapsed}}
[[رده:الگو:فضای نام پودمان]]
[[رده:پودمان‌های ویکی‌پدیا]]