home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS 1992 June / SIMTEL_0692.cdr / msdos / c / clp_v11.arc / CLP.DOC next >
Text File  |  1989-10-14  |  21KB  |  577 lines
  1.  
  2.          CLP - A 'C' Command Line Processor, Version 1.1
  3.         -------------------------------------------------
  4.  
  5.  
  6. *****************************************************************
  7. *                                                               *
  8. *   This archived software set is shareware! It is NOT public-  *
  9. *   domain, and though it is free of charge it may only be      *
  10. *   distributed with the following conditions:                  *
  11. *                                                               *
  12. *      1.  The full archive CLP_V11.ARC is distributed without  *
  13. *          modification.                                        *
  14. *      2.  No commercial gain is directly sought from any of    *
  15. *          the files contained within the archive without the   *
  16. *          author's prior approval.                             *
  17. *      3.  Notification should be sent to the Author (name &    *
  18. *          address & e-Mail address below) of any use of CLP    *
  19. *          in programs outside the individual's personal use.   *
  20. *          This includes public-domain and shareware software   *
  21. *          as well as commercial software.                      *
  22. *                                                               *
  23. *  Users requiring versions of CLP for different memory models  *
  24. *  should send a postage paid reply envelope to the address     *
  25. *  below.  Registering may also be accomplished by sending a    *
  26. *  diskette (360K, 1.2M, 740K, 1.44M) to the address below. In  *
  27. *  reply, you will receive the latest version of CLP for all    *
  28. *  memory models, the complete CLPLIB utility and instructions  *
  29. *  for linking CLP definitions into code directly without the   *
  30. *  need for a library.                                          *
  31. *                                                               *
  32. *  Please ensure that the reply envelope has enough postage to  *
  33. *  cover costs.  Instead of postage, you may send a 1.44M       *
  34. *  diskette!  Gets around the international stamp system!       *
  35. *                                                               *
  36. *-  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  *
  37. *                                                               *
  38. *   Queries, comments, suggestions & registration to:           *
  39. *                                                               *
  40. *   Karl Keyte,                 e-Mail:  ESC1332@ESOC.BITNET    *
  41. *   E.S.O.C.,                   Phone :  +(49) 6151 886783      *
  42. *   Robert-Bosch Strasse 5,                                     *
  43. *   6100 Darmstadt                                              *
  44. *   West Germany                Date  :  September 1989         *              
  45. *                                                               *
  46. *****************************************************************
  47.  
  48.  
  49.  
  50.    
  51.  
  52. 1  Introduction
  53.    ------------
  54.  
  55.  
  56. CLP  is  a general purpose command  line  processor  for  the 'C'
  57. language.  Looking at the sources for various programs written in
  58. 'C'  it is clear that a lot of work has been repeated in handling
  59. command  line  options and parameters.  CLP  provides  a means by
  60. which the general format of the command line may be  defined in a
  61. Command  Line Definition file  (.CLD),  and processed by a single
  62. interface  call.  Following  that  call,  values and  settings of
  63. parameters and switches may  be queried by additional  calls. The
  64. idea and much  of  the flavour  of  CLP  comes  from  the VAX/VMS
  65. operating system, where command definitions may be build up  in a
  66. very similar fashion.
  67.  
  68.  
  69. CLP has been tested with Turbo-C (2.0) and Microsoft C (5.1). The
  70. '#include' file given  conforms  to  ANSI  standards,  and should
  71. therefore be  accepted  by  any ANSI compiler.  The object module
  72. uses a standard 'C' parameter stack.
  73.  
  74.  
  75. A  compiler  is  provided which takes the Command Line Definition
  76. file and generates a  Command  Line  Library  (.CLL)  file  which
  77. contains definitions for ALL utilities  using  the CLP interface.
  78. The .CLD  file  should  be  maintained  by  adding  and  deleting
  79. utilities from it as required. Running the compiler will generate
  80. the full Library file (.CLL) from the definitions.
  81.  
  82.  
  83. Four  functions  are   available  to  the   caller.  'clp_accept'
  84. initialises  the CLP processor for a  given  program  and command
  85. line.   'clp_get_spec'  returns  the  specification  code  for  a
  86. particular parameter or  switch  option.  'clp_get_value' returns
  87. the  value  associated  with  a  parameter  or  switch  option if
  88. present. These are described in detail in the following sections.
  89. When parameter and switch processing has been completed, the user
  90. may  recover  certain  portions  of  system memory by calling the
  91. procedure 'clp_release'.
  92.  
  93.  
  94.  
  95. 2  Interface Calls
  96.    ---------------
  97.  
  98.  
  99. 2.1  clp_accept
  100.      ----------
  101.  
  102.  
  103. Function:
  104.        Initialise CLP for specified program and command line.
  105.  
  106.  
  107. Syntax:
  108.        #include "clp.h"
  109.        void clp_accept ( char *function, int argc, char argv** );
  110.  
  111.  
  112. Prototype:
  113.        clp.h
  114.  
  115.  
  116. Remarks:
  117.        Sets  up  the data  structures  in  preparation  for other
  118.        interface calls. 'function' specifies the program name, as
  119.        given in the CLD file.  'argc'  and 'argv' are the command
  120.        line parameters of the main program,  and should be passed
  121.        to 'clp_accept' exactly as they were received.
  122.  
  123.        If  the  command   specified  does  not  conform   to  the
  124.        definition in the CLD, the program will exit with the exit
  125.        status of 1.
  126.  
  127.        'clp_accept'  attempts to  open  the CLL  library  file by
  128.        checking first the environment variable CLPLIB. If this is
  129.        defined,  the file given will be used.  If the environment
  130.        variable is undefined, 'clp_accept' attempts to locate the
  131.        file CLP.CLL in  the  current  searchpath.  If  it  is not
  132.        found, the program will exit with an exit code of 1.
  133.  
  134.  
  135. Return Value:
  136.        None.
  137.  
  138.  
  139.  
  140. 2.2  clp_get_spec
  141.      ------------
  142.  
  143.  
  144. Function:
  145.        Returns the  specification code  for a specified parameter
  146.        or switch option.
  147.  
  148.  
  149. Syntax:
  150.        #include "clp.h"
  151.        int clp_get_spec ( char *name );
  152.  
  153.  
  154. Remarks:
  155.        Finds the specification  associated  with  the  switch  or
  156.        parameter 'name'.  The  name  must  be  present in the CLD
  157.        file.
  158.  
  159.  
  160. Return Value:
  161.        The return is one of the following:
  162.  
  163.                 CLP_ERROR           Not   found,   i.e.  was  not
  164.                                     defined in the CLD file.
  165.                 CLP_NOTSPECIFIED    Not specified in  the command
  166.                                     line.
  167.                 CLP_DEFAULTED       Not specified in  the command
  168.                                     line but is on by default.
  169.                 CLP_SPECIFIED       Explicitly    specified    in
  170.                                     command line.
  171.                 CLP_VALUEDEFAULTED  Contains  a  value  which has
  172.                                     been defaulted.
  173.                 CLP_VALUESPECIFIED  Contains  a  value  which has
  174.                                     been explicitly specified.
  175.                 CLP_NEGATED         Explicitly negated.
  176.  
  177.  
  178.  
  179. 2.3  clp_get_value
  180.      -------------
  181.  
  182.  
  183. Function:
  184.        Returns  the value associated  with  a parameter  or value
  185.        switch option.
  186.  
  187.  
  188. Syntax:
  189.        #include "clp.h"
  190.        char *clp_get_value ( char *name );
  191.  
  192.  
  193. Remarks:
  194.        Finds the value asociated with the specified  parameter or
  195.        switch option, 'name'. The name must be present in the CLD
  196.        file.
  197.  
  198.  
  199. Return Value:
  200.        Returns  a pointer to  the  value  string.  The  string is
  201.        static,  and  must be copied  by the  user if it  is to be
  202.        further used.  NULL is returned if no value is defined, or
  203.        if  the 'name'  specifies an  invalid parameter  or switch
  204.        name.
  205.  
  206.  
  207.  
  208. 2.4  clp_release
  209.      -----------
  210.  
  211.  
  212. Function:
  213.        Releases all memory reserved by the CLP processor.
  214.  
  215.  
  216. Syntax:
  217.        #include "clp.h"
  218.        void clp_release ( void );
  219.  
  220.  
  221. Remarks:
  222.        All memory and associated data structures for use with CLP
  223.        are released. No call to 'clp_get_value' or 'clp_get_spec'
  224.        should be attempted (they will return NULL  and  CLP_ERROR
  225.        respectively) before an intervening call to 'clp_accept'.
  226.  
  227.  
  228. Return Value:
  229.        None.
  230.  
  231.  
  232.  
  233. 3  CLD File Format
  234.    ---------------
  235.  
  236.  
  237. The definitions for  all  programs  using  CLP  must  exist  in a
  238. library.  This  library,  type  .CLL,  is  formed  from  a source
  239. definition file,  CLD. It is the CLD which must be changed when a
  240. command line format is changed or when new programs using CLP are
  241. added. This section describes the syntax of the source file, CLD.
  242.  
  243.  
  244. The CLD  file  generally  comprises  definitions,  each  of three
  245. sections:  a  program  name  definition;  one  or  more parameter
  246. specifications;  one  or  more  switch  specifications. These are
  247. covered in the respective order:
  248.  
  249.  
  250. 3.1  Program Name Specifier
  251.      ----------------------
  252.  
  253. :<program_name>
  254.  
  255. This key is used to introduce the name of  a new program  for use
  256. with the CLP system.  The  name  must  be a  valid MS-DOS program
  257. name,  i.e.  1-8 alpha-numeric characters. These clauses are used
  258. to separate program command line definitions,  a definition being
  259. considered complete  either when the end of  file  is reached, or
  260. when the next ':<program_name>' clause is encountered.
  261.  
  262.  
  263. 3.2  Parameter Specifier
  264.      -------------------
  265.  
  266. $<par_name>[[;DEFAULT="<def_val>"]|[;REQUIRED [;PROMPT="<prmt>"]]
  267.  
  268. <par_name>  is a parameter specifier. The names are not flexible.
  269. The first must be P1, the second, P2, etc.
  270.  
  271. <def_val> identifies a default value to be given to the parameter
  272. is  it  is  not specified on  the  command  line.  If  DEFAULT is
  273. specified,  the REQUIRED and PROMPT keywords have no meaning, and
  274. an error will be generated when the CLD is converted  to the CLL.
  275. The default value may contain up to 80 characters.
  276.  
  277. <prmt>  is a string which will be used  to prompt the user  for a
  278. required parameter.  For this reason, the PROMPT keyword only has
  279. a useful  context following the REQUIRED  keyword,  and  an error
  280. will  be  generated if  this  is  not the case.  <prmt>  may be a
  281. maximum of 50 characters.
  282.  
  283. If a parameter is REQUIRED, but has no PROMPT specified, the name
  284. of the parameter (e.g. P1) will be used for the prompt.
  285.  
  286.  
  287. 3.3  Switch Option Specifier
  288.      -----------------------
  289.  
  290. /<sw_name> [;NEGATABLE] [;DEFAULT] [;VALUE]
  291.            [ ; REQUIRED | DEFAULT="<def_val>" ]
  292.  
  293. <sw_name> may be up to 15 characters.
  294.  
  295. NEGATABLE  allows  the option  to be explicitly  negated with the
  296. /NO<sw_name>  form.  A switch value may not be  specified as both
  297. negated and containing a value.
  298.  
  299. DEFAULT  set the option  on  be  default.  It is meaningless (but
  300. valid)  to specify DEFAULT without  NEGATABLE,  since  the switch
  301. would be permanently set on.
  302.  
  303. VALUE allows the switch to take a value which is optional, unless
  304. the REQUIRED keyword follows VALUE.  If DEFAULT=<def_val> follows
  305. the VALUE keyword,  the switch will take the default value if one
  306. is not specified.  The <def_val>  default  value may be  up to 80
  307. characters.
  308.  
  309. If  a  NEGATABLE  switch  is  negated  and  has  a  default value
  310. specified in the definition,  the value will be discarded  by the
  311. negation, and will be set to NULL.
  312.  
  313. DEFAULT and DEFAULT="<def_value>" are mutually exclusive.
  314.  
  315.  
  316.  
  317.  
  318. 3.4  Example
  319.      -------
  320.  
  321.  
  322. The following example  serves  to  demonstrate  the  use  of CLP.
  323. Imagine a delete  facility  which allows  the  user  to  move the
  324. 'deleted'  file to  another  directory  rather  than  removing it
  325. completely.   Clearly,  one  parameter  is  essential;  the  file
  326. specification.  The directory for deleted files may  be specified
  327. by a value switch.  We can introduce two  further facilities. The
  328. first,  an option LOG to allow us to  have a  detailed display of
  329. the success or failure of the deletion,  and secondly, SAFETY, to
  330. allow the delete to be aborted if the file already  exists in the
  331. backup directory.
  332.  
  333. If we  call  the facility  XDEL,  the  .CLD definition (XDEL.CLD)
  334. would look similar to this:
  335.  
  336.  
  337. !==============================================================
  338. !
  339. !  XDEL   Command-Line Definition
  340. !
  341. !  Note how comments may be inserted, as well as blank lines!
  342. !
  343. !==============================================================
  344.  
  345. :xdel                                ! Function Name
  346.  
  347. $p1; required; prompt="Filespec"     ! Parameter required
  348.  
  349. /backupdir; negatable; value; default="C:\DELETED"  ! Del. dir
  350. /log                                 ! Display status info.
  351. /safety; negatable; default          ! Ask before overwriting
  352.  
  353. !==============================================================
  354.  
  355.  
  356. The file may then be compiled:
  357.  
  358. C:\> clplib xdel
  359.  
  360. which would generate XDEL.CLL
  361.  
  362. Note that the  /OUTPUT option  for  CLPLIB  changes  the  default
  363. library name, e.g.
  364.  
  365. C:\> clplib/outp=mylib xdel
  366.  
  367. would generate the output in a file called MYLIB.CLL.
  368.  
  369. The  /VERBOSE option displays the CLD source with line-numbers as
  370. it is being compiled.
  371.  
  372.  
  373.  
  374. 4  CLL File Format
  375.    ---------------
  376.  
  377.  
  378. The compiler provided with the CLP package is used to convert the
  379. .CLD  source  definition file to  a .CLL  library definition. The
  380. format  and syntax  of the  source has been described  above. The
  381. purpose of this section is to describe the internal format of the
  382. library file.  This format is subject to  change between versions
  383. of CLP,  and this document should be used as the  prime source of
  384. the library structure.
  385.  
  386. The CLP version 1.1 library file has the following format:
  387.  
  388.   Offset |  Size  |  Data Type  |  Description                   
  389. ---------+--------+-------------+--------------------------------
  390.       0  |   71   |    String   |  Copyright message. This
  391.          |        |             |  message may not be changed or
  392.          |        |             |  'clp_accept' will fail.
  393. ---------+--------+-------------+--------------------------------
  394.      71  |    9   |   ZString   |  Title of function (Program)
  395. ---------+--------+-------------+--------------------------------
  396.      80  |    2   |   Integer   |  Number of parameters/switches
  397.          |        |             |  belonging to function.
  398. ---------+--------+-------------+--------------------------------
  399.      82  |    2   |    Bytes    |  Unused, reserved.
  400. ---------+--------+-------------+--------------------------------
  401.      84  |    2   |    Bitmap   |  Bit mapped fields comprising:
  402.          |        |             |   Bit  0   : Negation permitted
  403.          |        |             |              flag. 1=Negation
  404.          |        |             |              permitted.
  405.          |        |             |        1-2 : Value mode flag.
  406.          |        |             |              00=No value
  407.          |        |             |              allowed. 01=Value
  408.          |        |             |              optional. 02=Value
  409.          |        |             |              required. 03=N/A.
  410.          |        |             |        3   : Parameter required
  411.          |        |             |              flag. 1=Parameter
  412.          |        |             |              required, else is
  413.          |        |             |              optional. Not used
  414.          |        |             |              used for switches.
  415.          |        |             |        4   : Type flag. 0=
  416.          |        |             |              parameter, 1=Swtch
  417.          |        |             |        5-6 : Default mode.
  418.          |        |             |              00=not defaulted,
  419.          |        |             |              01=defaulted,
  420.          |        |             |              02=default value.
  421.          |        |             |              03=undefined.
  422. ---------+--------+-------------+--------------------------------
  423.      86  |   16   |   ZString   |  Name of the switch or param.
  424. ---------+--------+-------------+--------------------------------
  425.     102  |   51   |   ZString   |  Prompt string for required
  426.          |        |             |  parameters.
  427. ---------+--------+-------------+--------------------------------
  428.     153  |   81   |   ZString   |  Default value for parameters &
  429.          |        |             |  switches with an associated
  430.          |        |             |  default value.
  431. ---------+--------+-------------+--------------------------------
  432.     334  |  150   |  Structure  |  Copy of above fields from
  433.          |        |             |  offset 84 onwards. One per
  434.          |        |             |  additional parameter or switch
  435. ---------+--------+-------------+--------------------------------
  436.     ???  |  ???   |  Structure  |  Complete copies of above from
  437.          |        |             |  offset 71 onwards. One per
  438.          |        |             |  additional function.
  439. -----------------------------------------------------------------
  440.  
  441. The ordering of the switches and parameters  in the  .CLL file is
  442. according to the order they appear in the  .CLD source definition
  443. file.  The same applies to the ordering  of  the functions within
  444. the file.
  445.  
  446.  
  447.  
  448. 5  Bugs fixed and changes made since version 1.0
  449.    ---------------------------------------------
  450.  
  451.  
  452. The  following is  a list  of  corrected  bugs  and  changes made
  453. since the last release (Version 1.0,  archive CLP_V10.ARC) of the
  454. CLP utilities.
  455.  
  456.  
  457.    o    When an ambiguous  switch was specified,  the checks made
  458.         only applied to  the first switch  matching,  rather than
  459.         reporting the ambiguity.  For example,  a switch given as
  460.         /NOA  (where  'A'  is  actually  ambiguous)  would report
  461.         "Switch  'Axxxxx'  not negatable",  if  the  first switch
  462.         starting with 'A'  is not actually negatable. The correct
  463.         response,  of  course,  is that switch 'A'  is ambiguous.
  464.         This has now been corrected.
  465.       
  466.    o    The copyright message at the header  of  the library file
  467.         (.CLL)   must remain intact,  or the call to 'clp_accept'
  468.         will fail with an 'Invalid Library Format' error.
  469.    
  470.    o    The  numbering  of  the  command  line   parameters  used
  471.         internally had  an  error  in  version  1.0  which caused
  472.         command  lines with  not all parameters  specified  to be
  473.         rejected.  This numbering has been corrected, and command
  474.         lines may now contain any mixture of parameters, provided
  475.         that the value '-'  is given for a parameter which is not
  476.         to be specified.
  477.  
  478.  
  479.  
  480. 6  Run-time Error Messages
  481.    -----------------------
  482.  
  483.  
  484. This  section covers  the possible run-time error  messages.  All
  485. are fatal and processing will abort should  one of  the errors be
  486. encountered.
  487.  
  488.  
  489. ?CLP01: Invalid function name for 'clp_accept'
  490.  
  491. The  function  name  passed  as  a parameter to  'clp_accept' has
  492. either 0 or >8 characters and is therefore invalid.
  493.  
  494.  
  495. ?CLP02: CLP file 'CLP.CLL' not found in search path
  496.  
  497. No  CLPLIB  environment variable  was set  to  point  to  the CLP
  498. library,  causing 'clp_accept'  to look for CLP.CLL in the search
  499. path. This file was not found.
  500.  
  501.  
  502. ?CLP03: CLP file 'XXXXXX' not found
  503.  
  504. The CLPLIB environment variable points  to a file which  does not
  505. exist or cannot be opened.
  506.  
  507.  
  508. ?CLP04: Function 'XXXXXX' not found in CLP library
  509.  
  510. The function name passed to 'clp_accept' was not found in the CLP
  511. library being used.
  512.  
  513.  
  514. ?CLP05: CLP library 'XXXXXX' has invalid format
  515.  
  516. Either the library is corrupt or the copyright  message header in
  517. the library has been changed.
  518.  
  519.  
  520. ?CLP06: Insufficient memory to process command line parameters
  521.  
  522. Available memory was exhausted when trying to allocate memory for
  523. parameter/switch  data structures,  default/prompt strings or the
  524. user's input string for a required parameter.
  525.  
  526.  
  527. ?CLP07: Ambiguous switch, 'XXXXXX'
  528.  
  529. More than  one switch  exists  with  the same  specified starting
  530. character sequence. Specify switch more fully.
  531.  
  532.  
  533. ?CLP08: Illegal switch, 'XXXXXX'
  534.  
  535. The switch specified is  not valid according to  the  CLP library
  536. specification.
  537.  
  538.  
  539. ?CLP09: Switch 'XXXXXX' is negated and has value
  540.  
  541. A switch was specified negated with associated value. This is not
  542. permitted.
  543.  
  544.  
  545. ?CLP10: Value not allowed for switch 'XXXXXX'
  546.  
  547. The specified switch may not take a value.
  548.  
  549.  
  550. ?CLP11: Switch 'XXXXXX' may not be negated
  551.  
  552. The specified switch may not appear in the negated form.
  553.  
  554.  
  555. ?CLP12: Value is required for switch 'XXXXXX'
  556.  
  557. Specifying  the  switch  without  an  associated  value   is  not
  558. permitted. Include a value.
  559.  
  560.  
  561. ?CLP13: Insufficient memory to process switch options
  562.  
  563. Available memory was exhausted when trying to allocate memory for
  564. the user's switch values.
  565.  
  566.  
  567. ?CLP14: Invalid parameter, 'XXXXXX'
  568.  
  569. A parameter was given which was not expected.  Examine the syntax
  570. of the command as too many parameters were specified.
  571.  
  572.  
  573. ?CLP15: Invalid switch, 'NO'
  574.  
  575. A  switch  'NO'  was specified,  implying the negation of  a null
  576. switch. This is not permitted.
  577.