پرس‌وجو encoding/query

رشته‌ی پرس‌وجو همان متن key=value&key=value بعد از ? در نشانی وب است، و بدنه‌ی فرم HTML که با نوع application/x-www-form-urlencoded فرستاده می‌شود هم همین قالب را دارد. این بسته چنین متنی را می‌خواند و می‌نویسد: گریزهای درصدی و + به جای فاصله را برمی‌گرداند و از مقدارهای شما رشته‌ای با گریزهای درست می‌سازد.

وقتی فقط متن پرس‌وجو را دارید از این بسته استفاده کنید: بدنه‌ی فرم، raw_query یک درخواست، یا فراخوانی امضاشده‌ی یک API. اگر نشانی کامل دارید و می‌خواهید پارامترهایش را تغییر دهید، بسته‌ی نشانی وب تابع‌های تنظیم پارامتر، حذف پارامتر و نگه داشتن پارامترها را روی همین بسته ساخته است. درون یک کنترل‌گر اچ تی تی پی، اچ تی تی پی.پرسمان و اچ تی تی پی.فرم مقدارهای تکی را برایتان می‌خوانند؛ هر وقت کلید تکراری دارید یا می‌خواهید پرس‌وجو را بازنویسی کنید، اچ تی تی پی.پرسمان خام را بگیرید و به این بسته بدهید.

دو شیوه‌ی کار

• روی متن. مقدار، همه مقدارها و دارد خود رشته‌ی پرس‌وجو را می‌گیرند. هر فراخوانی کل رشته را دوباره کدگشایی می‌کند که برای خواندن چند مقدار مشکلی نیست.
• روی نگاشت پرس‌وجو. کدگشایی متن را به نگاشتی تبدیل می‌کند که می‌توانید با تنظیم، افزودن، حذف و نگه داشتن تغییرش دهید و با کدگذاری دوباره بنویسید. یک کلید می‌تواند چند مقدار داشته باشد (tag=a&tag=b)، پس هر کلید فهرستی از مقدارها دارد و نگاشت ترتیب نخستین آمدن کلیدها را به خاطر می‌سپارد.

اشتباه‌های رایج

• نگاشت پرس‌وجو تابع خواندن ندارد. یا متن را با مقدار بخوانید، یا مستقیم سراغ نگاشت بروید: m.data.has("tag") و m.data.get("tag").items.
• برای مقدار، نبودن و خالی بودن یکی است. هم page= و هم نبودن page رشته‌ی خالی "" برمی‌گردانند؛ هر جا فرقشان مهم است از دارد بپرسید. flag تنها، موجود با مقدار خالی حساب می‌شود و کدگذاری آن را flag= می‌نویسد.
• عددها بررسی نمی‌شوند. "12abc".به صحیح() عدد ۱۲ است و "abc".به صحیح() صفر، پس هر عددی را که می‌خوانید پیش از استفاده محدود کنید.
• کلیدهای تکراری کنار هم جمع می‌شوند. a=1&b=2&a=3 دوباره به شکل a=1&a=3&b=2 نوشته می‌شود. داده همان است، ولی اگر امضا یا کلید حافظه‌ی نهان روی متن دقیق حساب می‌شود، آنچه را می‌فرستید امضا کنید، نه آنچه را دریافت کرده‌اید.
• کلیدها به بزرگی و کوچکی حروف حساس‌اند و کدگشایی از ? آغاز رشته می‌گذرد.

راهنما: خواندن پارامترهای صفحه‌ی جستجو

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

واردسازی کدگذاری.پرس‌وجو

