کتابخانه‌ی استاندارد · سیستم و ابزار

خط فرمان cli

برنامه‌های خط فرمان با چند دستور (مثل git commit)، و پرسیدن از کاربر.

واردسازی خط فرمان

نام آرگومان‌ها شناسه‌ی خود کد است و معادل فارسی ندارد؛ گونه‌ها، کلیدواژه‌ها و نام بسته‌ها با معادل فارسی نوشته می‌شوند.

بسیاری از ابزارها چند دستور دارند: git commit، salam build، salam run. بسته‌ی خط فرمان فهرست دستورها را نگه می‌دارد، از روی آرگومان اول می‌فهمد کدام دستور خواسته شده و راهنمای کلی برنامه را می‌سازد. با درخواست، درخواست با پیش فرض و تایید هم می‌شود در پایانه از کاربر چیزی پرسید.

این بسته عمداً کوچک است و گزینه‌ها را تجزیه نمی‌کند. بسته را از روی شکل برنامه‌تان انتخاب کنید:

  • یک دستور با چند گزینه، مثل resize --width 800 photo.png: بسته‌ی پرچم به‌تنهایی کافی است.
  • چند دستور که هر کدام گزینه‌های خودش را دارد: خط فرمان دستور را انتخاب می‌کند و برای هر دستور یک مجموعه‌ی پرچم گزینه‌هایش را می‌خواند.
  • خروجی رنگی یا تمام‌صفحه در پایانه: بسته‌ی پایانه.

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

  • توزیع آرگومان‌ها را بدون نام برنامه می‌خواهد. سیستم عامل.آرگومان ها نام برنامه را هم دارد، پس آرگومان‌های باقیمانده(سیستم عامل.آرگومان ها()) را بدهید.
  • نام‌های help، -h، --help، version، -v و --version را توزیع برای خودش برداشته است، و درون هر دستور هم بسته‌ی پرچم -h و --help را درخواست راهنما می‌داند. هیچ‌وقت h را نام کوتاه پرچم خودتان نگذارید.
  • نام دستورها باید دقیقاً یکی باشند: پیشوند، نام دیگر یا یکسان‌گرفتن حروف کوچک و بزرگ در کار نیست، و ثبت نام تکراری را رد نمی‌کند (اولی برنده است).
  • آرگومان‌های باقیمانده وکتور تازه‌ای برمی‌گرداند؛ آن را با دیرکن باقی.آزادکن() آزاد کنید.

ابزاری با چند دستور

شکل معمول این است: توزیع دستور را از آرگومان اول برمی‌دارد، آرگومان‌های باقیمانده هر چه پس از آن آمده را به همان دستور می‌دهد، و هر دستور مجموعه‌ی پرچم خودش را دارد؛ پس todo add و todo list می‌توانند گزینه‌های متفاوت داشته باشند. هر دستور یک کد خروج برمی‌گرداند.

cli-guide-subcommands.salam
واردسازی خط فرمان
واردسازی پرچم
واردسازی رشته

تابع دستور افزودن(آرگ: وکتور<رشته>): صحیح:
    ناپایا پ := پرچم.جدید("todo add"، "یک کار می‌افزاید")
    دیرکن پرچم.آزادسازی(پ)
    پرچم.افزودن صحیح(پ، "priority"، "p"، ۳، "۱ یعنی فوری‌ترین")
    اگر وارونه پرچم.تجزیه(پ، آرگ):
        سرچاپ "todo add:"، پرچم.خطا(پ)
        برگشت ۲
    پایان
    اگر پرچم.راهنما خواسته(پ):
        چاپ پرچم.راهنما(پ)
        برگشت ۰
    پایان
    واژه‌ها := پرچم.موقعیتی(پ)
    دیرکن واژه‌ها.آزادکن()
    سرچاپ "افزوده شد [" + رشته.بپیوند(واژه‌ها، " ") + "] با اولویت"، پرچم.دریافت صحیح(پ، "priority")
    برگشت ۰
پایان

تابع دستور فهرست(آرگ: وکتور<رشته>): صحیح:
    ناپایا پ := پرچم.جدید("todo list"، "کارها را فهرست می‌کند")
    دیرکن پرچم.آزادسازی(پ)
    پرچم.افزودن منطقی(پ، "all"، "a"، نادرست، "کارهای انجام‌شده را هم نشان بده")
    اگر وارونه پرچم.تجزیه(پ، آرگ):
        سرچاپ "todo list:"، پرچم.خطا(پ)
        برگشت ۲
    پایان
    سرچاپ "فهرست"، پرچم.دریافت منطقی(پ، "all") ? "همه‌ی کارها" : "کارهای باز"
    برگشت ۰
