pflag

وصف

pflag هو بديل مباشر لحزمة Go's flag، وينفذ نمط POSIX/GNU --flags.

يتوافق pflag مع امتدادات GNU لتوصيات POSIX لخيارات سطر الأوامر. للحصول على وصف أكثر دقة، راجع قسم "بناء جملة علامة سطر الأوامر" أدناه.

يتوفر pflag بنفس نمط ترخيص BSD مثل لغة Go، والذي يمكن العثور عليه في ملف الترخيص.

تثبيت

يتوفر pflag باستخدام الأمر go get القياسي.

التثبيت عن طريق التشغيل:

 go get github.com/spf13/pflag

قم بإجراء الاختبارات عن طريق التشغيل:

 go test github.com/spf13/pflag

الاستخدام

pflag هو بديل مباشر لحزمة العلم الأصلية لـ Go. إذا قمت باستيراد pflag تحت اسم "flag"، فيجب أن تستمر جميع التعليمات البرمجية في العمل دون أي تغييرات.

 import flag "github.com/spf13/pflag"

هناك استثناء واحد لهذا: إذا قمت بإنشاء مثيل لبنية العلم مباشرة، فهناك حقل آخر "Shorthhand" ستحتاج إلى تعيينه. لا تقوم معظم التعليمات البرمجية أبدًا بإنشاء مثيل لهذه البنية بشكل مباشر، وبدلاً من ذلك تستخدم وظائف مثل String() وBoolVar() وVar()، وبالتالي لا تتأثر.

تحديد العلامات باستخدام flag.String()، Bool()، Int()، إلخ.

يُعلن هذا عن علامة عدد صحيح، -flagname، مخزنة في عنوان IP الخاص بالمؤشر، بالنوع *int.

 var ip * int = flag . Int ( "flagname" , 1234 , "help message for flagname" )

إذا أردت، يمكنك ربط العلامة بمتغير باستخدام وظائف Var ().

 var flagvar int
func init () {
    flag . IntVar ( & flagvar , "flagname" , 1234 , "help message for flagname" )
}

أو يمكنك إنشاء علامات مخصصة تلبي واجهة القيمة (مع أجهزة استقبال المؤشر) وإقرانها بتحليل العلامات بواسطة

 flag . Var ( & flagVal , "name" , "help message for flagname" )

بالنسبة لمثل هذه العلامات، القيمة الافتراضية هي فقط القيمة الأولية للمتغير.

بعد تحديد كافة الأعلام، اتصل

 flag . Parse ()

لتحليل سطر الأوامر في العلامات المحددة.

ويمكن بعد ذلك استخدام الأعلام مباشرة. إذا كنت تستخدم الأعلام نفسها، فكلها مؤشرات؛ إذا قمت بربط المتغيرات، فهي قيم.

 fmt . Println ( "ip has value " , * ip )
fmt . Println ( "flagvar has value " , flagvar )

هناك وظائف مساعدة متاحة للحصول على القيمة المخزنة في العلامة إذا كان لديك FlagSet ولكنك تجد صعوبة في متابعة جميع المؤشرات الموجودة في التعليمات البرمجية الخاصة بك. إذا كان لديك pflag.FlagSet مع علامة تسمى "flagname" من النوع int، فيمكنك استخدام GetInt() للحصول على قيمة int. لكن لاحظ أن "اسم العلامة" يجب أن يكون موجودًا ويجب أن يكون int. ستفشل عملية GetString("flagname").

 i , err := flagset . GetInt ( "flagname" )

بعد التحليل، تتوفر الوسيطات بعد العلامة كشريحة flag.Args() أو بشكل فردي كـ flag.Arg(i). تتم فهرسة الوسائط من 0 إلى flag.NArg()-1.

تحدد الحزمة pflag أيضًا بعض الوظائف الجديدة غير الموجودة في العلم، والتي تعطي اختصارات من حرف واحد للأعلام. يمكنك استخدامها عن طريق إلحاق "P" باسم أي وظيفة تحدد العلامة.

 var ip = flag . IntP ( "flagname" , "f" , 1234 , "help message" )
