# Replace all occurrences of a regular expression in a scalar variable.
# The variable is modified directly.  Respects the setting of the option
# RE_MATCH_PCRE, but otherwise sets the zsh emulation mode.
#
# Arguments:
#
# 1. *name* (not contents) of variable or more generally any lvalue,
#    expected to be scalar.  That lvalue will be evaluated once to
#    retrieve the current value, and two more times (not just one as a
#    side effect of using ${(P)varname::=$value}; FIXME) for the
#    assignment of the new value if a substitution was made.  So lvalues
#    such as array[++n] where the subscript is dynamic should be
#    avoided.
#
# 2. regular expression
#
# 3. replacement string.  This can contain all forms of
#    $ and backtick substitutions; in particular, $MATCH will be
#    replaced by the portion of the string matched by the regular
#    expression. Parsing errors are fatal to the shell process.
#
# we use positional parameters instead of variables to avoid
# clashing with the user's variable.

if (( $# < 2 || $# > 3 )); then
  setopt localoptions functionargzero
  print -ru2 "Usage: $0 <varname> <regexp> [<replacement>]"
  return 2
fi

# $4 records whether pcre is enabled as that information would otherwise
# be lost after emulate -L zsh
4=0
[[ -o re_match_pcre ]] && 4=1
emulate -L zsh

# $5 is the string to be matched
5=${(P)1}

local    MATCH MBEGIN MEND
local -a match mbegin mend

if (( $4 )); then
  # if using pcre, we're using pcre_match and a running offset
  # That's needed for ^, \A, \b, and look-behind operators to work
  # properly.

  zmodload zsh/pcre || return 2
  pcre_compile -- "$2" && pcre_study || return 2

  # $4 is the current *byte* offset, $6, $7 reserved for later use
  4=0 7=

  local ZPCRE_OP
  while pcre_match -b -n $4 -- "$5"; do
    # append offsets and computed replacement to the array
    # we need to perform the evaluation in a scalar assignment so that if
    # it generates an array, the elements are converted to string (by
    # joining with the first chararacter of $IFS as usual)
    6=${(Xe)3}
    argv+=(${(s: :)ZPCRE_OP} "$6")

    # for 0-width matches, increase offset by 1 to avoid
    # infinite loop
    4=$(( argv[-2] + (argv[-3] == argv[-2]) ))
  done

  (( $# > 7 )) || return # no match

  set +o multibyte

  # $6 contains the result, $7 the current offset
  6= 7=1
  for 2 3 4 in "$@[8,-1]"; do
    6+=${5[$7,$2]}$4
    7=$(( $3 + 1 ))
  done
  6+=${5[$7,-1]}
else
  # in ERE, we can't use an offset so ^, (and \<, \b, \B, [[:<:]] where
  # available) won't work properly.
  while
    if [[ $5 =~ $2 ]]; then
      # append initial part and substituted match
      6+=${5[1,MBEGIN-1]}${(Xe)3}
      # truncate remaining string
      if (( MEND < MBEGIN )); then
	# zero-width match, skip one character for the next match
	(( MEND++ ))
	6+=${5[1]}
      fi
      5=${5[MEND+1,-1]}
      # indicate we did something
      7=1
    fi
    [[ -n $5 ]]
  do
    continue
  done
  [[ -n $7 ]] || return # no match
  6+=$5
fi

# assign result to target variable if at least one substitution was
# made.  At this point, if the variable was originally array or assoc, it
# is converted to scalar. If $1 doesn't contain a valid lvalue
# specification, an exception is raised (exits the shell process if
# non-interactive).
: ${(P)1::="$6"}