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

پرچم flag

خواندن گزینه‌های خط فرمان مثل --port 8080 و -v با گونه‌ی درست و راهنمای خودکار.

واردسازی پرچم

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

بسته‌ی پرچم گزینه‌های خط فرمان را می‌خواند. هر پرچم یک نام بلند (--port)، یک نام کوتاه اختیاری (-p)، یک گونه (منطقی، رشته، صحیح یا اعشاری)، مقدار پیش‌فرض و یک متن راهنما دارد. مقدار را می‌توان به هر دو شکل داد: --port=8080 یا --port 8080. هر آرگومانی که پرچم نباشد «موقعیتی» است، و پس از -- همه‌چیز موقعیتی حساب می‌شود. برای برنامه‌ای با زیرفرمان‌هایی مثل tool build و tool test بسته‌ی خط فرمان و برای تنظیم‌های محیطی بسته‌ی محیط را ببینید.

گام‌ها همیشه یکی‌اند: جدید، یک افزودن ... برای هر پرچم، تجزیه با آرگومان‌ها (بدون نام خود برنامه)، و بعد بررسی نتیجه‌ی تجزیه و راهنما خواسته پیش از خواندن مقدارها با دریافت رشته، دریافت صحیح، دریافت اعشاری و دریافت منطقی. --help و -h همیشه شناخته می‌شوند و رزرو شده‌اند، و متن راهنما خودکار ساخته می‌شود.

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

  • فراموش کردن این‌که پرچم مقداردار آرگومان بعدی را هر چه باشد برمی‌دارد. --name --verbose نام را --verbose می‌کند.
  • دادن عدد منفی به‌عنوان آرگومان موقعیتی. -5 شبیه پرچم است و خطای «پرچم ناشناخته» می‌دهد؛ پیش از آن -- بگذارید، یا برای مقدار پرچم --offset=-5 بنویسید.
  • انتظار خطا برای مقدار منطقی نادرست. --verbose=maybe پذیرفته می‌شود و نادرست خوانده می‌شود؛ فقط true، 1، yes و on درست‌اند.

خواندن خط فرمان واقعی

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

flag-guide-args.salam
واردسازی خط فرمان
واردسازی پرچم
واردسازی سیستم عامل

تابع ریشه:
    ناپایا آرگ := خط فرمان.آرگومان‌های باقیمانده(سیستم عامل.آرگومان ها())
    دیرکن آرگ.آزادکن()
    اگر آرگ.طول() برابر ۰:
        هر آ در ["--name"، "سارا"، "-n"، "2"، "--excited"]: آرگ.بیفزا(آ) پایان
    پایان
    ناپایا پ := پرچم.جدید("greet"، "یک خوشامد چاپ می‌کند")
    دیرکن پرچم.آزادسازی(پ)
    پرچم.افزودن رشته(پ، "name"، ""، "دنیا"، "به چه کسی سلام کنیم")
    پرچم.افزودن صحیح(پ، "times"، "n"، ۱، "چند بار")
    پرچم.افزودن منطقی(پ، "excited"، "e"، نادرست، "با سه علامت تعجب تمام کن")
    اگر وارونه پرچم.تجزیه(پ، آرگ):
        سرچاپ "greet:"، پرچم.خطا(پ)
        برگشت ۲
    پایان
    اگر پرچم.راهنما خواسته(پ):
        چاپ پرچم.راهنما(پ)
        برگشت ۰
    پایان
    خط := "سلام " + پرچم.دریافت رشته(پ، "name") + (پرچم.دریافت منطقی(پ، "excited") ? "!!!" : ".")
    تکرار پرچم.دریافت صحیح(پ، "times") برگردان صحیح:
        سرچاپ خط
    پایان
    برگشت ۰
پایان
خروجیسلام سارا!!! سلام سارا!!!

برای دادن آرگومان‌های خودتان آن را این‌طور اجرا کنید: salam run greet.salam --name علی -n 3. وقتی آرگومانی نگیرد، مثل این‌جا، یک نمونه‌ی درونی را به کار می‌برد تا خروجی بالا همیشه همین بماند.

گزارش ورودی نادرست

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

flag-guide-errors.salam
واردسازی پرچم
واردسازی رشته