var flagvar bool
func init () {
	flag . BoolVarP ( & flagvar , "boolname" , "b" , true , "help message" )
}
flag . VarP ( & flagVal , "varname" , "v" , "help message" )

يمكن استخدام الحروف المختصرة مع شرطات واحدة في سطر الأوامر. يمكن دمج أعلام الاختزال المنطقية مع أعلام الاختزال الأخرى.

يتم التحكم في المجموعة الافتراضية من إشارات سطر الأوامر بواسطة وظائف المستوى الأعلى. يسمح نوع FlagSet بتحديد مجموعات مستقلة من العلامات، مثل تنفيذ الأوامر الفرعية في واجهة سطر الأوامر. تشبه أساليب FlagSet وظائف المستوى الأعلى لمجموعة إشارات سطر الأوامر.

عدم تعيين قيم افتراضية للخيارات للأعلام

بعد إنشاء علامة، من الممكن تعيين pflag.NoOptDefVal للعلامة المحددة. يؤدي القيام بذلك إلى تغيير معنى العلم قليلاً. إذا كانت العلامة تحتوي على NoOptDefVal وتم تعيين العلامة في سطر الأوامر بدون خيار، فسيتم تعيين العلامة إلى NoOptDefVal. على سبيل المثال نظرا:

 var ip = flag . IntP ( "flagname" , "f" , 1234 , "help message" )
flag . Lookup ( "flagname" ). NoOptDefVal = "4321"

سوف يؤدي إلى شيء من هذا القبيل

الحجج المحللة	القيمة الناتجة
--اسم العلم=1357	الملكية الفكرية = 1357
--اسم العلم	الملكية الفكرية = 4321
[لا شئ]	الملكية الفكرية = 1234

بناء جملة إشارة سطر الأوامر

 --flag    // boolean flags, or flags with no option default values
--flag x  // only on flags without a default value
--flag=x

على عكس حزمة العلم، فإن الشرطة الواحدة قبل الخيار تعني شيئًا مختلفًا عن الشرطة المزدوجة. تشير الشرطات المفردة إلى سلسلة من الحروف المختصرة للأعلام. يجب أن تكون جميع الأحرف المختصرة ما عدا الحرف الأخير عبارة عن علامات منطقية أو علامة ذات قيمة افتراضية

 // boolean or flags where the 'no option default value' is set
-f
-f=true
-abc
but
-b true is INVALID

// non-boolean and flags without a 'no option default value'
-n 1234
-n=1234
-n1234

// mixed
-abcs "hello"
-absd="hello"
-abcs1234

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

تقبل الأعلام الصحيحة 1234، 0664، 0x1234 وقد تكون سالبة. تقبل الأعلام المنطقية (في شكلها الطويل) 1، 0، t، f، true، false، TRUE، FALSE، True، False. تقبل علامات المدة أي إدخال صالح للوقت.ParseDuration.

تغيير أو "تطبيع" أسماء العلم

من الممكن تعيين اسم علامة مخصصة "وظيفة التطبيع". فهو يسمح بتغيير أسماء العلامات عند إنشائها في التعليمات البرمجية وعند استخدامها في سطر الأوامر إلى نموذج "مطبيع". يتم استخدام النموذج "المطبيع" للمقارنة. فيما يلي مثالان لاستخدام وظيفة التطبيع المخصصة.

المثال رقم 1 : أنت تريد - و _ و . في الأعلام للمقارنة نفسه. ويعرف أيضًا باسم --my-flag == --my_flag == --my.flag

 func wordSepNormalizeFunc ( f * pflag. FlagSet , name string ) pflag. NormalizedName {
	from := [] string { "-" , "_" }
	to := "."
	for _ , sep := range from {
		name = strings . Replace ( name , sep , to , - 1 )
	}
	return pflag . NormalizedName ( name )
}

myFlagSet . SetNormalizeFunc ( wordSepNormalizeFunc )

