Java Quirks: java.lang.IllegalArgumentException: Illegal group reference in matcher.appendReplacement and how to solve it

I was doing some regexp work on one of my projects, when suddenly this well-known and hundred-of-times implemented code right from the javadoc, failed:

   StringBuffer result = new StringBuffer(text.length());
   while (includeMatcher.find()) {
      String includeFile = includeMatcher.group(1);
      String s = readTemplate(includeFile, area,topic,skins,false);
      includeMatcher.appendReplacement(result, s);
   }
   includeMatcher.appendTail(result);
   text = result.toString();


A java.lang.IllegalArgumentException was thrown.

Thanks to google, I found out what happened: There was a $ sign in the replacement string.
Now, of course this was mentioned in the Matcher javadoc but nowhere in the documentation is stated that an IllegalArgumentException will be thrown.

Just for the record: the solution I implemented was to insert the following line just before the appendReplacement call:


s=s.replaceAll("\\$","\\\\\\$")


Hope this post helps someone in the future.