تابع ریشه:
    پرسش := "q=green+tea&brand=nik&brand=pars&min=20&page=3&limit=500"

    واژه‌ها := پرس‌وجو.مقدار(پرسش، "q")
    ناپایا صفحه := ۱
    اگر پرس‌وجو.دارد(پرسش، "page"):
        صفحه = پرس‌وجو.مقدار(پرسش، "page").به صحیح()
    پایان
    ناپایا اندازه صفحه := ۲۰
    اگر پرس‌وجو.دارد(پرسش، "limit"):
        اندازه صفحه = پرس‌وجو.مقدار(پرسش، "limit").به صحیح()
    پایان
    اگر صفحه < ۱: صفحه = ۱ پایان
    اگر اندازه صفحه < ۱ یا اندازه صفحه > ۱۰۰: اندازه صفحه = ۱۰۰ پایان
    برندها := پرس‌وجو.همه مقدارها(پرسش، "brand")

    سرچاپ "جستجوی:"، واژه‌ها
    سرچاپ "برندها:"، برندها.طول()، برندها
    سرچاپ "کمترین قیمت:"، پرس‌وجو.مقدار(پرسش، "min").به صحیح()
    سرچاپ "ردیف‌های"، (صفحه - ۱) * اندازه صفحه + ۱، "تا"، صفحه * اندازه صفحه
پایان

مقدار هم برای کلید نبوده و هم برای key= رشته‌ی خالی برمی‌گرداند، پس هر جا تفاوت مهم است از دارد استفاده کنید، مثل پیش‌فرض‌های page و limit در اینجا. به عددها اعتماد نکنید: بازدیدکننده ۵۰۰ ردیف خواسته، ولی کنترل‌گر سقف limit را ۱۰۰ می‌گذارد و page را دست‌کم ۱ نگه می‌دارد تا مقدار بد نتواند کل جدول را بخواند یا جابه‌جایی منفی بسازد.

راهنما: پیوند صفحه‌ی بعد و قبل

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

واردسازی کدگذاری.پرس‌وجو
واردسازی رشته

تابع پیوند صفحه(کنونی: رشته، صفحه: صحیح): رشته:
    ناپایا ن := پرس‌وجو.کدگشایی(کنونی)
    پرس‌وجو.تنظیم(ن، "page"، رشته.از عدد(صفحه))
    برگشت "/products?" + پرس‌وجو.کدگذاری(ن)
پایان

تابع ریشه:
    کنونی := "category=books&sort=price&tag=new&tag=sale&page=2"
    سرچاپ "قبلی:"، پیوند صفحه(کنونی، ۱)
    سرچاپ "بعدی:"، پیوند صفحه(کنونی، ۳)
    سرچاپ "نخستین بازدید:"، پیوند صفحه("category=books"، ۲)
پایان

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

راهنما: بدنه‌ی فرم‌های HTML

فرمی که با method="post" فرستاده شود بدنه‌ای از نوع application/x-www-form-urlencoded دارد که همان قالب رشته‌ی پرسش است. آن را با همین تابع‌ها کدگشایی کنید. فاصله‌ها به شکل + و هر چیز بیرون از اَسکی ساده، از جمله متن فارسی، به شکل بایت‌های %XX می‌رسد.

واردسازی کدگذاری.پرس‌وجو

تابع ریشه:
    بدنه := "name=Sara+Ahmadi&city=%D8%B4%DB%8C%D8%B1%D8%A7%D8%B2&note=50%25+off%3F&agree=on"
    فرم := پرس‌وجو.کدگشایی(بدنه)
    سرچاپ "فیلدها:"، پرس‌وجو.کلیدها(فرم)
    سرچاپ "نام:"، پرس‌وجو.مقدار(بدنه، "name")
    سرچاپ "شهر:"، پرس‌وجو.مقدار(بدنه، "city")
    سرچاپ "یادداشت:"، پرس‌وجو.مقدار(بدنه، "note")
    سرچاپ "پذیرفت:"، پرس‌وجو.مقدار(بدنه، "agree") == "on"

    ناپایا پاسخ := پرس‌وجو.نگاشت پرس‌وجو جدید()
    پرس‌وجو.تنظیم(پاسخ، "status"، "saved ok")
    سرچاپ "به سبک فرم:"، پرس‌وجو.کدگذاری(پاسخ)
    سرچاپ "به سبک نشانی:"، پرس‌وجو.کدگذاری سفارشی(پاسخ، پرس‌وجو.گزینه‌های پرس‌وجو { فاصله پلاس = نادرست })
پایان

کدگذاری فاصله را مثل فرم‌ها + می‌نویسد. برخی APIها به جایش %20 می‌خواهند؛ کدگذاری سفارشی با space_as_plus = نادرست همین را می‌نویسد.

