home *** CD-ROM | disk | FTP | other *** search
/ PDA Software Library / pdasoftwarelib.iso / PSION / UTILS / SHELL3A / PROGRAM.TXT next >
Encoding:
Text File  |  1996-09-01  |  8.5 KB  |  237 lines
  1. Program.txt - Notes for programming external shell modules
  2. -----------
  3. This file contains information necessary for writing OPL modules
  4. that can be used by Shell3a as external commands.
  5.  
  6. Contents: How commands are executed
  7.           Command arguments
  8.           Wildcards
  9.           Shell3a variables
  10.           Shell3a procedures
  11.           Programming for 'pipes'
  12.           Detailed descriptions of some procedures
  13.  
  14. 1) How commands are executed
  15. ============================
  16.  
  17. When a command is typed the shell processes it as follows:
  18.  
  19. (a) The input is compared with the aliases and any substitutions
  20.    are made. A '\' as the first non-blank character prevents
  21.    aliases being expanded.
  22. (b) The arguments are parsed one at a time. If a wildcard is
  23.    found this is expanded. If no matches are found an error is
  24.    generated, otherwise all arguments are stored in memory. The
  25.    array argv%() points to successive arguments. The last
  26.    argument in this array is always 0. Comments and variable
  27.    substitutions are made.
  28. (c) Redirection of output is handled.
  29. (d) The first argument is matched against the following:-
  30.    (i) The shell builtins
  31.    (ii) Stored entries in the path
  32.    (iii) A valid .bat, .opo, .opa or .opa file in the path
  33.    (iv) A valid directory to 'cd' to
  34.  
  35. Modules are stored in the shell's path as their filename. ie.
  36. LOC::M:\OPO\MORE.OPO would be stored as 'more.opo' and can be
  37. accessed as either 'more' or 'more.opo'. When 'more' is typed at
  38. the prompt and found not to match any of the builtin functions or
  39. aliases, the path is searched and it's found here. The module
  40. LOC::M:\OPO\MORE.OPO is then LOADMed and a function more%:(x%)
  41. is called.
  42.  The module MUST contain a function of this specification - it
  43. must be called the same as the .opo file, return an integer and
  44. take 1 integer argument. Currently the return value of the
  45. procedure isn't used.
  46.  
  47. e.g. To have a command 'newcom' recognized:
  48.  
  49. (a) Write an opl module with a procedure newcom%:(int%)
  50. (b) Compile this module to newcom.opo
  51. (c) Move newcom.opo into a directory in the path
  52. (d) If you want a manual page for your command (e.g. if you want
  53.    to distribute the module), compile a help file 'newcom.hlp'
  54.    using the hcp.opo module, and put it in the helppath directory.
  55.  
  56.  
  57. 2) Command arguments
  58. ====================
  59. The input string is parsed by the shell and split into separate
  60. arguments. These are stored on the heap and are referenced by
  61. the argv%(n%) array. For example
  62.  
  63. cp file1.txt file2.txt
  64.  
  65. Stores: argv%(1)="cp"
  66.         argv%(2)="file1.txt"
  67.         argv%(3)="file2.txt"
  68.         argv%(4)=0            <- marks the end of the list
  69.  
  70.  Your module is passed the number of arguments - in this case 3 -
  71. as it's only parameter.
  72.  All text within quotes is stored as a single argument.
  73.  
  74.  
  75. 3) Wildcards
  76. ============
  77. Wildcards are expanded before they are passed to the individual
  78. commands. e.g. ls LOC::M:/ would pass 'ls' a command line like
  79.  
  80.      ls,LOC::M:\AGN,LOC::M:\APP,LOC::M:\OPO,...
  81.  
  82. Note that wildcards are expanded to absolute pathnames and always
  83. have the native separator '\'. 
  84.  To pass wildcards to a module they need to be quoted "*".
  85.  
  86.  
  87. 4) Shell3a variables
  88. ====================
  89. Internal global variables that are generally not intended for
  90. external use have names starting with "SH" to avoid accidental
  91. conflicts. The 'useful' globals are listed below along with a
  92. BRIEF description:
  93.  
  94. argv%()    the command argument array, discussed above
  95. varStyl%   the current font style
  96. varStat%   set if the status panel is visible
  97. varUnix%   set if / is to be used as the pathname separator
  98. varApp%    set if output redirection should always append to the output file
  99. varEcho%   set if commands in batch files are to be displayed as executed
  100. ScrInfo%() the data obtained from SCREENINFO function on the current screen
  101.  
  102. [NB. Unsetting a shell variable that has a corresponding var*% OPL
  103.  variable (eg. varUNIX% and $unix) will have no effect on the
  104.  var*%, these are only changed when shell variables are set.]
  105.  
  106.  
  107. 5) Shell3a procedures
  108. =====================
  109. Internal functions are prefaced by 'sh'; to avoid possible
  110. conflicts you should avoid functions starting 'sh...'. Also
  111. avoid function names that appear as builtin commands and the
  112. ones listed below.
  113.  
  114. Procedures that will be useful in writing modules are listed
  115. below. Some are described in greater detail in section (6) and
  116. are denoted with an asterix:
  117.  
  118.  SetVar%:(var$,val$)    Store val$ in the shell variable var$
  119.  s$=GetVar$:(var$)      Return the value of the shell variable var$
  120.  FreeVar%:(var$)        Delete the shell variable var$
  121. *ret%=Fparse%:(add%,s$) Enhanced PARSE$ function
  122. *ret%=fprint%:(string$) Handle output redirection
  123.  p$=PrPath$:(buf$)      convert a path to UNIX form (if necessary)
  124. *err$:(n%)              Enhanced err$ function
  125.  ShErr:(i%,n%)          PRINT PrPath$:(PEEK$(argv%(i%))),"-",err$:(n%)
  126. *log:(flag%,message$)   Display a message in the status window
  127.  
  128.  
  129. 6) Programming for 'pipes'
  130. ==========================
  131. As stated in the general Readme, commands must be specially written
  132. for input/output edirection and pipes to work. Pipes aren't coded
  133. for specially, if you code commands to use redirection, pipes will
  134. work!
  135.  
  136. Output Redirection: A command is informed if the output is
  137. redirected by a non-zero value for SHout%. This value is the OPL
  138. handle for the file that output is to be written to with the
  139. IOWRITE command. The easiest way to handle this is to use fprint%:
  140. to produce any output. The command should only write to SHout%,
  141. it shouldn't change the value or close the file handle.
  142.  
  143. Input redirection: A command is informed if the output is
  144. redirected by a non-zero value for SHin%. In general input
  145. redirection is only really useful for commands that could already
  146. take their input from a file. For redirected input, rather than
  147. opening a file whose name was supplied on the command line, data is
  148. read directly from SHin% with IOREAD. As with SHout%, SHin% should
  149. not have it's value changed and it should not be closed.
  150.  Included is Wc.opl, the source for a command that counts the
  151. characters, words and lines of a file, to demonstrate the redirection
  152. of input.
  153.  
  154.  
  155. 7) Detailed descriptions of some procedures
  156. ===========================================
  157. (a) Fparse%: ret%=Fparse%:(add%,s$) Enhanced PARSE$ function
  158.  
  159. It handles relative paths and appends the trailed \ onto
  160. directories.
  161.  
  162. add% - the address of a string, length 128 bytes. This will
  163.        contain the parsed string.
  164. s$   - the path to be parsed.
  165. ret%  - the status of the file as follows:
  166.  
  167. -33 : File / directory doesn't exist
  168. -127: Path contains wildcards
  169.  <0 : OPL error - the status of the returned pathname is undefined
  170.                  and shouldn't be used.
  171.  
  172.  >0 : Bit  0: file is not ReadOnly
  173.       Bit  1: file is Hidden
  174.       Bit  2: file is a System file
  175.       Bit  3: file is a Volume name
  176.       Bit  4: file is a Directory
  177.       Bit  5: file is Modified
  178. These are the values returned by the system call FilStatusGet
  179. (Fn $87 Sub $08)
  180.  
  181. eg. To test for a directory
  182.  
  183.  LOCAL x%,path$(128)
  184.  
  185.  x%=Fparse%:(ADDR(path$),"LOC::M:/APP/TEST")
  186.  IF x%<0
  187.    IF x%=-33
  188.      PRINT "Directory doesn't exist"
  189.    ELSE
  190.      PRINT ERR$(x%)
  191.    ENDIF
  192.  ELSEIF x% AND 16
  193.    PRINT "Found directory"
  194.  ELSE
  195.    PRINT "Isn't a directory"
  196.  ENDIF
  197.  
  198. -------------------------------------------------------------------
  199.  
  200. (b) ret%=fprint%:(string$)  Handle output redirection
  201.  
  202.  This procedure should be used to make use of output redirection.
  203. Depending on internal variables it either prints the string to the
  204. screen or to the file specified on the command line.
  205.  
  206. -------------------------------------------------------------------
  207.  
  208. (c) s$=err$:(n%)  Enhanced err$ function
  209.  
  210.  Returns error string as ERR$ except for these values for n%:
  211.  
  212. -127 "Wildcards not allowed"
  213. -111 "Argument overflow"
  214. -33  "No such file or directory"
  215. 1    "Not a directory"
  216. 2    "Must be a directory"
  217. 3    "Not a plain file"
  218. 4    "No match"
  219. 5    "Redirection isn't the penultimate argument"
  220. 6    "No such variable"
  221. 7    "Missing '"
  222. 8    "Bad ${..}"
  223. 8    "Not in autoexec.bat"
  224.  
  225. -------------------------------------------------------------------
  226.  
  227. (d)  log:(flag%,message$)  Display a message in the status window
  228.  
  229. Display message$ modified by flag% as follows:
  230.  
  231. Bit 0: set to create the window
  232. Bit 1: set to destroy the window
  233. Bit 2: set to display message$ on a new line
  234. Bit 3: set to display message$ in bold
  235. Bit 4: set to display message$
  236. Bit 5: set to use message$ as the title
  237.