Translator: Man getopt (1) Chinese manual

NAME

   getopt - 解析命令行选项(加强版)

Synopsis

       getopt optstring parameters       getopt [options] [--] optstring parameters       getopt [options] -o|--options optstring [options] [--] parameters

Moqtada

1. Each of the 3 syntax formats, Syntax 1, Syntax 2, and Syntax 3, will be referred to in the following translations.
   
2. Please distinguish between option, parameter, argument, option argument, non-option parameter. If not clear, please refer to: https://www.cnblogs.com/f-ck-need-u/p/9750845.html
   )

DESCRIPTION

The getopt is used to split (parse) the options on the command line so that it can be easily parsed by a shell thread, such as a shell script, and to check whether the options are justified. This command is implemented using the GNU getopt (3) program.

The parameters of the getopt are divided into two parts: the options for modifying the getopt parsing mode (that is, option and-o|--options optstring in the syntax) and the parameters to be parsed (that is, the parameters part of the syntax). The second section starts with the first non-option parameter, or from the first item after "--". If no "-o|--options" is given in the first section, the first parameter of the second part is used as a short option string.

If the environment variable getopt_compatible is set, or if its first parameter is not an option (that is, the string that begins with "-", Syntax 1), Getopt generates output that is compatible with the other getopt (1). It still adjusts the parameters and identifies the optional parameters (see the compatibility section below).

Traditional getopt (1) cannot copy whitespace characters and other special characters (specifically, special characters of the shell). To solve this problem, getopt can generate quotation-protected output and then use the shell to explain it (usually using the eval command), which protects these special characters, but only if the compatible version of Getopt (that is, Syntax 2 and syntax 3 can be resolved). To determine if the installed getopt is an enhanced version of getopt, simply test with the special option "-T".

OPTIONS

-a, --alternative
Allow long options to start with a single dash "-". (That is, options that start with a single dash are also considered long options)

-h, --help
The usage help information for the output getopt.

-l, --longoptions longopts
Identify long options (options for multiple characters). Longopts can specify multiple option names at once, just by separating them with commas. This option can be used multiple times and longopts will accumulate. In longopts, each long option name can be followed by a colon, indicating that the option requires either a parameter or a two colon, which indicates that the option parameter is optional.

-n, --name progname
When Getopt (3) reports an error, getopt (3) uses that name. Note that the getopt (1) error is still reported as coming from Getopt.

-o, --options shortopts
Identify short options (options for single characters). If this option is not given, the first parameter of getopt that does not begin with "-" (and not option argument) will be used for the short option string. Each short-choice character in the shortopts can be followed by a colon, indicating that the option requires either a parameter or a two colon, which indicates that the option's parameters are optional. The first character of Shortopts can be set to "+" or "-" to affect how the options are parsed and output (see scanning MODES below for details).

-q, --quiet
Disable getopt (3) Output error message.

-Q, --quiet-output
Disables the normal output. However, the error message generated by GETOPT (3) is still output unless the "-q" option is also specified.

-s, --shell shell
Specifies which Shell's quotation-mark resolution is used. If the-s option is not used, bash is used. Other supported shell types include: sh, bash, csh, and tcsh.

-u, --unquoted
Do not surround the output with quotation marks. Note that the white space character and the shell special characters will be destroyed (just like other versions of getopt (1)) after the forbidden quotation mark is protected.

-T, --test
The getopt (1) used in the test is a reinforced version or a legacy version. The getopt of the enhanced version has no output and the exit status code is 4. Other versions of getopt (1) or the enhanced version of getopt set the getopt_compatible environment variable, then output "--" and the exit status code is 0.

-V, --version
Output the version number of the Getopt and exit.

Parsing

This section specifies the format of the second part of the getopt parameter. The next section (output) describes the generated output. These parameters are usually parameters of the shell function call. It is important to note that each parameter that is called when the shell function is invoked exactly corresponds to one of the parameters in the getopt parameter list (see examples). All parsing behavior is done by the GNU getopt (3).

Parameter parsing is resolved from left to right. Each parameter is categorized as one of the short, long, option parameter (option argument) and non-option-type parameters (non-option parameter).

A simple short option is to use "-" followed by a short option character. If the option requires a parameter, this option parameter can be written directly after the option character (for example -n3 ), or as the next parameter (for example, use whitespace separation in the command (for example -n 3 )). If the parameter of the option is optional, the parameter must be written directly after the option character if the given option parameter needs to be parsed (that is, you cannot use whitespace to separate options and its arguments).

You can follow a single dash followed by a number of short option characters ( tar -zcf ZCF, for example, are all behind a single "-"), as long as they do not require parameters (which allows the last parameter) to be used (refer to tar -zcf a.tar.gz the format).

