trurl(1) 0.16.1 trurl(1)

trurl - ترانهش و دستکاری نشانی‌های وب (URL)

trurl [گزینه‌ها / URLs]

دستور trurl نشانی‌های وب (URL) و بخش‌های مختلف آن‌ها را تجزیه، دستکاری و در خروجی چاپ می‌کند.

این ابزار از تعریف URL در RFC 3986 و همچنین تجزیه‌گر نشانی وب در libcurl استفاده می‌کند که شامل چند «افزونه» نیز می‌شود. پشتیبانی از URL به نشانی‌های «سلسله‌مراتبی» (hierarchical) محدود است؛ یعنی مواردی که پس از طرح‌واره (scheme) از جداکننده‌ی :// استفاده می‌کنند.

به‌طور معمول شما یک یا چند URL به آن ارسال می‌کنید و تصمیم می‌گیرید چه بخشی از آن در خروجی نمایش داده شود؛ همچنین در صورت تمایل می‌توانید نشانی وب را تغییر دهید.

ابزار trurl ساختار URL را می‌شناسد و هر URL از حداکثر ده مؤلفه (component) مجزا و مستقل تشکیل شده است. این مؤلفه‌ها را می‌توان با trurl استخراج، حذف و به‌روزرسانی کرد و با نام‌های مربوطه‌شان به آن‌ها ارجاع داده می‌شود: scheme، user، password، options، host، port، path، query، fragment و zoneid.

هنگامی که یک URL برای کار به trurl داده می‌شود، آن را «نرمال‌سازی» می‌کند. بدین معنا که مؤلفه‌های مجزای URL ابتدا رمزگشایی (URL decode) شده، سپس مجدداً کدگذاری (URL encode) شده و در URL قرار می‌گیرند.

مثال:

$ trurl 'http://ex%61mple:80/%62ath/a/../b?%2e%FF#tes%74'
http://example/bath/b?.%ff#test

گزینه‌ها با یک یا دو خط تیره شروع می‌شوند. بسیاری از گزینه‌ها نیازمند یک مقدار اضافی در کنار خود هستند.

هر آرگومان دیگری به عنوان یک آرگومان URL تفسیر شده و مانند آن است که پس از گزینهٔ --url آمده باشد.

نخستین آرگومانی که دقیقاً دو خط تیره (--) باشد، نشان‌دهندهٔ پایان گزینه‌ها است؛ هر آرگومانی پس از پایان گزینه‌ها به عنوان یک آرگومان URL تفسیر می‌شود حتی اگر با خط تیره آغاز شود.

گزینه‌های بلند را می‌توان هم به صورت --flag argument و هم به صورت --flag=argument مشخص کرد.

افزودن داده به یک مؤلفه. این گزینه تنها می‌تواند داده را به مؤلفه‌های path و query اضافه کند.

برای path، بخش جدید را کدگذاری URL کرده و با یک اسلش (/) جدا نموده و به انتهای مسیر می‌افزاید.

برای query، بخش جدید را کدگذاری URL کرده و با علامت اتف (&) جدا نموده و به پرس‌وجو می‌افزاید. اگر بخش افزوده‌شده حاوی علامت مساوی (=) باشد، آن علامت بدون تغییر حفظ شده و دو طرف نخستین رخداد آن به‌طور جداگانه کدگذاری URL می‌شوند.

در صورت تعیین، trurl تلاش می‌کند فاصله‌ها (space) را به عنوان بخشی از URL بپذیرد و آن‌ها را به شکل مناسب کدگذاری URL کند.

طبق RFC 3986، فاصله نمی‌تواند به‌طور قانونی بخشی از یک URL باشد. این گزینه حداکثر تلاش ممکن را به کار می‌بندد تا رشتهٔ ارائه‌شده را به یک URL معتبر تبدیل کند.

یک نام میزبان اسکی punycode را به نام دامنهٔ بین‌المللی (IDN) اصلی آن در یونیکد (Unicode) تبدیل می‌کند. اگر نام میزبان از punycode استفاده نکند، همان نام میزبان اصلی به کار می‌رود.
فقط طرح‌واره‌های (schemes) نشانی وب را که توسط libcurl پشتیبانی می‌شوند می‌پذیرد.
در صورت تعیین، trurl برای نشانی‌های وب با طرح‌وارهٔ شناخته‌شده و بدون شماره درگاه صریح، از شماره پورت پیش‌فرض آن طرح‌واره استفاده می‌کند.

توجه داشته باشید که trurl فقط شماره پورت‌های پیش‌فرض طرح‌واره‌هایی را می‌شناسد که توسط libcurl پشتیبانی می‌شوند.

