Info Catalog elisp: Output Streams elisp: Read and Print elisp: Output Variables

elisp: Output Functions

 
 18.5 Output Functions
 =====================
 
 This section describes the Lisp functions for printing Lisp
 objects—converting objects into their printed representation.
 
    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 distinguish strings from symbols,
 and prevent punctuation characters in strings and symbols from being
 taken as delimiters when reading.  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 you should 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 usually
 better to print without quoting.
 
    Lisp objects can refer to themselves.  Printing a self-referential
 object in the normal way would require an infinite amount of text, and
 the attempt could cause infinite recursion.  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’ function 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 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 it doesn’t insert quoting characters and
      doesn’t put double-quotes 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 ensure
      This function outputs a newline to STREAM.  The name stands for
      “terminate print”.  If ENSURE is non-‘nil’ no newline is printed if
      STREAM is already at the beginning of a line.  Note in this case
      STREAM can not be a function and an error is signalled if it is.
      This function returns ‘t’ if a newline is printed.
 
  -- 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 Formatting Strings, for other ways to
      obtain the printed representation of a Lisp object as a string.
 
  -- Macro: with-output-to-string body...
      This macro executes the BODY forms with ‘standard-output’ set up to
      feed output into a string.  Then it returns that string.
 
      For example, if the current buffer name is ‘foo’,
 
           (with-output-to-string
             (princ "The buffer is ")
             (princ (buffer-name)))
 
      returns ‘"The buffer is foo"’.
 
  -- Function: pp object &optional stream
      This function outputs OBJECT to STREAM, just like ‘prin1’, but does
      it in a prettier way.  That is, it’ll indent and fill the object to
      make it more readable for humans.
 
    If you need to use binary I/O in batch mode, e.g., use the functions
 described in this section to write out arbitrary binary data or avoid
 conversion of newlines on non-Posix hosts, see set-binary-mode
 Input Functions.
 

Info Catalog elisp: Output Streams elisp: Read and Print elisp: Output Variables