diff options
author | Daniel C. Sobral <dcsobral@gmail.com> | 2012-01-25 15:34:12 -0200 |
---|---|---|
committer | Paul Phillips <paulp@improving.org> | 2012-03-23 06:57:13 -0700 |
commit | 479dd13148c380619d3e9156ef1913467decc05c (patch) | |
tree | 22394bca3237003e5c05862ff551e49bdf8a8296 /src/library/scala/util/matching/Regex.scala | |
parent | e3dec9f006ac2631281fb936c4ca206daa8fda5d (diff) | |
download | scala-479dd13148c380619d3e9156ef1913467decc05c.tar.gz scala-479dd13148c380619d3e9156ef1913467decc05c.tar.bz2 scala-479dd13148c380619d3e9156ef1913467decc05c.zip |
Document regex replacement strings behavior.
All replacement methods use dolar signs to identify groups in the
matched string, and backslashes to escape characters. Document this
behavior, and provide a method that can be used to properly quote
replacement strings when this behavior is not desired.
Closes SI-4750.
Diffstat (limited to 'src/library/scala/util/matching/Regex.scala')
-rw-r--r-- | src/library/scala/util/matching/Regex.scala | 35 |
1 files changed, 33 insertions, 2 deletions
diff --git a/src/library/scala/util/matching/Regex.scala b/src/library/scala/util/matching/Regex.scala index 2debd247b8..3f21cc9724 100644 --- a/src/library/scala/util/matching/Regex.scala +++ b/src/library/scala/util/matching/Regex.scala @@ -133,6 +133,15 @@ import java.util.regex.{ Pattern, Matcher } * * @param regex A string representing a regular expression * @param groupNames A mapping from names to indices in capture groups + * + * @define replacementString + * In the replacement String, a dollar sign (`$`) followed by a number will be + * interpreted as a reference to a group in the matched pattern, with numbers + * 1 through 9 corresponding to the first nine groups, and 0 standing for the + * whole match. Any other character is an error. The backslash (`\`) character + * will be interpreted as an escape character, and can be used to escape the + * dollar sign. One can use [[scala.util.matching.Regex]]'s `quoteReplacement` + * to automatically escape these characters. */ @SerialVersionUID(-2094783597747625537L) class Regex(regex: String, groupNames: String*) extends Serializable { @@ -277,6 +286,8 @@ class Regex(regex: String, groupNames: String*) extends Serializable { /** Replaces all matches by a string. * + * $replacementString + * * @param target The string to match * @param replacement The string that will replace each match * @return The resulting string @@ -299,6 +310,8 @@ class Regex(regex: String, groupNames: String*) extends Serializable { * val repl = datePattern replaceAllIn (text, m => m.group("month")+"/"+m.group("day")) * }}} * + * $replacementString + * * @param target The string to match. * @param replacer The function which maps a match to another string. * @return The target string after replacements. @@ -317,13 +330,15 @@ class Regex(regex: String, groupNames: String*) extends Serializable { * {{{ * import scala.util.matching.Regex._ * - * val map = Map("x" -> "a var", "y" -> "another var") + * val map = Map("x" -> "a var", "y" -> """some $ and \ signs""") * val text = "A text with variables %x, %y and %z." * val varPattern = """%(\w+)""".r - * val mapper = (m: Match) => map get (m group 1) + * val mapper = (m: Match) => map get (m group 1) map (quoteReplacement(_)) * val repl = varPattern replaceSomeIn (text, mapper) * }}} * + * $replacementString + * * @param target The string to match. * @param replacer The function which optionally maps a match to another string. * @return The target string after replacements. @@ -338,6 +353,8 @@ class Regex(regex: String, groupNames: String*) extends Serializable { /** Replaces the first match by a string. * + * $replacementString + * * @param target The string to match * @param replacement The string that will replace the match * @return The resulting string @@ -588,4 +605,18 @@ object Regex { def replace(rs: String) = matcher.appendReplacement(sb, rs) } + + /** Quotes replacement strings to be used in replacement methods. + * + * Replacement methods give special meaning to backslashes (`\`) and + * dollar signs (`$`) in replacement strings, so they are not treated + * as literals. This method escapes these characters so the resulting + * string can be used as a literal replacement representing the input + * string. + * + * @param text The string one wishes to use as literal replacement. + * @return A string that can be used to replace matches with `text`. + * @example {{{"CURRENCY".r.replaceAllIn(input, Regex quoteReplacement "US$")}}} + */ + def quoteReplacement(text: String): String = Matcher quoteReplacement text } |