home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 1 / ARM_CLUB_CD.iso / contents / apps / program / a / cutils / Readme < prev    next >
Encoding:
Text File  |  1991-10-20  |  3.8 KB  |  90 lines
  1. General notes
  2. -------------
  3.  
  4. Sorry - not much documentation yet.  Maybe next release. 
  5.  
  6. The actual library is file Utils.  The rest is sources, headers etc. 
  7. The makefile is suitable for use with Amu or !Make. The file GMakefile
  8. is a makefile for my port of Unix Gnu Make, which should be available
  9. on various BBSs - otherwise it is on one of David Pilling's disks -
  10. sorry but I forget which.  See his ads.
  11.  
  12. However, all should become clear if you look at the sources or the
  13. header files.  Most stuff is fairly simple and/or implementations of
  14. Unix stuff.
  15.  
  16. Most of this is tested fairly thoroughly (particularly the Unix-like
  17. stuff - I use it all the time!) but the more obscure stuff such as the
  18. data structures - stack, queue, etc - are probably less robust.
  19.  
  20. Some parts of this package are not my own work. They are PD routines
  21. which I have found sufficiently useful to want to incorporate in this
  22. library. I take NO credit for anything good in these routines. The
  23. errors and mistakes, however, are most likely caused by me changing
  24. things to conform to the "style" of this library. My thanks go to the
  25. authors of these routines, for making them PD.
  26.  
  27. Specifically, the parts I did not write are:
  28.     The execution profiler, by Ferdinand Oeinck.
  29.     The regular expression routines, by the Free Software Foundation.
  30.     The option parser (getopt), by the Free Software Foundation.
  31.     The coroutine handler, by David McQuillan.
  32.     The swi veneers, by Edward Nevill.
  33. In the case of the profiler (in subdirectory Profile), coroutine (in
  34. file C.Coroutines) and swi (in files S.Swi and H.Swi) routines, I have
  35. made very few changes beyond any reformatting. The sources here should
  36. be largely complete. The two FSF packages - options (in directory Getopt)
  37. and regular expressions (in directory Regex) - have been hacked about, on
  38. the other hand. In the case of getopt, the changes are fairly small, but
  39. in the case of regex, I have done some massive "streamlining", plus a few
  40. changes to the RE syntax accepted (to standardise the RE syntax accepted
  41. across all my Arc ports. The resulting syntax is based on perl).
  42.  
  43. Enjoy!
  44.  
  45. Gustav (pmoore@cix.compulink.co.uk)
  46.  
  47. ---------------------------------------------------------------------------
  48.  
  49. The filter package
  50. ------------------
  51.  
  52. These functions (source in C.Filter) implement "filters", which
  53. basically simulate Unix pipes. What you do is, you create a filter as
  54.  
  55.      FILTER *f = FLTopen();
  56.  
  57. and then shove data into it using the (FILE *) FLTin(f). This is a
  58. file handle which has been opened for writing by the FLTopen().
  59.  
  60. Once you've finished writing data in, you can pass it through a set
  61. of commands by simply typing
  62.  
  63.      FLTfilter(f,command);
  64.  
  65. This returns a return code, or -2 (FILTER_ERROR) if an error occurred.
  66. Assuming everything went OK, you can read the output on the file pointer
  67. FLTout(f), and then execute another FLTfilter() - or you can just go
  68. straight on to the next command.
  69.  
  70. When you've finished, use FLTclose(f) to close the filter and tidy up (ie
  71. close files, and remove temporary files).
  72.  
  73. FLTfilter assumes all commands conform to C redirection specifications
  74. (in other words they use < and > to redirect stdin and stdout), except
  75. for a set list of builtin commands (see the file C.OsCmd - I basically
  76. just did a *HELP on my machine). Alternatively, starting any command
  77. with a % forces it to be treated as a builtin, and the % is ignored.
  78. Builtins are redirected using { < ... } and { > ... }, and the output
  79. file is post-processed to remove all the extra CRs which are generated.
  80.  
  81. It would be fairly simple with these functions to build a *PIPE command, say
  82.  
  83.      *PIPE cmd1 <in | cmd2 -o -x | cmd3 >out
  84.  
  85. I'll probably do so one day...
  86.  
  87. They are also used in the EMACS (C-X !), (C-X @) and (C-X #) commands.
  88.  
  89. ---------------------------------------------------------------------------
  90.