ForHosting KIT · أدوات المطورين

حلّل وسيطات سطر الأوامر وفق مواصفات محددة

حوّل مصفوفة وسيطات سطر الأوامر الخام إلى كائن منتظم يمكن توقّع بنيته، من دون توزيع قواعد التحليل في أجزاء تطبيقكم.

● Betaمجاني · داخل متصفحك

استخدمها من الويبAPIالبريدTelegramالتطبيق قريبًا

قدّموا العناصر ومواصفات موجزة تسمّي كل علم منطقي وكل خيار يتطلب قيمة. يربط المحلل الأسماء البديلة بالأسماء القياسية، ويحفظ الوسيطات الموضعية، ويكشف الأعلام المجهولة، ويدعم الخيارات الطويلة المتبوعة بعلامة المساواة، ثم يوقف تفسير الخيارات بعد علامة الشرطتين المتعارف عليها. تؤدي المواصفات غير الصحيحة والوسيطات المكررة والخيارات التي تفتقد قيمتها الإلزامية إلى أخطاء إدخال واضحة.

صفوا واجهة سطر الأوامر في صورة بيانات

ابدؤوا بعناصر الوسيطات كما يقدّمها نظام التشغيل بعد حذف اسم الملف التنفيذي واسم البرنامج النصي. عرّفوا بعد ذلك كل وسيط مقبول ضمن المواصفات. يتضمن كل إدخال اسماً قياسياً واسماً بديلاً واحداً أو أكثر ونوعاً. استخدموا flag للمفتاح الذي يعني وجوده القيمة الصحيحة، مثل <code>--verbose</code>. واستخدموا option عندما يجب أن تتبع الصيغة قيمة، مثل <code>--output result.json</code>. تتيح الأسماء البديلة للصيغتين القصيرة والطويلة ملء الخاصية القياسية نفسها؛ لذا يمكن لكل من <code>-o</code> و<code>--output</code> إنتاج <code>output</code>. تستخدم الأسماء القياسية حروفاً إنجليزية صغيرة وأرقاماً وشرطات سفلية، كي يصبح الكائن الناتج صالحاً للاستهلاك من دون مرحلة إعادة تسمية. يجب أن تبدأ الأسماء البديلة بشرطة واحدة أو شرطتين. يرفض المحلل تكرار الأسماء القياسية أو البديلة لأن هذا التعارض سيجعل النتيجة رهينة لترتيب التعريف. اضبطوا <code>multiple</code> فقط إذا كان تكرار الوسيط جزءاً مقصوداً من الواجهة؛ وعندئذ تعاد القيم بحسب ترتيب ظهورها.

افهموا تحليل العناصر وبنية الناتج

تفصل النتيجة بين القيم المعروفة والعناصر الموضعية والأعلام المجهولة. يتحول العلم المعروف إلى القيمة الصحيحة تحت اسمه القياسي، بينما يخزن الخيار العنصر الذي يليه. ويمكن للخيار الطويل أن يحمل قيمته في العنصر نفسه، كما في <code>--format=json</code>. تتطلب المطابقة تطابقاً تاماً؛ فلا تُفكك مجموعات الأعلام القصيرة مثل <code>-abc</code> ما لم تُدرج الصيغة كاملة اسماً بديلاً. يضاف كل عنصر مجهول يبدأ بشرطة إلى <code>unknown_flags</code>، وبذلك يمكنكم رفضه أو عرض تحذير بشأنه أو تمريره عمداً. أما العناصر المجهولة الأخرى فتعد قيماً موضعية. تنهي <code>--</code> المستقلة معالجة الخيارات، وتصبح جميع العناصر اللاحقة موضعية حتى لو بدأت بشرطة. يزيل هذا الأسلوب المتعارف عليه الالتباس عن أسماء ملفات مثل <code>-draft.txt</code>. لا ينشئ المحلل قيماً افتراضية ولا يحوّل النصوص إلى أرقام، لأن هذه السياسات تخص التطبيق وقد تخفي أخطاء المستخدم. الناتج حتمي ويحافظ على ترتيب العناصر الموضعية والمجهولة.

تعاملوا بأمان مع القيم الناقصة والتكرار