تابع امتحان(خط: رشته): صحیح:
    آرگ := رشته.تفکیک کردن(خط، " ")
    دیرکن آرگ.آزادکن()
    ناپایا پ := پرچم.جدید("resize"، "اندازه‌ی تصویرها را عوض می‌کند")
    دیرکن پرچم.آزادسازی(پ)
    پرچم.افزودن صحیح(پ، "width"، "w"، ۸۰۰، "پهنای تازه به پیکسل")
    پرچم.افزودن اعشاری(پ، "quality"، "q"، ۰.۹، "کیفیت JPEG")
    پرچم.افزودن رشته(پ، "out"، "o"، "out"، "پوشه‌ی خروجی")
    اگر وارونه پرچم.تجزیه(پ، آرگ):
        سرچاپ "خطا:"، پرچم.خطا(پ)
        برگشت ۲
    پایان
    سرچاپ "پذیرفته شد: پهنا"، پرچم.دریافت صحیح(پ، "width")، "کیفیت"، پرچم.دریافت اعشاری(پ، "quality")، "پرونده‌ها"، پرچم.موقعیتی(پ)
    برگشت ۰
پایان

تابع ریشه:
    هر خط در ["-w 640 a.jpg"، "--width=wide a.jpg"، "--quality=0,5 a.jpg"، "--height 100"، "a.jpg -o"]:
        سرچاپ "$ resize"، خط
        سرچاپ "کد خروج"، امتحان(خط)
    پایان
پایان
خروجی$ resize -w 640 a.jpg پذیرفته شد: پهنا 640 کیفیت 0.9 پرونده‌ها ["a.jpg"] کد خروج 0 $ resize --width=wide a.jpg خطا: invalid int value for --width: wide کد خروج 2 $ resize --quality=0,5 a.jpg خطا: invalid float value for --quality: 0,5 کد خروج 2 $ resize --height 100 خطا: unknown flag: --height کد خروج 2 $ resize a.jpg -o خطا: missing value for flag: -o کد خروج 2

پیام‌ها انگلیسی‌اند. پرچم ناشناخته و مقدار جاافتاده تجزیه را همان‌جا متوقف می‌کنند؛ عددها پس از خواندن کل خط و به ترتیب تعریف پرچم‌ها بررسی می‌شوند. مقدار اعشاری باید نقطه (یا ممیز فارسی ٫) داشته باشد، پس 0,5 رد می‌شود. پرچم‌های عددی رقم‌های فارسی را هم می‌پذیرند. اگر پرچمی دو بار بیاید، مقدار آخر می‌ماند.

اول پرچم، بعد محیط، بعد پیش‌فرض

بسیاری از برنامه‌ها یک تنظیم را از پرچم می‌خوانند، اگر نبود سراغ متغیر محیطی می‌روند و در آخر پیش‌فرض درونی را به کار می‌برند. تنظیم شده این را ممکن می‌کند: فرق «کاربر --port 8080 نوشت» با «۸۰۸۰ فقط پیش‌فرض است» را می‌گوید، کاری که دریافت صحیح به‌تنهایی نمی‌تواند.

flag-guide-precedence.salam
واردسازی محیط
واردسازی پرچم
واردسازی رشته

تابع درگاه از(خط: رشته): صحیح۶۴:
    آرگ := رشته.تفکیک کردن(خط، " ")
    دیرکن آرگ.آزادکن()
    ناپایا پ := پرچم.جدید("server"، "")
    دیرکن پرچم.آزادسازی(پ)
    پرچم.افزودن صحیح(پ، "port"، "p"، ۸۰۸۰، "درگاهی که روی آن گوش می‌دهد")
    پرچم.تجزیه(پ، آرگ)
    اگر پرچم.تنظیم شده(پ، "port"): برگشت پرچم.دریافت صحیح(پ، "port") پایان
    برگشت محیط.دریافت صحیح("PORT"، پرچم.دریافت صحیح(پ، "port"))
پایان

