# $EPIC: msar,v 1.3 2005/03/08 05:53:31 jnelson Exp $
Synopsis:
   $msar([i][g][r]/[<search>/<replace>/]*<text>)

Technical:
   The arguments are composed of:
   1) zero or more of the options 'i', 'g', and 'r',
   2) a delimiter which can be any character other than 'i', 'g', or 'r',
      and is customarily a forward-slash,
   3) ZERO OR MORE SETS OF SUBSTITUTIONS:
      3a) some text ("<search>") that may not contain the delimiter to be 
          removed,
      3b) a delimiter; the same as (2),
      3c) some text ("<replace>") that may not contain the delimiter to be 
          inserted in place of (3a),
      3d) a delimiter; the same as (2),
   4) a string of text ("<text>") that MAY NOT contain the delimiter to be 
      transformed.

   No matter what, <text> is always the text that follows the final delimiter.
   If properly formed, there should always be an odd number of delimiters in
   the arguments.  But if there is an even number of delimiters, this would
   result in a substutition with a <search> but no <replace>.  This <search>
   would be ignored as a syntax error.

   In its simple form, the string <text> is returned with the first instance
   of each of the <search> strings replaced with each of the corresponding
   <replace> strings.  The search of <search> is case insensitive.

   The options modify this behavior:
      i    The search for <search> should be case sensitive.
      g    All instances of <search> should be replaced with <replace>.
           You must be careful that the contents of <replace> do not match
           <search> because this would cause it to be infinitely replaced.
      r    The <text> argument is a variable that should be substituted.
           The result of the substitution(s) are assigned back to this
           variable.

Synopsis:
   $msar(/<search>/<replace>/ ... /<text>)

Returns:
   the resultant string

Examples:
   $msar(/as/xy/asdf)                 returns "xydf"
   $msar(/as/xy/yd/42/asdf)           returns "x42f"
   $msar(/e/he/pi/ll/c/o/epic)        returns "hello"

See Also:
   tr(6); sar(6)