از آنجا که trurl به‌طور پیش‌فرض شماره پورت‌های پیش‌فرض را از نشانی‌های وب با طرح‌وارهٔ شناخته‌شده حذف می‌کند، این گزینه عملاً نادیده گرفته می‌شود مگر اینکه یکی از گزینه‌های --get، --json یا --keep-port نیز مشخص نشده باشد.

خواندن نشانی‌های وب برای پردازش از فایل داده‌شده. از نام فایل - (یک علامت منفی منفرد) استفاده کنید تا trurl نشانی‌ها را از ورودی استاندارد (stdin) بخواند.

هر خط باید شامل یک URL معتبر منفرد باشد. trurl در صورت وجود، یک نویسهٔ carriage return را در انتهای خط حذف می‌کند، تمام نویسه‌های فاصله و تب انتهایی را پاک کرده و از تمام خطوط خالی (پس از پیراستن) صرف‌نظر می‌کند.

حداکثر طول خط پشتیبانی‌شده در چنین فایلی ۴۰۹۴ بایت است. خطوطی که از این طول فراتر روند نادیده گرفته شده و هنگام مواجهه با آن‌ها هشداری در خروجی خطای استاندارد (stderr) چاپ می‌شود.

چاپ متن و داده‌های URL بر اساس رشتهٔ قالب‌بندی ارائه‌شده. مؤلفه‌های URL را می‌توان با مشخص کردن به صورت {component} یا [component] در خروجی نمایش داد، به طوری که نام بخش در میان آکولاد یا کروشه قرار گیرد. نمی‌توانید برای این منظور آکولاد و کروشه را در یک خط فرمان با یکدیگر ترکیب کنید.

نام‌های مؤلفهٔ زیر در دسترس هستند (حساس به حروف کوچک و بزرگ): url، scheme، user، password، options، host، port، path، query، fragment و zoneid.

اگر مؤلفهٔ داده‌شده مقداری نداشته باشد، {component} به هیچ متنی گسترش نمی‌یابد (خالی می‌ماند).

مؤلفه‌ها به‌طور پیش‌فرض به صورت رمزگشایی‌شده (URL decoded) نمایش داده می‌شوند.

رمزگشایی URL یک مؤلفه ممکن است مشکلاتی در نمایش آن ایجاد کند. چنین مشکلاتی باعث چاپ یک هشدار می‌شوند، مگر اینکه از گزینهٔ --quiet استفاده شود.

ابزار trurl از مجموعه‌ای از توصیف‌کننده‌ها یا پیشوندهای مختلف برای مؤلفه پشتیبانی می‌کند که نحوهٔ رفتار با آن را تغییر می‌دهند:

اگر url: مشخص شود، مانند {url:path}، مؤلفه به‌صورت کدگذاری‌شده (URL encoded) در خروجی قرار می‌گیرد. به عنوان میان‌بر، url: با نوشتن یک دو‌نقطهٔ تنها نیز کار می‌کند: {:path}.

اگر strict: مشخص شود، مانند {strict:path}، مشکلات رمزگشایی URL به خطا تبدیل می‌شوند. در این حالت سخت‌گیرانه‌تر، بروز مشکل در رمزگشایی URL موجب توقف کار trurl و بازگشت با کد خروج ۱۰ می‌شود.

اگر must: مشخص شود، مانند {must:query}، در صورتی که مؤلفهٔ درخواستی در URL وجود نداشته باشد trurl یک خطا برمی‌گرداند. به‌طور پیش‌فرض، یک مؤلفهٔ ناموجود فقط به صورت خالی نمایش داده می‌شود.

اگر default: مشخص شود، مانند {default:url} یا {default:port}، و پورت به‌طور صریح در URL مشخص نشده باشد، در صورت شناخته‌شده بودن، پورت پیش‌فرض طرح‌واره در خروجی قرار می‌گیرد.

اگر puny: مشخص شود، مانند {puny:url} یا {puny:host}، نسخهٔ punycode نام میزبان در خروجی استفاده می‌شود. این گزینه با idn: مانعة‌الجمع است.

اگر idn: مشخص شود، مانند {idn:url} یا {idn:host}، نسخهٔ نام دامنهٔ بین‌المللی (IDN) نام میزبان در خروجی استفاده می‌شود (چنانچه به صورت یک نسخهٔ punycode با کدگذاری صحیح ارائه شده باشد). این گزینه با puny: مانعة‌الجمع است.

