نمایش مبدأ برای راهنما:تابع تجزیه‌گر گزینه

{{چگونه‌های ویکی‌پدیا|وپ:تابع گزینه}}
{{وابسته|:mw:Help:Extension:ParserFunction##switch}}
'''تابع تجزیه‌گر گزینه''' ({{lang-en|switch parser function}}) که کد آن به‌شکل «'''#گزینه'''» یا «{{چر}}#switch{{چر}}» است، از میان فهرستی از گزینه‌ها، نخستین شاخهٔ منطبق را انتخاب می‌کند و به عبارت دیگر مانند [[case statement|گزارهٔ حالت]] ({{lang-en|case statement}}) عمل می‌کند. 

هر یک از شاخه‌ها می‌توانند یک [[مقدار (علوم رایانه)|مقدار]]، یک [[expression (computer science)|عبارت]] ([[:m:Help:Calculation|محاسبه]]) یا یک فراخوانی [[ویکی‌پدیا:الگوهای ویکی‌پدیا|الگو]]<ref>یک '''فراخوانی الگو''' (که با عنوان '''برچسب الگو''' نیز شناخته می‌شود) دارای دو «آکولاد» در هر دو طرف عنوان صفحهٔ الگو است و فاقد پیشوند «الگو:» است. <code><nowiki>{{الگو:Tc}}</nowiki></code> نیز قابل استفاده است، اما وجود «الگو:» ضرورتی ندارد. نتیجهٔ این الگو «{{الگوک|...}}» خواهد بود.</ref> باشند که ارزیابی شده و برای بررسی انطباق، با مقدار داده‌شده با تابع گزینه مقایسه می‌شوند. اگرچه بسیاری از ساختارهای #گزینه برای گشتن در میان مجموعه‌ای ساده از مقدارها مورد استفاده قرار می‌گیرند، اما شاخه‌ها می‌توانند شامل [[boolean expression|عبارت بولی]] نیز باشند تا به‌عنوان پیش‌شرط‌هایی جهت آزمودن تا پیش از صحیح بودن یکی از مقدارها عمل کنند و ساختار آن‌ها نیز مشابه ساختار ''if-elseif-elseif-elseif-else'' خواهد بود. مقدار تابع گزینه در قالب یک [[رشته (علوم رایانه)|رشتهٔ نویسه]] با سایر گزینه‌ها مقایسه می‌شود و نه یک عدد؛ بنابراین «5» با «5.00» برابر نخواهد بود مگر آن که در قالب {{چر}}{{code|<nowiki>"{{#expr:{{{1|5.00}}}&nbsp;}}" (="5")</nowiki>}}{{چر}} مورد مقایسه قرار گیرد.

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

== قالب اصلی ==
{{سرنویس|برای درک بهتر، در این بخش مثال‌هایی هم برای تابع انگلیسی {{چر}}«#switch»{{چر}} و هم برای برابر فارسی آن «#گزینه» ارائه شده‌است.}}
تابع {{mono|#گزینه}} می‌تواند به شکل یک‌خطی نوشته شود:

<syntaxhighlight lang=moin>
{{#switch: {{{x}}} |1=one |2=two |3|4|5=range 3–5 |other}}
</syntaxhighlight>
<pre>
{{#گزینه:{{{فلان}}} |۱=یک |۲=دو |۳|۴|۵=بازهٔ ۳ تا ۵ |سایر}}
</pre>
این تابع {{mono|#گزینه}} یک‌خطی، مقدار {{mono|<nowiki>{{{x}}}</nowiki>}} را می‌خواند. اگر مقدار آن برابر با 1 باشد، عبارت «one» را برمی‌گرداند. اگر مقدار آن برابر با 2 باشد، «two» را برمی‌گرداند. اگر مقدار آن برابر با 3، 4 یا 5 باشد، عبارت «range 3–5» را برمی‌گرداند. در صورتی که مقدار هر چیز دیگری به‌جز این موارد باشد، یا مقداری به آن وارد نشده‌باشد، عبارت «other» را برمی‌گرداند. به همین ترتیب، در مثال فارسی نیز برای مقدار ۱ عبارت «یک»، برای مقدار ۲ عبارت «دو»، برای مقدارهای ۳، ۴ و ۵ عبارت «بازهٔ ۳ تا ۵» و در صورت نبود مقدار، عبارت «سایر» را برمی‌گرداند.

با این حال، در بیشتر موارد تابع {{mono|#گزینه}} در قالب چندخطی مانند نمونهٔ زیر نوشته می‌شود و هر شاخهٔ آن در یک خط مجزا قرار می‌گیرد:

<syntaxhighlight lang=moin>
{{#switch: {{{x}}}
 | 1 = one
 | 2 = two
 | #default = other
 | 3|4|5 = any of 3–5
 | {{#expr: 2*3}} = six
 | {{#expr: 2*3+1}} = {{lc:SEVEN}} 
}}
</syntaxhighlight>

<pre>
{{#گزینه: {{{فلان}}}
 | ۱ = یک
 | ۲ = دو
 | #پیش‌فرض = سایر
 | ۳|۴|۵ = هر عددی بین ۳ تا ۵
 | {{#حساب: 2*3}} = شش
 | {{آرایش‌عدد: {{#حساب: 2*3+1}} }} = هفت
}}
</pre>

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

اگر هیچ پیش‌فرضی مشخ نشده‌باشد و هیچ یک از حالت‌ها با مقدار واردشده به تابع منطبق نباشند، یک مقدار خالی برگردانده خواهد شد.

در هریک از شاخه‌های تابع {{mono|#گزینه}}، در هر یک از طرفین علامت مساوی «=» می‌توان یک مقدارِ ساده، یک عبارت یا یک فراخوانی الگو را قرار داد.

در نمونهٔ فارسی فوق، خروجی عبارت {{کد|<nowiki>{{#حساب: 2*3}}</nowiki>}} که از تابع #حساب استفاده می‌کند، با ارقام انگلیسی خواهد بود: {{#حساب: 2*3}}. در نتیجه اگر مقدار فرستاده‌شده به تابع #گزینه عدد فارسی ۶ باشد، این شاخه صحیح نخواهد بود.

در عوض، در شاخهٔ آخر و در عبارت {{کد|<nowiki>{{آرایش‌عدد: {{#حساب: 2*3+1}} }}</nowiki>}} از [[راهنما:کلمات جادویی|کلمهٔ جادویی]] «آرایش‌عدد» ({{lang-en|formatnum}}) استفاده شده‌است و خروجی تابع #حساب به ارقام فارسی تبدیل خواهد شد: {{آرایش‌عدد: {{#حساب: 2*3+1}} }}. در نتیجه اگر مقدار فرستاده‌شده به تابع #گزینه عدد ۷ باشد، این شاخه صحیح خواهد بود و واژهٔ «هفت» برگردانده خواهد شد.

== استفاده از گزینه‌ها به‌شکل if-elseif-elseif ==
توابع #گزینه می‌توانند همانند مجموعه‌ای از پیش‌شرط‌ها که تا پیش از صحیح بودن (برابر با «1») یکی از شاخه‌ها آزموده می‌شوند، ساختارمند باشند. برای مثال، اعداد پس‌زمینه برای جلوگیری از تقسیم بر صفر در فرمول:&nbsp; {{nowrap|<math>x/x2 + y/y2</math>:}}
{{چپ‌چین}}
:: <code><nowiki>{{#switch: 1</nowiki></code>
:: <code><nowiki>| {{#ifeq:{{{x2|none}}}|none|1|0}} = Parameter x2 has no data.</nowiki></code>
:: <code><nowiki>| {{#ifeq:{{{y2|none}}}|none|1|0}} = Parameter y2 has no data.</nowiki></code>
:: <code><nowiki>| {{#expr: {{{x2}}} = 0}} = Parameter x2 is 0 – cannot divide.</nowiki></code>
:: <code><nowiki>| {{#expr: {{{y2}}} = 0}} = Parameter y2 is 0 – cannot divide.</nowiki></code>
:: <code><nowiki>| 1 = {{#expr: {{{x}}}/{{{x2}}} + {{{y}}}/{{{y2}}}}}</nowiki></code>
:: <code><nowiki>}}</nowiki></code>
{{پایان چپ‌چین}}

در زمان آزمودن مقدار پارامترهای x2 و y2، اگر هر یک از آن‌ها برابر با صفر (none) باشد، تابع #گزینه به‌جای محاسبهٔ [[میانگین وزنی]] میزان x و y با x2 و y2، یک هشدار را برمی‌گرداند. هر یک از شاخه‌های به‌عنوان یک پیش‌شرط عمل می‌کند، بنابراین کل ساختار #گزینه مشابه ساختار ''if-elseif-elseif-elseif-else'' عمل خواهد کرد؛ حتی با وجود این که ساختار یک تابع #اگر نمی‌تواند دارای شرط «elseif» باشد. به دو نوع داده‌ای که مقایسه شده‌اند دقت کنید:

* '''داده‌های الفبایی:''' رشته‌ای از نویسهٔ الفبایی را می‌توان در تابع <code>#گزینه</code> با استفاده از تابع <code>#اگرمساوی:</code> {{nowrap|مانند این مثال مقایسه کرد:{{nb5}}{{چر}}<nowiki>{{#ifeq:{{{x2|none}}}|none|1|0}}</nowiki>{{چر}}.}}<br>در این مثال در صورت صحیح‌بودن عبارت، نتیجه «1»، و در صورت غلط بودن آن، نتیجه «0» خواهد بود.
* '''داده‌های عددی:''' بعضی اعداد را می‌توان در تابع <code>#گزینه</code> با استفاده از تابع <code>#حساب:</code> {{nowrap|مانند این مثال مقایسه کرد:{{nb5}}{{چر}}<nowiki>{{#expr: {{{y2}}} = 0}}</nowiki>{{چر}} یا {{چر}}<nowiki>{{#expr: {{{x}}} < 41500}}.</nowiki>{{چر}}}}<br>در این مثال، هر یک از نتایج در صورت صحیح بودن عبارت برابر با «1» و در صورت غلط بودن آن برابر با «0» خواهند بود.</br>'''{{قرمز|نکتهٔ مهم}}''': توابع تجزیه‌گر ارقام فارسی را نمی‌پذیرند. در نتیجه توابعی نظیر <code>#اگرحساب</code> یا <code>#حساب</code> (برابر با {{چر}}<code>#ifexpr</code>{{چر}} و {{چر}}<code>#expr</code>{{چر}}) تنها در صورتی عمل خواهند کرد که ارقام وارد شده به آن‌ها انگلیسی باشد. با این حال، تابعی مانند <code>#اگرمساوی</code> (یا <code>#ifeq</code>) تمام ورودی‌های خود را به‌عنوان رشته در نظر می‌گیرد و ارقام فارسی را هم می‌پذیرد. در نتیجه، در این تابع عدد «۴» با «۴» برابر است، اما با «4» برابر نخواهد بود.

مثالی دیگر برای آزمودن «n» با هدف مشخص‌کردن رقم اعشار:
{{چپ‌چین}}
:: <code><nowiki>{{#switch: 1</nowiki></code>
:: <code><nowiki>| {{#expr: floor({{{n}}}*100) <> {{{n}}}*100}} = 3</nowiki></code>
:: <code><nowiki>| {{#expr: floor({{{n}}}*10) <> {{{n}}}*10}} = 2</nowiki></code>
:: <code><nowiki>| {{#expr: floor( {{{n}}} ) <> {{{n}}} }} = 1</nowiki></code>
:: <code><nowiki>| {{#expr: {{{n}}} mod 1000 = 0}} = −3</nowiki></code>
:: <code><nowiki>| {{#expr: {{{n}}} mod 100 = 0 }} = −2</nowiki></code>
:: <code><nowiki>| {{#expr: {{{n}}} mod 10 = 0 }} = −1</nowiki></code>
:: <code><nowiki>| 1 = 0</nowiki></code>
:: <code><nowiki>}}</nowiki></code>
{{پایان چپ‌چین}}
این یک مثال دیگر با استفاده از «{{چر}}#switch: 1{{چر}}» برای دسته‌بندی مجموعه‌ای از پیش‌شرط‌ها است که تا زمانی که یکی از آن‌ها صحیح باشد (برابر با «1» باشد) به‌ترتیب آزموده می‌شوند.

== در نظر داشتن عملکرد ==
یک تابع #گزینه می‌توان بیشاز ۱٬۰۰۰ تا ۲٬۰۰۰ شاخه داشته‌باشد، اما بهتر است تا به‌منظور دربرگرفتن کمتر از ۱۰۰ شاخه، به چندین بخش آشیانه‌ای تفکیک شود. در برخی موارد، ممکن است بتوان آن را به چندین ساختار #گزینه تقسیم کرد. مانند زمانی که حرف اول در همهٔ حالت‌ها یکسان است. در این صورت، با استفاده از {&#123;padleft:|1|{{{value}}}&nbsp;}} می‌توان نخستین حرف از {{{مقدار}}} را استخراج کرد تا از آن در یک #گزینه در سطح بالاتر که با حروف پرکاربردتر شاخه‌بندی شده‌است، و به‌دنبال آن سایر حالت‌ها یا مقدار «#پیش‌فرض» قرار گرفته‌اند، استفاده کرد. نوع معمول دیگری از تفکیک این تابع، می‌تواند تفکیک مقادیر عددی به بازه‌های پرکاربردتر و قرار دادن سایر حالت‌ها در دنبالهٔ آن باشد.

شاخه‌های بالایی تابع #گزینه سریع‌تر اجرا می‌شوند و شاخه‌هایی پایین‌تر باید تا زمان پایان مقایسهٔ شاخه‌های بالایی منتظر بمانند. از این رو، بالاترین شاخه باید پرکاربردترین حالت باشد، مگر آن که در شاخه‌های اولیه از داده‌های پس‌زمینه‌ای استفاده شده باشد.

== جستارهای وابسته ==
* [[راهنما:کلمات جادویی]]
* [[عملگر رابطه‌ای]]
* [[راهنما:کلمات جادویی#متغیرها]]

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

{{راهنمای فنی ویکی‌پدیا}}