home *** CD-ROM | disk | FTP | other *** search
/ SPACE 2 / SPACE - Library 2 - Volume 1.iso / program / 619 / strsed / strsed.3c < prev    next >
Encoding:
Text File  |  1992-07-05  |  10.6 KB  |  248 lines
  1.  
  2. NAME
  3.     strsed - ed(1)/tr(1)-like substitute and replace function
  4.  
  5. SYNOPSIS
  6.     char *strsed(string, command, 0)
  7.     char *string;
  8.     char *command;
  9.  
  10.     or
  11.  
  12.     char *strsed(string, command, range)
  13.     char *string;
  14.     char *command;
  15.     int range[2];
  16.  
  17. DESCRIPTION
  18.     Strsed  is  a  regular  expression  pattern  match  and  replace
  19.     function that also combines tr(1)-like transliteration.  The GNU
  20.     regex package is used for the regular expression matching.
  21.  
  22.     Strsed can be used to provide the functionality of most  of  the
  23.     other more   "complicated"   string  functions  (e.g.    strchr,
  24.     strrchr, strpbrk, strspn, strcspn, and  strtok),  although  less
  25.     efficiently in  each  case,  due to its generality.  Strsed is a
  26.     very powerful and general function that can be used to carry out
  27.     complicated string manipulations such as those that are possible
  28.     in text editors.
  29.  
  30. USAGE
  31.     String should be a null-terminated character string.  A copy  is
  32.     made and will be operated on according to the search and replace
  33.     instructions contained  in command.  Unless an error occurs (see
  34.     ERRORS), the passed character strings  string  and  command  are
  35.     never  corrupted,  and the string that is returned may always be
  36.     passed to free(3) since its space is obtained from malloc(3).
  37.  
  38.     Both string and command may contain the following C-like  escape
  39.     sequences:
  40.  
  41.         \b      Backspace.
  42.         \f      Formfeed.
  43.         \n      Newline.
  44.         \r      Carriage Return.
  45.         \s      Space.
  46.         \t      Horizontal Tab.
  47.         \v      Vertical Tab.
  48.         \z      Used to remove ambiguity if necessary.
  49.         \0-9    A reference to a register.
  50.             (except for \0 in a regular expression.)
  51.         \0x3d   The character whose value is 3d hexadecimal.
  52.         \0X3d   The character whose value is 3d hexadecimal.
  53.         \040    The character whose value is 40 octal.
  54.         \32     The character whose value is 32 decimal.
  55.  
  56.     The NUL  (0) character cannot be specified.  A ``\'' followed by
  57.     one to three digits can be interpreted in several ways.  If  one
  58.     or  two  hex  digits are preceeded by an ``x'' or an ``X'', they
  59.     will be taken as specifying a  character  in  hexadecimal.    If
  60.     there  are  exactly  three  octal digits and the first is in the
  61.     range ``0'' to  ``3''  then  they  are  taken  as  specifying  a
  62.     character in  octal.   Otherwise a single digit is taken to be a
  63.     register reference and two or three digits  are  interpreted  as
  64.     specifying a  character  in  decimal.    \z can be used to avoid
  65.     problems with ambiguity.  For instance, \007 will be interpreted
  66.     by strsed as octal 007.  To specify  the  contents  of  register
  67.     zero  (\0)  followed  by  the two characters ``07'', use \0\z07.
  68.     The \z makes it clear what is meant (acting like  a  punctuation
  69.     mark) and is otherwise ignored.
  70.  
  71.     Strsed  allows  ed(1) like regular expressions and substitutions
  72.     on string.  The search  and  replace  command  is  specified  by
  73.     command.  The format of command is either
  74.  
  75.     /search_pattern/replacement/
  76.     or
  77.     g/search_pattern/replacement/
  78.  
  79.     In  the  first form, the search and replace is performed once on
  80.     the string, and in the second, the replacement is done  globally
  81.     (i.e. for every occurrence of the search pattern in string.).  A
  82.     leading ``s'' in the above is silently ignored.  This allows for
  83.     a syntax more  like  that of ed(1).  e.g.  s/e/x/ is the same as
  84.     /e/x/.
  85.  
  86.     If replacement is empty, then the matched text will be  replaced
  87.     by nothing - i.e.  deleted.
  88.  
  89.     Search_pattern   is  a  full  regular  expression  (see  ed(1)),
  90.     including register specifications (i.e. \( ... \)) and  register
  91.     references,  (e.g.  \2)  but not the {m,n} repetition feature of
  92.     ed(1).
  93.  
  94.     Replacement consists  of  ordinary  characters  and/or  register
  95.     references (e.g.  \1  or \2).  \0 means the entire matched text.
  96.     In addition, a register reference may be immediately followed by
  97.     a transliteration request, of the form
  98.  
  99.     {char-list-1}{char-list-2}.
  100.  
  101.     The characters from char-list-1 will be transliterated into  the
  102.     corresponding  ones  from  char-list-2  in  the  same  manner as
  103.     tr(1).  If  the  register  reference  before  a  transliteration
  104.     request is omitted, it defaults to \0.  Within a transliteration
  105.     request,  the characters "}" and "-" are metacharacters and must
  106.     be escaped with a leading \ if you want them to  be  interpreted
  107.     literally.   Character  ranges  such  as a-z are expanded in the
  108.     same fashion  as  tr(1).    If  char-list-2  is   shorter   than
  109.     char-list-1  then char-list-2 is padded to be the same length as
  110.     char-list-1 by repeating its last character as many times as are
  111.     needed.  For example, the transliteration request
  112.  
  113.     {a-z}{X}
  114.  
  115.     will  transliterate  all  lower  case  letters  into   an   'X'.
  116.     Character ranges may be increasing or decreasing.
  117.  
  118.     Unusual  character ranges (such as a-f-0- x2d-c) are interpreted
  119.     as running from their first character  to  their  last  (so  the
  120.     above would  be  treated  as a-c).  Note that it is not possible
  121.     (in this release) to specify the complement of a character range
  122.     in a transliteration request.  However, this can be done in  the
  123.     search_pattern by commencing a character class with a "^" in the
  124.     normal regular expression fashion.
  125.  
  126.     The highest register that can be referenced is \9.
  127.  
  128. EXAMPLES
  129.     Here  are  some  example  command strings that might be given to
  130.     strsed:
  131.  
  132.     /a/A/            # Change the first 'a' into an 'A'
  133.     g/a/A/           # Change every 'a' into an 'A'
  134.     g/://            # Delete every ':'
  135.     g/jack/jill/     # Change every 'jack' to a 'jill'
  136.     /[^\s\t]/X/      # Change the first non-whitespace
  137.                  # character into an 'X'.
  138.  
  139.     Some more advanced examples...
  140.  
  141.     /\([\s\t]*\)\([^\s\t]*\)/\1\2{a-z}{A-Z}/
  142.  
  143.     This converts the  first  non-whitespace  word  to  upper  case,
  144.     preserving any  initial whitespace.  It catches the first run of
  145.     spaces and TABs into register  one  \([\s\t]*\),  and  then  the
  146.     following   run   of  non-white  characters  into  register  two
  147.     \([^\s\t]*\).    The   replacement,   \1\2{a-z}{A-Z}   specifies
  148.     register 1 (the whitespace) followed by the contents of register
  149.     2 transliterated into uppercase.  This would produce
  150.  
  151.     "   SPOTTED pinto bean"
  152.  
  153.     if called on the string
  154.  
  155.     "   spotted pinto bean".
  156.  
  157.     g/\([a-z]\)\1+/\1/
  158.  
  159.     This  is a very useful example and performs the same function as
  160.     tr -s.  That is, it squeezes runs of  identical  characters  (in
  161.     the  range  a to z) down to a single instance of that character.
  162.     So "beeee good" becomes "be  god".    The  "+"  is  the  regular
  163.     expression notation meaning "one or more".
  164.  
  165.     g/\([\t\s]*\)\(.\)\([^\t\s]*\)/\1\2{a-z}{A-Z}\3/
  166.  
  167.     This  example  capitalises  the first letter of each word in the
  168.     string, and preserves all whitespace.  It catches three things,
  169.  
  170.     1) the initial whitespace         \([\t\s]*\)  in register 1
  171.     2) the next letter                \(.\)        in register 2
  172.     3) the following nonwhite letters \([^\t\s]*\) in register 3
  173.  
  174.     and then prints them out as  they  were  found,  with  the  only
  175.     difference  being  the  uppercase  conversion of the contents of
  176.     register 2.  Given the string
  177.  
  178.     "  this is a line  "
  179.  
  180.     this command would return
  181.  
  182.     "  This Is A Line  ".
  183.  
  184.     If the initial 'g' was not present  in  the  command,  then  the
  185.     capitalisation  would  only  be  done  to  the first word in the
  186.     string.  It is important to understand this difference well.
  187.  
  188. SEARCHING ONLY
  189.     Strsed may be used to search  for  a  regular  expression  in  a
  190.     string, but  perform  no action.  The portion of the string that
  191.     matched will be returned in the third argument range.   In  this
  192.     case command  should  be  of  the  form  /pattern/.   On return,
  193.     range[0] will contain an  index  into  the  original  string  to
  194.     indicate  where  the  match  began,  and range[1] will index the
  195.     first character after the end of the match.  For example,  after
  196.     the call
  197.  
  198.     strsed("two big macs please", "/b.*c/", range);
  199.     range[0] will  contain  4  and range[1] will contain 11.  If not
  200.     match is found, both elements of range will contain -1.
  201.  
  202. ERRORS
  203.     If strsed detects any error it returns NULL.  This can happen if
  204.     the syntax of command is incorrect, if the regular expression in
  205.     command  is  incorrect,  if  space  cannot  be   obtained   from
  206.     malloc(3), or for other similar reasons.  Note that it is not an
  207.     error if the empty string is returned.
  208.  
  209. COMPILING AND LINKING STRSED
  210.     Strsed  should  be compiled with the -O and -c options of your C
  211.     compiler.  It has no main() function.  When you  come  to  link,
  212.     you use strsed.o and regex.o from the GNU 18.55 (or 18.54) emacs
  213.     distribution.
  214.  
  215. OBSCURE NOTE ON REGULAR EXPRESSIONS
  216.     It  is possible (but not too likely) that the regular expression
  217.     language  that  is   recognised   may   differ   slightly   from
  218.     installation to  installation.   This is because the GNU regular
  219.     expression package may  compiled  with  different  settings  for
  220.     recognition of   meta-characters.     So  on  one  machine,  the
  221.     character "|" might be taken as being the  OR  operator,  whilst
  222.     somewhere else  you  need  to  give  "\|" - or vice-versa.  This
  223.     could be a pain in the neck, but there's not alot  that  can  be
  224.     done about  it.   If you really need to know the difference in a
  225.     portable way, look in regex.h to see what things are defined and
  226.     then act accordingly when constructing commands for strsed.
  227.  
  228. AUTHOR
  229.     Terry Jones
  230.     PCS Computer Systeme GmbH
  231.     Pfaelzer-Wald-Str 36
  232.     8000 Muenchen 90
  233.     West Germany 49-89-68004288
  234.  
  235.     terry@distel.pcs.com
  236.     or ...!{pyramid,unido}!pcsbst!distel!terry
  237.  
  238.     January 8th, 1990.
  239.  
  240. ACKNOWLEDGEMENTS
  241.     Many thanks to  Jordan  K.  (mother)  Hubbard  for  discussions,
  242.     bugfinding, handholding, forcing me to use emacs and torrents of
  243.     (usually) uncalled-for abuse.
  244.  
  245. SEE ALSO
  246.     ed(1), tr(1)
  247.  
  248.