The long option typically starts with "--" followed by the name of the long option. If the long option requires parameters, you can use the "=" connection to the long option and its parameters, or the parameter as the next parameter for the long option (for example, two forms: --file=FILE or --file FILE ). If the parameter of the long option is optional, you must use the "=" connection long option and its parameter value. Long options can be abbreviated, as long as they do not create ambiguity.

If a parameter does not start with "-" and is not the required parameter for the option preceding it, then it is a non-option type parameter (non-option parameter). Each parameter that followed the "--" long option is always resolved to a non-option type parameter (non-option parameter). If an environment variable is set POSIXLY_CORRECT , or if the short option character starts with "+", all remaining arguments are resolved to a parameter of the non-option type (non-option parameter).

OUTPUT

Output is generated for each element described in the previous section. Output outputs are in the same order as input given, except for non-option-type parameters (non-option parameter). You can use compatibility mode (without using quotation marks) to process output, or you can use the quoted pattern to process output, so that whitespace characters, special characters in argument, and parameters of non-option types can be preserved as they are (see quoting below). When working with output in a shell script, in general, the individual elements can be processed one at a time (most shell languages can be implemented with the shift command), but this pattern is defective, non-quoted protected mode, if there are special characters, Each element may be cut in an unexpected position.

If there is a problem parsing parameter, such as if the required argument is not found, or if an option is not recognized, an error is reported to stderr, and the option that produces the error will not have any output and returns a non-0 status code.

For short options, a parameter consisting of "-" and an option character is generated. If the option has an option parameter (argument), the next parameter will be used as the argument for that option. If the option has an optional parameter, but this parameter is not found, if in quotation-protected mode, an empty argument surrounded by quotation marks is generated as the next parameter, and if it is under compatibility mode (non-quotation-protected), the next parameter is not generated. Note that many other versions of getopt (1) Do not support optional parameters.

(for example, the "-a" option, which will be generated -a as a parameter if it has an option parameter, generates a -a ARG total of two parameter, if the option parameter is optional, in quotation-protected mode, generates a "-a" "" total of two parameter, In non-quote protected mode, there will be only -a one parameter)

If a single horizontal line "-" is followed by multiple short option characters at once, they will be separated as separate parameter. (such as "-avz" will generate -a -v -z a total of 3 parameter).

For the long option, a parameter consisting of "--" and a full long option name is generated. As long as it is a long option, whether it is abbreviated or is specified with a single dash "-", the parameter will be filled when it is generated. In addition, the parameters of the long option are handled the same way as the short option.

In general, output for non-option type parameters (non-option parameter) is not generated until all option and their argument are processed. When dealing with a non-option type parameter, a "--" is first generated as a separate parameter, and then the parameters of the various non-option types (non-option parameter) will generate their output in order, each of which is a separate parameter. The output of a parameter of the non-option type (non-option parameter) is generated at the location where they were found only if the first character of the short option character is "-", which is not supported if Syntax 1 is used. At this point, the "-" and "+" of all the prefixes will be ignored.

Quoting

In compatibility mode, special characters in white-space characters, argument, or non-option-type parameters (non-option parameter) will not be processed correctly. Because output is provided to the shell script, the script does not know how to split the output into different parameter. To avoid this problem, you can use the quoting feature provided by the enhanced version of Getopt, which will use quotation marks to protect these parameter, which will be correctly split into separate parameter when the output is re-supplied to the shell (typically parsed with the eval command).

If the getopt_compatible environment variable is set, or Syntax 1 is used, or the "-u" option is used, the quoting feature is disabled.

Different shells use different quotation marks to handle the rules. You can use the "-S" option to specify the shell you want to use. The currently supported shell types are: sh, bash, csh, and tcsh. In fact, there are only two stylistic differences: Class sh (sh-like) quotes handling style and class CSH (Csh-like) 's quotation-processing style. Even if you use other types of shells, you can still specify these kinds of shells.

Scanning MODES

The first character of a short option can use the "+" or "-" to specify a scan mode. If you use Syntax 1, these two special symbols will be ignored, but if you set the environment variable posixly_correct, the scan will still be performed.

If the first character is "+" or if the environment variable posixly_correct is set, any argument (non-option parameter) that finds the first non-option type stops parsing (for example, parameter does not use "-"). And all parameters that follow it are interpreted as non-option-type parameters (non-option parameter).

If the first character is "-", output of a non-option-type parameter (non-option parameter) is generated based on where it is located. By default, they are collected after a separate "--" parameter. In this scanning mode, the "--" parameter is generated, but it is generated at the tail end of all parameter.

Translator: Man getopt (1) Chinese manual