پایان

تابع اجرا کن(ب &: خط فرمان.برنامه، خط: رشته): صحیح:
    آرگ := رشته.تفکیک کردن(خط، " ")
    دیرکن آرگ.آزادکن()
    دستور := خط فرمان.توزیع(ب، آرگ)
    باقی := خط فرمان.آرگومان‌های باقیمانده(آرگ)
    دیرکن باقی.آزادکن()
    اگر دستور برابر "add": برگشت دستور افزودن(باقی) پایان
    اگر دستور برابر "list": برگشت دستور فهرست(باقی) پایان
    اگر دستور برابر خط فرمان.دستور نسخه:
        سرچاپ ب.نام، ب.نسخه
        برگشت ۰
    پایان
    اگر دستور برابر خط فرمان.دستور نامشخص: سرچاپ "todo: دستور ناشناخته:"، آرگ.بگیر(۰) پایان
    چاپ خط فرمان.راهنما(ب)
    برگشت دستور برابر خط فرمان.دستور راهنما ? ۰ : ۲
پایان

تابع ریشه:
    ناپایا ب := خط فرمان.جدید("todo"، "یک فهرست کار کوچک"، "0.3.0")
    خط فرمان.ثبت(ب، "add"، "افزودن یک کار")
    خط فرمان.ثبت(ب، "list"، "نمایش کارها")
    هر خط در ["add -p 1 خرید شیر"، "list --all"، "add --priority=high تماس با مادر"، "add --help"، "--version"، "remove 3"]:
        سرچاپ "$ todo"، خط
        سرچاپ "کد خروج"، اجرا کن(ب، خط)
    پایان
پایان
خروجی$ todo add -p 1 خرید شیر افزوده شد [خرید شیر] با اولویت 1 کد خروج 0 $ todo list --all فهرست همه‌ی کارها کد خروج 0 $ todo add --priority=high تماس با مادر todo add: invalid int value for --priority: high کد خروج 2 $ todo add --help Usage: todo add [options] [args] یک کار می‌افزاید Options: -p, --priority <int> ۱ یعنی فوری‌ترین (default: 3) -h, --help show this help کد خروج 0 $ todo --version todo 0.3.0 کد خروج 0 $ todo remove 3 todo: دستور ناشناخته: remove todo 0.3.0 یک فهرست کار کوچک Usage: todo <command> [options] Commands: add افزودن یک کار list نمایش کارها Run 'todo <command> --help' for help on a specific command. کد خروج 2

خط فرمان.راهنما در پایان پیشنهاد می‌کند todo <command> --help را اجرا کنید، ولی پاسخ دادن به آن کار خود هر دستور است: پس از تجزیه، پرچم.راهنما خواسته را بررسی کنید و پرچم.راهنما را چاپ کنید، همان کاری که add این‌جا می‌کند. هر دو متن راهنما انگلیسی ساخته می‌شوند و فقط شرح‌ها همان‌طور که نوشته‌اید می‌آیند.

وصل کردن به آرگومان‌های واقعی

در یک برنامه‌ی واقعی آرگومان‌ها از سیستم عامل.آرگومان ها می‌آیند. نام خود برنامه را با آرگومان‌های باقیمانده کنار بگذارید و بقیه را به توزیع بدهید. وقتی هیچ آرگومانی نباشد توزیع مقدار دستور راهنما را برمی‌گرداند، پس اجرای ابزار بدون آرگومان راهنمایش را چاپ می‌کند و کاربر هم همین را انتظار دارد.

cli-guide-main.salam
واردسازی خط فرمان
واردسازی سیستم عامل

تابع ریشه:
    ناپایا ب := خط فرمان.جدید("notes"، "یادداشت‌های کوتاه نگه می‌دارد"، "1.2.0")
    خط فرمان.ثبت(ب، "new"، "یک یادداشت تازه بنویس")
    خط فرمان.ثبت(ب، "show"، "همه‌ی یادداشت‌ها را چاپ کن")
    آرگ := خط فرمان.آرگومان‌های باقیمانده(سیستم عامل.آرگومان ها())
    دیرکن آرگ.آزادکن()
    دستور := خط فرمان.توزیع(ب، آرگ)
    اگر دستور برابر خط فرمان.دستور راهنما:
        چاپ خط فرمان.راهنما(ب)
        برگشت ۰
    وگرنه دستور برابر خط فرمان.دستور نسخه:
        سرچاپ ب.نسخه
        برگشت ۰
    وگرنه دستور برابر خط فرمان.دستور نامشخص:
        سرچاپ "notes: چنین دستوری نیست:"، آرگ.بگیر(۰)
        برگشت ۲
    پایان
    سرچاپ "اجرای"، دستور، "با"، خط فرمان.آرگومان‌های باقیمانده(آرگ)
    برگشت ۰