تابع ریشه:
    محیط.حذف("PORT")
    سرچاپ "هیچ چیز تنظیم نشده:"، درگاه از("app.log")
    محیط.تنظیم("PORT"، "3000")
    سرچاپ "PORT=3000:"، درگاه از("app.log")
    سرچاپ "PORT=3000 و -p 9000:"، درگاه از("-p 9000")
    سرچاپ "PORT=3000 و --port=8080:"، درگاه از("--port=8080")
پایان
خروجیهیچ چیز تنظیم نشده: 8080 PORT=3000: 3000 PORT=3000 و -p 9000: 9000 PORT=3000 و --port=8080: 8080

خط آخر مهم است: --port=8080 همان عدد پیش‌فرض است، ولی کاربر آن را صریح خواسته، پس بر PORT مقدم است. برای سمت محیط، بسته‌ی محیط را ببینید.

نام‌های کوتاه، پرچم‌های منطقی و آرگومان‌های موقعیتی

پرچم‌ها و آرگومان‌های موقعیتی به هر ترتیبی می‌توانند بیایند. پرچم منطقی هیچ‌وقت آرگومان بعدی را مقدار خودش نمی‌گیرد؛ برای خاموش کردن پرچمی که پیش‌فرضش درست است بنویسید --name=false. پس از -- حتی آرگومان‌هایی که شبیه پرچم‌اند موقعیتی‌اند؛ برنامه این‌طور پرونده‌ای به نام -r را می‌پذیرد.

flag-guide-positional.salam
واردسازی پرچم
واردسازی رشته

تابع ریشه:
    آرگ := رشته.تفکیک کردن("-r --dry-run=false --depth ۳ src docs -- --not-a-flag -r"، " ")
    دیرکن آرگ.آزادکن()
    ناپایا پ := پرچم.جدید("sync"، "پوشه‌ها را رونوشت می‌کند")
    دیرکن پرچم.آزادسازی(پ)
    پرچم.افزودن منطقی(پ، "recursive"، "r"، نادرست، "زیرپوشه‌ها را هم بگرد")
    پرچم.افزودن منطقی(پ، "dry-run"، "n"، درست، "فقط بگو چه می‌شود")
    پرچم.افزودن صحیح(پ، "depth"، "d"، ۱، "تا چه عمقی برود")
    سرچاپ پرچم.تجزیه(پ، آرگ)، "[" + پرچم.خطا(پ) + "]"
    سرچاپ "بازگشتی:"، پرچم.دریافت منطقی(پ، "recursive")
    سرچاپ "اجرای آزمایشی:"، پرچم.دریافت منطقی(پ، "dry-run")
    سرچاپ "عمق:"، پرچم.دریافت صحیح(پ، "depth")
    موقعیت‌ها := پرچم.موقعیتی(پ)
    دیرکن موقعیت‌ها.آزادکن()
    هر ش، م در موقعیت‌ها:
        سرچاپ "آرگومان"، ش، م
    پایان
پایان
خروجیtrue [] بازگشتی: true اجرای آزمایشی: false عمق: 3 آرگومان 0 src آرگومان 1 docs آرگومان 2 --not-a-flag آرگومان 3 -r

نام‌های کوتاه را نمی‌توان با هم نوشت: -rv یک پرچم به نام rv خوانده می‌شود و خطای «پرچم ناشناخته» می‌دهد. به جایش بنویسید -r -v.

گونه‌ها

مجموعه پرچم FlagSet

ساختار مجموعه پرچم
مجموعه‌ی پرچم‌های یک برنامه و نتیجه‌ی تجزیه.
نامانگلیسیگونهتوضیح
برنامهprogرشته = ""نام برنامه، برای راهنما.
شرحdescرشته = ""شرح برنامه، برای راهنما.
نام‌هاnamesوکتور<رشته>نام بلند پرچم‌ها.
نام‌های کوتاهshortsوکتور<رشته>نام کوتاه پرچم‌ها.
گونه‌هاkindsوکتور<صحیح>گونه‌ی هر پرچم.
مقدارهاvalsوکتور<رشته>مقدار فعلی هر پرچم به شکل متن.
پیش‌فرض‌هاdefsوکتور<رشته>مقدار پیش‌فرض هر پرچم.
راهنماهاhelpsوکتور<رشته>متن راهنمای هر پرچم.
تنظیم‌شدهwas_setوکتور<منطقی>اینکه هر پرچم در خط فرمان آمده یا نه.
موقعیتی‌هاposوکتور<رشته>آرگومان‌های موقعیتی.
خطاerrرشته = ""پیام آخرین خطای تجزیه.
راهنما خواسته شدhelp_wantedمنطقی = نادرستاگر --help آمده باشد، درست است.
flag-Parse.salam
واردسازی پرچم