مثال رقم 2 : تريد تسمية علامتين باسم مستعار. ويعرف أيضًا باسم --old-flag-name == --new-flag-name

 func aliasNormalizeFunc ( f * pflag. FlagSet , name string ) pflag. NormalizedName {
	switch name {
	case "old-flag-name" :
		name = "new-flag-name"
		break
	}
	return pflag . NormalizedName ( name )
}

myFlagSet . SetNormalizeFunc ( aliasNormalizeFunc )

استنكار العلم أو اختصاره

من الممكن إهمال العلم أو مجرد اختصاره. يؤدي إهمال العلامة/الاختزال إلى إخفاءها من نص المساعدة وطباعة رسالة استخدام عند استخدام العلامة/الاختزال المهمل.

المثال رقم 1 : تريد إيقاف علامة تسمى "badflag" بالإضافة إلى إعلام المستخدمين بالعلامة التي يجب عليهم استخدامها بدلاً من ذلك.

 // deprecate a flag by specifying its name and a usage message
flags . MarkDeprecated ( "badflag" , "please use --good-flag instead" )

يؤدي هذا إلى إخفاء "badflag" من نص المساعدة، وطباعة Flag --badflag has been deprecated, please use --good-flag instead عند استخدام "badflag".

المثال رقم 2 : تريد الاحتفاظ باسم العلم "noshorthandflag" ولكن مع إلغاء اسمه المختصر "n".

 // deprecate a flag shorthand by specifying its flag name and a usage message
flags . MarkShorthandDeprecated ( "noshorthandflag" , "please use --noshorthandflag only" )

يؤدي هذا إلى إخفاء الاسم المختصر "n" من نص المساعدة، ويطبع Flag shorthand -n has been deprecated, please use --noshorthandflag only عند استخدام الاختصار "n".

لاحظ أن رسالة الاستخدام ضرورية هنا، ويجب ألا تكون فارغة.

أعلام مخفية

من الممكن وضع علامة على العلم على أنه مخفي، مما يعني أنه سيظل يعمل كالمعتاد، ومع ذلك لن يظهر في نص الاستخدام/التعليمات.

مثال : لديك علامة باسم "secretFlag" تحتاجها للاستخدام الداخلي فقط ولا تريد ظهورها في نص المساعدة، أو أن يكون نص الاستخدام متاحًا.

 // hide a flag by specifying its name
flags . MarkHidden ( "secretFlag" )

تعطيل فرز الأعلام

يتيح لك pflag تعطيل فرز الإشارات الخاصة برسائل المساعدة والاستخدام.

مثال :

 flags . BoolP ( "verbose" , "v" , false , "verbose output" )
flags . String ( "coolflag" , "yeaah" , "it's really cool flag" )
flags . Int ( "usefulflag" , 777 , "sometimes it's very useful" )
flags . SortFlags = false
flags . PrintDefaults ()

الإخراج :

  -v, --verbose           verbose output
      --coolflag string   it's really cool flag (default "yeaah")
      --usefulflag int    sometimes it's very useful (default 777)

دعم علامات Go عند استخدام pflag

من أجل دعم الأعلام المحددة باستخدام حزمة flag Go، يجب إضافتها إلى مجموعة أعلام pflag . يعد هذا ضروريًا عادةً لدعم العلامات المحددة بواسطة تبعيات الطرف الثالث (مثل golang/glog ).

مثال : تريد إضافة علامات Go إلى مجموعة علامات CommandLine

 import (
	goflag "flag"
	flag "github.com/spf13/pflag"
)

var ip * int = flag . Int ( "flagname" , 1234 , "help message for flagname" )

func main () {
	flag . CommandLine . AddGoFlagSet ( goflag . CommandLine )
	flag . Parse ()
}

مزيد من المعلومات

يمكنك الاطلاع على الوثائق المرجعية الكاملة لحزمة pflag على godoc.org، أو من خلال نظام التوثيق القياسي الخاص بـ go عن طريق تشغيل godoc -http=:6060 والتصفح على http://localhost:6060/pkg/github.com/spf13/pflag بعد التثبيت.