.\" generated by cd2nroff 0.1 from trurl.md
.TH trurl 1 "2025-05-12" trurl 0.16.1
.SH "نام (NAME)"
trurl \- ترانهش و دستکاری نشانی‌های وب (URL)
.SH "خلاصه دستور (SYNOPSIS)"
\fBtrurl [گزینه‌ها / URLs]\fP
.SH "توضیحات (DESCRIPTION)"
دستور \fBtrurl\fP نشانی‌های وب (URL) و بخش‌های مختلف آن‌ها را تجزیه، دستکاری و در خروجی چاپ می‌کند.

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

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

ابزار trurl ساختار URL را می‌شناسد و هر URL از حداکثر ده \fIمؤلفه\fP (component) مجزا و مستقل تشکیل شده است. این مؤلفه‌ها را می‌توان با trurl استخراج، حذف و به‌روزرسانی کرد و با نام‌های مربوطه‌شان به آن‌ها ارجاع داده می‌شود: scheme، user، password، options، host، port، path، query، fragment و zoneid.
.SH "نرمال‌سازی (NORMALIZATION)"
هنگامی که یک URL برای کار به trurl داده می‌شود، آن را «نرمال‌سازی» می‌کند. بدین معنا که مؤلفه‌های مجزای URL ابتدا رمزگشایی (URL decode) شده، سپس مجدداً کدگذاری (URL encode) شده و در URL قرار می‌گیرند.

مثال:

.nf
$ trurl 'http://ex%61mple:80/%62ath/a/../b?%2e%FF#tes%74'
http://example/bath/b?.%ff#test
.fi
.SH "گزینه‌ها (OPTIONS)"
گزینه‌ها با یک یا دو خط تیره شروع می‌شوند. بسیاری از گزینه‌ها نیازمند یک مقدار اضافی در کنار خود هستند.

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

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

گزینه‌های بلند را می‌توان هم به صورت \fI\--flag argument\fP و هم به صورت \fI\--flag=argument\fP مشخص کرد.
.IP "-a, --append [component]=[data]"
افزودن داده به یک مؤلفه. این گزینه تنها می‌تواند داده را به مؤلفه‌های path و query اضافه کند.

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

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

طبق RFC 3986، فاصله نمی‌تواند به‌طور قانونی بخشی از یک URL باشد. این گزینه حداکثر تلاش ممکن را به کار می‌بندد تا رشتهٔ ارائه‌شده را به یک URL معتبر تبدیل کند.
.IP --as-idn
یک نام میزبان اسکی punycode را به نام دامنهٔ بین‌المللی (IDN) اصلی آن در یونیکد (Unicode) تبدیل می‌کند. اگر نام میزبان از punycode استفاده نکند، همان نام میزبان اصلی به کار می‌رود.
.IP --curl
فقط طرح‌واره‌های (schemes) نشانی وب را که توسط libcurl پشتیبانی می‌شوند می‌پذیرد.
.IP --default-port
در صورت تعیین، trurl برای نشانی‌های وب با طرح‌وارهٔ شناخته‌شده و بدون شماره درگاه صریح، از شماره پورت پیش‌فرض آن طرح‌واره استفاده می‌کند.

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

از آنجا که trurl به‌طور پیش‌فرض شماره پورت‌های پیش‌فرض را از نشانی‌های وب با طرح‌وارهٔ شناخته‌شده حذف می‌کند، این گزینه عملاً نادیده گرفته می‌شود مگر اینکه یکی از گزینه‌های \fI\--get\fP، \fI\--json\fP یا \fI\--keep\-port\fP نیز مشخص نشده باشد.
.IP "-f, --url-file [filename]"
خواندن نشانی‌های وب برای پردازش از فایل داده‌شده. از نام فایل \fI\-\fP (یک علامت منفی منفرد) استفاده کنید تا trurl نشانی‌ها را از ورودی استاندارد (stdin) بخواند.

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

حداکثر طول خط پشتیبانی‌شده در چنین فایلی ۴۰۹۴ بایت است. خطوطی که از این طول فراتر روند نادیده گرفته شده و هنگام مواجهه با آن‌ها هشداری در خروجی خطای استاندارد (stderr) چاپ می‌شود.
.IP "-g, --get [format]"
چاپ متن و داده‌های URL بر اساس رشتهٔ قالب‌بندی ارائه‌شده. مؤلفه‌های URL را می‌توان با مشخص کردن به صورت \fB{component}\fP یا \fB[component]\fP در خروجی نمایش داد، به طوری که نام بخش در میان آکولاد یا کروشه قرار گیرد. نمی‌توانید برای این منظور آکولاد و کروشه را در یک خط فرمان با یکدیگر ترکیب کنید.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