راهنما: فقط پارامترهای شناخته‌شده را نگه دارید

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

واردسازی کدگذاری.پرس‌وجو

تابع ریشه:
    رسیده := "q=lamp&page=2&utm_source=ad&debug=1&sort=new&callback=x"

    ناپایا ن := پرس‌وجو.کدگشایی(رسیده)
    ناپایا مجاز := وکتور {} برگردان وکتور<رشته>
    مجاز.بیفزا("q")
    مجاز.بیفزا("page")
    مجاز.بیفزا("sort")
    پرس‌وجو.نگه داشتن(ن، مجاز)
    سرچاپ "ماند:"، پرس‌وجو.کدگذاری(ن)

    سرچاپ "sort حذف شد:"، پرس‌وجو.حذف(ن، "sort")
    سرچاپ "دوباره حذف شد:"، پرس‌وجو.حذف(ن، "sort")
    سرچاپ "کلید حافظه‌ی نهان:"، پرس‌وجو.کدگذاری(ن)، "با"، پرس‌وجو.اندازه(ن)، "کلید"
پایان

تابع‌های متنی یا نگاشت پرس‌وجو

گونه‌ها

ساختار گزینه‌های پرس‌وجو

واردسازی کدگذاری.پرس‌وجو

تابع ریشه:
    متن := "q=%D8%B3%D9%84%D8%A7%D9%85&page=2&tag=a&tag=b&empty="
    سرچاپ پرس‌وجو.مقدار(متن، "q")، پرس‌وجو.مقدار(متن، "page")، پرس‌وجو.دارد(متن، "empty")، پرس‌وجو.دارد(متن، "x")
    سرچاپ پرس‌وجو.همه مقدارها(متن، "tag")
    ناپایا ن := پرس‌وجو.کدگشایی(متن)
    سرچاپ پرس‌وجو.اندازه(ن)، پرس‌وجو.کلیدها(ن)
    پرس‌وجو.افزودن(ن، "tag"، "c")
    پرس‌وجو.تنظیم(ن، "page"، "3")
    سرچاپ پرس‌وجو.حذف(ن، "empty")
    سرچاپ پرس‌وجو.کدگذاری(ن)
    ناپایا نگه := وکتور {} برگردان وکتور<رشته>
    نگه.بیفزا("q")
    پرس‌وجو.نگه داشتن(ن، نگه)
    سرچاپ پرس‌وجو.کدگذاری(ن)
    گ := پرس‌وجو.گزینه‌های پرس‌وجو {}
    سرچاپ پرس‌وجو.کدگذاری سفارشی(پرس‌وجو.کدگشایی سفارشی("b=2&a=1"، گ)، گ)
    خالی := پرس‌وجو.نگاشت پرس‌وجو جدید()
    سرچاپ پرس‌وجو.اندازه(خالی)
پایان

ساختار مقدارهای پرس‌وجو

ساختار نگاشت پرس‌وجو

تابع‌ها

تابع نگاشت پرس‌وجو جدید(): نگاشت پرس‌وجو

تابع کدگشایی سفارشی(qs: رشته، opts: گزینه‌های پرس‌وجو): نگاشت پرس‌وجو

تابع کدگشایی(qs: رشته): نگاشت پرس‌وجو

تابع کدگذاری سفارشی(values: نگاشت پرس‌وجو، opts: گزینه‌های پرس‌وجو): رشته

تابع کدگذاری(values: نگاشت پرس‌وجو): رشته

تابع همه مقدارها(qs: رشته، key: رشته): وکتور<رشته>

تابع مقدار(qs: رشته، key: رشته): رشته

تابع دارد(qs: رشته، key: رشته): منطقی

تابع اندازه(m: نگاشت پرس‌وجو): صحیح

تابع افزودن(values &: نگاشت پرس‌وجو، key: رشته، val: رشته)

تابع تنظیم(values &: نگاشت پرس‌وجو، key: رشته، val: رشته)

تابع کلیدها(values: نگاشت پرس‌وجو): وکتور<رشته>

تابع حذف(values &: نگاشت پرس‌وجو، key: رشته): منطقی

تابع نگه داشتن(values &: نگاشت پرس‌وجو، keep: وکتور<رشته>)