home *** CD-ROM | disk | FTP | other *** search
/ Programmer 7500 / MAX_PROGRAMMERS.iso / INFO / C / CLMFEB85.ZIP / ARGPARSE.USE < prev    next >
Encoding:
Text File  |  1988-07-25  |  5.9 KB  |  146 lines
  1.  
  2. #ifdef COMMENT
  3. /*
  4. /* This file describes the use of files: argparse.h, argbegin.h, argloop.h,
  5. /* and argend.h.  Those files make a more portable implementation of the
  6. /* macros defined and described in the file argpar.h.
  7. /* The most important difference is that macros ArgBEGIN(), ArgLOOP, and
  8. /* ArgEND have been replaced with include files argbegin.h, argloop.h, and
  9. /* argend.h.  Text of those macros exceeds buffer sizes of C preprocessors
  10. /* on micro-computers.
  11. /*
  12. /* Macros described in this file can be used to parse command line
  13. /* as it is passed to the main program.  Macro MAIN
  14. /* can be used to produce the header of the function "main()".
  15. /* Other macros should be used within the body of the function
  16. /* main(). Includes argbegin.h, argloop.h, and argend.h must be used to
  17. /* sandwich in the macros.
  18. /*
  19. /* Command arguments can be positional or key letter arguments.
  20. /* Key letter arguments start with a trigger character. Any
  21. /* character can be specified as trigger character.
  22. /* The default trigger character is '-'.
  23. /*
  24. /* Key letter arguments can be defined as either flag or text
  25. /* arguments.
  26. /*
  27. /* Flag argument consists of a single key letter that
  28. /* follows the trigger character. No text is expected after the
  29. /* flag key letter. If any text follows a flag key letter without
  30. /* a white space it is interpreted as additional key letters.
  31. /* If any text follows a flag key letter after a white space
  32. /* it is interpreted as another argument. Several flag key letters
  33. /* may follow one trigger character.
  34. /*
  35. /* Text argument consists of a single key letter immediately
  36. /* following a trigger character and followed by text either
  37. /* immediately or after a white space.
  38. /*
  39. /* Positional arguments can be processed either after all
  40. /* key letter arguments have been processed, or all arguments
  41. /* can be processed in order, intermixing positional arguments
  42. /* with key arguments. Double trigger character can be used
  43. /* to signal the end of key letter arguments.  Another mode
  44. /* is provided, but not recommended, in which the first
  45. /* positional argument terminates key letter arguments.
  46. /*
  47. /*
  48. /* For both Flag and Text arguments two macros exist:
  49. /* one that Sets a variable and another that Calls a user
  50. /* defined function.
  51. /*
  52. /* Following flags are predefined and can not be redefined:
  53. /* '?'  Output tutorial information to stderr.
  54. /* '!'  Output debugging information to stderr.
  55. /* '-'  (i.e. trigger character) end of key letter arguments.
  56. /*
  57. /*
  58. /* Macros:
  59. /*
  60. /* @(#) ArgTutor( ... ) -- used internally.
  61. /*   Print tutorial message from string array 'tutorial'
  62. /*   to stderr and exit abnormally.
  63. /*
  64. /* @(#) MAIN()
  65. /*   Defines header for function main(argc, argv, envp).
  66. /*
  67. /* @(#) #define ArgCount  argc
  68. /* @(#) #define ArgVector argv
  69. /* @(#) #include 'argbegin.h'
  70. /*   Begins sandwich that parses command arguments.
  71. /*   Macros described before argloop.h are optional.
  72. /*   If present, they must be coded between argbegin.h
  73. /*   and argloop.h.  Those macros override provided defaults.
  74. /*   Each of them should be coded only once, if at all.
  75. /*   Macros described between argloop.h and argend.h should
  76. /*   also be coded between argloop.h and argend.h.
  77. /*   One of those macros must be coded for each key letter
  78. /*   argument.
  79. /*
  80. /* @(#) ArgTrigger( TriggerCharacter )
  81. /*   TriggerCharacter is used to recognize key letter arguments.
  82. /*   Default is '-'.
  83. /*
  84. /* @(#) ArgDescription( DescriptionStringArray )
  85. /*   Provides text to be printed after an error is detected
  86. /*   while parsing arguments.
  87. /*      char * tutorial[] = { 'Command', 'summary', 0 };
  88. /*
  89. /* @(#) ArgKeyLeading
  90. /*   If this macro is coded key arguments must precede positional
  91. /*   arguments.  After the first positional argument is recognized,
  92. /*   all following arguments are treated as positional.
  93. /*   This mode is not recommended.  It is provided just for the
  94. /*   sake of completeness (many programs parse arguments this way).
  95. /*
  96. /* @(#) ArgPosCall( FunctionName )
  97. /*   FunctionName is called for each positional argument.
  98. /*   If positional arguments are to be processed after all
  99. /*   key letter arguments, this macro should be left out.
  100. /*   It defaults to the dummy function "argPos()"
  101. /*   defined in this file. Otherwise a function
  102. /*   should be defined as:
  103. /*     char * functionName( keyCharacter, textString )
  104. /*     char   keyCharacter;  /* Always contains '\0'. */
  105. /*     char * textString;    /* Points to positional argument. */
  106. /*     { ... }
  107. /*
  108. /* @(#) ArgMin( MinPositionals )
  109. /*   MinPositionals is minimum number of positional arguments.
  110. /*   If this macro is not coded, the check is not performed.
  111. /*
  112. /* @(#) ArgMax( MaxPositionals )
  113. /*   MaxPositionals is maximum number of positional arguments.
  114. /*   If this macro is not coded, the check is not performed.
  115. /*
  116. /* @(#) #include 'argloop.h'
  117. /*   This macro marks the end of default override macros.
  118. /*   It is followed by macros describing key letter arguments.
  119. /*
  120. /* @(#) ArgFlagSet( KeyLetter, CounterVariable )
  121. /*   Increment counter for this flag.
  122. /*   CounterVariable should be initially zero.
  123. /*
  124. /* @(#) ArgTextSet( KeyLetter, PointerVariable )
  125. /*   Set pointer to text argument.
  126. /*
  127. /* @(#) ArgFlagCall( KeyLetter, FunctionName )
  128. /* @(#) ArgTextCall( KeyLetter, FunctionName )
  129. /*   Call user defined function to process key letter argument.
  130. /*   Function must be defined as:
  131. /*     char * functionName( keyCharacter, textString )
  132. /*     char   keyCharacter;  /* Key letter. */
  133. /*     char * textString;    /* NULL for flag, or points to text. */
  134. /*     { ... }
  135. /*   If pointer returned by this function is not NULL,
  136. /*   the tutorial message will be printed to stderr
  137. /*   and abnormal exit will be taken.
  138. /*
  139. /* @(#) #include 'argend.h'
  140. /*   Ends sandwich that parses command arguments.
  141. /*
  142. /* Example of use: See end of file argparse.h.
  143. */
  144. #endif COMMENT
  145.  
  146.