home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / modu1096.zip / GPMsym / buildargs.def < prev    next >
Text File  |  1996-08-29  |  3KB  |  89 lines
  1. (****************************************************************)
  2. (*                                                              *)
  3. (*         Gardens Point Modula-2 Library Definition            *)
  4. (*                                                              *)
  5. (*                                                              *)
  6. (*     (c) Copyright 1996 Faculty of Information Technology     *)
  7. (*              Queensland University of Technology             *)
  8. (*                                                              *)
  9. (*     Permission is granted to use, copy and change this       *)
  10. (*     program as long as the copyright message is left intact  *)
  11. (*                                                              *)
  12. (****************************************************************)
  13.  
  14. (* !LIBRARY! *) DEFINITION MODULE BuildArgs;
  15.  
  16.   TYPE ArgPtr; (* ==> "pointer to array of strings" in UNIX  *)
  17.  
  18.   (* The first set of procedures are simple & efficient and
  19.      have several restrictions to their use. However, they
  20.      suffice for most purposes, when used as shown below.
  21.    *)
  22.  
  23.   PROCEDURE Arg1(a1 : ARRAY OF CHAR) : ArgPtr;
  24.   PROCEDURE Arg2(a1, a2 : ARRAY OF CHAR) : ArgPtr;
  25.   PROCEDURE Arg3(a1, a2, a3 : ARRAY OF CHAR) : ArgPtr;
  26.   PROCEDURE Arg4(a1, a2, a3, a4 : ARRAY OF CHAR) : ArgPtr;
  27.   (*
  28.      preconditions : a's may be literals or variable arrays.
  29.      These procedures safely copy array parameters into a
  30.      dynamically allocated block, adding NUL termination if
  31.      necessary. Actual param variables may thus be reused.
  32.  
  33.      usage example:
  34.         ...
  35.         FROM BuildArgs IMPORT Arg3;
  36.         FROM UxProcesses IMPORT Execp; (* execs from $PATH *)
  37.           VAR cmd, fNm : ARRAY [0 .. 39] OF CHAR;
  38.           ...
  39.           Execp("foo", Arg3("foo", cmd, fNm));
  40.           Error("Can't exec 'foo'");
  41.           ...
  42.  
  43.  
  44.      The next set of procedures allow argument blocks of any
  45.      size to be built, and allow for explicit reclaiming of
  46.      memory space from used blocks, where that is necessary.
  47.      These procedures safely copy array parameters into a
  48.      dynamically allocated block, adding NUL termination if
  49.      necessary. Actual param variables may thus be reused.
  50.    *)
  51.  
  52.   TYPE ArgBlock; (* args + builder state information *)
  53.  
  54.   PROCEDURE NewArgBlock(VAR b : ArgBlock; max : CARDINAL);
  55.   (* postcondition : buffer space for max args is allocated
  56.                      and the block state is initialized
  57.    *)
  58.  
  59.   PROCEDURE DisposeArgBlock(VAR b : ArgBlock);
  60.   (* postcondition : buffer space is reclaimed, b is NIL *)
  61.  
  62.   PROCEDURE AppendArg(b : ArgBlock; a : ARRAY OF CHAR);
  63.   (* precondition  : b has been initialized by NewArgBlock;
  64.                      is not fully occupied; 
  65.      postcondition : the block designated by b is updated so
  66.                      that a is its final argument. On block
  67.                      overflow an index error is raised
  68.    *)
  69.  
  70.   PROCEDURE ArgsOf(b : ArgBlock) : ArgPtr;
  71.   (*
  72.      extracts the args from the valid ArgBlock buffers
  73.  
  74.      usage example:
  75.         ...
  76.         WHILE condition DO
  77.           NewArgBlock(blk,64);
  78.           WHILE xxx DO (* build block *)
  79.             ....
  80.             AppendArg(blk,str);
  81.           END;
  82.           Foo(ArgsOf(blk)); (* use block *)
  83.           DisposeArgBlock(blk); (* reclaim space *)
  84.         END;
  85.         ...
  86.   *)
  87.  
  88. END BuildArgs.
  89.