پایان
خروجیnotes 1.2.0 یادداشت‌های کوتاه نگه می‌دارد Usage: notes <command> [options] Commands: new یک یادداشت تازه بنویس show همه‌ی یادداشت‌ها را چاپ کن Run 'notes <command> --help' for help on a specific command.

خروجی بالا همان چیزی است که بدون آرگومان چاپ می‌کند. salam run notes.salam show --all یا salam run notes.salam --version را هم امتحان کنید.

پرچم‌های الزامی

پرچمی که پیش‌فرض معقولی ندارد، مثل سروری که باید روی آن مستقر شد، باید الزامی باشد. الزامی بودن پرچم‌ها نام‌هایی را که باید بیایند می‌گیرد و آن‌هایی را که نیامده‌اند برمی‌گرداند؛ پس می‌توانید همه را یک‌جا گزارش کنید، نه در هر اجرا یکی.

cli-guide-required.salam
واردسازی خط فرمان
واردسازی پرچم
واردسازی رشته

تابع استقرار(خط: رشته): صحیح:
    آرگ := رشته.تفکیک کردن(خط، " ")
    دیرکن آرگ.آزادکن()
    ناپایا پ := پرچم.جدید("deploy"، "یک نسخه را بارگذاری می‌کند")
    دیرکن پرچم.آزادسازی(پ)
    پرچم.افزودن رشته(پ، "host"، "H"، ""، "سروری که روی آن مستقر می‌شود")
    پرچم.افزودن رشته(پ، "user"، "u"، ""، "نام کاربری")
    پرچم.افزودن صحیح(پ، "port"، "p"، ۲۲، "درگاه SSH")
    اگر وارونه پرچم.تجزیه(پ، آرگ):
        سرچاپ "deploy:"، پرچم.خطا(پ)
        برگشت ۲
    پایان
    ناپایا لازم := وکتور {} برگردان وکتور<رشته>
    دیرکن لازم.آزادکن()
    لازم.بیفزا("host")
    لازم.بیفزا("user")
    جاافتاده := خط فرمان.الزامی بودن پرچم‌ها(پ، لازم)
    دیرکن جاافتاده.آزادکن()
    اگر جاافتاده.طول() بزرگتر ۰:
        سرچاپ "deploy: این پرچم‌ها لازم‌اند: --" + رشته.بپیوند(جاافتاده، "، --")
        برگشت ۲
    پایان
    سرچاپ "استقرار روی"، پرچم.دریافت رشته(پ، "user") + "@" + پرچم.دریافت رشته(پ، "host")، "درگاه"، پرچم.دریافت صحیح(پ، "port")
    برگشت ۰
پایان

تابع ریشه:
    هر خط در ["-H example.com -u sara"، "--host=example.com -p 2222"، "-p 2222"]:
        سرچاپ "$ deploy"، خط
        سرچاپ "کد خروج"، استقرار(خط)
    پایان
پایان
خروجی$ deploy -H example.com -u sara استقرار روی sara@example.com درگاه 22 کد خروج 0 $ deploy --host=example.com -p 2222 deploy: این پرچم‌ها لازم‌اند: --user کد خروج 2 $ deploy -p 2222 deploy: این پرچم‌ها لازم‌اند: --host، --user کد خروج 2

این تابع پرچم.تنظیم شده را به کار می‌برد، پس بررسی می‌کند که پرچم نوشته شده باشد، نه این‌که مقدار داشته باشد: --host= داده‌شده حساب می‌شود. اگر این مهم است، رشته‌ی خالی را هم بررسی کنید.

پرسش‌هایی که در اسکریپت هم کار می‌کنند

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

cli-guide-noninteractive.salam
واردسازی خط فرمان
واردسازی پرچم
واردسازی رشته