اگر --default-port مشخص شود، تمام قالب‌ها به گونه‌ای بسط می‌یابند که گویی از default: استفاده کرده‌اند؛ و اگر --punycode به کار رود، تمام قالب‌ها به گونه‌ای بسط می‌یابند که گویی از puny: استفاده کرده‌اند. همچنین توجه داشته باشید که {url} تحت تأثیر گزینهٔ --keep-port قرار می‌گیرد.

میزبان‌هایی که به صورت نشانی‌های عددی IPv6 ارائه می‌شوند، درون کروشه قرار می‌گیرند؛ مانند [fe80::20c:29ff:fe9c:409b].

میزبان‌هایی که به صورت نشانی‌های عددی IPv4 ارائه می‌شوند، نرمال‌سازی شده و در خروجی به شکل چهار عدد ده‌دهی جداشده با نقطه ارائه می‌گردند.

می‌توانید با استفاده از قالب {query:key} به کلیدهای مشخصی در رشتهٔ پرس‌وجو (query) دسترسی پیدا کنید. در این حالت، مقدار نخستین کلید منطبق با استفاده از مقایسهٔ حساس به حروف کوچک و بزرگ در خروجی قرار می‌گیرد. هنگام استخراج یک کلید پرس‌وجوی رمزگشایی‌شده از URL که حاوی %00 باشد، این بایت در خروجی با یک نقطهٔ تنها . جایگزین می‌شود.

می‌توانید به کلیدهای مشخصی در رشتهٔ پرس‌وجو دسترسی داشته باشید و تمام مقادیر را با استفاده از قالب {query-all:key} دریافت کنید. این قالب، key را به صورت حساس به حروف کوچک و بزرگ جستجو کرده و تمام مقادیر آن کلید را جداشده با فاصله در خروجی چاپ می‌کند.

رشتهٔ format از دنباله‌های ممیز وارونه (backslash) زیر پشتیبانی می‌کند:

\ - ممیز وارونه (backslash)

\t - تب (tab)

\n - خط جدید (newline)

\r - بازگشت به ابتدای سطر (carriage return)

