کتابخانه‌ی استاندارد · متن

قالب template

پر کردن قالب‌های متنی و HTML با مقدارها، با گریز خودکار برای امنیت.

واردسازی قالب

نام آرگومان‌ها شناسه‌ی خود کد است و معادل فارسی ندارد؛ گونه‌ها، کلیدواژه‌ها و نام بسته‌ها با معادل فارسی نوشته می‌شوند.

قالب متنی است که جاهای خالی دارد؛ هر {{نام}} با مقدار همان نام از یک «زمینه» پر می‌شود. زمینه یک نگاشت از نام به مقدار است.

اگر خروجی HTML است و مقدارها از کاربر آمده‌اند، حتماً رندر اچ تی ام ال را به کار ببرید. این تابع نویسه‌های خطرناک مثل < را گریز می‌دهد تا کسی نتواند کد در صفحه‌تان جا بدهد. همین وب‌سایت با این بسته ساخته شده است.

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

زبان قالب چه دارد و چه ندارد

  • فقط سه برچسب: {{نام}}، {{#if نام}} با {{else}} اختیاری و {{/if}} پایانی، و توضیح {{! ... }}. حلقه، پالایه و مسیر نقطه‌دار ندارد: بخش‌های تکراری را در سلام بسازید و نتیجه را در زمینه بگذارید، همان کاری که نمونه‌ی HTML می‌کند.
  • زمینه فقط رشته نگه می‌دارد. عددها و مقدارهای منطقی را پیش از گذاشتن به متن تبدیل کنید.
  • مقدارها همان‌طور که هستند گذاشته می‌شوند و دوباره پویش نمی‌شوند، پس مقداری که {{ دارد نمی‌تواند برچسبی جا بزند.
  • رندر اچ تی ام ال نویسه‌های & < > " ' را گریز می‌دهد. این برای متن صفحه و درون ویژگی گیومه‌دار امن است، ولی نه درون بلوک <script> یا به عنوان نشانی پیوند: مقداری مثل javascript:... بی‌تغییر رد می‌شود.

پر کردن یک پیام متنی

رایج‌ترین کار، پیامی است که چند نام در آن جا می‌گیرد: یک ایمیل، یک اعلان یا یک رسید. هر مقدار را با درج در زمینه بگذارید و بعد رندر را صدا بزنید. همان زمینه را می‌شود دوباره پر کرد و باز رندر گرفت، پس یک قالب برای همه‌ی مشتری‌ها بس است. بخشی که میان {{#if کلید}} و {{/if}} باشد فقط وقتی دیده می‌شود که آن کلید مقدار داشته باشد، و {{! ... }} یادداشتی است که هرگز به خروجی نمی‌رسد.

template-guide-email.salam
واردسازی قالب

تابع ریشه:
    نامه := "سلام {{نام}}،\n\nسفارش {{سفارش}} شما ارسال شد.\n{{#if رهگیری}}از این نشانی پیگیری کنید: {{رهگیری}}\n{{/if}}{{! خط رهگیری اختیاری است }}\nبا سپاس،\n{{فروشگاه}}"

    ناپایا ز := قالب.زمینه جدید()
    دیرکن ز.آزادکن()
    ز.درج("نام"، "سارا")
    ز.درج("سفارش"، "#۱۰۴۲")
    ز.درج("رهگیری"، "https://post.example/T-77")
    ز.درج("فروشگاه"، "کتاب‌فروشی کوچه")
    سرچاپ قالب.رندر(نامه، ز)
    سرچاپ "-----"
    ز.درج("نام"، "رضا")
    ز.درج("سفارش"، "#۱۰۴۳")
    ز.درج("رهگیری"، "")
    سرچاپ قالب.رندر(نامه، ز)
پایان
خروجیسلام سارا، سفارش #۱۰۴۲ شما ارسال شد. از این نشانی پیگیری کنید: https://post.example/T-77 با سپاس، کتاب‌فروشی کوچه ----- سلام رضا، سفارش #۱۰۴۳ شما ارسال شد. با سپاس، کتاب‌فروشی کوچه

شرط و else

{{#if کلید}} می‌تواند شاخه‌ی {{else}} هم داشته باشد و این بلوک‌ها را می‌شود تودرتو نوشت. کلیدی که نباشد، خالی باشد، یا مقدارش "false" یا "0" باشد نادرست حساب می‌شود؛ هر متن دیگری مثل "بله" یا "۳" درست است. دقت کنید که "۰" با رقم فارسی هم درست حساب می‌شود، چون فقط "0" لاتین نادرست است. زمینه فقط رشته نگه می‌دارد، پس عدد یا مقدار منطقی را اول به متن تبدیل کنید، مثلاً با رشته.از عدد.

template-guide-conditions.salam
واردسازی قالب

تابع نشان(کاربر: رشته، مدیر: رشته، نخوانده: رشته): رشته:
    ناپایا ز := قالب.زمینه جدید()
    دیرکن ز.آزادکن()
    ز.درج("کاربر"، کاربر)
    ز.درج("مدیر"، مدیر)
    ز.درج("نخوانده"، نخوانده)
    برگشت قالب.رندر("{{کاربر}}{{#if مدیر}} [مدیر]{{/if}}: {{#if نخوانده}}{{نخوانده}} پیام تازه{{else}}پیام تازه‌ای نیست{{/if}}"، ز)
پایان

تابع ریشه:
    سرچاپ نشان("سارا"، "true"، "۳")
    سرچاپ نشان("رضا"، "false"، "0")
    سرچاپ نشان("مینا"، ""، "۱۲")
    سرچاپ نشان("علی"، "بله"، "")
پایان
خروجیسارا [مدیر]: ۳ پیام تازه رضا: پیام تازه‌ای نیست مینا: ۱۲ پیام تازه علی [مدیر]: پیام تازه‌ای نیست

HTML امن از داده‌ی کاربر

صفحه معمولاً از تکه‌های کوچک ساخته می‌شود. هر ردیف را با رندر اچ تی ام ال بسازید تا هر چه بازدیدکننده نوشته گریز داده شود، و بعد ردیف‌های آماده را با رندر در اسکلت بیرونی بگذارید. اگر برای مرحله‌ی بیرونی هم رندر اچ تی ام ال را به کار ببرید، ردیف‌ها دوباره گریز می‌خورند و مرورگر برچسب‌ها را به شکل متن نشان می‌دهد.

template-guide-page.salam
واردسازی قالب

ساختار کتاب:
    همگانی عنوان: رشته = ""
    همگانی نویسنده: رشته = ""
پایان

تابع ریشه:
    ناپایا کتاب‌ها := وکتور {} برگردان وکتور<کتاب>
    دیرکن کتاب‌ها.آزادکن()
    کتاب‌ها.بیفزا(کتاب { عنوان = "نمک و جوهر"، نویسنده = "ن. کریمی" })
    کتاب‌ها.بیفزا(کتاب { عنوان = "<script>alert(1)</script>"، نویسنده = "یک بازدیدکننده" })

    ردیف := "<li>{{عنوان}} نوشته‌ی {{نویسنده}}</li>\n"
    ناپایا ردیف‌ها := ""
    ناپایا مورد := قالب.زمینه جدید()
    دیرکن مورد.آزادکن()
    هر ک در کتاب‌ها:
        مورد.درج("عنوان"، ک.عنوان)
        مورد.درج("نویسنده"، ک.نویسنده)
        ردیف‌ها += قالب.رندر اچ تی ام ال(ردیف، مورد)
    پایان

    ناپایا صفحه‌ی اصلی := قالب.زمینه جدید()
    دیرکن صفحه‌ی اصلی.آزادکن()
    صفحه‌ی اصلی.درج("سرتیتر"، "کتاب‌های تازه")
    صفحه‌ی اصلی.درج("موردها"، ردیف‌ها)
    اسکلت := "<h1>{{سرتیتر}}</h1>\n<ul>\n{{موردها}}</ul>"
    سرچاپ قالب.رندر(اسکلت، صفحه‌ی اصلی)
پایان
خروجی<h1>کتاب‌های تازه</h1> <ul> <li>نمک و جوهر نوشته‌ی ن. کریمی</li> <li>&lt;script&gt;alert(1)&lt;/script&gt; نوشته‌ی یک بازدیدکننده</li> </ul>

قاعده‌ای که باید یادتان بماند: هر مقدار را درست یک بار گریز بدهید، همان لحظه‌ای که وارد HTML می‌شود. متنی که قبلاً گریز داده‌اید یا HTMLی که برنامه‌ی خودتان ساخته با رندر جا می‌گیرد.

پرونده‌ی پیکربندی و حالت‌های مرزی

قالب فقط برای HTML نیست. پرونده‌ی پیکربندی، سرآیند یک مهاجرت SQL یا یک اسکریپت پوسته را هم می‌شود همین‌طور ساخت، و وقتی خود قالب را با کد سرهم می‌کنید متغیر جای خالی را می‌سازد. کلیدی که در زمینه نیست با هیچ جایگزین می‌شود و خطایی نمی‌دهد، و {{ بی‌آکولاد بسته همان‌طور که هست کپی می‌شود.

template-guide-config.salam
واردسازی قالب

تابع پیکربندی سایت(نام: رشته، درگاه: رشته، رمزنگاری: رشته): رشته:
    ناپایا ز := قالب.زمینه جدید()
    دیرکن ز.آزادکن()
    ز.درج("نام"، نام)
    ز.درج("درگاه"، درگاه)
    ز.درج("رمزنگاری"، رمزنگاری)
    ناپایا متن := "server {\n"
    متن = متن + "    server_name " + قالب.متغیر("نام") + ";\n"
    متن += "    listen {{درگاه}}{{#if رمزنگاری}} ssl{{/if}};\n"
    متن += "    root /srv/{{نام}}/public;\n}"
    برگشت قالب.رندر(متن، ز)
پایان

تابع ریشه:
    سرچاپ پیکربندی سایت("blog.example"، "443"، "on")
    سرچاپ پیکربندی سایت("intranet.local"، "8080"، "")
    ناپایا خالی := قالب.زمینه جدید()
    دیرکن خالی.آزادکن()
    سرچاپ "[" + قالب.رندر("{{ناموجود}}"، خالی) + "]"
    سرچاپ قالب.رندر("چپ {{باز"، خالی)
پایان
خروجیserver { server_name blog.example; listen 443 ssl; root /srv/blog.example/public; } server { server_name intranet.local; listen 8080; root /srv/intranet.local/public; } [] چپ {{باز
کارتابع
ایمیل، متن ساده، پرونده‌ی پیکربندیرندر
HTML با مقدارهایی که از کاربر آمدهرندر اچ تی ام ال
گذاشتن HTML آماده در اسکلت صفحهرندر
گریز دادن دستی یک مقدارگریز اچ تی ام ال
نوشتن جای خالی با کدمتغیر

چون کلید ناموجود به متن خالی تبدیل می‌شود، غلط تایپی در نام کلید بی‌صدا از چشم می‌افتد. وقتی مقداری اجباری است، پیش از رندر با دارد روی زمینه بررسی‌اش کنید. برای صفحه‌های کامل HTML با مؤلفه و سبک، سراغ زبان صفحه‌سازی بروید؛ این بسته برای پر کردن متن است.

تابع‌ها

زمینه جدید NewContext

تابع زمینه جدید(): نگاشت<رشته، رشته>
یک زمینه‌ی خالی می‌سازد: نگاشتی از نام به مقدار. مقدارها را با درج بیفزایید و پس از کار آزادش کنید.
template-Render.salam
واردسازی قالب

تابع ریشه:
    ناپایا ز := قالب.زمینه جدید()
    دیرکن ز.آزادکن()
    ز.درج("نام"، "سارا")
    ز.درج("پیام"، "<سلام>")
    سرچاپ قالب.رندر("سلام {{نام}}! {{پیام}}"، ز)
    سرچاپ قالب.رندر اچ تی ام ال("<p>{{پیام}}</p>"، ز)
    سرچاپ قالب.گریز اچ تی ام ال("<a href=\"x\">&</a>")
    سرچاپ قالب.متغیر("نام")
پایان
خروجیسلام سارا! <سلام> <p>&lt;سلام&gt;</p> &lt;a href=&quot;x&quot;&gt;&amp;&lt;/a&gt; {{نام}}

گریز اچ تی ام ال EscapeHTML

تابع گریز اچ تی ام ال(s: رشته): رشته
نویسه‌های ویژه‌ی HTML را گریز می‌دهد تا متن همان‌طور که هست نمایش داده شود.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: template-Render.salam

رندر Render

تابع رندر(tmpl: رشته، ctx: نگاشت<رشته، رشته>): رشته
هر {{نام}} در قالب را با مقدارش از زمینه پر می‌کند، بی‌هیچ گریزی. برای متن ساده، ایمیل یا پرونده‌ی پیکربندی.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: template-Render.salam

رندر اچ تی ام ال RenderHTML

تابع رندر اچ تی ام ال(tmpl: رشته، ctx: نگاشت<رشته، رشته>): رشته
مثل رندر، ولی هر مقدار را پیش از جاگذاری گریز HTML می‌دهد.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: template-Render.salam

متغیر Var

تابع متغیر(name: رشته): رشته
نشانه‌ی جای خالی را برای یک نام می‌سازد؛ یعنی {{نام}}. وقتی قالب را با کد می‌سازید مفید است.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: template-Render.salam