حلّل وسيطات سطر الأوامر وفق مواصفات محددة
صرّح بالمفاتيح والخيارات التي يقبلها برنامجك فيُرتَّب سطر الأوامر: يصبح --tag=stable --tag latest وسمين هما stable وlatest، ويبقى src.js وسيطاً حراً، ويُبلَّغ عن --mystery على أنه مجهول. مجاناً في متصفحك.
- مجاني
- يعمل في متصفحك
- دون تسجيل
- بياناتك لا تغادر جهازك
شغّل الأداة مجانًا
تعمل هذه الأداة داخل متصفحك — مجانًا، ولا تُرسل بياناتك إلى أي خادم
حوّل مصفوفة وسيطات سطر الأوامر الخام إلى كائن منتظم يمكن توقّع بنيته، من دون توزيع قواعد التحليل في أجزاء تطبيقكم. قدّموا العناصر ومواصفات موجزة تسمّي كل علم منطقي وكل خيار يتطلب قيمة. تؤدي المواصفات غير الصحيحة والوسيطات المكررة والخيارات التي تفتقد قيمتها الإلزامية إلى أخطاء إدخال واضحة.
صفوا واجهة سطر الأوامر في صورة بيانات
ابدؤوا بعناصر الوسيطات كما يقدّمها نظام التشغيل بعد حذف اسم الملف التنفيذي واسم البرنامج النصي. عرّفوا بعد ذلك كل وسيط مقبول ضمن المواصفات. يتضمن كل إدخال اسماً قياسياً واسماً بديلاً واحداً أو أكثر ونوعاً.
استخدموا flag للمفتاح الذي يعني وجوده القيمة الصحيحة، مثل <code>--verbose</code>. واستخدموا option عندما يجب أن تتبع الصيغة قيمة، مثل <code>--output result.json</code>. تستخدم الأسماء القياسية حروفاً إنجليزية صغيرة وأرقاماً وشرطات سفلية، كي يصبح الكائن الناتج صالحاً للاستهلاك من دون مرحلة إعادة تسمية.
يرفض المحلل تكرار الأسماء القياسية أو البديلة لأن هذا التعارض سيجعل النتيجة رهينة لترتيب التعريف. اضبطوا <code>multiple</code> فقط إذا كان تكرار الوسيط جزءاً مقصوداً من الواجهة؛ وعندئذ تعاد القيم بحسب ترتيب ظهورها.
افهموا تحليل العناصر وبنية الناتج
تفصل النتيجة بين القيم المعروفة والعناصر الموضعية والأعلام المجهولة. يتحول العلم المعروف إلى القيمة الصحيحة تحت اسمه القياسي، بينما يخزن الخيار العنصر الذي يليه. ويمكن للخيار الطويل أن يحمل قيمته في العنصر نفسه، كما في <code>--format=json</code>.
تتطلب المطابقة تطابقاً تاماً؛ فلا تُفكك مجموعات الأعلام القصيرة مثل <code>-abc</code> ما لم تُدرج الصيغة كاملة اسماً بديلاً. أما العناصر المجهولة الأخرى فتعد قيماً موضعية. تنهي <code>--</code> المستقلة معالجة الخيارات، وتصبح جميع العناصر اللاحقة موضعية حتى لو بدأت بشرطة.
يزيل هذا الأسلوب المتعارف عليه الالتباس عن أسماء ملفات مثل <code>-draft.txt</code>. لا ينشئ المحلل قيماً افتراضية ولا يحوّل النصوص إلى أرقام، لأن هذه السياسات تخص التطبيق وقد تخفي أخطاء المستخدم. الناتج حتمي ويحافظ على ترتيب العناصر الموضعية والمجهولة.
تعاملوا بأمان مع القيم الناقصة والتكرار
يتطلب كل إدخال من نوع option قيمة غير فارغة كلما ظهر أحد أسمائه البديلة. إذا كان الاسم البديل آخر عنصر، أو جاء قبل علامة إنهاء الخيارات، أو تبعه عنصر آخر يشبه علماً، يفشل التحليل بخطأ إدخال يذكر الاسم البديل المتسبب بالمشكلة. وتنطبق القاعدة نفسها على الصيغة الملحقة الفارغة مثل <code>--output=</code>.
يمنع هذا السلوك الصارم استهلاك علم تالٍ باعتباره بيانات من دون تنبيه، ويعالج مباشرة أحد أخطر أخطاء تحليل سطر الأوامر. يمكن مع ذلك استخدام شرطة منفردة قيمةً، وهو أمر مفيد للبرامج التي تمثل الإدخال أو الإخراج القياسي بالرمز <code>-</code>. يؤدي تكرار الوسيط المعروف افتراضياً إلى خطأ أيضاً.
أعلنوا <code>multiple: true</code> عندما يكون التكرار صحيحاً، مثل مسارات التضمين أو التصنيفات المتعددة؛ وستحتوي الخاصية القياسية حينها دائماً على مصفوفة. يبلّغ المحلل عن الأعلام المجهولة ولا يوقف التنفيذ بسببها، فتظل سياسة التوافق والتمرير تحت تحكمكم.
حالات الاستخدام
تحققوا من مغلف CLI
حلّلوا خيارات المغلف الخاصة وأبلغوا عن الأعلام غير المدعومة قبل تشغيل العملية المغلفة.
وحّدوا الخيارات القصيرة والطويلة
اربطوا أسماء بديلة مثل -o و--output بخاصية ثابتة واحدة لتبسيط منطق التطبيق.
أنشئوا معاينات واختبارات للأوامر
حوّلوا مصفوفات العناصر إلى تجهيزات منظمة وحتمية من دون تنفيذ أمر أو الوصول إلى صدفة أوامر.
الأسئلة الشائعة
ما التكلفة؟
تنفذ نسخة المتصفح منطق التحليل الحتمي نفسه محلياً.
هل تدعم الصيغة --name=value؟
نعم، للخيارات الطويلة التي تتطلب قيمة. تؤدي القيمة الفارغة بعد علامة المساواة إلى خطأ.
ماذا يحدث بعد شرطتين مستقلتين؟
يتوقف تحليل الخيارات، وتُعاد جميع العناصر المتبقية بوصفها وسيطات موضعية.
هل يمكن أن يملأ -o و--output الخيار نفسه؟
نعم. صرّح بالكتابتين تحت اسم واحد، فتحفظ أي منهما قيمتها هناك، وتعطي الصيغة القصيرة والطويلة النتيجة نفسها. ويُرفض خياران يتشاركان الكتابة نفسها، لأن النتيجة ستتوقف عندئذ على ترتيب التصريح.
ماذا يحدث إذا نقصت قيمة أحد الخيارات؟
تتوقف القراءة برسالة خطأ واضحة تذكر الكتابة المسببة. يحدث ذلك عندما يكون الخيار آخر كلمة، أو يأتي قبل الشرطتين مباشرة، أو يتبعه علم آخر، فلا يُبتلع مفتاح لاحق على أنه قيمة أبداً.
أدوات ذات صلة
للمطوّرين — الوصول عبر API
كل ما في هذه الصفحة متاح برمجيًا. هذا القسم موجّه للفرق التقنية التي تريد ربط الأداة بأنظمتها الخاصة؛ بقية المستخدمين يمكنهم استخدام الأداة أعلاه مباشرة دون الحاجة لقراءة ما يلي.
الـEndpoint
صادِق على طلبك بترويسة Bearer، وأرسل طلب POST واحدًا لتدخل مهمتك قائمة التنفيذ فورًا؛ ثم تستلم النتيجة عبر webhook أو رابط موقّع.
استدعِ الخدمة من بيئتك
curl -X POST https://api.kit.forhosting.com/dev2/cli-arg-parse-spec \
-H "Authorization: Bearer $KIT_KEY" \
-H "Content-Type: application/json" \
-d '{"args":["--verbose","--output=result.json","input.txt"],"spec":[{"name":"verbose","aliases":["--verbose","-v"],"kind":"flag"},{"name":"output","aliases":["--output","-o"],"kind":"option"}]}'const res = await fetch("https://api.kit.forhosting.com/dev2/cli-arg-parse-spec", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.KIT_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"args": [
"--verbose",
"--output=result.json",
"input.txt"
],
"spec": [
{
"name": "verbose",
"aliases": [
"--verbose",
"-v"
],
"kind": "flag"
},
{
"name": "output",
"aliases": [
"--output",
"-o"
],
"kind": "option"
}
]
})
});
const { task_id } = await res.json();import os, requests
res = requests.post(
"https://api.kit.forhosting.com/dev2/cli-arg-parse-spec",
headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
json={
"args": [
"--verbose",
"--output=result.json",
"input.txt"
],
"spec": [
{
"name": "verbose",
"aliases": [
"--verbose",
"-v"
],
"kind": "flag"
},
{
"name": "output",
"aliases": [
"--output",
"-o"
],
"kind": "option"
}
]
},
)
task_id = res.json()["task_id"]<?php
$res = file_get_contents("https://api.kit.forhosting.com/dev2/cli-arg-parse-spec", false, stream_context_create([
"http" => [
"method" => "POST",
"header" => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
"content" => '{"args":["--verbose","--output=result.json","input.txt"],"spec":[{"name":"verbose","aliases":["--verbose","-v"],"kind":"flag"},{"name":"output","aliases":["--output","-o"],"kind":"option"}]}',
],
]));
$task = json_decode($res, true);body := bytes.NewBufferString(`{"args":["--verbose","--output=result.json","input.txt"],"spec":[{"name":"verbose","aliases":["--verbose","-v"],"kind":"flag"},{"name":"output","aliases":["--output","-o"],"kind":"option"}]}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/dev2/cli-arg-parse-spec", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)مثال على الطلب
{
"args": [
"--verbose",
"--output=result.json",
"input.txt"
],
"spec": [
{
"name": "verbose",
"aliases": [
"--verbose",
"-v"
],
"kind": "flag"
},
{
"name": "output",
"aliases": [
"--output",
"-o"
],
"kind": "option"
}
]
}مثال على الاستجابة
{
"task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
"type": "dev2.cli_arg_parse_spec",
"status": "queued",
"_links": {
"result": "/tasks/tsk_…/result"
}
}الواجهة غير متزامنة: تستلم task_id فور الإرسال، ويمكنك الاستعلام عن الحالة بمعدل طلب واحد في الثانية.
الأسعار
السعر معلن كما تراه: لا tokens ولا نظام نقاط؛ وإن فشلت المهمة فلن تُحاسَب عليها.
الأخطاء
| HTTP | الرمز | المعنى |
|---|---|---|
401 | unauthorized | مفتاح الوصول مفقود أو غير صالح؛ تحقق من ترويسة Bearer في طلبك. |
402 | insufficient_balance | رصيدك لا يكفي لتنفيذ هذه المهمة؛ أعد شحن الرصيد ثم أعد المحاولة. |
404 | unknown_type | نوع المهمة المطلوب غير موجود في الكتالوج — راجع الاسم المرسل في الطلب. |
429 | rate_limited | تجاوزت الحد المسموح من الطلبات؛ انتظر قليلًا ثم أعد المحاولة. |
ملاحظات تقنية
يربط المحلل الأسماء البديلة بالأسماء القياسية، ويحفظ الوسيطات الموضعية، ويكشف الأعلام المجهولة، ويدعم الخيارات الطويلة المتبوعة بعلامة المساواة، ثم يوقف تفسير الخيارات بعد علامة الشرطتين المتعارف عليها.
صفوا واجهة سطر الأوامر في صورة بيانات
تتيح الأسماء البديلة للصيغتين القصيرة والطويلة ملء الخاصية القياسية نفسها؛ لذا يمكن لكل من <code>-o</code> و<code>--output</code> إنتاج <code>output</code>. يجب أن تبدأ الأسماء البديلة بشرطة واحدة أو شرطتين.
افهموا تحليل العناصر وبنية الناتج
يضاف كل عنصر مجهول يبدأ بشرطة إلى <code>unknown_flags</code>، وبذلك يمكنكم رفضه أو عرض تحذير بشأنه أو تمريره عمداً.
أسئلة تقنية
هل تُرفض الأعلام المجهولة؟
لا. تعاد في unknown_flags لتتمكنوا من رفضها أو التحذير منها أو تمريرها.
هل تُدمج الأعلام القصيرة مثل -abc؟
لا. تطابق الأسماء البديلة عناصر كاملة، ولذلك لا يُعرف -abc إلا إذا أعلنت المواصفات هذا الاسم بعينه.