\{ - یک آکولاد باز که متغیری را شروع نمی‌کند

\[ - یک کروشه باز که متغیری را شروع نمی‌کند

تمام متن‌های دیگر در رشتهٔ قالب، عیناً نمایش داده می‌شوند.

نمایش خروجی راهنما.
تنظیم مؤلفه به چندین مقدار و چاپ نتیجه یک بار به ازای هر تکرار. چندین تکرار ترکیبی برای ایجاد حالات گوناگون مجاز است، اما برای هر مؤلفه تنها یک گزینهٔ --iterate می‌توان مشخص کرد. موارد فهرست‌شده برای تکرار باید با یک فاصله از یکدیگر جدا شوند.

مثال:

$ trurl example.com --iterate=scheme="ftp https" --iterate=port="22 80"
ftp://example.com:22/
ftp://example.com:80/
https://example.com:22
https://example.com:80
تمام مؤلفه‌های مقداردهی‌شده‌ی URLها را در قالب اشیاء JSON خروجی می‌دهد. تمام مؤلفه‌های URL که حاوی داده هستند، با استفاده از نام مؤلفه‌شان در شیء parts قرار می‌گیرند. برای جزئیات مربوط به قالب، به ادامه مراجعه کنید.
مؤلفه‌های URL به‌صورت رمزگشایی‌شده (URL decoded) ارائه می‌شوند. این رفتار را با --urlencode تغییر دهید.
به‌طور پیش‌فرض، trurl شماره درگاه‌های (port) پیش‌فرض را از URLهای دارای طرحواره (scheme) شناخته‌شده حذف می‌کند، حتی اگر به‌طور صریح در URL ورودی مشخص شده باشند. این گزینه باعث می‌شود trurl آن‌ها را حذف نکند.
مثال:
$ trurl https://example.com:443 --keep-port
https://example.com:443
قابلیت حدس زدن طرحواره (scheme) در libcurl' را غیرفعال می‌کند. با URLهایی که فاقد طرحواره هستند، به‌عنوان URLهای نامعتبر برخورد می‌شود.

مثال:

$ trurl example.com --no-guess-scheme
trurl note: Bad scheme [example.com]
از نگارش punycode نام میزبان (hostname) استفاده می‌کند، که روش تبدیل نام‌های دامنه بین‌المللی (IDN) به ASCII ساده است. اگر نام میزبان از IDN استفاده نکند، همان نام استاندارد ASCII به کار می‌رود.

مثال:

$ trurl http://åäö --punycode
http://xn--4cab6c
داده‌ها را از یک پرسمان (query) می‌پیراید.

مقدار what به‌صورت یک نام کامل از یک جفت نام/مقدار، یا به‌صورت یک پیشوند کلمه (با استفاده از یک ستاره‌ی پایانی (*)) مشخص می‌شود که باعث می‌شود trurl تاپل‌هایی را از رشته‌ی query که با دستورالعمل مطابقت دارند حذف کند.

برای تطبیق لفظی با یک ستاره‌ی پایانی به‌جای نویسه عمومی (wildcard)، یک بک‌اسلش پیش از آن قرار دهید (آن را escape کنید)؛ مانند \*.

تک‌نویسه‌ای را که برای جداسازی جفت‌های query استفاده می‌شود مشخص می‌کند. مقدار پیش‌فرض & است، اما دست‌کم در گذشته گاهی از نقطه‌ویرگول ; یا حتی دونقطه : برای این منظور استفاده شده است. اگر URL شما از چیزی غیر از نویسه پیش‌فرض استفاده می‌کند، تعیین نویسه درست تضمین می‌کند که trurl بتواند عملیات‌های query خود را به‌درستی انجام دهد.

مثال:

$ trurl "https://curl.se?b=name:a=age" --sort-query --query-separator ":"
https://curl.se/?a=age:b=name
فرونشاندن (برخی از) یادداشت‌ها و هشدارها.
تغییر مسیر دادن (redirect) URL به این مکان جدید. تغییر مسیر بر روی URL پایه انجام می‌شود، بنابراین اگر هیچ URL پایه‌ای مشخص نشده باشد، تغییر مسیری انجام نمی‌گیرد.

مثال:

$ trurl --url https://curl.se/we/are.html --redirect ../here.html
https://curl.se/here.html
یک query از URL را جایگزین می‌کند.

پارامتر data می‌تواند به شکل یک مقدار تکی، یا به‌صورت یک جفت کلید/مقدار در قالب foo=bar باشد. اگر replace روی موردی فراخوانی شود که در فهرست queries وجود ندارد، trurl از آن صرف‌نظر می‌کند.

دستور trurl هر دو طرف نویسه = را در آرگومان داده ورودی کدگذاری URL (URL encode) می‌کند.

مشابه --replace کار می‌کند، اما اگر رشته query در فهرست query وجود نداشته باشد، trurl آن را ضمیمه (append) می‌کند.
تنظیم این مؤلفه URL. مقداردهی با یک رشته خالی ("") مؤلفه را از URL پاک می‌کند.

مؤلفه‌های زیر قابل تنظیم هستند: url، scheme، user، password، options، host، port، path، query، fragment و zoneid.

اگر از یک انتساب ساده = استفاده شود، داده هنگام اعمال شدن کدگذاری URL (URL encoded) می‌شود. اگر از := استفاده شود، فرض می‌شود که داده از پیش URL encode شده است و همان‌طور که هست ذخیره می‌شود.

اگر از ?= استفاده شود، تنظیم تنها در صورتی انجام می‌گیرد که مؤلفه از قبل مقدار نداشته باشد. این کار از بازنویسی داده‌های موجود جلوگیری می‌کند.

همچنین در صورت تمایل می‌توانید : و ? را به‌صورت ?:= با یکدیگر ترکیب کنید.

اگر هیچ URL یا آرگومان --url-file ارائه نشود، trurl تلاش می‌کند تا با استفاده از مؤلفه‌های ارائه‌شده توسط گزینه‌های --set یک URL بسازد. اگر مؤلفه‌های کافی مشخص نشده باشند، این عملیات با خطا مواجه می‌شود.

تاپل‌های "variable=content" در مؤلفه query بر اساس حروف الفبا و بدون حساسیت به حروف بزرگ و کوچک مرتب می‌شوند. این کار به یکسان‌سازی URLهایی کمک می‌کند که تنها تفاوتشان در ترتیب قرارگیری جفت‌های query است.
منسوخ‌شده: از --qtrim استفاده کنید.

داده‌ها را از یک مؤلفه می‌پیراید. در حال حاضر این گزینه فقط می‌تواند مؤلفه query را بپیراید.

مقدار what به‌صورت یک کلمه کامل یا یک پیشوند کلمه (با استفاده از یک ستاره‌ی پایانی (*)) مشخص می‌شود که باعث می‌شود trurl تاپل‌هایی را از رشته query که با دستورالعمل مطابقت دارند حذف کند.

برای تطبیق لفظی با یک ستاره‌ی پایانی به‌جای نویسه عمومی (wildcard)، یک بک‌اسلش پیش از آن قرار دهید؛ مانند \*.

--url [URL]
تنظیم URL ورودی برای کار با آن. ممکن است URL بدون طرحواره (scheme) ارائه شود که در این حالت معمولاً در عمل یک URL معتبر نیست، اما trurl سعی می‌کند منظور را دریافته و scheme مناسب را حدس بزند (مگر اینکه از --no-guess-scheme استفاده شده باشد).

ارائه چند URL باعث می‌شود trurl به‌صورت متوالی روی تمام URLها عمل کند.

اگر URL به هر دلیلی قابل تجزیه نباشد، trurl به‌سادگی به سراغ URL بعدی می‌رود - مگر اینکه از --verify استفاده شده باشد.

هنگام استفاده از --get یا --json، خروجی مؤلفه‌ها را به‌طور پیش‌فرض به‌صورت کدگذاری‌شده (URL encoded) ارائه می‌دهد.
نمایش اطلاعات نگارش و خروج.
هنگام دریافت URL، در صورتی که نتواند به‌عنوان یک URL معتبر تجزیه شود، فوراً خطا بازمی‌گرداند. در شرایط عادی، trurl می‌تواند از ورودی‌های نامعتبر URL چشم‌پوشی کند..SH "مؤلفه‌های URL (URL COMPONENTS)"
این دنباله نویسه‌های ابتدایی یک URL است که شامل جداکننده «://» نمی‌شود. این مؤلفه را نمی‌توان به‌صورت URL-encoded تعیین کرد.

یک URL نمی‌تواند بدون scheme وجود داشته باشد، اما مگر در حالتی که از --no-guess-scheme استفاده شود، اگر مقداری ارائه نشده باشد trurl حدس می‌زند چه schemeای مد نظر بوده است.

مثال‌ها:

$ trurl https://odd -g '{scheme}'
https
$ trurl odd -g '{scheme}'
http
$ trurl odd -g '{scheme}' --no-guess-scheme
trurl note: Bad scheme [odd]
پس از جداکننده scheme، ممکن است یک نام کاربری (username) ارائه شود. اگر به یک دونقطه (:) ختم شود، گذرواژه ارائه شده است. اگر به نویسه ات‌ساین (@) ختم شود، هیچ گذرواژه‌ای در URL ارائه نشده است.

مثال:

$ trurl https://user%3a%40:secret@odd -g '{user}'
user:@
اگر گذرواژه به یک نقطه‌ویرگول (;) ختم شود، فیلد گزینه‌ها (options) به دنبال آن می‌آید. این فیلد در trurl تنها برای URLهایی که از طرحواره (scheme) IMAP استفاده می‌کنند پذیرفته می‌شود.

مثال:

$ trurl https://user:secr%65t@odd -g '{password}'
secret
این فیلد تنها می‌تواند به یک نویسه ات‌ساین (@) ختم شود که گزینه‌ها را از hostname جدا می‌کند. 
$ trurl 'imap://user:pwd;giraffe@odd' -g '{options}'
giraffe

اگر طرحواره (scheme) از نوع IMAP نباشد، بخش giraffe در عوض بخشی از گذرواژه در نظر گرفته می‌شود:

$ trurl 'sftp://user:pwd;giraffe@odd' -g '{password}'
pwd;giraffe

البته ما اکیداً به کاربران توصیه می‌کنیم برای کاهش احتمال بروز تداخل و سردرگمی، نویسه‌های ;، : و @ را در URLها به‌صورت %-encode کدگذاری کنند.

مؤلفه host همان نام میزبان (hostname) یا یک نشانی عددی IP است. اگر یک hostname ارائه شود، می‌تواند یک نام دامنه بین‌المللی (IDN) شامل نویسه‌های غیر ASCII باشد. یک hostname می‌تواند به‌صورت کدگذاری‌شده بر اساس URL (به‌صورت URL-encoded) نیز ارائه شود.

برنامه trurl گزینه‌هایی را برای کار با hostnameهای IDN، چه به‌صورت IDN و چه در نگارش punycode آن ارائه می‌دهد.

مثال، تبدیل یک نام IDN به punycode در خروجی:

$ trurl http://åäö --punycode
http://xn--4cab6c

یا برعکس، تبدیل یک hostname با فرمت punycode به نسخه IDN آن:

$ trurl http://xn--4cab6c --as-idn
http://åäö

اگر hostname در URL با یک براکت باز ([) آغاز شود، یک نشانی عددی IPv6 است که باید با یک براکت بسته (]) نیز پایان یابد. trurl نشانی‌های IPv6 را استانداردسازی (نرمال‌سازی) می‌کند.

مثال:

$ trurl 'http://[2001:9b1:0:0:0:0:7b97:364b]'
http://[2001:9b1::7b97:364b]

یک نشانی عددی IPv4 می‌تواند با استفاده از یک، دو، سه یا چهار عدد که با نقطه از هم جدا شده‌اند مشخص شود و این اعداد می‌توانند در مبنای ده‌دهی (decimal)، هشت‌هشتی (octal) یا شانزده‌شانزدهی (hexadecimal) باشند. trurl نشانی‌های ارائه‌شده را استانداردسازی کرده و در خروجی خود از چهار عدد ده‌دهیِ نقطه‌دار استفاده می‌کند.

مثال‌ها:

$ trurl http://646464646
http://38.136.68.134
$ trurl http://246.646
http://246.0.2.134
$ trurl http://246.46.646
http://246.46.2.134
$ trurl http://0x14.0xb3022
http://20.11.48.34
اگر میزبان مشخص‌شده یک نشانی IPv6 باشد، ممکن است شامل یک zoneid خاص باشد؛ که معمولاً یک عدد یا نام یک رابط شبکه (network interface) است.

مثال:

$ trurl 'http://[2001:9b1::f358:1ba4:7b97:364b%enp3s0]' -g '{zoneid}'
enp3s0
اگر میزبان به یک دونقطه (:) ختم شود، شماره درگاه (port) به دنبال آن می‌آید. این یک عدد ده‌دهی ۱۶ بیتی است که نباید به‌صورت URL-encoded مشخص شود.

برنامه trurl شماره درگاه پیش‌فرض را برای بسیاری از طرحواره‌های URL می‌داند، بنابراین می‌تواند شماره درگاه را برای یک URL نشان دهد حتی اگر هیچ درگاهی به‌طور صریح در URL استفاده نشده باشد. با گزینه --default-port می‌تواند درگاه پیش‌فرض را به URL بیفزاید حتی زمانی که ارائه نشده باشد.

مثال:

$ trurl http:/a --default-port
http://a:80

به‌طور مشابه، trurl معمولاً اگر شماره پورت داده‌شده همان پورت پیش‌فرض باشد، آن را پنهان می‌کند.

مثال:

$ trurl http:/a:80
http://a

اما کاربر می‌تواند با استفاده از گزینه --keep-port ترتیبی دهد که trurl حتی در صورت پیش‌فرض بودن نیز درگاه را حفظ کند.

مثال:

$ trurl http:/a:80 --keep-port
http://a:80
فرض بر این است که مسیر (path) در URL همیشه با حداقل یک اسلش (/) شروع شده و حاوی آن است، حتی اگر در واقع هیچ اسلشی در URL ارائه نشده باشد.

مثال:

$ trurl http://xn--4cab6c -g '[path]'
/

هنگام تنظیم مسیر، چنانچه هیچ اسلشی مشخص نشده باشد، trurl یک اسلش در ابتدای آن درج خواهد کرد:.nf $ trurl http://hello -s path="pony"; http://hello/pony 

$ trurl http://hello -s path="/pony"
http://hello/pony

اگر مسیر ورودی حاوی توالی‌های نقطه-نقطه (..) یا نقطه-اسلش (./) باشد، نرمال‌سازی شده و حذف می‌گردند.

مثال:

$ trurl http://hej/one/../two/../three/./four
http://hej/three/four

می‌توانید با استفاده از --append یک بخش جدید را به مسیر موجود اضافه کنید، مانند زیر:

$ trurl http://twelve/three?hello --append path=four
http://twelve/three/four?hello
بخش پرس‌وجو (query) هنگام استخراج با trurl، شامل علامت سؤال (?) آغازین جداکننده نمی‌شود.

مثال:

$ trurl http://horse?elephant -g '{query}'
elephant

برای مثال، اگر query را با یک علامت سؤال آغازین تنظیم کنید:

$ trurl http://horse?elephant -s "query=?elephant"
http://horse/?%3felephant

بخش‌های query اغلب از مجموعه‌ای از جفت‌های name=value تشکیل شده‌اند که با علامت امپرسند (&) از یکدیگر جدا می‌شوند، و trurl روش‌های متعددی را برای کار با آن‌ها ارائه می‌دهد.

الحاق یک جفت نام و مقدار جدید به یک URL با --append:

$ trurl http://host?name=hello --append query=search=life
http://host/?name=hello&search=life

می‌توانید با --replace مقدار یک نامِ خاصِ موجود را در میان جفت‌ها جایگزین کنید:

$ trurl 'http://alpha?one=real&two=fake' --replace two=alsoreal
http://alpha/?one=real&two=alsoreal

اگر نام مشخصی که می‌خواهید جایگزین کنید در URL وجود نداشته باشد، می‌توانید جایگزینی یا الحاق جفت را انتخاب کنید:

$ trurl 'http://alpha?one=real&two=fake' --replace-append three=alsoreal
http://alpha/?one=real&two=fake&three=alsoreal

به منظور مقایسه احتمالی دو URL با استفاده از جفت‌های نام و مقدارِ query، مرتب‌سازی اولیه آن‌ها حداقل شانس رسیدن به نتیجه درست را افزایش می‌دهد:

$ trurl "http://alpha/?one=real&two=fake&three=alsoreal" --sort-query
http://alpha/?one=real&three=alsoreal&two=fake

حذف جفت‌های نام/مقدار از URL با تعیین نام دقیق یا الگوی عامه‌نما (wildcard) از طریق --qtrim:

$ trurl 'https://example.com?a12=hej&a23=moo&b12=foo' --qtrim a*'
https://example.com/?b12=foo
بخش قطعه (fragment) هنگام استخراج با trurl، شامل علامت هش (#) آغازین جداکننده نمی‌شود.

مثال:

$ trurl http://horse#elephant -g '{fragment}'
elephant

برای مثال، اگر fragment را با یک علامت هش آغازین تنظیم کنید:

$ trurl "http://horse#elephant" -s "fragment=#zebra"
http://horse/#%23zebra

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

ابزار trurl از url به عنوان یک مؤلفه نام‌گذاری‌شده برای --get پشتیبانی می‌کند تا امکان خروجی‌های قدرتمندتری را فراهم آورد، اما مشخصاً این مقدار در واقع یک «مؤلفه» نیست؛ بلکه کل URL است.

مثال:

$ trurl ftps://example.com:2021/p%61th -g '{url}'
ftps://example.com:2021/path
گزینهٔ --json یک آرایهٔ JSON حاوی یک یا چند شیء را خروجی می‌دهد؛ یکی برای
هر URL. هر شیء JSON مربوط به URL شامل چندین ویژگی، مجموعه‌ای از
جفت‌های کلید/مقدار است. مجموعهٔ دقیق موارد موجود به URL ارائه‌شده بستگی دارد.
این کلید در تمام اشیاء وجود دارد. این همان URL کامل است. تحت تأثیر
--default-port، --keep-port و --punycode قرار می‌گیرد.
این کلید در تمام اشیاء وجود دارد و شامل شیئی با یک کلید برای هر یک از
مؤلفه‌های قابل تنظیم URL است. اگر مؤلفه‌ای وجود نداشته باشد، به این معنی است که
در URL موجود نیست. بخش‌ها رمزگشایی URL می‌شوند، مگر اینکه --urlencode استفاده شود.
طرح‌وارهٔ (scheme) مربوط به URL.
نام کاربری.
گذرواژه.
گزینه‌ها. توجه داشته باشید که تنها تعداد کمی از طرح‌واره‌های URL از مؤلفهٔ «options»
پشتیبانی می‌کنند.
نام میزبان نرمال‌شده. در صورتی که از نام IDN استفاده شده باشد، ممکن است یک نام UTF-8 باشد.
همچنین می‌تواند یک نشانی نرمال‌شدهٔ IPv4 یا IPv6 باشد. یک نشانی IPv6 همواره با
یک قلاب ([) آغاز می‌شود - و هیچ نام میزبان دیگری نمی‌تواند حاوی چنین نمادی باشد. اگر
--punycode استفاده شود، نسخهٔ punycode میزبان در خروجی قرار می‌گیرد.
شماره درگاه ارائه‌شده به‌صورت رشته. اگر شماره درگاه در
URL ارائه نشده باشد، اما طرح‌واره شناخته‌شده باشد و --default-port در حال استفاده باشد،
درگاه پیش‌فرض برای آن طرح‌واره در اینجا ارائه می‌شود.
مسیر؛ شامل ممیز اسلش آغازین.
پرس‌وجوی کامل (query)، بدون علامت سوال جداکننده.
بخش فرگمنت (fragment)، بدون علامت هش جداکننده.
شناسهٔ ناحیه (zone id) که تنها می‌تواند در یک نشانی IPv6 وجود داشته باشد. هنگامی که این کلید
موجود است، آن‌گاه host یک نشانی عددی IPv6 است.
این کلید حاوی آرایه‌ای از اشیاء کلید/مقدار پرس‌وجو است. هر جفت با
«key» و «value» و محتوای مربوط به آن‌ها در خروجی فهرست می‌شود.
کلید/مقدارها از بخش پرس‌وجو استخراج می‌شوند؛ جایی که با علامت‌های
امپرسند (&) - یا آنچه کاربر با --query-separator تنظیم کرده است - جدا شده‌اند.
جفت‌های پرس‌وجو به ترتیب حضور از چپ به راست فهرست می‌شوند،
اما می‌توان با --sort-query آن‌ها را به‌صورت الفبایی مرتب کرد.
این کلید تنها در صورتی وجود دارد که URL دارای پرس‌وجو باشد.

جایگزینی نام میزبان یک URL
$ trurl --url https://curl.se --set host=example.com
https://example.com
ایجاد یک URL با تنظیم مؤلفه‌ها
$ trurl --set host=example.com --set scheme=ftp
ftp://example.com/
تغییر مسیر یک URL
$ trurl --url https://curl.se/we/are.html --redirect here.html
https://curl.se/we/here.html
تغییر شماره درگاه
این مثال همچنین نشان می‌دهد که trurl چگونه توالی‌های نقطه-نقطه (..) را حذف می‌کند 
$ trurl --url https://curl.se/we/../are.html --set port=8080
https://curl.se:8080/are.html
استخراج مسیر از یک URL
$ trurl --url https://curl.se/we/are.html --get '{path}'
/we/are.html
استخراج درگاه از یک URL
اگر درگاه در URL تنظیم نشده باشد، این دستور درگاه پیش‌فرض را بر اساس طرح‌واره دریافت می‌کند. 
$ trurl --url https://curl.se/we/are.html --get '{default:port}'
443
افزودن یک بخش مسیر به URL
$ trurl --url https://curl.se/hello --append path=you
https://curl.se/hello/you
افزودن یک بخش پرس‌وجو به URL
$ trurl --url "https://curl.se?name=hello" --append query=search=string
 https://curl.se/?name=hello&search=string
خواندن URLها از stdin
$ cat urllist.txt | trurl --url-file -
...
خروجی JSON
$ trurl "https://fake.host/search?q=answers&user=me#frag" --json
[
  {
    "url": "https://fake.host/search?q=answers&user=me#frag",
    "parts": [
        "scheme": "https",
        "host": "fake.host",
        "path": "/search",
        "query": "q=answers&user=me"
        "fragment": "frag",
    ],
    "params": [
      {
        "key": "q",
        "value": "answers"
      },
      {
        "key": "user",
        "value": "me"
      }
    ]
  }
]
حذف چندتایی‌های رهگیری از پرس‌وجو
$ trurl "https://curl.se?search=hey&utm_source=tracker" --qtrim "utm_*"
https://curl.se/?search=hey
نمایش مقدار یک کلید خاص در پرس‌وجو
$ trurl "https://example.com?a=home&here=now&thisthen" -g '{query:a}'
home
مرتب‌سازی جفت‌های کلید/مقدار در مؤلفهٔ پرس‌وجو
$ trurl "https://example.com?b=a&c=b&a=c" --sort-query
https://example.com?a=c&b=a&c=b
کار با پرس‌وجویی که از جداکنندهٔ نقطه‌ویرگول استفاده می‌کند
$ trurl "https://curl.se?search=fool;page=5" --qtrim "search" --query-separator ";"
https://curl.se?page=5
پذیرش فاصله در مسیر URL
$ trurl "https://curl.se/this has space/index.html" --accept-space
https://curl.se/this%20has%20space/index.html
ایجاد چندین نگارش از یک URL با طرح‌واره‌های مختلف
$ trurl "https://curl.se/path/index.html" --iterate "scheme=http ftp sftp"
http://curl.se/path/index.html
ftp://curl.se/path/index.html
sftp://curl.se/path/index.html
دستور trurl برای نشان دادن مشکلات، یک کد خروج غیرصفر بازمی‌گرداند.
1
مشکل در --url-file
2
مشکل در --append
3
یک گزینه خط فرمان فاقد آرگومان است
4
اشتباه در گزینه خط فرمان یا ترکیب غیرمجاز گزینه‌ها.
5
مشکل در --set
6
کمبود حافظه
7
امکان خروجی دادن یک URL معتبر وجود نداشت
8
مشکل در --qtrim
9
اگر --verify تنظیم شده باشد و URL ورودی قابل تجزیه نباشد.
10
مشکل در --get
11
مشکل در --iterate
12
مشکل در --replace یا --replace-append

https://curl.se/trurl

curl(1), wcurl(1)

2025-05-12 trurl