Add OVERRIDES argument to prin1/prin1-to-string

* doc/lispref/streams.texi (Output Functions): Document it.
(Output Overrides): New node.

* src/process.c (Faccept_process_output):
* src/print.c (debug_print, print_error_message):
* src/pdumper.c (print_paths_to_root_1, decode_emacs_reloc):
* src/lread.c (readevalloop):
* src/eval.c (internal_lisp_condition_case):
* src/editfns.c (styled_format): Adjust prin1/prin1-to-string
callers.

* src/print.c (Fprin1): Take an OVERRIDES parameter.
(print_bind_overrides, print_bind_all_defaults): New functions.
(Fprin1_to_string): Take an OVERRIDES parameter.

2 files changed, 102 insertions, 2 deletions

diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index 968a2790e21..a3d1d804086 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -739,6 +739,7 @@ Reading and Printing Lisp Objects
 * Output Functions::        Functions to print Lisp objects as text.
 * Output Variables::        Variables that control what the printing
                               functions do.
+* Output Overrides::        Overriding output variables.
 
 Minibuffers
 
diff --git a/doc/lispref/streams.texi b/doc/lispref/streams.texi
index 781a50f5c49..d805d087447 100644
--- a/doc/lispref/streams.texi
+++ b/doc/lispref/streams.texi
@@ -21,6 +21,7 @@ reading) or where to put it (if printing).
 * Output Streams::    Various data types that can be used as output streams.
 * Output Functions::  Functions to print Lisp objects as text.
 * Output Variables::  Variables that control what the printing functions do.
+* Output Overrides::  Overriding output variables.
 @end menu
 
 @node Streams Intro
@@ -634,7 +635,7 @@ characters are used.  @code{print} returns @var{object}.  For example:
 @end example
 @end defun
 
-@defun prin1 object &optional stream
+@defun prin1 object &optional stream overrides
 This function outputs the printed representation of @var{object} to
 @var{stream}.  It does not print newlines to separate output as
 @code{print} does, but it does use quoting characters just like
@@ -649,6 +650,10 @@ This function outputs the printed representation of @var{object} to
      @result{} " came back"
 @end group
 @end example
+
+If @var{overrides} is non-@code{nil}, it should either be @code{t}
+(which tells @code{prin1} to use the defaults for all printer related
+variables), or a list of settings.  @xref{Output Overrides} for details.
 @end defun
 
 @defun princ object &optional stream
@@ -694,7 +699,7 @@ newline character first, which enables you to display incomplete
 lines.
 @end defun
 
-@defun prin1-to-string object &optional noescape
+@defun prin1-to-string object &optional noescape overrides
 @cindex object to string
 This function returns a string containing the text that @code{prin1}
 would have printed for the same argument.
@@ -708,6 +713,10 @@ would have printed for the same argument.
 (prin1-to-string (mark-marker))
      @result{} "#<marker at 2773 in strings.texi>"
 @end group
+
+If @var{overrides} is non-@code{nil}, it should either be @code{t}
+(which tells @code{prin1} to use the defaults for all printer related
+variables), or a list of settings.  @xref{Output Overrides} for details.
 @end example
 
 If @var{noescape} is non-@code{nil}, that inhibits use of quoting
@@ -971,3 +980,93 @@ Letter, Number, Punctuation, Symbol and Private-use
 (@pxref{Character Properties}), as well as the control characters
 having their own escape syntax such as newline.
 @end defvar
+
+@node Output Overrides
+@section Overriding Output Variables
+
+@xref{Output Functions} lists the numerous variables that controls how
+the Emacs Lisp printer outputs data.  These are generally available
+for users to change, but sometimes you want to output data in the
+default format.  For instance, if you're storing Emacs Lisp data in a
+file, you don't want that data to be shortened by a
+@code{print-length} setting.
+
+The @code{prin1} and @code{prin1-to-string} functions therefore have
+an optional @var{overrides} argument.  This variable can either be
+@code{t} (which means that all printing variables should be the
+default values), or a list of settings.  Each element in the list can
+either be @code{t} (which means ``reset to defaults'') or a pair where
+the @code{car} is a symbol, and the @code{cdr} is the value.
+
+For instance, this prints using nothing but defaults:
+
+@lisp
+(prin1 object nil t)
+@end lisp
+
+This prints @var{object} using the current printing settings, but
+overrides @code{print-length} to 5:
+
+@lisp
+(prin1 object nil '((length . 5)))
+@end lisp
+
+And finally, this prints @var{object} using only default settings, but
+overrides @code{print-length} to 5:
+
+@lisp
+(prin1 object nil '(t (length . 5)))
+@end lisp
+
+Below is a list of symbols that can be used, and which variables they
+map to:
+
+@table @code
+@item length
+This overrides @code{print-length}.
+
+@item level
+This overrides @code{print-level}.
+
+@item circle
+This overrides @code{print-circle}.
+
+@item quoted
+This overrides @code{print-quoted}.
+
+@item escape-newlines
+This overrides @code{print-escape-newlines}.
+
+@item escape-control-characters
+This overrides @code{print-escape-control-characters}.
+
+@item escape-nonascii
+This overrides @code{print-escape-nonascii}.
+
+@item escape-multibyte
+This overrides @code{print-escape-multibyte}.
+
+@item charset-text-property
+This overrides @code{print-charset-text-property}.
+
+@item unreadeable-function
+This overrides @code{print-unreadable-function}.
+
+@item gensym
+This overrides @code{print-gensym}.
+
+@item continuous-numbering
+This overrides @code{print-continuous-numbering}.
+
+@item number-table
+This overrides @code{print-number-table}.
+
+@item float-format
+This overrides @code{float-output-format}.
+
+@item integers-as-characters
+This overrides @code{print-integers-as-characters}.
+@end table
+
+In the future, more overrides may be offered that do not map directly
+to a variable, but can only be used via this parameter.