\\t \- تب (tab)

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

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

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

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

تمام متن‌های دیگر در رشتهٔ قالب، عیناً نمایش داده می‌شوند.
.IP "-h, --help"
نمایش خروجی راهنما.
.IP "--iterate [component]=[item1 item2 ...]"
تنظیم مؤلفه به چندین مقدار و چاپ نتیجه یک بار به ازای هر تکرار. چندین تکرار ترکیبی برای ایجاد حالات گوناگون مجاز است، اما برای هر مؤلفه تنها یک گزینهٔ \fI\--iterate\fP می‌توان مشخص کرد. موارد فهرست‌شده برای تکرار باید با یک فاصله از یکدیگر جدا شوند.

مثال:

.nf
$ 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
.fi.IP --json
تمام مؤلفه‌های مقداردهی‌شده‌ی URLها را در قالب اشیاء JSON خروجی می‌دهد. تمام مؤلفه‌های URL که حاوی داده هستند، با استفاده از نام مؤلفه‌شان در شیء parts قرار می‌گیرند. برای جزئیات مربوط به قالب، به ادامه مراجعه کنید.

مؤلفه‌های URL به‌صورت رمزگشایی‌شده (URL decoded) ارائه می‌شوند. این رفتار را با \fB\--urlencode\fP تغییر دهید.
.IP --keep-port
به‌طور پیش‌فرض، trurl شماره درگاه‌های (port) پیش‌فرض را از URLهای دارای طرحواره (scheme) شناخته‌شده حذف می‌کند، حتی اگر به‌طور صریح در URL ورودی مشخص شده باشند. این گزینه باعث می‌شود trurl آن‌ها را حذف نکند.

مثال:

