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

همچنین ببینید: mw:Help:Extension:ParserFunction § #switch

تابع تجزیه‌گر گزینه (انگلیسی: switch parser function) که کد آن به‌شکل «#گزینه» یا «‎#switch‎» است، از میان فهرستی از گزینه‌ها، نخستین شاخهٔ منطبق را انتخاب می‌کند و به عبارت دیگر مانند گزارهٔ حالت (انگلیسی: case statement) عمل می‌کند.

هر یک از شاخه‌ها می‌توانند یک مقدار، یک عبارت (محاسبه) یا یک فراخوانی الگو باشند که ارزیابی شده و برای بررسی انطباق، با مقدار داده‌شده با تابع گزینه مقایسه می‌شوند. اگرچه بسیاری از ساختارهای #گزینه برای گشتن در میان مجموعه‌ای ساده از مقدارها مورد استفاده قرار می‌گیرند، اما شاخه‌ها می‌توانند شامل عبارت بولی نیز باشند تا به‌عنوان پیش‌شرط‌هایی جهت آزمودن تا پیش از صحیح بودن یکی از مقدارها عمل کنند و ساختار آن‌ها نیز مشابه ساختار if-elseif-elseif-elseif-else خواهد بود. مقدار تابع گزینه در قالب یک رشتهٔ نویسه با سایر گزینه‌ها مقایسه می‌شود و نه یک عدد؛ بنابراین «5» با «5.00» برابر نخواهد بود مگر آن که در قالب ‎"{{#expr:{{{1|5.00}}} }}" (="5")‎ مورد مقایسه قرار گیرد.

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

قالب اصلی

برای درک بهتر، در این بخش مثال‌هایی هم برای تابع انگلیسی ‎«#switch»‎ و هم برای برابر فارسی آن «#گزینه» ارائه شده‌است.

تابع #گزینه می‌تواند به شکل یک‌خطی نوشته شود:

{{#switch: {{{x}}} |1=one |2=two |3|4|5=range 3–5 |other}}

{{#گزینه:{{{فلان}}} |۱=یک |۲=دو |۳|۴|۵=بازهٔ ۳ تا ۵ |سایر}}

این تابع #گزینه یک‌خطی، مقدار {{{x}}} را می‌خواند. اگر مقدار آن برابر با 1 باشد، عبارت «one» را برمی‌گرداند. اگر مقدار آن برابر با 2 باشد، «two» را برمی‌گرداند. اگر مقدار آن برابر با 3، 4 یا 5 باشد، عبارت «range 3–5» را برمی‌گرداند. در صورتی که مقدار هر چیز دیگری به‌جز این موارد باشد، یا مقداری به آن وارد نشده‌باشد، عبارت «other» را برمی‌گرداند. به همین ترتیب، در مثال فارسی نیز برای مقدار ۱ عبارت «یک»، برای مقدار ۲ عبارت «دو»، برای مقدارهای ۳، ۴ و ۵ عبارت «بازهٔ ۳ تا ۵» و در صورت نبود مقدار، عبارت «سایر» را برمی‌گرداند.

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

{{#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}} 
}}

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

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

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

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

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

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

استفاده از گزینه‌ها به‌شکل if-elseif-elseif

توابع #گزینه می‌توانند همانند مجموعه‌ای از پیش‌شرط‌ها که تا پیش از صحیح بودن (برابر با «1») یکی از شاخه‌ها آزموده می‌شوند، ساختارمند باشند. برای مثال، اعداد پس‌زمینه برای جلوگیری از تقسیم بر صفر در فرمول:  $x/x2+y/y2$:

{{#switch: 1

| {{#ifeq:{{{x2|none}}}|none|1|0}} = Parameter x2 has no data.

| {{#ifeq:{{{y2|none}}}|none|1|0}} = Parameter y2 has no data.

| {{#expr: {{{x2}}} = 0}} = Parameter x2 is 0 – cannot divide.

| {{#expr: {{{y2}}} = 0}} = Parameter y2 is 0 – cannot divide.

| 1 = {{#expr: {{{x}}}/{{{x2}}} + {{{y}}}/{{{y2}}}}}

}}

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

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

مثالی دیگر برای آزمودن «n» با هدف مشخص‌کردن رقم اعشار:

{{#switch: 1

| {{#expr: floor({{{n}}}*100) <> {{{n}}}*100}} = 3

| {{#expr: floor({{{n}}}*10) <> {{{n}}}*10}} = 2

| {{#expr: floor( {{{n}}} ) <> {{{n}}} }} = 1

| {{#expr: {{{n}}} mod 1000 = 0}} = −3

| {{#expr: {{{n}}} mod 100 = 0 }} = −2

| {{#expr: {{{n}}} mod 10 = 0 }} = −1

| 1 = 0

}}

این یک مثال دیگر با استفاده از «‎#switch: 1‎» برای دسته‌بندی مجموعه‌ای از پیش‌شرط‌ها است که تا زمانی که یکی از آن‌ها صحیح باشد (برابر با «1» باشد) به‌ترتیب آزموده می‌شوند.

در نظر داشتن عملکرد

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

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

جستارهای وابسته

• راهنما:کلمات جادویی
• عملگر رابطه‌ای
• راهنما:کلمات جادویی#متغیرها