@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998 Free Software Foundation, Inc. 
@c See the file elisp.texi for copying conditions.
@setfilename ../info/streams
@node Read and Print, Minibuffers, Debugging, Top
@comment  node-name,  next,  previous,  up
@c @chapter Reading and Printing Lisp Objects
@chapter Lispオブジェクトの読み取りと表示

@c   @dfn{Printing} and @dfn{reading} are the operations of converting Lisp
@c objects to textual form and vice versa.  They use the printed
@c representations and read syntax described in @ref{Lisp Data Types}.
@dfn{表示}（printing）とは
Lispオブジェクトをテキスト表現へ変換する操作であり、
@dfn{読み取り}（reading）は逆の変換操作です。
これには、@ref{Lisp Data Types}で述べた表示表現と入力構文を用います。

@c   This chapter describes the Lisp functions for reading and printing.
@c It also describes @dfn{streams}, which specify where to get the text (if
@c reading) or where to put it (if printing).
本章では、読み取りや表示を行うLisp関数について述べます。
また、（読み取るときに）テキストをどこから得たり、
（表示するときに）どこへ出すかを指定する
@dfn{ストリーム}（stream）についても述べます。

@menu
* Streams Intro::     Overview of streams, reading and printing.
* Input Streams::     Various data types that can be used as input streams.
* Input Functions::   Functions to read Lisp objects from text.
* 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.
@end menu

@node Streams Intro, Input Streams, Compilation Errors, Read and Print
@c @section Introduction to Reading and Printing
@section 読み取りと表示の概要
@c @cindex Lisp reader
@c @cindex printing
@c @cindex reading
@cindex Lispリーダ
@cindex 表示
@cindex 読み取り

@c   @dfn{Reading} a Lisp object means parsing a Lisp expression in textual
@c form and producing a corresponding Lisp object.  This is how Lisp
@c programs get into Lisp from files of Lisp code.  We call the text the
@c @dfn{read syntax} of the object.  For example, the text @samp{(a .@: 5)}
@c is the read syntax for a cons cell whose @sc{car} is @code{a} and whose
@c @sc{cdr} is the number 5.
Lispオブジェクトの@dfn{読み取り}とは、
テキスト表現のLisp式を解析して対応するLispオブジェクトを生成することを
意味します。
これにより、プログラムはLispコードのファイルからLispへ取り込まれます。
テキストをオブジェクトの@dfn{入力構文}（read syntax）と呼びます。
たとえば、テキスト@samp{(a .@: 5)}は、
@sc{car}が@code{a}であり@sc{cdr}が数5であるコンスセルの入力構文です。

@c   @dfn{Printing} a Lisp object means producing text that represents that
@c object---converting the object to its @dfn{printed representation}
@c (@pxref{Printed Representation}).  Printing the cons cell described
@c above produces the text @samp{(a .@: 5)}.
Lispオブジェクトの@dfn{表示}とは、
オブジェクトを表現するテキストを生成することを意味します。
つまり、オブジェクトをその@dfn{表示表現}
（@pxref{Printed Representation}）に変換します。
上に述べたコンスセルを表示するとテキスト@samp{(a .@: 5)}を生成します。

@c   Reading and printing are more or less inverse operations: printing the
@c object that results from reading a given piece of text often produces
@c the same text, and reading the text that results from printing an object
@c usually produces a similar-looking object.  For example, printing the
@c symbol @code{foo} produces the text @samp{foo}, and reading that text
@c returns the symbol @code{foo}.  Printing a list whose elements are
@c @code{a} and @code{b} produces the text @samp{(a b)}, and reading that
@c text produces a list (but not the same list) with elements @code{a}
@c and @code{b}.
読み取りと表示は、多かれ少なかれ、逆操作です。
与えられたテキスト断片を読み取ることで得られたオブジェクトを表示すると、
しばしば、同じテキストを生成します。
オブジェクトを表示することによって得られたテキストを読み取ると、
通常、似たようなオブジェクトを生成します。
たとえば、シンボル@code{foo}を表示するとテキスト@samp{foo}を生成し、
そのテキストを読み取るとシンボル@code{foo}が返されます。
要素が@code{a}と@code{b}であるリストを表示すると
テキスト@samp{(a b)}を生成し、
そのテキストを読み取ると
要素が@code{a}と@code{b}である（もとと同じではないが）リストを生成します。

@c   However, these two operations are not precisely inverses.  There are
@c three kinds of exceptions:
しかし、これら2つの操作は厳密には逆操作ではありません。
3種類の例外があります。

