home *** CD-ROM | disk | FTP | other *** search
/ The C Users' Group Library 1994 August / wc-cdrom-cusersgrouplibrary-1994-08.iso / listings / v_11_11 / splash / readme.2nd < prev    next >
Text File  |  1993-01-15  |  8KB  |  244 lines
  1. For support Email to morris@netcom.com or jegm@sgi.com
  2.  
  3. I would welcome bug reports for a while!
  4. Also comments are always welcome.
  5.  
  6. The latest version of SPLASH is always available via anonymous
  7. FTP from netcom.com in ~ftp/pub/morris/splash.tar.Z (for Unix)
  8. and ~ftp/pub/morris/splash.zoo (for MSDOS)
  9.  
  10. Introducing SPLASH
  11. ==================
  12.  
  13. SPLASH is a c++ class library that implements my favourite perl
  14. constructs.  Obviously I can't duplicate all the functionality of perl,
  15. and wouldn't need to as perl already exists!! However I find this
  16. useful, because it allows me to do Perl-like things in my programs.
  17.  
  18. This Code is not copyright, use as you will.  The regexp code is by
  19. Henry Spencer, see the comments for Copyright info.  The only changes I
  20. have made are to the header file, by adding a c++ prototype field.
  21.  
  22. The Class Hierarchy and member functions are are fully described in
  23. the file splash.doc
  24.          
  25. Building NOTES
  26. ==============
  27. This must be compiled with a 3.0 or greater c++ compiler that can
  28. handle Templates and nested classes.
  29.  
  30. It has been tested on Borland c++ v3.1 and USL-based 3.0.  GCC v2.2.2
  31. doesn't like the Copy constructor syntax in template classes, and gives
  32. an assert error as well.
  33.  
  34. To build:
  35.  
  36. compile splash.c++ and regex.c. Link in with your App.
  37. Include splash.h, (and assoc.h if used).
  38.  
  39. > cc -c regex.c
  40. > CC -c splash.c++
  41. > CC yourapp.c++ splash.o regex.o -o yourapp
  42.  
  43. To test:
  44.  
  45. > CC -DTEST spltest.c++ splash.c++ regex.o -o spltest
  46. > spltest > x
  47. > diff x splash.v
  48.  
  49. and
  50.  
  51. > CC -DTEST slicetst.c++ splash.o regex.o -o slicetst
  52. > slicetst > x
  53. > diff x slicetst.v
  54.  
  55. This will do a full regression test. splash.v & slicetst.v contains the
  56. sample output of a correct run, so no differences should be
  57. encountered.
  58.  
  59. regex.c is not an ANSI c file, so you will have to turn off prototype
  60. checking on your ANSI c compiler (or select kr checking).
  61.  
  62. Some of the samples use a file called tracer.h, this is a fairly useful
  63. Debugging helper grabbed from the net and slightly modified. I include
  64. tracer.h and tracer.c++ for completeness, however they are not required.
  65.  
  66. CAVEATS (known ones that is)
  67. =======
  68. This is not an optimised implementation, by any stretch of the
  69. imagination. It is a quick and dirty, "but it works" one.
  70.  
  71. No "out of memory checking" is done, I thought I'd wait for
  72. exceptions!!
  73.  
  74. I have taken a few liberties in translating the selected perl
  75. functionality into a class library, apologies to Larry Wall, and
  76. anyone else this may offend.  You are welcome to fix it, just tell me
  77. how you did it.
  78.  
  79. A SPList<T> can only contain a list of type T, it cannot, as yet,
  80. have multiple types in the same list. (This is feasible but messy).
  81.  
  82. Assigning to an element of a SPList that is greater than the current
  83. length of the SPList will expand the list as in perl, but the values
  84. in the newly created elements will be undefined, unlike perl. Except
  85. SPStringList which will create empty strings. Also if <T> is a class
  86. then the values will be whatever the default constructor creates.
  87.  
  88. Anything that you make a SPList out of must define an operator<(),
  89. for the sort routine. Its ok if it is a dummy.
  90.  
  91. The first index of a list is always 0. (Again this could be fixed).
  92.  
  93. Unlike perl you can also access characters within
  94. a SPString using the '[]' syntax. But you must use substr() to
  95. change them.
  96.  
  97. Note that SPStrings cannot have embedded '\0' like perl, this
  98. is an efficiency trade off, because '\0' as a terminator is so
  99. ingrained in c++ and c strings. (This could be fixed by carefully
  100. replacing all str... functions with mem... functions
  101.  
  102. Regular Expressions
  103. -------------------
  104.  
  105. Regular expressions may be slightly different, I used the straight
  106. Henry Spencer version. I'm not sure what changes Larry made to them.
  107. (It definitely doesn't support \w \b \s \S \d \D, or global match
  108. mode). - If someone can make Larry's regexp stuff into a stand-alone
  109. package like the original regex stuff, then I'll use it!
  110.  
  111. The g & o options are not supported in the m() functions.
  112. I will try to support the 'g' option for m() in a list context.
  113.  
  114. SPStringList::m(exp, targ) and SPString::m(exp, list) are used to
  115. simulate $&, $0 - $9 in perl. In both cases the list gets loaded with
  116. the subexpression matches. The 0'th element is equivalent to $& in perl
  117. and the 1'st element is equivalent to $1 etc.
  118.  
  119. Note that in the SPStringlist::m() member function, result lists are
  120. appended whereas in SPString::m(s, list) 'list' is reset first.
  121. eg
  122. {
  123. SPString s;
  124. SPStringList l1, l2;
  125.  
  126.     s= "hello frobo goodbye";
  127.     l1.push("was here first1"); l2.push("was here first2");
  128.     s.m("(.*)frobo(.*)", l2); // Overwrites l with new list
  129.     l1.m("(.*)frobo(.*)", s); // appends l with new list
  130. // produces this result:
  131. // l2[0] is "hello frobo goodbye"    // equiv of $&
  132. // l2[1] is "hello "            // equiv of $1
  133. // l2[2] is " goodbye"            //        $2
  134. // and
  135. // l1[0] is "was here first"
  136. // l1[1] is "hello frobo goodbye"    // equiv of $&
  137. // l1[2] is "hello "            //          $1
  138. // l1[3] is " goodbye"            //        $2
  139. // an l1.reset() preceding the l1.m() would get rid of l1[0] in the
  140. // above example.    
  141. }
  142.  
  143. To get the exact perl semantics of the m function in a list context
  144. you can use the global m() function as follows:-
  145. {
  146. SPStringList sl;
  147. sl = m("(..) (..)", "ab cd ef"); // sl[0] gets "ab", sl[1] gets "cd"
  148. }
  149.  
  150. SP expressions (s/123/$&*2/e) in a substitute command
  151. (SPString::s()) are obviously not done. However $& and $0-$9 are
  152. correctly expanded and substituted.
  153.  
  154. Also remember that if you want to put a \ in the regular expression
  155. then you must actually type \\ as the c compiler will interpret a \ for
  156. you. What happens to things like \t is up to your compiler.
  157.  
  158.  
  159. I/O
  160. ---
  161. I/O is done using standard c++ streams. I think this is ok, although
  162. some perl-ism maybe introduced one day.
  163. eg to copy a text file a line at a time:-
  164. {
  165. ifstream fin("file1.txt");
  166. ofstream fout("file2.txt");
  167. SPString si;
  168.  
  169.     while(fin >> si) fout << si << endl;
  170. }
  171.  
  172. This will read the entire file into a SPStringList:-
  173. {
  174. SPStringList l;
  175. ifstream fin("file1.txt");
  176.  
  177.     fin >> l;
  178. }
  179.  
  180. One nifty outcome of using streams this way is the following syntax
  181. will load a SPStringList and SPList<T> in a reasonably compact
  182. way:-
  183. {
  184. SPStringList slist;
  185. strstream ss;
  186.     ss << "one\n" << "two\nthree\nfour\n";
  187.     ss >> slist; // creates a 4 element string list
  188.  
  189. strstream iss;
  190. SPList<int> il;
  191.  
  192.     iss << "1 2 3 4 5 6 7 8 9 10" << endl; // quick load an integer array
  193.     iss >> il; // creates a 10 element integer list
  194. }
  195.  
  196.  
  197. Iterators
  198. ---------
  199. There is no iterator per-se, but all lists (including Assoc) allow
  200. an index to step through the list one by one. So iteration can be
  201. achieved, albeit clumsily.
  202. eg
  203.  
  204. SPList<int> intlist;
  205.  
  206. for(int i=0;i<inlist.scalar();i++){
  207.     cout << intlist[i];
  208. }
  209.  
  210. foreach could be simulated with the following macro:-
  211.  
  212. #define FOREACH(var, array)\
  213.   for(int i=0;i<array.scalar() && (var=array[i], 1);i++)
  214.  
  215. eg
  216. {
  217.  
  218.     SPList<int> fred;
  219.     int val, tot= 0;
  220.  
  221.     {    // this is useful to avoid the 'i' in the macro colliding
  222.     FOREACH(val, fred){
  223.         tot += val;
  224.     }
  225.     }
  226. }
  227.  
  228. A SPList or SPStringList may be used in an if statement to test
  229. if the list is empty or not.
  230. eg
  231. {
  232. SPList<int> il;
  233.  
  234.     if(il) cout << "List is not empty" << endl;
  235.     else il.push(1);
  236. }
  237.  
  238. ==========
  239. Disclaimer
  240. ==========
  241.  
  242. This is a personal work, and SGI is not responsible for anything
  243. contained herein.
  244.