README.md (2021B)
1 # rsc.io/getopt 2 3 [For full package documentation, see [https://godoc.org/rsc.io/getopt](https://godoc.org/rsc.io/getopt).] 4 5 package getopt // import "rsc.io/getopt" 6 7 Package getopt parses command lines using [_getopt_(3)](http://man7.org/linux/man-pages/man3/getopt.3.html) syntax. It is a 8 replacement for `flag.Parse` but still expects flags themselves to be defined 9 in package flag. 10 11 Flags defined with one-letter names are available as short flags (invoked 12 using one dash, as in `-x`) and all flags are available as long flags (invoked 13 using two dashes, as in `--x` or `--xylophone`). 14 15 To use, define flags as usual with [package flag](https://godoc.org/flag). Then introduce any aliases 16 by calling `getopt.Alias`: 17 18 getopt.Alias("v", "verbose") 19 20 Or call `getopt.Aliases` to define a list of aliases: 21 22 getopt.Aliases( 23 "v", "verbose", 24 "x", "xylophone", 25 ) 26 27 One name in each pair must already be defined in package flag (so either 28 "v" or "verbose", and also either "x" or "xylophone"). 29 30 Then parse the command-line: 31 32 getopt.Parse() 33 34 If it encounters an error, `Parse` calls `flag.Usage` and then exits the 35 program. 36 37 When writing a custom `flag.Usage` function, call `getopt.PrintDefaults` instead 38 of `flag.PrintDefaults` to get a usage message that includes the 39 names of aliases in flag descriptions. 40 41 At initialization time, package getopt installs a new `flag.Usage` that is the same 42 as the default `flag.Usage` except that it calls `getopt.PrintDefaults` instead 43 of `flag.PrintDefaults`. 44 45 This package also defines a `FlagSet` wrapping the standard `flag.FlagSet`. 46 47 ## Caveat 48 49 In general Go flag parsing is preferred for new programs, because it is not 50 as pedantic about the number of dashes used to invoke a flag (you can write 51 `-verbose` or `--verbose` and the program does not care). This package is meant 52 to be used in situations where, for legacy reasons, it is important to use 53 exactly _getopt_(3) syntax, such as when rewriting in Go an existing tool that 54 already uses _getopt_(3).