@itemize @bullet
@item
@c Printing can produce text that cannot be read.  For example, buffers,
@c windows, frames, subprocesses and markers print as text that starts
@c with @samp{#}; if you try to read this text, you get an error.  There is
@c no way to read those data types.
表示では、読み取れないテキストを生成することがある。
たとえば、バッファ、ウィンドウ、フレーム、サブプロセス、マーカは、
@samp{#}で始まるテキストとして表示されるが、
これを読み取ろうとするとエラーになる。
これらのデータ型を読み取る方法は存在しない。

@item
@c One object can have multiple textual representations.  For example,
@c @samp{1} and @samp{01} represent the same integer, and @samp{(a b)} and
@c @samp{(a .@: (b))} represent the same list.  Reading will accept any of
@c the alternatives, but printing must choose one of them.
1つのオブジェクトには複数のテキスト表現がありえる。
たとえば、@samp{1}と@samp{01}は同じ整数を表し、
@samp{(a b)}と@samp{(a .@: (b))}は同じリストを表す。
読み取りではいずれの表現も受け付けるが、
表示では1つの表現を選ぶ。

@item
@c Comments can appear at certain points in the middle of an object's
@c read sequence without affecting the result of reading it.
オブジェクトを読み取る途中にコメントが現れてもよく、
しかも読み取り結果にはまったく影響しない。
@end itemize

@node Input Streams, Input Functions, Streams Intro, Read and Print
@c @section Input Streams
@section 入力ストリーム
@c @cindex stream (for reading)
@c @cindex input stream
@cindex ストリーム（読み取り）
@cindex 入力ストリーム

@c   Most of the Lisp functions for reading text take an @dfn{input stream}
@c as an argument.  The input stream specifies where or how to get the
@c characters of the text to be read.  Here are the possible types of input
@c stream:
テキストを読み取るほとんどのLisp関数は、
@dfn{ストリーム}（stream）を引数として受け付けます。
入力ストリームは、読み取るべきテキストの文字をどこからどのように得るのかを
指定します。
入力ストリームとして使える型は以下のとおりです。

@table @asis
@item @var{buffer}
@c @cindex buffer input stream
@cindex バッファ入力ストリーム
@c The input characters are read from @var{buffer}, starting with the
@c character directly after point.  Point advances as characters are read.
入力文字はバッファ@var{buffer}のポイント直後の文字から読み取られる。
1文字読むごとにポイントを進める。

@item @var{marker}
@c @cindex marker input stream
@cindex マーカ入力ストリーム
@c The input characters are read from the buffer that @var{marker} is in,
@c starting with the character directly after the marker.  The marker
@c position advances as characters are read.  The value of point in the
@c buffer has no effect when the stream is a marker.
入力文字は、マーカ@var{marker}があるバッファの
マーカ直後の文字から読み取られる。
1文字読むごとにマーカ位置を進める。
ストリームがマーカであるときには、バッファのポイント位置は影響しない。

@item @var{string}
@c @cindex string input stream
@cindex 文字列入力ストリーム
@c The input characters are taken from @var{string}, starting at the first
@c character in the string and using as many characters as required.
入力文字は文字列@var{string}の先頭文字から必要な文字数だけ読み取られる。

@item @var{function}
@c @cindex function input stream
@cindex 関数入力ストリーム
@c The input characters are generated by @var{function}, which must support
@c two kinds of calls:
入力文字は関数@var{function}が生成する。
この関数は2種類の呼び出し方を扱える必要がある。

@itemize @bullet
@item
@c When it is called with no arguments, it should return the next character.
引数なしで呼ばれると、つぎの文字を返す。

@item
@c When it is called with one argument (always a character), @var{function}
@c should save the argument and arrange to return it on the next call.
@c This is called @dfn{unreading} the character; it happens when the Lisp
@c reader reads one character too many and wants to ``put it back where it
@c came from''.  In this case, it makes no difference what value
@c @var{function} returns.
1つの（つねに文字である）引数で呼ばれると、
@var{function}は引数を保存し、
つぎに呼ばれたときにそれを返すように準備する。
これを文字の@dfn{読み戻し}（unreading）と呼ぶ。
これは、Lispリーダが1文字多く読みすぎたので『読み取った場所へ戻し』たいときに
発生する。
このとき、@var{function}が返す値はなんでもよい。
@end itemize

@item @code{t}
@c @cindex @code{t} input stream
@cindex @code{t}入力ストリーム
@c @code{t} used as a stream means that the input is read from the
@c minibuffer.  In fact, the minibuffer is invoked once and the text
@c given by the user is made into a string that is then used as the
@c input stream.
ストリームとして@code{t}を使うと、ミニバッファから読み取ることを意味する。
実際には、ミニバッファを表示しユーザーが指定したテキストから成る文字列を作り、
それを入力ストリームとして使う。

@item @code{nil}
@c @cindex @code{nil} input stream
@cindex @code{nil}入力ストリーム
@c @code{nil} supplied as an input stream means to use the value of
@c @code{standard-input} instead; that value is the @dfn{default input
@c stream}, and must be a non-@code{nil} input stream.
入力ストリームとして@code{nil}を指定すると、
@code{standard-input}の値をかわりに使うことを意味する。
その値は@dfn{デフォルト入力ストリーム}であり、
@code{nil}以外の入力ストリームであること。

@item @var{symbol}
@c A symbol as input stream is equivalent to the symbol's function
@c definition (if any).
入力ストリームとしてのシンボルは、
そのシンボルの（あれば）関数定義と等価である。
@end table

@c   Here is an example of reading from a stream that is a buffer, showing
@c where point is located before and after:
バッファであるストリームからの読み取りの例を
読み取り前後のポイント位置を含めて示します。

@example
@group
---------- Buffer: foo ----------
This@point{} is the contents of foo.
---------- Buffer: foo ----------
@end group

@group
(read (get-buffer "foo"))
     @result{} is
@end group
@group
(read (get-buffer "foo"))
     @result{} the
@end group

@group
---------- Buffer: foo ----------
This is the@point{} contents of foo.
---------- Buffer: foo ----------
@end group
@end example

@noindent
@c Note that the first read skips a space.  Reading skips any amount of
@c whitespace preceding the significant text.
最初の読み取りでは空白を読み飛ばしていることに注意してください。
読み取りでは、意味あるテキストのまえにある白文字はいくつでも読み飛ばします。

@c   Here is an example of reading from a stream that is a marker,
@c initially positioned at the beginning of the buffer shown.  The value
@c read is the symbol @code{This}.
つぎは、マーカをストリームとして読み取る例です。
マーカの初期位置は下に示したバッファの先頭にあります。
読み取った値はシンボル@code{This}です。

@example
@group

---------- Buffer: foo ----------
This is the contents of foo.
---------- Buffer: foo ----------
@end group

@group
(setq m (set-marker (make-marker) 1 (get-buffer "foo")))
     @result{} #<marker at 1 in foo>
@end group
@group
(read m)
     @result{} This
@end group
@group
m
@c      @result{} #<marker at 5 in foo>   ;; @r{Before the first space.}
     @result{} #<marker at 5 in foo>   ;; @r{最初の空白の直前}
@end group
@end example

@c   Here we read from the contents of a string:
つぎは文字列の内容から読み取ります。

@example
@group
(read "(When in) the course")
     @result{} (When in)
@end group
@end example

@c   The following example reads from the minibuffer.  The
@c prompt is: @w{@samp{Lisp expression: }}.  (That is always the prompt
@c used when you read from the stream @code{t}.)  The user's input is shown
@c following the prompt.
以下の例は、ミニバッファから読み取ります。
プロンプトは@w{@samp{Lisp expression: }}です。
（ストリーム@code{t}から読むとつねにこのプロンプトが使われる。）
ユーザーの入力はプロンプトに続けて示してあります。

@example
@group
(read t)
     @result{} 23
---------- Buffer: Minibuffer ----------
Lisp expression: @kbd{23 @key{RET}}
---------- Buffer: Minibuffer ----------
@end group
@end example

@c   Finally, here is an example of a stream that is a function, named
@c @code{useless-stream}.  Before we use the stream, we initialize the
@c variable @code{useless-list} to a list of characters.  Then each call to
@c the function @code{useless-stream} obtains the next character in the list
@c or unreads a character by adding it to the front of the list.
最後は、@code{useless-stream}という名前の関数をストリームにした例です。
このストリームを使うまえに、
変数@code{useless-list}を文字のリストで初期化します。
そうすると、関数@code{useless-stream}を呼び出すたびに
リスト内のつぎの文字を返すか、
リストの先頭に追加して文字を読み戻します。

@example
@group
(setq useless-list (append "XY()" nil))
     @result{} (88 89 40 41)
@end group

@group
(defun useless-stream (&optional unread)
  (if unread
      (setq useless-list (cons unread useless-list))
    (prog1 (car useless-list)
           (setq useless-list (cdr useless-list)))))
     @result{} useless-stream
@end group
@end example

@noindent
@c Now we read using the stream thus constructed:
つぎのようにしてストリームを使って読み取ります。

@example
@group
(read 'useless-stream)
     @result{} XY
@end group

@group
useless-list
     @result{} (40 41)
@end group
@end example

@noindent
@c Note that the open and close parentheses remain in the list.  The Lisp
@c reader encountered the open parenthesis, decided that it ended the
@c input, and unread it.  Another attempt to read from the stream at this
@c point would read @samp{()} and return @code{nil}.
リストには開き括弧と閉じ括弧が残っていることに注意してください。
Lispリーダが開き括弧に出会うとこれで入力を終えると決定し、
それを読み戻すのです。
この時点で読み取りを試みると、
@samp{()}を読み取って@code{nil}を返します。

@defun get-file-char
@c This function is used internally as an input stream to read from the
@c input file opened by the function @code{load}.  Don't use this function
@c yourself.
この関数は、関数@code{load}で開いた入力ファイルから読み取るための
入力ストリームとして内部的に使われる。
読者はこの関数を使ってはならない。
@end defun

@node Input Functions, Output Streams, Input Streams, Read and Print
@c @section Input Functions
@section 入力関数

@c   This section describes the Lisp functions and variables that pertain
@c to reading.
本節では読み取りに関係するLisp関数や変数について述べます。

@c   In the functions below, @var{stream} stands for an input stream (see
@c the previous section).  If @var{stream} is @code{nil} or omitted, it
@c defaults to the value of @code{standard-input}.
以下の関数では、@var{stream}は入力ストリーム（前節参照）を表します。
@var{stream}が@code{nil}であったり省略すると、
@code{standard-input}の値をデフォルトにします。

@c @kindex end-of-file
@kindex end-of-file（ファイルの終り）
@c   An @code{end-of-file} error is signaled if reading encounters an
@c unterminated list, vector, or string.
読み取り中に閉じていないリストやベクトル、文字列に出会うと、
エラー@code{end-of-file}を通知します。

@defun read &optional stream
@c This function reads one textual Lisp expression from @var{stream},
@c returning it as a Lisp object.  This is the basic Lisp input function.
この関数は@var{stream}から1つのLisp式のテキスト表現を読み取り、
それをLispオブジェクトとして返す。
これは基本的なLisp入力関数である。
@end defun

@defun read-from-string string &optional start end
@c @cindex string to object
@cindex 文字列からオブジェクトへ
@c This function reads the first textual Lisp expression from the text in
@c @var{string}.  It returns a cons cell whose @sc{car} is that expression,
@c and whose @sc{cdr} is an integer giving the position of the next
@c remaining character in the string (i.e., the first one not read).
この関数は@var{string}のテキストから先頭のLisp式のテキスト表現を読み取る。
読み取った式を@sc{car}、文字列に残っているつぎの文字
（つまり読み取っていない最初の文字）の位置を表す整数を@sc{cdr}
とするコンスセルを返す。

@c If @var{start} is supplied, then reading begins at index @var{start} in
@c the string (where the first character is at index 0).  If you specify
@c @var{end}, then reading is forced to stop just before that index, as if
@c the rest of the string were not there.
@var{start}が指定してあると、文字列の@var{start}で添字付け
（先頭文字の添字は0）されるところから読み始める。
@var{end}を指定すると、その添字位置の直前で読み取りを終らせ、
文字列には残りの文字がないかのように扱う。

@c For example:
例：

@example
@group
(read-from-string "(setq x 55) (setq y 5)")
     @result{} ((setq x 55) . 11)
@end group
@group
(read-from-string "\"A short string\"")
     @result{} ("A short string" . 16)
@end group

@group
@c ;; @r{Read starting at the first character.}
;; @r{最初の文字から読み始める}
(read-from-string "(list 112)" 0)
     @result{} ((list 112) . 10)
@end group
@group
@c ;; @r{Read starting at the second character.}
;; @r{2番目の文字から読み始める}
(read-from-string "(list 112)" 1)
     @result{} (list . 5)
@end group
@group
@c ;; @r{Read starting at the seventh character,}
@c ;;   @r{and stopping at the ninth.}
;; @r{7番目の文字から読み始め、9番目の文字で読み終える}
(read-from-string "(list 112)" 6 8)
     @result{} (11 . 8)
@end group
@end example
@end defun

@defvar standard-input
@c This variable holds the default input stream---the stream that
@c @code{read} uses when the @var{stream} argument is @code{nil}.
この変数はデフォルトの入力ストリーム、
つまり、引数@var{stream}が@code{nil}である場合に@code{read}が使う
ストリームを保持する。
@end defvar

@node Output Streams, Output Functions, Input Functions, Read and Print
@c @section Output Streams
@section 出力ストリーム
@c @cindex stream (for printing)
@c @cindex output stream
@cindex ストリーム（表示）
@cindex 出力ストリーム

@c   An output stream specifies what to do with the characters produced
@c by printing.  Most print functions accept an output stream as an
@c optional argument.  Here are the possible types of output stream:
出力ストリームは表示で生成した文字群をどのように扱うかを指定します。
ほとんどの表示関数は省略可能な引数として出力ストリームを受け付けます。
出力ストリームとして使える型は以下のとおりです。

@table @asis
@item @var{buffer}
@c @cindex buffer output stream
@cindex バッファ出力ストリーム
@c The output characters are inserted into @var{buffer} at point.
@c Point advances as characters are inserted.
出力文字はバッファ@var{buffer}のポイント位置に挿入される。
文字が挿入されるたびにポイント位置は進められる。

@item @var{marker}
@c @cindex marker output stream
@cindex マーカ出力ストリーム
@c The output characters are inserted into the buffer that @var{marker}
@c points into, at the marker position.  The marker position advances as
@c characters are inserted.  The value of point in the buffer has no effect
@c on printing when the stream is a marker, and this kind of printing
@c does not move point.
出力文字はマーカ@var{marker}があるバッファのマーカ位置に挿入される。
文字を挿入するたびにマーカ位置は進められる。
ストリームがマーカであるときには、バッファのポイント位置は影響せず、
この種の表示ではポイントを移動しない。

@item @var{function}
@c @cindex function output stream
@cindex 関数出力ストリーム
@c The output characters are passed to @var{function}, which is responsible
@c for storing them away.  It is called with a single character as
@c argument, as many times as there are characters to be output, and
@c is responsible for storing the characters wherever you want to put them.
出力文字は関数@var{function}に渡され、この関数が文字の保存に責任を持つ。
1つの文字を引数として出力する文字数の回数だけ呼び出され、
読者の望む場所に文字を保存する責任を持つ。

@item @code{t}
@c @cindex @code{t} output stream
@cindex @code{t}出力ストリーム
@c The output characters are displayed in the echo area.
出力文字はエコー領域に表示される。

@item @code{nil}
@c @cindex @code{nil} output stream
@cindex @code{nil}出力ストリーム
@c @code{nil} specified as an output stream means to use the value of
@c @code{standard-output} instead; that value is the @dfn{default output
@c stream}, and must not be @code{nil}.
出力ストリームとして@code{nil}を指定すると、
@code{standard-output}の値をかわりに使うことを意味する。
その値は@dfn{デフォルト出力ストリーム}であり、
@code{nil}以外であること。

@item @var{symbol}
@c A symbol as output stream is equivalent to the symbol's function
@c definition (if any).
出力ストリームとしてのシンボルは、
そのシンボルの（あれば）関数定義と等価である。
@end table

@c   Many of the valid output streams are also valid as input streams.  The
@c difference between input and output streams is therefore more a matter
@c of how you use a Lisp object, than of different types of object.
正当な出力ストリームの多くは、入力ストリームとしても正当です。
入力ストリームと出力ストリームの違いは、
オブジェクト型の違いというよりは、
読者がLispオブジェクトをどのように使うかです。

@c   Here is an example of a buffer used as an output stream.  Point is
@c initially located as shown immediately before the @samp{h} in
@c @samp{the}.  At the end, point is located directly before that same
@c @samp{h}.
バッファを出力ストリームとして使った例を示します。
ポイントの初期位置は以下に示すように@samp{the}の@samp{h}の直前にあります。
終了後でも、ポイントは同じ@samp{h}の直前に位置しています。

@c @cindex print example
@cindex printの例
@cindex 例、print
@example
@group
---------- Buffer: foo ----------
This is t@point{}he contents of foo.
---------- Buffer: foo ----------
@end group

(print "This is the output" (get-buffer "foo"))
     @result{} "This is the output"

@group
---------- Buffer: foo ----------
This is t
"This is the output"
@point{}he contents of foo.
---------- Buffer: foo ----------
@end group
@end example

@c   Now we show a use of a marker as an output stream.  Initially, the
@c marker is in buffer @code{foo}, between the @samp{t} and the @samp{h} in
@c the word @samp{the}.  At the end, the marker has advanced over the
@c inserted text so that it remains positioned before the same @samp{h}.
@c Note that the location of point, shown in the usual fashion, has no
@c effect.
つぎは、マーカを出力ストリームとして用いた例です。
バッファ@code{foo}のマーカの初期位置は、
単語@samp{the}の@samp{t}と@samp{h}のあいだにあります。
終了後には、マーカは挿入したテキストを越えて同じ@samp{h}の直前に位置します。
ポイント位置はなんの影響もないことに注意してください。

@example
@group
---------- Buffer: foo ----------
This is the @point{}output
---------- Buffer: foo ----------
@end group

@group
(setq m (copy-marker 10))
     @result{} #<marker at 10 in foo>
@end group

@group
(print "More output for foo." m)
     @result{} "More output for foo."
@end group

@group
---------- Buffer: foo ----------
This is t
"More output for foo."
he @point{}output
---------- Buffer: foo ----------
@end group

@group
m
     @result{} #<marker at 34 in foo>
@end group
@end example

@c   The following example shows output to the echo area:
つぎは、エコー領域への出力の例です。

@example
@group
(print "Echo Area output" t)
     @result{} "Echo Area output"
---------- Echo Area ----------
"Echo Area output"
---------- Echo Area ----------
@end group
@end example

@c   Finally, we show the use of a function as an output stream.  The
@c function @code{eat-output} takes each character that it is given and
@c conses it onto the front of the list @code{last-output} (@pxref{Building
@c Lists}).  At the end, the list contains all the characters output, but
@c in reverse order.
最後は、関数を出力ストリームとして使った例を示します。
関数@code{eat-output}は与えられた文字を受け取り、
それをリスト@code{last-output}の先頭にコンスします
（@pxref{Building Lists}）。
終了後には、リストがすべての出力文字を保持していますが逆順です。

@example
@group
(setq last-output nil)
     @result{} nil
@end group

@group
(defun eat-output (c)
  (setq last-output (cons c last-output)))
     @result{} eat-output
@end group

@group
(print "This is the output" 'eat-output)
     @result{} "This is the output"
@end group

@group
last-output
     @result{} (10 34 116 117 112 116 117 111 32 101 104 
    116 32 115 105 32 115 105 104 84 34 10)
@end group
@end example

@noindent
@c Now we can put the output in the proper order by reversing the list:
リストの順番を逆にすれば正しい順序の出力になります。

@example
@group
(concat (nreverse last-output))
     @result{} "
\"This is the output\"
"
@end group
@end example

@noindent
@c Calling @code{concat} converts the list to a string so you can see its
@c contents more clearly.
@code{concat}を呼び出してリストを文字列に変換し、
内容を読みやすいようにしました。

@node Output Functions, Output Variables, Output Streams, Read and Print
@c @section Output Functions
@section 出力関数

@c   This section describes the Lisp functions for printing Lisp
@c objects---converting objects into their printed representation.
本節ではLispオブジェクトを表示する、
つまり、オブジェクトを表示表現に変換するLisp関数について述べます。

@c @cindex @samp{"} in printing
@c @cindex @samp{\} in printing
@c @cindex quoting characters in printing
@c @cindex escape characters in printing
@cindex @samp{"}、表示
@cindex @samp{\}、表示
@cindex クォート文字、表示
@cindex エスケープ文字、表示
@c   Some of the Emacs printing functions add quoting characters to the
@c output when necessary so that it can be read properly.  The quoting
@c characters used are @samp{"} and @samp{\}; they distinguish strings from
@c symbols, and prevent punctuation characters in strings and symbols from
@c being taken as delimiters when reading.  @xref{Printed Representation},
@c for full details.  You specify quoting or no quoting by the choice of
@c printing function.
Emacsの表示関数のなかには、正しく読み取れるように
クォート文字を出力に追加するものがあります。
使用されるクォート文字は@samp{"}と@samp{\}です。
これらは、文字列とシンボルを区別したり、
文字列やシンボル内の句読点文字を読み取るときに区切り文字として扱うこと
を防ぎます。
詳しくは@xref{Printed Representation}。
出力関数を選べば、クォートのありなしを指定できます。

@c   If the text is to be read back into Lisp, then you should print with
@c quoting characters to avoid ambiguity.  Likewise, if the purpose is to
@c describe a Lisp object clearly for a Lisp programmer.  However, if the
@c purpose of the output is to look nice for humans, then it is usually
@c better to print without quoting.
テキストをLispシステムへ読み取る意図がある場合には、
曖昧さを避けるためにクォート文字付きで表示するべきです。
Lispプログラマに対してLispオブジェクトを明確に記述する場合も同様です。
しかし、人間向けの見やすい出力が目的であれば、
クォートせずに表示するのが普通はよいでしょう。

@c   Lisp objects can refer to themselves.  Printing a self-referential
@c object in the normal way would require an infinite amount of text, and
@c the attempt could cause infinite recursion.  Emacs detects such
@c recursion and prints @samp{#@var{level}} instead of recursively printing
@c an object already being printed.  For example, here @samp{#0} indicates
@c a recursive reference to the object at level 0 of the current print
@c operation:
Lispオブジェクトはそれ自身を参照できます。
自己参照しているオブジェクトを普通の方法で表示するには
無限のテキストが必要であり、
そのような試みは無限再帰をもたらします。
Emacsはそのような再帰を検出し、
すでに表示したオブジェクトを再帰的に表示するかわりに
@samp{#@var{level}}を表示します。
たとえば、@samp{#0}は、現在の表示操作においてレベル0のオブジェクトを
再帰的に参照することを示します。

@example
(setq foo (list nil))
     @result{} (nil)
(setcar foo foo)
     @result{} (#0)
@end example

@c   In the functions below, @var{stream} stands for an output stream.
@c (See the previous section for a description of output streams.)  If
@c @var{stream} is @code{nil} or omitted, it defaults to the value of
@c @code{standard-output}.
以下の関数では、@var{stream}は出力ストリームを表します。
（出力ストリームについては前節を参照。）
@var{stream}が@code{nil}であったり省略すると、
@code{standard-output}の値をデフォルトにします。

@defun print object &optional stream
@c @cindex Lisp printer
@cindex Lispプリンタ
@c The @code{print} function is a convenient way of printing.  It outputs
@c the printed representation of @var{object} to @var{stream}, printing in
@c addition one newline before @var{object} and another after it.  Quoting
@c characters are used.  @code{print} returns @var{object}.  For example:
関数@code{print}は便利な表示方法である。
オブジェクト@var{object}の表示表現を
ストリーム@var{stream}に出力し、
@var{object}の前後に改行を1つずつ表示する。
クォート文字を使う。
@code{print}は@var{object}を返す。
たとえばつぎのとおり。

@example
@group
(progn (print 'The\ cat\ in)
       (print "the hat")
       (print " came back"))
     @print{} 
     @print{} The\ cat\ in
     @print{} 
     @print{} "the hat"
     @print{} 
     @print{} " came back"
     @print{} 
     @result{} " came back"
@end group
@end example
@end defun

@defun prin1 object &optional stream
@c This function outputs the printed representation of @var{object} to
@c @var{stream}.  It does not print newlines to separate output as
@c @code{print} does, but it does use quoting characters just like
@c @code{print}.  It returns @var{object}.
この関数はオブジェクト@var{object}の表示表現を
ストリーム@var{stream}に出力する。
@code{print}のようには出力を区切る改行を表示しないが、
@code{print}と同様にクォート文字を用いる。
@var{object}を返す。

@example
@group
(progn (prin1 'The\ cat\ in) 
       (prin1 "the hat") 
       (prin1 " came back"))
     @print{} The\ cat\ in"the hat"" came back"
     @result{} " came back"
@end group
@end example
@end defun

@defun princ object &optional stream
@c This function outputs the printed representation of @var{object} to
@c @var{stream}.  It returns @var{object}.
この関数はオブジェクト@var{object}の表示表現を
ストリーム@var{stream}に出力する。
@var{object}を返す。

@c This function is intended to produce output that is readable by people,
@c not by @code{read}, so it doesn't insert quoting characters and doesn't
@c put double-quotes around the contents of strings.  It does not add any
@c spacing between calls.
この関数は、@code{read}ではなく人が読みやすい出力を意図しており、
クォート文字を挿入せず、文字列を囲むダブルクォートも出力しない。
空白も追加しない。

@example
@group
(progn
  (princ 'The\ cat)
  (princ " in the \"hat\""))
     @print{} The cat in the "hat"
     @result{} " in the \"hat\""
@end group
@end example
@end defun

@defun terpri &optional stream
@c @cindex newline in print
@cindex 改行、表示
@c This function outputs a newline to @var{stream}.  The name stands
@c for ``terminate print''.
この関数はストリーム@var{stream}に改行を出力する。
関数名は『terminate print』の略。
@end defun

@defun write-char character &optional stream
@c This function outputs @var{character} to @var{stream}.  It returns
@c @var{character}.
この関数は文字@var{character}をストリーム@var{stream}へ出力する。
@var{character}を返す。
@end defun

@defun prin1-to-string object &optional noescape
@c @cindex object to string
@cindex オブジェクトから文字列へ
@c This function returns a string containing the text that @code{prin1}
@c would have printed for the same argument.
この関数は同じ引数に対して@code{prin1}が表示するであろう
テキストから成る文字列を返す。

@example
@group
(prin1-to-string 'foo)
     @result{} "foo"
@end group
@group
(prin1-to-string (mark-marker))
     @result{} "#<marker at 2773 in strings.texi>"
@end group
@end example

@c If @var{noescape} is non-@code{nil}, that inhibits use of quoting
@c characters in the output.  (This argument is supported in Emacs versions
@c 19 and later.)
@var{noescape}が@code{nil}以外であると、
出力にはクォート文字を使わない。
（この引数は、Emacs 19版以降で使える。）

@example
@group
(prin1-to-string "foo")
     @result{} "\"foo\""
@end group
@group
(prin1-to-string "foo" t)
     @result{} "foo"
@end group
@end example

@c See @code{format}, in @ref{String Conversion}, for other ways to obtain
@c the printed representation of a Lisp object as a string.
文字列としてのLispオブジェクトの表示表現を得るための別の方法については、
@ref{String Conversion}の@code{format}を参照。
@end defun

@defmac with-output-to-string body...
@tindex with-output-to-string
@c This macro executes the @var{body} forms with @code{standard-output} set
@c up to feed output into a string.  Then it returns that string.
このマクロは、@code{standard-output}を文字列への出力と設定して
フォーム@var{body}を実行する。
そして、その文字列を返す。

@c For example, if the current buffer name is @samp{foo},
たとえば、カレントバッファの名前が@samp{foo}であると

@example
(with-output-to-string
  (princ "The buffer is ")
  (princ (buffer-name)))
@end example

@noindent
@c returns @code{"The buffer is foo"}.
は@code{"The buffer is foo"}を返す。
@end defmac

@node Output Variables,  , Output Functions, Read and Print
@c @section Variables Affecting Output
@section 出力に影響する変数

@defvar standard-output
@c The value of this variable is the default output stream---the stream
@c that print functions use when the @var{stream} argument is @code{nil}.
この変数の値はデフォルトの出力ストリーム、つまり、
引数@var{stream}が@code{nil}の場合に表示関数が用いるストリーム。
@end defvar

@defvar print-escape-newlines
@c @cindex @samp{\n} in print
@c @cindex escape characters
@cindex @samp{\n}、表示
@cindex エスケープ文字
@c If this variable is non-@code{nil}, then newline characters in strings
@c are printed as @samp{\n} and formfeeds are printed as @samp{\f}.
@c Normally these characters are printed as actual newlines and formfeeds.
この変数が@code{nil}以外であると、
文字列内の改行文字を@samp{\n}、ページ送り文字を@samp{\f}と表示する。
通常、これらの文字は実際の改行やページ送りとして表示される。

@c This variable affects the print functions @code{prin1} and @code{print}
@c that print with quoting.  It does not affect @code{princ}.  Here is an
@c example using @code{prin1}:
この変数は、クォート付きで表示する表示関数@code{prin1}や
@code{print}に影響を与える。
@code{princ}には影響しない。
@code{prin1}を用いた例を示す。

@example
@group
(prin1 "a\nb")
     @print{} "a
     @print{} b"
     @result{} "a
b"
@end group

@group
(let ((print-escape-newlines t))
  (prin1 "a\nb"))
     @print{} "a\nb"
     @result{} "a
b"
@end group
@end example

@noindent
@c In the second expression, the local binding of
@c @code{print-escape-newlines} is in effect during the call to
@c @code{prin1}, but not during the printing of the result.
2番目の式では、@code{prin1}の呼び出し中には
@code{print-escape-newlines}のローカル束縛が有効であるが、
結果を表示するときには有効ではない。
@end defvar

@tindex print-escape-nonascii
@defvar print-escape-nonascii
@c If this variable is non-@code{nil}, then unibyte non-@sc{ASCII}
@c characters in strings are unconditionally printed as backslash sequences
@c by the print functions @code{prin1} and @code{print} that print with
@c quoting.
この変数が@code{nil}以外であると、
クォート付きで表示する出力関数@code{prin1}や@code{print}は、
文字列内のユニバイト非@sc{ASCII}文字を無条件で
バックスラッシュ列として表示する。

@c Those functions also use backslash sequences for unibyte non-@sc{ASCII}
@c characters, regardless of the value of this variable, when the output
@c stream is a multibyte buffer or a marker pointing into one.
これらの関数は、出力ストリームがマルチバイトバッファや
マルチバイトバッファのマーク位置であると、
この変数の値に関係なくユニバイト非@sc{ASCII}文字に対して
バックスラッシュ列を用いる。
@end defvar

@tindex print-escape-multibyte
@defvar print-escape-multibyte
@c If this variable is non-@code{nil}, then multibyte non-@sc{ASCII}
@c characters in strings are unconditionally printed as backslash sequences
@c by the print functions @code{prin1} and @code{print} that print with
@c quoting.
この変数が@code{nil}以外であると、
クォート付きで表示する表示関数@code{prin1}や@code{print}は、
文字列内のマルチバイト非@sc{ASCII}文字を無条件で
バックスラッシュ列として表示する。

@c Those functions also use backslash sequences for multibyte
@c non-@sc{ASCII} characters, regardless of the value of this variable,
@c when the output stream is a unibyte buffer or a marker pointing into
@c one.
これらの関数は、出力ストリームがユニバイトバッファや
ユニバイトバッファのマーク位置であると、
この変数の値に関係なくマルチバイト非@sc{ASCII}文字に対して
バックスラッシュ列を用いる。
@end defvar

@defvar print-length
@c @cindex printing limits
@cindex 表示制限
@c The value of this variable is the maximum number of elements to print in
@c any list, vector or bool-vector.  If an object being printed has more
@c than this many elements, it is abbreviated with an ellipsis.
この変数の値は、任意のリスト、ベクトル、ブールベクトルを表示するときの
最大要素数である。
表示するオブジェクトがこれより多くの要素を持つと、
「…」で省略する。

@c If the value is @code{nil} (the default), then there is no limit.
値が@code{nil}（デフォルト）であると無制限。

@example
@group
(setq print-length 2)
     @result{} 2
@end group
@group
(print '(1 2 3 4 5))
     @print{} (1 2 ...)
     @result{} (1 2 ...)
@end group
@end example
@end defvar

@defvar print-level
@c The value of this variable is the maximum depth of nesting of
@c parentheses and brackets when printed.  Any list or vector at a depth
@c exceeding this limit is abbreviated with an ellipsis.  A value of
@c @code{nil} (which is the default) means no limit.
この変数の値は、表示するときの括弧や角括弧の入れ子の最大の深さ。
この制限を越える任意のリストやベクトルは「…」で省略する。
値が@code{nil}（デフォルト）であると無制限。
@end defvar
