(lispref.info)Output Functions


Next: Output Variables Prev: Output Streams Up: Streams

Output Functions
================

   This section describes the Lisp functions for printing Lisp objects.

   Some of the Emacs printing functions add quoting characters to the
output when necessary so that it can be read properly.  The quoting
characters used are `\' and `"'; they are used to distinguish strings
from symbols, and to prevent punctuation characters in strings and
symbols from being taken as delimiters.  Note: Printed
Representation, for full details.  You specify quoting or no quoting
by the choice of printing function.

   If the text is to be read back into Lisp, then it is best to print
with quoting characters to avoid ambiguity.  Likewise, if the purpose is
to describe a Lisp object clearly for a Lisp programmer.  However, if
the purpose of the output is to look nice for humans, then it is better
to print without quoting.

   Printing a self-referent Lisp object requires an infinite amount of
text.  In certain cases, trying to produce this text leads to a stack
overflow.  Emacs detects such recursion and prints `#LEVEL' instead of
recursively printing an object already being printed.  For example,
here `#0' indicates a recursive reference to the object at level 0 of
the current print operation:

     (setq foo (list nil))
          => (nil)
     (setcar foo foo)
          => (#0)

   In the functions below, STREAM stands for an output stream.  (See
the previous section for a description of output streams.)  If STREAM
is `nil' or omitted, it defaults to the value of `standard-output'.

 - Function: print OBJECT &optional STREAM
     The `print' is a convenient way of printing.  It outputs the
     printed representation of OBJECT to STREAM, printing in addition
     one newline before OBJECT and another after it.  Quoting
     characters are used.  `print' returns OBJECT.  For example:

          (progn (print 'The\ cat\ in)
                 (print "the hat")
                 (print " came back"))
               -|
               -| The\ cat\ in
               -|
               -| "the hat"
               -|
               -| " came back"
               -|
               => " came back"

 - Function: prin1 OBJECT &optional STREAM
     This function outputs the printed representation of OBJECT to
     STREAM.  It does not print any spaces or newlines to separate
     output as `print' does, but it does use quoting characters just
     like `print'.  It returns OBJECT.

          (progn (prin1 'The\ cat\ in)
                 (prin1 "the hat")
                 (prin1 " came back"))
               -| The\ cat\ in"the hat"" came back"
               => " came back"

 - Function: princ OBJECT &optional STREAM
     This function outputs the printed representation of OBJECT to
     STREAM.  It returns OBJECT.

     This function is intended to produce output that is readable by
     people, not by `read', so quoting characters are not used and
     double-quotes are not printed around the contents of strings.  It
     does not add any spacing between calls.

          (progn
            (princ 'The\ cat)
            (princ " in the \"hat\""))
               -| The cat in the "hat"
               => " in the \"hat\""

 - Function: terpri &optional STREAM
     This function outputs a newline to STREAM.  The name stands for
     "terminate print".

 - Function: write-char CHARACTER &optional STREAM
     This function outputs CHARACTER to STREAM.  It returns CHARACTER.

 - Function: prin1-to-string OBJECT &optional NOESCAPE
     This function returns a string containing the text that `prin1'
     would have printed for the same argument.

          (prin1-to-string 'foo)
               => "foo"
          (prin1-to-string (mark-marker))
               => "#<marker at 2773 in strings.texi>"

     If NOESCAPE is non-`nil', that inhibits use of quoting characters
     in the output.  (This argument is supported in Emacs versions 19
     and later.)

          (prin1-to-string "foo")
               => "\"foo\""
          (prin1-to-string "foo" t)
               => "foo"

     See `format', in Note: String Conversion, for other ways to
     obtain the printed representation of a Lisp object as a string.


automatically generated by info2www