يتطلب كل إدخال من نوع option قيمة غير فارغة كلما ظهر أحد أسمائه البديلة. إذا كان الاسم البديل آخر عنصر، أو جاء قبل علامة إنهاء الخيارات، أو تبعه عنصر آخر يشبه علماً، يفشل التحليل بخطأ إدخال يذكر الاسم البديل المتسبب بالمشكلة. وتنطبق القاعدة نفسها على الصيغة الملحقة الفارغة مثل <code>--output=</code>. يمنع هذا السلوك الصارم استهلاك علم تالٍ باعتباره بيانات من دون تنبيه، ويعالج مباشرة أحد أخطر أخطاء تحليل سطر الأوامر. يمكن مع ذلك استخدام شرطة منفردة قيمةً، وهو أمر مفيد للبرامج التي تمثل الإدخال أو الإخراج القياسي بالرمز <code>-</code>. يؤدي تكرار الوسيط المعروف افتراضياً إلى خطأ أيضاً. أعلنوا <code>multiple: true</code> عندما يكون التكرار صحيحاً، مثل مسارات التضمين أو التصنيفات المتعددة؛ وستحتوي الخاصية القياسية حينها دائماً على مصفوفة. يبلّغ المحلل عن الأعلام المجهولة ولا يوقف التنفيذ بسببها، فتظل سياسة التوافق والتمرير تحت تحكمكم.

حالات الاستخدام

تحققوا من مغلف CLI

حلّلوا خيارات المغلف الخاصة وأبلغوا عن الأعلام غير المدعومة قبل تشغيل العملية المغلفة.

وحّدوا الخيارات القصيرة والطويلة

اربطوا أسماء بديلة مثل -o و--output بخاصية ثابتة واحدة لتبسيط منطق التطبيق.

أنشئوا معاينات واختبارات للأوامر

حوّلوا مصفوفات العناصر إلى تجهيزات منظمة وحتمية من دون تنفيذ أمر أو الوصول إلى صدفة أوامر.

الأسئلة الشائعة

ما التكلفة؟

تبلغ تكلفة كل طلب API مقدار $0.002. تنفذ نسخة المتصفح منطق التحليل الحتمي نفسه محلياً.

هل تُرفض الأعلام المجهولة؟

لا. تعاد في unknown_flags لتتمكنوا من رفضها أو التحذير منها أو تمريرها.

هل تدعم الصيغة --name=value؟

نعم، للخيارات الطويلة التي تتطلب قيمة. تؤدي القيمة الفارغة بعد علامة المساواة إلى خطأ.

هل تُدمج الأعلام القصيرة مثل -abc؟

لا. تطابق الأسماء البديلة عناصر كاملة، ولذلك لا يُعرف -abc إلا إذا أعلنت المواصفات هذا الاسم بعينه.

ماذا يحدث بعد شرطتين مستقلتين؟

يتوقف تحليل الخيارات، وتُعاد جميع العناصر المتبقية بوصفها وسيطات موضعية.

للمطوّرين — الوصول عبر API

كل ما في هذه الصفحة متاح برمجيًا. هذا القسم موجّه للفرق التقنية التي تريد ربط الأداة بأنظمتها الخاصة؛ بقية المستخدمين يمكنهم استخدام الأداة أعلاه مباشرة دون الحاجة لقراءة ما يلي.

الـEndpoint

POSThttps://api.kit.forhosting.com/dev2/cli-arg-parse-spec

صادِق على طلبك بترويسة 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 فور الإرسال، ويمكنك الاستعلام عن الحالة بمعدل طلب واحد في الثانية.

الأسعار

لكل طلب$0.002

السعر معلن كما تراه: لا tokens ولا نظام نقاط؛ وإن فشلت المهمة فلن تُحاسَب عليها.

الأخطاء

HTTP	الرمز	المعنى
`401`	`unauthorized`	مفتاح الوصول مفقود أو غير صالح؛ تحقق من ترويسة Bearer في طلبك.
`402`	`insufficient_balance`	رصيدك لا يكفي لتنفيذ هذه المهمة؛ أعد شحن الرصيد ثم أعد المحاولة.
`404`	`unknown_type`	نوع المهمة المطلوب غير موجود في الكتالوج — راجع الاسم المرسل في الطلب.
`429`	`rate_limited`	تجاوزت الحد المسموح من الطلبات؛ انتظر قليلًا ثم أعد المحاولة.

اطّلع على توثيق KIT الكامل ←