pflag

คำอธิบาย

pflag เป็นการแทนที่แบบดรอปอินสำหรับแพ็คเกจแฟล็กของ Go โดยใช้ POSIX/GNU-style --flags

pflag เข้ากันได้กับส่วนขยาย GNU ไปยังคำแนะนำ POSIX สำหรับตัวเลือกบรรทัดคำสั่ง สำหรับคำอธิบายที่แม่นยำยิ่งขึ้น โปรดดูส่วน "ไวยากรณ์แฟล็กบรรทัดคำสั่ง" ด้านล่าง

pflag มีให้บริการภายใต้ลิขสิทธิ์ BSD รูปแบบเดียวกับภาษา Go ซึ่งสามารถพบได้ในไฟล์ LICENSE

การติดตั้ง

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"

มีข้อยกเว้นประการหนึ่งสำหรับสิ่งนี้: หากคุณสร้างอินสแตนซ์ของโครงสร้าง Flag โดยตรง จะมีฟิลด์ "ชวเลข" อีกหนึ่งฟิลด์ที่คุณจะต้องตั้งค่า โค้ดส่วนใหญ่ไม่เคยสร้างอินสแตนซ์ของโครงสร้างนี้โดยตรง และใช้ฟังก์ชันต่างๆ เช่น 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 )

มีฟังก์ชันตัวช่วยที่สามารถใช้เพื่อรับค่าที่จัดเก็บไว้ใน Flag หากคุณมี FlagSet แต่พบว่าเป็นเรื่องยากที่จะติดตามพอยน์เตอร์ทั้งหมดในโค้ดของคุณ หากคุณมี pflag.FlagSet ที่มีแฟล็กชื่อ 'flagname' ประเภท int คุณสามารถใช้ GetInt() เพื่อรับค่า int แต่สังเกตว่าต้องมี 'ชื่อธง' อยู่และต้องเป็น int GetString("flagname") จะล้มเหลว

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

หลังจากแยกวิเคราะห์ อาร์กิวเมนต์หลังแฟล็กจะพร้อมใช้งานเป็นแฟล็กสไลซ์ Args() หรือแยกเป็นแฟล็ก 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, จริง, เท็จ ธงระยะเวลายอมรับอินพุตใด ๆ ที่ถูกต้องสำหรับ time.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 : คุณต้องการใช้นามแฝงสองแฟล็ก aka --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 หลังการติดตั้ง