تابع ریشه:
    ناپایا پ := پرچم.جدید("کپی"، "پرونده‌ها را رونوشت می‌کند")
    دیرکن پرچم.آزادسازی(پ)
    پرچم.افزودن منطقی(پ، "verbose"، "v"، نادرست، "گزارش کامل")
    پرچم.افزودن رشته(پ، "out"، "o"، "خروجی"، "پوشه‌ی مقصد")
    پرچم.افزودن صحیح(پ، "jobs"، "j"، ۱، "تعداد کار همزمان")
    پرچم.افزودن اعشاری(پ، "ratio"، "r"، ۱.۰، "نسبت فشرده‌سازی")
    ناپایا آرگ := وکتور {} برگردان وکتور<رشته>
    دیرکن آرگ.آزادکن()
    هر آ در ["-v"، "--out=backup"، "-j"، "4"، "a.txt"، "b.txt"]:
        آرگ.بیفزا(آ)
    پایان
    سرچاپ پرچم.تجزیه(پ، آرگ)، "[" + پرچم.خطا(پ) + "]"
    سرچاپ پرچم.دریافت منطقی(پ، "verbose")، پرچم.دریافت رشته(پ، "out")، پرچم.دریافت صحیح(پ، "jobs")، پرچم.دریافت اعشاری(پ، "ratio")
    سرچاپ پرچم.تنظیم شده(پ، "jobs")، پرچم.تنظیم شده(پ، "ratio")
    سرچاپ پرچم.موقعیتی(پ)، پرچم.راهنما خواسته(پ)
    سرچاپ پرچم.نوع منطقی، پرچم.نوع رشته، پرچم.نوع صحیح، پرچم.نوع اعشاری
پایان
خروجیtrue [] true backup 4 1 true false ["a.txt", "b.txt"] false 0 1 2 3

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

نوع منطقی FlagKindBool

پایا نوع منطقی: صحیح۳۲ = 0
گونه‌ی پرچم منطقی.

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

نوع رشته FlagKindStr

پایا نوع رشته: صحیح۳۲ = 1
گونه‌ی پرچم رشته.

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

نوع صحیح FlagKindInt

پایا نوع صحیح: صحیح۳۲ = 2
گونه‌ی پرچم عدد صحیح.

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

نوع اعشاری FlagKindFloat

پایا نوع اعشاری: صحیح۳۲ = 3
گونه‌ی پرچم عدد اعشاری.

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

تابع‌ها

جدید New

تابع جدید(prog_name: رشته، description: رشته): مجموعه پرچم
مجموعه‌ی پرچم تازه‌ای با نام و شرح برنامه می‌سازد.

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

افزودن منطقی AddBool

تابع افزودن منطقی(fs &: مجموعه پرچم، name: رشته، short: رشته، def: منطقی، help: رشته)
یک پرچم منطقی تعریف می‌کند؛ با آمدنش درست می‌شود و --name=false (یا =0، =no) خاموشش می‌کند. هرگز آرگومان بعدی را مقدار خودش نمی‌گیرد.

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

افزودن رشته AddStr

تابع افزودن رشته(fs &: مجموعه پرچم، name: رشته، short: رشته، def: رشته، help: رشته)
یک پرچم رشته‌ای تعریف می‌کند. مقدارش متن پس از = یا آرگومان بعدی است، حتی اگر با - شروع شود.

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

افزودن صحیح AddInt

تابع افزودن صحیح(fs &: مجموعه پرچم، name: رشته، short: رشته، def: صحیح۶۴، help: رشته)
یک پرچم عدد صحیح تعریف می‌کند؛ علامت و رقم فارسی پذیرفته است و هر چیز دیگری تجزیه را شکست می‌دهد.

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

افزودن اعشاری AddFloat

