home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD2.mdf / c / library / dos / cmdline / c_parse / parse.doc < prev   
Encoding:
Text File  |  1987-06-17  |  6.0 KB  |  153 lines
  1.  
  2.                    
  3.                    Command-Line Parsing Routines
  4.  
  5.        These routines are used to help you parse the C command line.
  6.    As far as I know, I haven't used any compiler-specific code, so
  7.    the routines should run on any C compiler.
  8.  
  9.        The command line consists of several strings that are passed to
  10.    MAIN in the <argv> vector. They are not interpreted by the compiler
  11.    at all; that's left up to the program. These parsing routines help
  12.    the programmer sort out command-line parameters of the form:
  13.  
  14.                keyword         and         keyword=value
  15.  
  16.    where "keyword" is a mnemonic (for the user) and "value" is a number
  17.    or string. The programmer may elect to give the user the option of 
  18.    abbreviating the keyword:
  19.  
  20.                key=value       or          k=value
  21.  
  22.        Each of the four parse routine searches the argument vector for the
  23.    specified keyword. If it is found, that argument is DELETED FROM THE
  24.    ARGUMENT VECTOR. If it isn't found, or if an error occurs, <argv> isn't
  25.    changed. This is what makes these routines so useful: You don't have to
  26.    worry about parsing keywords and then ignoring them later. As an example,
  27.    if you're searching the command line for a flag called "-flag", and the
  28.    command line is as follows:
  29.  
  30.                command  start  -flag  end
  31.  
  32.    and you call the routine GET_FLAG, the command line <argv> will be
  33.    changed to:
  34.  
  35.                command  start  end
  36.  
  37.    and you won't have to worry about "parsing around" the already-parsed 
  38.    parameter.
  39.  
  40.  
  41.  
  42.    The parse routines are as follows:
  43.  
  44.        GET_FLAG searches for a command-line parameter of the form:
  45.  
  46.                    keyword
  47.  
  48.        GET_INT searches for a command-line parameter of the form:
  49.  
  50.                    keyword=number          where <number> is an integer.
  51.  
  52.        GET_FLOAT searches for a command-line parameter of the form:
  53.  
  54.                    keyword=number          where <number> is any number
  55.  
  56.        GET_CHAR searches for a command-line parameter of the form:
  57.  
  58.                    keyword=word
  59.            or      keyword="word or words"
  60.  
  61.            In the latter case, the surrounding quotes are removed. 
  62.  
  63.  
  64.    The syntax of the routines are as follows:
  65.  
  66.            argc = get_xxxx (keyword, must, out, argv);
  67.  
  68.    <keyword> is a string containing the keyword to search for.
  69.  
  70.    <must>    is an int and is the minimum number of characters in the
  71.            keyword that must be there. For example, if <keyword> is "name"
  72.            and <must> is 2, then valid keywords (successful matches) are:
  73.                    na   nam   name
  74.            Invalid keywords (unsuccessful matches) are:
  75.                    n    naming   namer
  76.  
  77.    <out>     is a pointer to the output, and depends on the routine:
  78.  
  79.             routine      type            returns
  80.  
  81.            GET_FLAG    int *out    1 if found, 0 otherwise
  82.            GET_INT     int *out    <number> if found; unchanged otherwise
  83.            GET_FLOAT   float *out  <number> if found; unchanged otherwise
  84.            GET_CHAR    char *out   <word or words> if found; unchaned otherwise
  85.  
  86.    <argv>    is the argument vector, as passed to your MAIN routine.
  87.  
  88.    <argc>    is the number of arguments in the argument vector after the
  89.            call. It is negative if an error was detected.
  90.  
  91.  
  92.    Error conditions
  93.  
  94.        An error condition (indicated by a negative return value) means that
  95.    one or more of the following happened:
  96.  
  97.            <keyword> was NULL or pointed to a null string.
  98.            <must> was zero or negative. 
  99.            <out> was a NULL pointer.
  100.            The user specified "too much" of the keyword. For example: your
  101.                program is looking for the keyword "-name", and one of the 
  102.                command-line parameters is -names=Jack. The extra 's' is an 
  103.                error.
  104.            The user specified enough of the keyword, but the rest is junk. For
  105.                example, your program is looking for the keyword "-name" and
  106.                <must> is 3. That means that the user must specify at least "-na"
  107.                to be recognized. If he types "-namqr", that's an error.
  108.            The user used a character for an INT parameter that wasn't in the
  109.                following set: "0123456789-"
  110.            The user used a character for a FLOAT parameter that wasn't in the
  111.                following set: "0123456789.-eE"
  112.            The user used an equals sign for a FLAG parameter.
  113.  
  114.        Please note that the user won't know what parse routines that you're
  115.    using, and what he types, he types innocently and ignorantly. That's the
  116.    purpose of these routines: to make input more user friendly and still not
  117.  
  118.  
  119.  
  120.    burden down the programmer too much. These routines, in my mind, provide
  121.    the user with the ability to use more "plain english" without slowing down
  122.    the experienced user. Here's a typical command line:
  123.  
  124.            command   input=file1   output=file2   loops=5
  125.  
  126.    That's a cinch to parse with my routines, and it makes sense to a beginner.
  127.    The more experienced user, who doesn't like typing, does this:
  128.  
  129.            command   i=file1       o=file2        l=5
  130.  
  131.    (assuming your program called the routines with <must> = 1)
  132.  
  133.  
  134.    Conclusion
  135.  
  136.        Hopefully, these routines will make your job a little easier. I have
  137.    included all the source code, and a sample program that demonstrates all
  138.    of the options. Feel free to make copies for yourself and your friends.
  139.    I only ask two things: a) please don't give someone copies without this
  140.    doc file, and b) please make copies only of the original files; keep your
  141.    "custom" versions to yourself. I ask this latter since I have worked to
  142.    get all of the bugs out of this package, and I can't account for any bugs
  143.    that you may inadvertently add.
  144.  
  145.  
  146.                Questions, comments, etc:
  147.  
  148.                    Eric J. Roode
  149.                    119 Hoosick St
  150.                    Troy, NY  12180
  151.                (current as of 6/17/87)
  152.  
  153.