home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 3 / PDCD_3.iso / pocketbk / utilsr / shell3a / PROGRAM.TXT < prev    next >
Text File  |  1995-04-17  |  4KB  |  125 lines
  1. Notes for programming external shell modules
  2. ============================================
  3.  
  4. When a command is typed the shell processes it as follows:
  5.  
  6. (1) The input is compared with the aliases and any substitutions
  7.    are made. A '\' as the first non-blank character prevents
  8.    aliases being expanded.
  9. (2) The arguments are parsed one at a time. If a wildcard is
  10.    found this is expanded. If no matches are found an error is
  11.    generated, otherwise all arguments are stored in memory. The
  12.    array argv%() points to successive arguments. The last
  13.    argument in this array is always 0.
  14. (3) Redirection of output is handled.
  15. (4) The first argument is matched against the following:-
  16.    (a) The shell builtins
  17.    (b) Stored entries in the path
  18.    (c) A valid directory to 'cd' to
  19.    (d) A valid .opo or .bat file
  20.  
  21. Modules are stored in the shell's path as their basename. ie.
  22. LOC::M:\OPO\MORE.OPO would be stored as just 'more'. When 'more'
  23. is typed at the prompt and found not to match any of the builtin
  24. functions or aliases, the path is searched and it's found here.
  25. The module LOC::M:\OPO\MORE.OPO is then LOADMed and a function
  26. more%:(x%) is called.
  27.  The module MUST contain a function of this specification - it
  28. must be called the same as the .opo file, return an integer and
  29. take 1 integer argument. Currently the return value of the
  30. procedure isn't used.
  31.  
  32. e.g. To have a command 'newcom' recognized:
  33.  
  34. (1) Write an opl module with a procedure newcom%:(int%)
  35. (2) Compile this module to newcom.opo
  36. (3) Move newcom.opo into a directory in the path
  37. (4) Use the 'rehash' command to put the new command in your path
  38. (5) If you want a manual page for your command (e.g. if you want
  39.    to distribute the module), compile a help file 'newcom.hlp'
  40.    using the hcp.opo module, and put it in the helppath directory.
  41.  
  42.  
  43. Programming notes:
  44.  
  45. (a) Command arguments (this may change in future releases)
  46. ---------------------
  47. The input string is parsed by the shell and split into separate
  48. arguments. These are stored on the heap and are referenced by
  49. the argv%(n%) array. For example
  50.  
  51. cp file1.txt file2.txt
  52.  
  53. Stores: argv%(1)="cp"
  54.         argv%(2)="file1.txt"
  55.         argv%(3)="file2.txt"
  56.         argv%(4)=0            <- marks the end of the list
  57.  
  58.  Your module is passed the number of arguments - in this case 3 -
  59. as it's only parameter.
  60.  All text within quotes is stored as a single argument.
  61.  
  62.  
  63. (b) Wildcards
  64. -------------
  65. Wildcards are expanded before they are passed to the individual
  66. commands. e.g. ls LOC::M:/ would pass 'ls' a command line like
  67.  
  68.      ls,LOC::M:\AGN,LOC::M:\APP,LOC::M:\OPO,...
  69.  
  70. Note that wildcards are expanded to absolute pathnames and always
  71. have the native separator '\'. 
  72.  To pass wildcards to a module they need to be quoted "*".
  73.  
  74. (c) Useful functions (specifications may change in future releases)
  75. --------------------
  76.  
  77. ret%=Fparse%:(addr%,src$)
  78.  
  79. An 'enhanced' version of the OPL parse$ function. It handles
  80. relative paths and appends the trailed \ onto directories.
  81.  
  82. addr% - the address of a string, length 128 bytes. This will
  83.        contain the parsed string.
  84. src$  - the path to be parsed.
  85. ret%  - the status of the file as follows:
  86.  
  87. -33 : File / directory doesn't exist
  88. -127: Path contains wildcards
  89.  <0 : OPL error - the status of the returned pathname is undefined
  90.                  and shouldn't be used.
  91.  
  92.  >0 : Bit  0: file is not ReadOnly
  93.       Bit  1: file is Hidden
  94.       Bit  2: file is a System file
  95.       Bit  3: file is a Volume name
  96.       Bit  4: file is a Directory
  97.       Bit  5: file is Modified
  98. These are the values returned by the system call FilStatusGet
  99. (Fn $87 Sub $08)
  100.  
  101. eg. To test for a directory
  102.  
  103.  LOCAL x%,path$(128)
  104.  
  105.  x%=Fparse%:(ADDR(path$),"LOC::M:/APP/TEST")
  106.  IF x%<0
  107.    IF x%=-33
  108.      PRINT "Directory doesn't exist"
  109.    ELSE
  110.      PRINT ERR$(x%)
  111.    ENDIF
  112.  ELSEIF x% AND 16
  113.    PRINT "Found directory"
  114.  ELSE
  115.    PRINT "Isn't a directory"
  116.  ENDIF
  117.  
  118. -------------------------------------------------------------------
  119.  
  120.  ret%=fprint%:(string$)
  121.  
  122.  This procedure should be used to make use of output redirection.
  123. Depending on internal variables it either prints the string to the
  124. screen or to the file specified on the command line.
  125.