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 < prev    next >
Text File  |  1993-01-15  |  7KB  |  180 lines
  1. The SPLASH c++ class library
  2. ============================
  3.  
  4. (Small Perl-like List And String Handling class library)
  5.  
  6.  
  7. SPLASH is a c++ class library that implements my favourite Perl
  8. constructs.
  9.  
  10. For those not familiar with Perl, it is an excellent scripting language
  11. by Larry Wall and is available for most platforms.
  12.  
  13. This Class library provides List and String handling capabilities based
  14. on those provided in Perl, because the Perl constructs are so useful.
  15.  
  16. Overview
  17. -------- 
  18. In a nut-shell SPLASH provides a Dynamic List template class
  19. (SPList<T>) that allows you to add and extract data from the top of the
  20. list (push & pop), and from the bottom of the list (unshift & shift).
  21. ie a FIFO could be implemented by push'ing data onto the list and
  22. shift'ing data off the list.  The list can be sorted (uses operator< on
  23. the elements) and reversed.  (mylist.sort().reverse() will produce a
  24. list sorted in reverse order).  Another list can be inserted anywhere
  25. in a list, or elements deleted from within the list (splice).  And any
  26. individual element can be accessed using the '[]' operator.
  27.  
  28. The String class (SPString) implements a Dynamic string which provides
  29. an index() and rindex() function that finds the offset within the
  30. string of a sub-string. A substring may be extracted from the string,
  31. or assigned to within a string (expanding or shrinking the string as
  32. required). The string may be used anywhere a const char * can be used.
  33. The standard comparison functions (< > == etc) are available.  It
  34. allows string concatenation using the '+' and '+=' operator.  It
  35. provides regular expressions (with sub-expression extraction) that can
  36. be easily applied to the strings. A powerful substitute function and
  37. translation function (s() and tr()) are available.
  38.  
  39. The String List class (SPStringList) is basically a List class with
  40. some added functionality specific to lists of strings. It lets you grep
  41. for a regular expression within the list, returning a list of strings
  42. that match. It lets you generate a list of strings from a single string
  43. by splitting the string at a given regular expression (token parsing).
  44. It lets you generate a single string by concatenating a list of strings
  45. separated by a given string.
  46.  
  47. The Associative array class (Assoc<T>) lets you keep a list which is
  48. indexed by a string.
  49.  
  50. All the Classes have fully implemented streams operators for input and
  51. output, to allow convenient file or stream processing.
  52.  
  53. The Regexp class fully encapsulates the regular expression library, so
  54. you can easily use your own favourite one.
  55.  
  56. Usage Restrictions
  57. ------------------
  58.  
  59. There are none. This Code is not Copyright, use as you will.  The
  60. regexp code is Copyright by Henry Spencer, see the comments in regex.c
  61. for Copyright info.  The only changes I have made are to the header
  62. file, by adding a c++ prototype field.
  63.  
  64. Class description
  65. -----------------
  66. The Class Hierarchy and member functions are:-
  67.  
  68. class SPList<T>
  69.     T& operator[]    // index into list
  70.     void reset()    // clear out list
  71.     int scalar()    // returns number of elements in list
  72.     int count()        // ditto
  73.     T pop()        // returns and removes top of list
  74.     void push(T)    // enters element onto top of list
  75.     void push(SPList<T>) // enters a list of elements onto top of list
  76.     T shift()        // returns & removes element at bottom of list
  77.     int unshift(T)    // enters element into bottom of list
  78.     int unshift(SPList<T>) // enters lists into bottom of list
  79.     SPList<T> reverse()       // returns reverse order of list
  80.     SPList<T> splice(offset) // removes elements in list from 'offset'
  81.     SPList<T> splice(offset, len) // removes 'len' elements in list
  82.     SPList<T> splice(offset, len, SPList<T>)// replaces elements in list
  83.     SPList<T> sort() // sorts list according to result of '<' operator
  84.     ostream& operator>>() // input stream
  85.     istream& operator<<() // output stream
  86.  
  87.     class SPStringList // everything SPList does and ...
  88.         int split(str [,pat] [,limit]) // splits string on pattern
  89.     SPString join([pat])     // concatenates list with 'pat'
  90.     int m(exp, targ)      // makes list of sub exp matches
  91.     SPStringList grep(exp) // returns matches in list
  92.     ostream& operator>>()
  93.         istream& operator<<()
  94.  
  95. class SPString
  96.     int length()    // length of string
  97.     char chop()        // remove last character in string
  98.     int index(SPString [, offset]) // find string from start
  99.     int rindex(SPString [, offset]) // find string from end
  100.     SPString substr(offset [, len]) // substring works as lvalue as well
  101.     operator[]    // index character
  102.     operator<   // less than
  103.     operator>
  104.     operator<=
  105.     operator>=
  106.     operator==
  107.     operator!=
  108.     operator+        // concatenate 2 strings
  109.     operator+=        // as per c
  110.     int m(exp)         // return true if regexp matches string
  111.     int m(exp, SPStringList&) // ditto & generates a list of subexpressions
  112.     int tr(exp, rep [,opts]) // translate 'ex'p into 'rep'
  113.     int s(exp, rep [,opts]) // substitute 'exp' with 'rep'
  114.     ostream& operator>>()
  115.     istream& operator<<()
  116.  
  117. Associative array and helpers
  118. -----------------------------
  119.  
  120. class Binar<T>    // a key, value pair
  121.     T& value()
  122.     SPString& key()
  123.  
  124. class Assoc<T>    // an associateive array, loosely based on the perl one
  125.     T& operator(SPString) // equivalent to perl $assoc{"one"} = value
  126.     Binar& operator[n]      // returns n'th entry in associative array
  127.     SPStringList keys()   // returns a list of keys
  128.     SPList<T> values()    // returns a list of values
  129.     int isin(SPString)    // tests if key is in assoc array
  130.     T adelete(SPString)    // deletes given key/value
  131.  
  132. Other Classes
  133. -------------
  134.  
  135. VarString    - A variable length string class, used in SPString.
  136.  
  137. SPListBase<T>     - is the base class for SPList and handles the
  138.           auto expanding dynamic array, optimized for
  139.           prepending and appending data.
  140.  
  141. TempString     - makes a copy of a string, and can return a char *
  142.                and will free the storage when done. Something like
  143.           a cross between strsave() and alloca().
  144.  
  145. Regexp        - Handles the interface to the regular expression
  146.           library being used.
  147.  
  148. Range         - Simple class to maintain a range, just makes things
  149.           easier.
  150.  
  151. For More Info
  152. =============
  153.  
  154. See readme.2nd for how to build and test, and various caveats.
  155. See splash.doc for documentation on each function.
  156. See sample/*.c++ for examples of how to use splash
  157. See regexp.doc for an explanation of the regexp library used
  158.  
  159. Distribution
  160. ------------
  161.  
  162. This is also available as a compressed tar file or
  163. .zoo format with MSDOS compatible names.
  164.  
  165. Email: morris@netcom.com or jegm@sgi.com for a different format.
  166. or
  167. get the latest version of SPLASH, which is always available via
  168. anonymous FTP.
  169.  
  170. Also the current alpha version will also be available. This is for
  171. adventurous users only. It will be called splalphaxxx.tar.Z
  172.  
  173. site:-
  174. netcom.com
  175.  
  176. Path:-
  177. ~ftp/pub/morris/splash.tar.Z
  178. ~ftp/pub/morris/splash.zoo
  179.  
  180.