parscl (2) --- parse command line arguments 01/07/83 _C_a_l_l_i_n_g _I_n_f_o_r_m_a_t_i_o_n integer function parscl (str, buf) character str (ARB), buf (MAXARGBUF) Library: vswtlb (standard Subsystem library) _F_u_n_c_t_i_o_n 'Parscl' is used to parse most standard Subsystem command line formats automatically. It examines the command line, parses it according to instructions present in its arguments, and makes the result available to the user for further processing. This processing is normally done with the aid of a set of standard Subsystem macros, described below. All arguments handled by 'parscl' are deleted from the command line, so any remaining special cases may be han- dled by the user. The argument 'str' is a string describing the syntax of the command line. The argument 'buf' is a one-dimensional array of characters normally declared with the standard Subsystem macro 'ARG_DECL'. The function return is OK if the command line parsed successfully, ERR if an illegal option was seen or a required parameter was missing. 'Parscl' handles several types of arguments. "Flag" arguments are single-letter flags, preceded by a hyphen or dash, that have no parameters and may be grouped together in a single argument; for example, "-a" or "-acq". Arguments with parameters may have a string or integer value following the single-letter, or present in the next argument in the command line. For example, "-p1", "-p 1", "-nfilename", or "-n filename". Parameters for such arguments may be optional or required. Finally, some arguments may be ignored entirely, while others may not be allowable at all. The argument 'str' contains a specification of allowable arguments and their types. Each specification consists of an option letter (case is ignored) followed by a type in angle brackets. The following types are allowable: 'f' or 'flag' for flag arguments, 'ign' or 'ignored' for ignorable arguments, 'na' for arguments that are not allowable, 'oi' or 'opt int' for arguments with an optional integer parameter, 'os' or 'opt str' for arguments with an optional string parameter, 'ri' or 'req int' for arguments with a required integer parameter, and 'rs' or 'req str' for arguments with a required string parameter. For example, a command with the syntax -u [-l ] [-i []] would pass the following string to 'parscl': u l i parscl (2) - 1 - parscl (2) parscl (2) --- parse command line arguments 01/07/83 Order of arguments on the command line is unimportant, as well as the case of the option letter used. The command line is typically parsed and then examined with a number of standard Subsystem macros. 'ARG_DECL' is used to declare the buffer required by 'parscl'. "PARSE_COMMAND_LINE(str,msg)" is used to invoke 'parscl'; 'str' is passed to 'parscl' as its first argument, and 'msg' is passed to 'error' to be printed if the command line could not be parsed. For example, one might use PARSE_COMMAND_LINE ("uli"s, "Usage: cmd -u [-l] [-i[]]"p) Once 'parscl' has been called in this manner, default values for optional parameters may be supplied with 'ARG_DEFAULT_INT' and 'ARG_DEFAULT_STR': ARG_DEFAULT_STR(i,"/dev/stdin1"s) ARG_DEFAULT_INT(l, 1) One may test for the presence of an argument on the command line with 'ARG_PRESENT', and retrieve argument values with 'ARG_VALUE' and 'ARG_TEXT': if (ARG_PRESENT (l)) lower = ARG_VALUE (l) else lower = 1 call ctoc (ARG_TEXT (i), filename, MAXLINE) Once as much as possible of this kind of argument parsing is complete, the user may examine any remaining arguments by fetching them with 'getarg'. _I_m_p_l_e_m_e_n_t_a_t_i_o_n 'Parscl' scans the specification string and builds a 26 element array. Each element of the array corresponds to a letter A - Z and contains an integer describing the type of argument expected when that letter is encountered. If an unrecognized argument type (in angle brackets) is encountered, 'parscl' calls 'error' to print an error mes- sage. Then 'parscl' scans the command line arguments, skipping those that do not begin with a hyphen or have a letter as the second character. Arguments that begin with hyphens are examined further. If the letter in the second position of the argument is to be ignored, it is skipped. Flag arguments are simply marked "present" in the argument buffer. Values for string parameters are stored in the argument buffer for later retrieval. Values for integer parameters are converted with 'gctoi' (thus allowing arbitrary radix representation) then stored in the argument parscl (2) - 2 - parscl (2) parscl (2) --- parse command line arguments 01/07/83 buffer. So that variables can be used in the macro calls, the fol- lowing macros take an integer or variable containing an integer in the range 1 to 26 rather than a letter: ARG_VALUE_I () ARG_PRESENT_I () ARG_DEFAULT_INT_I (, ) ARG_DEFAULT_STR_I (, ) _C_a_l_l_s ctoc, delarg, error, gctoi, getarg, mapdn, putlin, strbsr _A_r_g_u_m_e_n_t_s _M_o_d_i_f_i_e_d buf _S_e_e _A_l_s_o delarg (2), getarg (2), gfnarg (2) parscl (2) - 3 - parscl (2)