تابع ریشه:
    آرگ := رشته.تفکیک کردن("--name demo"، " ")
    دیرکن آرگ.آزادکن()
    ناپایا پ := پرچم.جدید("init"، "یک پروژه می‌سازد")
    دیرکن پرچم.آزادسازی(پ)
    پرچم.افزودن رشته(پ، "name"، ""، ""، "نام پروژه")
    پرچم.افزودن منطقی(پ، "yes"، "y"، نادرست، "تایید نپرس")
    پرچم.تجزیه(پ، آرگ)
    ناپایا نام := پرچم.دریافت رشته(پ، "name")
    اگر نام.طول() برابر ۰: نام = خط فرمان.درخواست با پیش فرض("نام پروژه"، "my-app") پایان
    زبان برنامه := خط فرمان.درخواست با پیش فرض("زبان"، "فارسی")
    سرچاپ ""
    ناپایا ادامه := پرچم.دریافت منطقی(پ، "yes")
    اگر وارونه ادامه: ادامه = خط فرمان.تایید("پروژه‌ی " + نام + " به " + زبان برنامه + " ساخته شود؟") پایان
    سرچاپ ""
    اگر ادامه:
        سرچاپ "ساخته شد:"، نام
    وگرنه:
        سرچاپ "چیزی ساخته نشد؛ برای نپرسیدن --yes را بدهید"
    پایان
پایان
خروجیزبان (فارسی): پروژه‌ی demo به فارسی ساخته شود؟ [y/N]: چیزی ساخته نشد؛ برای نپرسیدن --yes را بدهید

این خروجی حالتی است که ورودی استاندارد خالی است، مثل یک کار CI: پرسش زبان پیش‌فرضش را می‌گیرد و تایید رد می‌شود. پس از پرسش‌ها خط تازه‌ای نیامده، چون کسی Enter را نزده است.

گونه‌ها

برنامه App

ساختار برنامه
یک برنامه‌ی خط فرمان و دستورهایش.
نامانگلیسیگونهتوضیح
نامnameرشته = ""نام برنامه.
شرحdescرشته = ""شرح برنامه.
نسخهversionرشته = ""نسخه‌ی برنامه.
نام دستورهاcmd_namesوکتور<رشته>نام دستورها.
شرح دستورهاcmd_descsوکتور<رشته>شرح دستورها.
cli-Dispatch.salam
واردسازی خط فرمان
واردسازی رشته

تابع اجرا کن(ب &: خط فرمان.برنامه، خط: رشته):
    آرگ := رشته.تفکیک کردن(خط، " ")
    د := خط فرمان.توزیع(ب، آرگ)
    اگر د == خط فرمان.دستور راهنما:
        سرچاپ "راهنما خواسته شد"
    وگرنه د == خط فرمان.دستور نسخه:
        سرچاپ "نسخه:", ب.نسخه
    وگرنه د == خط فرمان.دستور نامشخص:
        سرچاپ "دستور ناشناخته"
    وگرنه:
        سرچاپ "اجرا:", د، خط فرمان.آرگومان‌های باقیمانده(آرگ)
    پایان
    آرگ.آزادکن()
پایان

تابع ریشه:
    ناپایا ب := خط فرمان.جدید("salamctl"، "مدیریت پروژه"، "1.0.0")
    خط فرمان.ثبت(ب، "build"، "ساختن پروژه")
    خط فرمان.ثبت(ب، "test"، "اجرای آزمون‌ها")
    سرچاپ خط فرمان.دستور دارد(ب، "build")، خط فرمان.شرح دستور(ب، "test")
    هر خط در ["build --fast"، "--help"، "--version"، "deploy"]:
        اجرا کن(ب، خط)
    پایان
    چاپ خط فرمان.راهنما(ب)
پایان
خروجیtrue اجرای آزمون‌ها اجرا: build ["--fast"] راهنما خواسته شد نسخه: 1.0.0 دستور ناشناخته salamctl 1.0.0 مدیریت پروژه Usage: salamctl <command> [options] Commands: build ساختن پروژه test اجرای آزمون‌ها Run 'salamctl <command> --help' for help on a specific command.

پایاها و متغیرها

دستور راهنما CmdHelp

پایا دستور راهنما: رشته = "__help__"
نتیجه‌ی توزیع وقتی راهنما خواسته شده، یا هیچ آرگومانی نیامده.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: cli-Dispatch.salam

دستور نسخه CmdVersion

پایا دستور نسخه: رشته = "__version__"
نتیجه‌ی توزیع وقتی نسخه خواسته شده.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: cli-Dispatch.salam

دستور نامشخص CmdUnknown

پایا دستور نامشخص: رشته = "__unknown__"
نتیجه‌ی توزیع برای دستوری که ثبت نشده.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: cli-Dispatch.salam

تابع‌ها

جدید New

تابع جدید(name: رشته، desc: رشته، version: رشته): برنامه
برنامه‌ای با نام، شرح و نسخه می‌سازد.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: cli-Dispatch.salam

ثبت Register

تابع ثبت(app &: برنامه، name: رشته، desc: رشته)
یک دستور را با شرحش می‌افزاید. دستورها به همان ترتیب ثبت در راهنما می‌آیند؛ نام تکراری رد نمی‌شود.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: cli-Dispatch.salam

