خط فرمان 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 میتوانند گزینههای متفاوت داشته باشند. هر دستور یک کد خروج برمیگرداند.
واردسازی خط فرمان
واردسازی پرچم
واردسازی رشته
تابع دستور افزودن(آرگ: وکتور<رشته>): صحیح:
ناپایا پ := پرچم.جدید("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 <command> --help را اجرا کنید، ولی پاسخ دادن به آن کار خود هر دستور است: پس از تجزیه، پرچم.راهنما خواسته را بررسی کنید و پرچم.راهنما را چاپ کنید، همان کاری که add اینجا میکند. هر دو متن راهنما انگلیسی ساخته میشوند و فقط شرحها همانطور که نوشتهاید میآیند.
وصل کردن به آرگومانهای واقعی
در یک برنامهی واقعی آرگومانها از سیستم عامل.آرگومان ها میآیند. نام خود برنامه را با آرگومانهای باقیمانده کنار بگذارید و بقیه را به توزیع بدهید. وقتی هیچ آرگومانی نباشد توزیع مقدار دستور راهنما را برمیگرداند، پس اجرای ابزار بدون آرگومان راهنمایش را چاپ میکند و کاربر هم همین را انتظار دارد.
واردسازی خط فرمان
واردسازی سیستم عامل
تابع ریشه:
ناپایا ب := خط فرمان.جدید("notes"، "یادداشتهای کوتاه نگه میدارد"، "1.2.0")
خط فرمان.ثبت(ب، "new"، "یک یادداشت تازه بنویس")
خط فرمان.ثبت(ب، "show"، "همهی یادداشتها را چاپ کن")
آرگ := خط فرمان.آرگومانهای باقیمانده(سیستم عامل.آرگومان ها())
دیرکن آرگ.آزادکن()
دستور := خط فرمان.توزیع(ب، آرگ)
اگر دستور برابر خط فرمان.دستور راهنما:
چاپ خط فرمان.راهنما(ب)
برگشت ۰
وگرنه دستور برابر خط فرمان.دستور نسخه:
سرچاپ ب.نسخه
برگشت ۰
وگرنه دستور برابر خط فرمان.دستور نامشخص:
سرچاپ "notes: چنین دستوری نیست:"، آرگ.بگیر(۰)
برگشت ۲
پایان
سرچاپ "اجرای"، دستور، "با"، خط فرمان.آرگومانهای باقیمانده(آرگ)
برگشت ۰
پایانخروجی بالا همان چیزی است که بدون آرگومان چاپ میکند. salam run notes.salam show --all یا salam run notes.salam --version را هم امتحان کنید.
پرچمهای الزامی
پرچمی که پیشفرض معقولی ندارد، مثل سروری که باید روی آن مستقر شد، باید الزامی باشد. الزامی بودن پرچمها نامهایی را که باید بیایند میگیرد و آنهایی را که نیامدهاند برمیگرداند؛ پس میتوانید همه را یکجا گزارش کنید، نه در هر اجرا یکی.
واردسازی خط فرمان
واردسازی پرچم
واردسازی رشته
تابع استقرار(خط: رشته): صحیح:
آرگ := رشته.تفکیک کردن(خط، " ")
دیرکن آرگ.آزادکن()
ناپایا پ := پرچم.جدید("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"، خط
سرچاپ "کد خروج"، استقرار(خط)
پایان
پایاناین تابع پرچم.تنظیم شده را به کار میبرد، پس بررسی میکند که پرچم نوشته شده باشد، نه اینکه مقدار داشته باشد: --host= دادهشده حساب میشود. اگر این مهم است، رشتهی خالی را هم بررسی کنید.
پرسشهایی که در اسکریپت هم کار میکنند
درخواست با پیش فرض و تایید یک خط از ورودی استاندارد میخوانند. وقتی چیزی تایپ نشود، یا برنامه در اسکریپتی بیپایانه اجرا شود، درخواست با پیش فرض پیشفرضش را برمیگرداند و تایید نادرست؛ پس پرسشی که از یاد رفته هیچوقت کار خطرناکی نمیکند. برای هر پرسش یک پرچم هم بگذارید، اینجا --name و --yes، تا برنامه بدون کسی پشت صفحهکلید هم اجرا شود.
واردسازی خط فرمان
واردسازی پرچم
واردسازی رشته
تابع ریشه:
آرگ := رشته.تفکیک کردن("--name demo"، " ")
دیرکن آرگ.آزادکن()
ناپایا پ := پرچم.جدید("init"، "یک پروژه میسازد")
دیرکن پرچم.آزادسازی(پ)
پرچم.افزودن رشته(پ، "name"، ""، ""، "نام پروژه")
پرچم.افزودن منطقی(پ، "yes"، "y"، نادرست، "تایید نپرس")
پرچم.تجزیه(پ، آرگ)
ناپایا نام := پرچم.دریافت رشته(پ، "name")
اگر نام.طول() برابر ۰: نام = خط فرمان.درخواست با پیش فرض("نام پروژه"، "my-app") پایان
زبان برنامه := خط فرمان.درخواست با پیش فرض("زبان"، "فارسی")
سرچاپ ""
ناپایا ادامه := پرچم.دریافت منطقی(پ، "yes")
اگر وارونه ادامه: ادامه = خط فرمان.تایید("پروژهی " + نام + " به " + زبان برنامه + " ساخته شود؟") پایان
سرچاپ ""
اگر ادامه:
سرچاپ "ساخته شد:"، نام
وگرنه:
سرچاپ "چیزی ساخته نشد؛ برای نپرسیدن --yes را بدهید"
پایان
پایاناین خروجی حالتی است که ورودی استاندارد خالی است، مثل یک کار CI: پرسش زبان پیشفرضش را میگیرد و تایید رد میشود. پس از پرسشها خط تازهای نیامده، چون کسی Enter را نزده است.
گونهها
برنامه App
ساختار برنامه| نام | انگلیسی | گونه | توضیح |
|---|---|---|---|
| نام | name | رشته = "" | نام برنامه. |
| شرح | desc | رشته = "" | شرح برنامه. |
| نسخه | version | رشته = "" | نسخهی برنامه. |
| نام دستورها | cmd_names | وکتور<رشته> | نام دستورها. |
| شرح دستورها | cmd_descs | وکتور<رشته> | شرح دستورها. |
واردسازی خط فرمان
واردسازی رشته
تابع اجرا کن(ب &: خط فرمان.برنامه، خط: رشته):
آرگ := رشته.تفکیک کردن(خط، " ")
د := خط فرمان.توزیع(ب، آرگ)
اگر د == خط فرمان.دستور راهنما:
سرچاپ "راهنما خواسته شد"
وگرنه د == خط فرمان.دستور نسخه:
سرچاپ "نسخه:", ب.نسخه
وگرنه د == خط فرمان.دستور نامشخص:
سرچاپ "دستور ناشناخته"
وگرنه:
سرچاپ "اجرا:", د، خط فرمان.آرگومانهای باقیمانده(آرگ)
پایان
آرگ.آزادکن()
پایان
تابع ریشه:
ناپایا ب := خط فرمان.جدید("salamctl"، "مدیریت پروژه"، "1.0.0")
خط فرمان.ثبت(ب، "build"، "ساختن پروژه")
خط فرمان.ثبت(ب، "test"، "اجرای آزمونها")
سرچاپ خط فرمان.دستور دارد(ب، "build")، خط فرمان.شرح دستور(ب، "test")
هر خط در ["build --fast"، "--help"، "--version"، "deploy"]:
اجرا کن(ب، خط)
پایان
چاپ خط فرمان.راهنما(ب)
پایانپایاها و متغیرها
دستور راهنما 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=، نوشتهشده حساب میشود.واردسازی خط فرمان
واردسازی پرچم
تابع ریشه:
ناپایا پ := پرچم.جدید("deploy"، "")
دیرکن پرچم.آزادسازی(پ)
پرچم.افزودن رشته(پ، "host"، "H"، ""، "سرور")
پرچم.افزودن رشته(پ، "user"، "u"، ""، "کاربر")
ناپایا آرگ := وکتور {} برگردان وکتور<رشته>
دیرکن آرگ.آزادکن()
آرگ.بیفزا("--host=example.com")
پرچم.تجزیه(پ، آرگ)
ناپایا لازم := وکتور {} برگردان وکتور<رشته>
دیرکن لازم.آزادکن()
لازم.بیفزا("host")
لازم.بیفزا("user")
سرچاپ "جاافتاده:", خط فرمان.الزامی بودن پرچمها(پ، لازم)
پایانتایید Confirm
تابع تایید(question: رشته): منطقی[y/N]: چاپ میکند و یک خط میخواند. y یا yes، با حروف کوچک یا بزرگ و با فاصله در دو طرف، درست است؛ هر چیز دیگر، خط خالی یا پایان ورودی نادرست.واردسازی خط فرمان
تابع ریشه:
نام := خط فرمان.درخواست("نام پروژه")
زبان := خط فرمان.درخواست با پیش فرض("زبان"، "فارسی")
اگر خط فرمان.تایید("ساخته شود؟"):
سرچاپ "ساختن"، نام، "به"، زبان
پایان
پایاندرخواست Prompt
تابع درخواست(question: رشته): رشته: در پایانش چاپ میکند، یک خط میخواند و آن را بیفاصلههای دو طرف برمیگرداند. خودتان پرسش را با دونقطه تمام نکنید. در پایان ورودی رشتهی خالی برمیگرداند.نمونهی این مورد همراه با موارد بالاتر آمده است: cli-Prompt.salam
درخواست با پیش فرض PromptOr
تابع درخواست با پیش فرض(question: رشته، def: رشته): رشتهدرخواست، ولی پیشفرض را در پرانتز نشان میدهد، مثل زبان (فارسی): ، و اگر پاسخ خالی باشد همان را برمیگرداند.نمونهی این مورد همراه با موارد بالاتر آمده است: cli-Prompt.salam