Document the reconvert module.

3 files changed, 83 insertions, 0 deletions

diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex
index 78556bf..1350dd9 100644
--- a/Doc/lib/lib.tex
+++ b/Doc/lib/lib.tex
@@ -106,6 +106,7 @@ and how to embed it in other applications.
 \input{libstrings}              % String Services
 \input{libstring}
 \input{libre}
+\input{libreconvert}
 \input{libstruct}
 \input{libdifflib}
 \input{libfpformat}
diff --git a/Doc/lib/libreconvert.tex b/Doc/lib/libreconvert.tex
new file mode 100644
index 0000000..29c6e52
--- /dev/null
+++ b/Doc/lib/libreconvert.tex
@@ -0,0 +1,80 @@
+\section{\module{reconvert} ---
+         Convert regular expressions from regex to re form}
+\declaremodule{standard}{reconvert}
+\moduleauthor{Andrew M. Kuchling}{amk@amk.ca}
+\sectionauthor{Skip Montanaro}{skip@pobox.com}
+
+
+\modulesynopsis{Convert regex-, emacs- or sed-style regular expressions
+to re-style syntax.}
+
+
+This module provides a facility to convert regular expressions from the
+syntax used by the deprecated \module{regex} module to those used by the
+newer \module{re} module.  Because of similarity between the regular
+expression syntax of \code{sed(1)} and \code{emacs(1)} and the
+\module{regex} module, it is also helpful to convert patterns written for
+those tools to \module{re} patterns.
+
+When used as a script, a Python string literal (or any other expression
+evaluating to a string) is read from stdin, and the translated expression is
+written to stdout as a string literal.  Unless stdout is a tty, no trailing
+newline is written to stdout.  This is done so that it can be used with
+Emacs \code{C-U M-|} (shell-command-on-region) which filters the region
+through the shell command.
+
+\begin{seealso}
+  \seetitle{Mastering Regular Expressions}{Book on regular expressions
+            by Jeffrey Friedl, published by O'Reilly.  The second 
+            edition of the book no longer covers Python at all, 
+            but the first edition covered writing good regular expression
+            patterns in great detail.}
+\end{seealso}
+
+\subsection{Module Contents}
+\nodename{Contents of Module reconvert}
+
+The module defines two functions and a handful of constants.
+
+\begin{funcdesc}{convert}{pattern\optional{, syntax=None}}
+ Convert a \var{pattern} representing a \module{regex}-stype regular
+ expression into a \module{re}-style regular expression.  The optional
+ \var{syntax} parameter is a bitwise-or'd set of flags that control what
+ constructs are converted.  See below for a description of the various
+ constants.
+\end{funcdesc}
+
+\begin{funcdesc}{quote}{s\optional{, quote=None}}
+ Convert a string object to a quoted string literal.
+
+ This is similar to \function{repr} but will return a "raw" string (r'...'
+ or r"...") when the string contains backslashes, instead of doubling all
+ backslashes.  The resulting string does not always evaluate to the same
+ string as the original; however it will do just the right thing when passed
+ into re.compile().
+
+ The optional second argument forces the string quote; it must be a single
+ character which is a valid Python string quote.  Note that prior to Python
+ 2.5 this would not accept triple-quoted string delimiters.
+\end{funcdesc}
+
+\begin{datadesc}{RE_NO_BK_PARENS}
+ Suppress paren conversion.  This should be omitted when converting
+ \code{sed}-style or \code{emacs}-style regular expressions.
+\end{datadesc}
+
+\begin{datadesc}{RE_NO_BK_VBAR}
+ Suppress vertical bar conversion.  This should be omitted when converting
+ \code{sed}-style or \code{emacs}-style regular expressions.
+\end{datadesc}
+
+\begin{datadesc}{RE_BK_PLUS_QM}
+ Enable conversion of \code{+} and \code{?} characters.  This should be
+ added to the \var{syntax} arg of \function{convert} when converting
+ \code{sed}-style regular expressions and omitted when converting
+ \code{emacs}-style regular expressions.
+\end{datadesc}
+
+\begin{datadesc}{RE_NEWLINE_OR}
+ When set, newline characters are replaced by \code{|}.
+\end{datadesc}
diff --git a/Misc/NEWS b/Misc/NEWS
index 63081b0..035bacf 100644
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -124,6 +124,8 @@ Library
 - Bug #1083110: ``zlib.decompress.flush()`` would segfault if called immediately
   after creating the object, without any intervening ``.decompress()`` calls.
 
+- The reconvert.quote function can now emit triple-quoted strings.  The
+  reconvert module now has some simple documentation.
 
 Build
 -----