دستور دارد HasCommand

تابع دستور دارد(app &: برنامه، name: رشته): منطقی
اگر دستور ثبت شده باشد، درست برمی‌گرداند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: cli-Dispatch.salam

شرح دستور CommandDesc

تابع شرح دستور(app &: برنامه، name: رشته): رشته
شرح یک دستور.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: cli-Dispatch.salam

توزیع Dispatch

تابع توزیع(app &: برنامه، argv: وکتور<رشته>): رشته
از روی آرگومان اول می‌گوید کدام دستور خواسته شده: نام آن دستور، یا دستور راهنما، دستور نسخه یا دستور نامشخص. آرگومان‌ها را بدون نام برنامه بدهید. help، -h و --help و همچنین فهرست خالی دستور راهنما می‌دهند؛ version، -v و --version هم دستور نسخه.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: cli-Dispatch.salam

آرگومان‌های باقیمانده RemainingArgs

تابع آرگومان‌های باقیمانده(argv: وکتور<رشته>): وکتور<رشته>
وکتوری تازه با همه‌ی آرگومان‌ها به‌جز اولی، برای دادن به بسته‌ی پرچم. یک بار برای کنار گذاشتن نام برنامه از سیستم عامل.آرگومان ها() به کار می‌رود و بار دیگر برای کنار گذاشتن نام دستور. نتیجه را آزاد کنید.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: cli-Dispatch.salam

راهنما Usage

تابع راهنما(app &: برنامه): رشته
متن راهنمای کلی برنامه: نام و نسخه، شرح، خط کاربرد و دستورها با شرحشان. با شکستن خط تمام می‌شود، پس با چاپ چاپش کنید.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: cli-Dispatch.salam

الزامی بودن پرچم‌ها RequireFlags

تابع الزامی بودن پرچم‌ها(fs &: پرچم.مجموعه پرچم، names: وکتور<رشته>): وکتور<رشته>
از میان نام‌های داده‌شده، پرچم‌هایی را که در خط فرمان نوشته نشده‌اند به همان ترتیب برمی‌گرداند. پرچمی با مقدار خالی، مثل --host=، نوشته‌شده حساب می‌شود.
cli-RequireFlags.salam
واردسازی خط فرمان
واردسازی پرچم

تابع ریشه:
    ناپایا پ := پرچم.جدید("deploy"، "")
    دیرکن پرچم.آزادسازی(پ)
    پرچم.افزودن رشته(پ، "host"، "H"، ""، "سرور")
    پرچم.افزودن رشته(پ، "user"، "u"، ""، "کاربر")
    ناپایا آرگ := وکتور {} برگردان وکتور<رشته>
    دیرکن آرگ.آزادکن()
    آرگ.بیفزا("--host=example.com")
    پرچم.تجزیه(پ، آرگ)
    ناپایا لازم := وکتور {} برگردان وکتور<رشته>
    دیرکن لازم.آزادکن()
    لازم.بیفزا("host")
    لازم.بیفزا("user")
    سرچاپ "جاافتاده:", خط فرمان.الزامی بودن پرچم‌ها(پ، لازم)
پایان
خروجیجاافتاده: ["user"]

تایید Confirm

تابع تایید(question: رشته): منطقی
پرسش را با [y/N]: چاپ می‌کند و یک خط می‌خواند. y یا yes، با حروف کوچک یا بزرگ و با فاصله در دو طرف، درست است؛ هر چیز دیگر، خط خالی یا پایان ورودی نادرست.
cli-Prompt.salam
واردسازی خط فرمان

تابع ریشه:
    نام := خط فرمان.درخواست("نام پروژه")
    زبان := خط فرمان.درخواست با پیش فرض("زبان"، "فارسی")
    اگر خط فرمان.تایید("ساخته شود؟"):
        سرچاپ "ساختن"، نام، "به"، زبان
    پایان
پایان

درخواست Prompt

تابع درخواست(question: رشته): رشته
پرسش را با : در پایانش چاپ می‌کند، یک خط می‌خواند و آن را بی‌فاصله‌های دو طرف برمی‌گرداند. خودتان پرسش را با دونقطه تمام نکنید. در پایان ورودی رشته‌ی خالی برمی‌گرداند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: cli-Prompt.salam

درخواست با پیش فرض PromptOr

تابع درخواست با پیش فرض(question: رشته، def: رشته): رشته
مثل درخواست، ولی پیش‌فرض را در پرانتز نشان می‌دهد، مثل زبان (فارسی): ، و اگر پاسخ خالی باشد همان را برمی‌گرداند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: cli-Prompt.salam