.nf
$ trurl https://example.com:443 --keep-port
https://example.com:443
.fi
.IP --no-guess-scheme
قابلیت حدس زدن طرحواره (scheme) در libcurl\(aq را غیرفعال می‌کند. با URLهایی که فاقد طرحواره هستند، به‌عنوان URLهای نامعتبر برخورد می‌شود.

مثال:

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

مثال:

.nf
$ trurl http://åäö --punycode
http://xn--4cab6c
.fi
.IP "--qtrim [what]"
داده‌ها را از یک پرسمان (query) می‌پیراید.

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

برای تطبیق لفظی با یک ستاره‌ی پایانی به‌جای نویسه عمومی (wildcard)، یک بک‌اسلش پیش از آن قرار دهید (آن را escape کنید)؛ مانند \fI\\*\fP.
.IP "--query-separator [what]"
تک‌نویسه‌ای را که برای جداسازی جفت‌های query استفاده می‌شود مشخص می‌کند. مقدار پیش‌فرض \fI&\fP است، اما دست‌کم در گذشته گاهی از نقطه‌ویرگول \fI;\fP یا حتی دونقطه \fI:\fP برای این منظور استفاده شده است. اگر URL شما از چیزی غیر از نویسه پیش‌فرض استفاده می‌کند، تعیین نویسه درست تضمین می‌کند که trurl بتواند عملیات‌های query خود را به‌درستی انجام دهد.

مثال:

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

مثال:

.nf
$ trurl --url https://curl.se/we/are.html --redirect ../here.html
https://curl.se/here.html
.fi
.IP "--replace [data]"
یک query از URL را جایگزین می‌کند.

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

دستور trurl هر دو طرف نویسه \fI=\fP را در آرگومان داده ورودی کدگذاری URL (URL encode) می‌کند.
.IP "--replace-append [data]"
مشابه \fI\--replace\fP کار می‌کند، اما اگر رشته query در فهرست query وجود نداشته باشد، trurl آن را ضمیمه (append) می‌کند.
.IP "-s, --set [component][:]=[data]"
تنظیم این مؤلفه URL. مقداردهی با یک رشته خالی (\fI""\fP) مؤلفه را از URL پاک می‌کند.

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

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

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

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

اگر هیچ URL یا آرگومان \fI\--url\-file\fP ارائه نشود، trurl تلاش می‌کند تا با استفاده از مؤلفه‌های ارائه‌شده توسط گزینه‌های \fI\--set\fP یک URL بسازد. اگر مؤلفه‌های کافی مشخص نشده باشند، این عملیات با خطا مواجه می‌شود.
.IP --sort-query
تاپل‌های "variable=content" در مؤلفه query بر اساس حروف الفبا و بدون حساسیت به حروف بزرگ و کوچک مرتب می‌شوند. این کار به یکسان‌سازی URLهایی کمک می‌کند که تنها تفاوتشان در ترتیب قرارگیری جفت‌های query است.
.IP "--trim [component]=[what]"
منسوخ‌شده: از \fB\--qtrim\fP استفاده کنید.

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

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

برای تطبیق لفظی با یک ستاره‌ی پایانی به‌جای نویسه عمومی (wildcard)، یک بک‌اسلش پیش از آن قرار دهید؛ مانند \fI\\*\fP.
.IP "--url [URL]"
تنظیم URL ورودی برای کار با آن. ممکن است URL بدون طرحواره (scheme) ارائه شود که در این حالت معمولاً در عمل یک URL معتبر نیست، اما trurl سعی می‌کند منظور را دریافته و scheme مناسب را حدس بزند (مگر اینکه از \fI\--no\-guess\-scheme\fP استفاده شده باشد).

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

اگر URL به هر دلیلی قابل تجزیه نباشد، trurl به‌سادگی به سراغ URL بعدی می‌رود \- مگر اینکه از \fI\--verify\fP استفاده شده باشد.
.IP --urlencode
هنگام استفاده از \fI\--get\fP یا \fI\--json\fP، خروجی مؤلفه‌ها را به‌طور پیش‌فرض به‌صورت کدگذاری‌شده (URL encoded) ارائه می‌دهد.
.IP "-v, --version"
نمایش اطلاعات نگارش و خروج.
.IP --verify
هنگام دریافت URL، در صورتی که نتواند به‌عنوان یک URL معتبر تجزیه شود، فوراً خطا بازمی‌گرداند. در شرایط عادی، trurl می‌تواند از ورودی‌های نامعتبر URL چشم‌پوشی کند..SH "مؤلفه‌های URL (URL COMPONENTS)"
.IP scheme
این دنباله نویسه‌های ابتدایی یک URL است که شامل جداکننده «://» نمی‌شود. این مؤلفه را نمی‌توان به‌صورت URL-encoded تعیین کرد.

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

مثال‌ها:

.nf
$ trurl https://odd -g '{scheme}'
https
.fi

.nf
$ trurl odd -g '{scheme}'
http
.fi

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

مثال:

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

مثال:

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

.nf
$ trurl 'imap://user:pwd;giraffe@odd' -g '{options}'
giraffe
.fi

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

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

البته ما اکیداً به کاربران توصیه می‌کنیم برای کاهش احتمال بروز تداخل و سردرگمی، نویسه‌های \fI;\fP، \fI:\fP و \fI@\fP را در URLها به‌صورت %\-encode کدگذاری کنند.
.IP host
مؤلفه host همان نام میزبان (hostname) یا یک نشانی عددی IP است. اگر یک hostname ارائه شود، می‌تواند یک نام دامنه بین‌المللی (IDN) شامل نویسه‌های غیر ASCII باشد. یک hostname می‌تواند به‌صورت کدگذاری‌شده بر اساس URL (به‌صورت URL-encoded) نیز ارائه شود.

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

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

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

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

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

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

مثال:

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

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

مثال‌ها:

.nf
$ trurl http://646464646
http://38.136.68.134
.fi

.nf
$ trurl http://246.646
http://246.0.2.134
.fi

.nf
$ trurl http://246.46.646
http://246.46.2.134
.fi

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

مثال:

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

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

مثال:

.nf
$ trurl http:/a --default-port
http://a:80
.fi

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

مثال:

.nf
$ trurl http:/a:80
http://a
.fi

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

مثال:

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

مثال:

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

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

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

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

مثال:

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

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

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

مثال:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

مثال:

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

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

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

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

مثال:

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

کلید/مقدارها از بخش پرس‌وجو استخراج می‌شوند؛ جایی که با علامت‌های
امپرسند (\fB&\fP) \- یا آنچه کاربر با \fB\--query\-separator\fP تنظیم کرده است \- جدا شده‌اند.

جفت‌های پرس‌وجو به ترتیب حضور از چپ به راست فهرست می‌شوند،
اما می‌توان با \fB\--sort\-query\fP آن‌ها را به‌صورت الفبایی مرتب کرد.

این کلید تنها در صورتی وجود دارد که URL دارای پرس‌وجو باشد.
.SH "مثال‌ها (EXAMPLES)"
.IP "جایگزینی نام میزبان یک URL"
.nf
$ trurl --url https://curl.se --set host=example.com
https://example.com
.fi
.IP "ایجاد یک URL با تنظیم مؤلفه‌ها"
.nf
 $ trurl --set host=example.com --set scheme=ftp
 ftp://example.com/
.fi
.IP "تغییر مسیر یک URL"
.nf
$ trurl --url https://curl.se/we/are.html --redirect here.html
https://curl.se/we/here.html
.fi
.IP "تغییر شماره درگاه"
این مثال همچنین نشان می‌دهد که trurl چگونه توالی‌های نقطه\-نقطه (..) را حذف می‌کند
.nf
$ trurl --url https://curl.se/we/../are.html --set port=8080
https://curl.se:8080/are.html
.fi
.IP "استخراج مسیر از یک URL"
.nf
$ trurl --url https://curl.se/we/are.html --get '{path}'
/we/are.html
.fi
.IP "استخراج درگاه از یک URL"
اگر درگاه در URL تنظیم نشده باشد، این دستور درگاه پیش‌فرض را بر اساس
طرح‌واره دریافت می‌کند.
.nf
$ trurl --url https://curl.se/we/are.html --get '{default:port}'
443
.fi
.IP "افزودن یک بخش مسیر به URL"
.nf
$ trurl --url https://curl.se/hello --append path=you
https://curl.se/hello/you
.fi
.IP "افزودن یک بخش پرس‌وجو به URL"
.nf
$ trurl --url "https://curl.se?name=hello" --append query=search=string
 https://curl.se/?name=hello&search=string
.fi
.IP "خواندن URLها از stdin"
.nf
$ cat urllist.txt | trurl --url-file -
\&...
.fi
.IP "خروجی JSON"
.nf
$ 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"
      }
    ]
  }
]
.fi
.IP "حذف چندتایی‌های رهگیری از پرس‌وجو"
.nf
$ trurl "https://curl.se?search=hey&utm_source=tracker" --qtrim "utm_*"
https://curl.se/?search=hey
.fi
.IP "نمایش مقدار یک کلید خاص در پرس‌وجو"
.nf
$ trurl "https://example.com?a=home&here=now&thisthen" -g '{query:a}'
home
.fi
.IP "مرتب‌سازی جفت‌های کلید/مقدار در مؤلفهٔ پرس‌وجو"
.nf
$ trurl "https://example.com?b=a&c=b&a=c" --sort-query
https://example.com?a=c&b=a&c=b
.fi
.IP "کار با پرس‌وجویی که از جداکنندهٔ نقطه‌ویرگول استفاده می‌کند"
.nf
$ trurl "https://curl.se?search=fool;page=5" --qtrim "search" --query-separator ";"
https://curl.se?page=5
.fi
.IP "پذیرش فاصله در مسیر URL"
.nf
$ trurl "https://curl.se/this has space/index.html" --accept-space
https://curl.se/this%20has%20space/index.html
.fi
.IP "ایجاد چندین نگارش از یک URL با طرح‌واره‌های مختلف"
.nf
$ 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
.fi.SH "کدهای خروج (EXIT CODES)"
دستور trurl برای نشان دادن مشکلات، یک کد خروج غیرصفر بازمی‌گرداند.
.IP 1
مشکل در \--url\-file
.IP 2
مشکل در \--append
.IP 3
یک گزینه خط فرمان فاقد آرگومان است
.IP 4
اشتباه در گزینه خط فرمان یا ترکیب غیرمجاز گزینه‌ها.
.IP 5
مشکل در \--set
.IP 6
کمبود حافظه
.IP 7
امکان خروجی دادن یک URL معتبر وجود نداشت
.IP 8
مشکل در \--qtrim
.IP 9
اگر \--verify تنظیم شده باشد و URL ورودی قابل تجزیه نباشد.
.IP 10
مشکل در \--get
.IP 11
مشکل در \--iterate
.IP 12
مشکل در \--replace یا \--replace\-append
.SH "وبگاه (WWW)"
https://curl.se/trurl
.SH "همچنین ببینید (SEE ALSO)"
.BR curl (1),
.BR wcurl (1)