تابع افزودن اعشاری(fs &: مجموعه پرچم، name: رشته، short: رشته، def: اعشار۶۴، help: رشته)
یک پرچم اعشاری تعریف می‌کند؛ نقطه یا ٫، توانی مثل 1e3 و رقم فارسی پذیرفته است.

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

تجزیه Parse

تابع تجزیه(fs &: مجموعه پرچم، arglist: وکتور<رشته>): منطقی
آرگومان‌ها را بدون نام برنامه تجزیه می‌کند. با پرچم ناشناخته، مقدار جاافتاده یا عدد نادرست نادرست برمی‌گرداند و خطا دلیلش را می‌گوید. --help آن را شکست نمی‌دهد؛ راهنما خواسته را بررسی کنید.

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

دریافت رشته GetStr

تابع دریافت رشته(fs &: مجموعه پرچم، name: رشته): رشته
مقدار پرچم رشته‌ای یا پیش‌فرض آن؛ برای نامی که هرگز تعریف نشده خالی.

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

دریافت صحیح GetInt

تابع دریافت صحیح(fs &: مجموعه پرچم، name: رشته): صحیح۶۴
مقدار پرچم عدد صحیح.

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

دریافت اعشاری GetFloat

تابع دریافت اعشاری(fs &: مجموعه پرچم، name: رشته): اعشار۶۴
مقدار پرچم اعشاری.

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

دریافت منطقی GetBool

تابع دریافت منطقی(fs &: مجموعه پرچم، name: رشته): منطقی
مقدار پرچم منطقی: برای true، 1، yes یا on درست و برای هر چیز دیگر نادرست.

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

تنظیم شده WasSet

تابع تنظیم شده(fs &: مجموعه پرچم، name: رشته): منطقی
اگر پرچم در خط فرمان آمده باشد، درست برمی‌گرداند؛ برای تشخیص «مقدار پیش‌فرض» از «کاربر خودش همین را داده».

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

موقعیتی Positional

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

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

راهنما خواسته HelpWanted

تابع راهنما خواسته(fs &: مجموعه پرچم): منطقی
اگر کاربر راهنما خواسته باشد، درست برمی‌گرداند.
flag-Usage.salam
واردسازی پرچم

تابع ریشه:
    ناپایا پ := پرچم.جدید("ابزار"، "یک ابزار نمونه")
    دیرکن پرچم.آزادسازی(پ)
    پرچم.افزودن منطقی(پ، "quiet"، "q"، نادرست، "بی‌صدا")
    پرچم.افزودن صحیح(پ، "port"، "p"، ۸۰۸۰، "درگاه")
    ناپایا آرگ := وکتور {} برگردان وکتور<رشته>
    دیرکن آرگ.آزادکن()
    آرگ.بیفزا("--help")
    پرچم.تجزیه(پ، آرگ)
    اگر پرچم.راهنما خواسته(پ):
        چاپ پرچم.راهنما(پ)
    پایان
    ناپایا بد := وکتور {} برگردان وکتور<رشته>
    دیرکن بد.آزادکن()
    بد.بیفزا("--port=abc")
    ناپایا پ۲ := پرچم.جدید("ابزار"، "")
    دیرکن پرچم.آزادسازی(پ۲)
    پرچم.افزودن صحیح(پ۲، "port"، "p"، ۸۰۸۰، "درگاه")
    سرچاپ پرچم.تجزیه(پ۲، بد)، پرچم.خطا(پ۲)
پایان
خروجیUsage: ابزار [options] [args] یک ابزار نمونه Options: -q, --quiet بی‌صدا -p, --port <int> درگاه (default: 8080) -h, --help show this help false invalid int value for --port: abc

خطا Error

تابع خطا(fs &: مجموعه پرچم): رشته
پیام خطای آخرین تجزیه.

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

راهنما Usage

تابع راهنما(fs &: مجموعه پرچم): رشته
متن کامل راهنما: یک خط کاربرد، توضیح برنامه، و برای هر پرچم یک خط با نام کوتاه، گونه، راهنما و پیش‌فرض، و در پایان -h, --help.

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

آزادسازی Free

تابع آزادسازی(fs &: مجموعه پرچم)
حافظه‌ی مجموعه را آزاد می‌کند.

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