GADS(33.4) ARP Programmers Manual GADS(33.4) NAME GADS -- Do standard AmigaDOS command line parsing. SYNOPSIS Count = GADS( "line", len, "help" args, "tplate"); d0 a0 d0 a1 a2 a3 FUNCTION This function performs the standard AmigaDOS style command line parsing, using the standard AmigaDOS style templates. It also handles interactive command lines for you. This program will also perform all the normal AmigaDOS processing on the command line before the parse. In particular, this means handling any escape characters that are found in the line. The method used by AmigaDOS (and in this function) is to escape quoted commands, but not unquoted commands. Quotes will be stripped unless escaped. Note that ArpLib recognizes a more extensive escape vocabulary than AmigDOS (see EscapeString). Note also that one exception to the above occurs when a function is passed a null 'tplate' pointer. INPUTS "cmdline" -- pointer to the command line, just as you get it from DOS. cmdlen -- length of command line, just as handed to you by DOS. argarray -- Pointer to the start of an array of longwords which will receive the results of the argument parse. There must be as many longwords in this array as there are arguments in the template. There must ALWAYS be at least one element in this array. "tplate" -- Pointer to an AmigaDOS style template. This function assumes that the template is 'well formed', i.e., no spaces, tabs, etc., and that it null terminated. Do NOT end your template with ':'. It may contain mixed cases. "xtra help" -- optional extra help string, which may be as long as you like, and include any type of characters you desire. The user will see this string if they type a question mark after they have already entered interactive processing. This should be NULL if you do not have any xtra help to supply. RESULT COUNT -- The number of arguments found, or -1 if there is an Page 1 (printed 2/22/88) GADS(33.4) ARP Programmers Manual GADS(33.4) error in the comand line. This function is fairly demanding about command line syntax. ArgArray -- If COUNT is nonzero, ArgArray contains the results of the parse. Each argument (if present) will be placed in the position of the argument array reserved for it in the template. For example, in the template "DIR,TO", DIR will always appear in the first argument position, and TO will always appear in the second, regardless of how the user supplied the string. If COUNT is zero, then the ArgArray contains the values it was initialized with. This allows you to submit preset argument values. If COUNT is less than zero, an argument error occured, and the first entry in the ArgArray is a pointer to an error string which describes the error. Typically, a program will display this message and then exit. ADDITIONAL CONSIDERATIONS This function will return an error if the user omitted a required argument (indicated by a /A in the template) only if the command line is non-null. The initial command line pointer may not be valid after a call to this function, since GADS() uses the resource tracking functions to allocate additional memory for interactive command line processing as needed. If template is a NULL pointer, special command line processing takes effect. This option is used by programs such as Echo or Set which do more of their own command line processing, but still want the Escape and string cleaning functions of GADS() to be in effect. Additions for V33.4 Two additions have been made to GADS() for this release of the library. A new template type, sometimes referred to as multiargs, has been added to the original set of template types of AmigaDOS. This allows an essentially infinite number of arguments to be supplied, and dispenses with the ugly and limited ",,,,,,,,,,," construct. Note that this is still supported, if you wish to use it. Multiargs are indicated by using "/..." as the type indicator. For example, the template "Files/...,OPT/K", allows any number of files to be entered. The GADS() return value will be the total number of arguments entered, as always. The value of the multiarged item will be of type *(*char[]), i.e., a pointer to an array of character Page 2 (printed 2/22/88) GADS(33.4) ARP Programmers Manual GADS(33.4) pointers. The arguments will be placed in this array in the order in which they are found, and the last item is guaranteed to be NULL. Note that the memory for this array is allocated by GADS() using the tracking functions, you do not have to obtain, and should not free, this memory. One important aspect of using the multiarg template type in designing templates is that you should allow only keywords or switches to follow the multiarged item. For example: "Files/...,TO/K,SILENT/S" would work well, but the following template has a problem: "Files/...,TO" If a user specifies the TO argument without the keyword TO, the parsing routine has no way to tell where the Files/... args end, and the TO argument begins, therefore, it will parse the TO argument as a member of the Files/... type. This 'swallowing' of optional arguments can cause difficulties, and should be avoided by using only one optional argument, the multiarged one, per template. If you must use additional optional arguments, then these should preceed the multiarg argument. Ordinarily, GADS() (like AmigaDOS) regards the equal sign (=) as a statement separator. You can now override that if you wish by using the character sequence "-=" to begin a template. This will not appear to the user if he types a '?', but it will cause the equal signs to be treated as literal characters, rather than delimiters. This is useful in programs like Set. The lack of this feature in the original AmigaDOS arg parser is probably why Assign has such an unnatural syntax. BUGS No error checking is performed on the actual syntax of the template. This routine assumes you did it right. Could alter the original cmdline area, and will, except in the case of interactive input. SEE ALSO EscapeString(), ReadLine(), ArpAlloc() AUTHOR SDB Page 3 (printed 2/22/88)