npt-japanese

% Function OPEN

Function OPEN

Function OPEN

構文

open filespec &key direction element-type if-exists if-does-not-exist external-format
=> stream

引数と戻り値

filespec - パス名指定子
direction - :input, :output, :io, :probeのどれか。デフォルトは:input。
element-type - characterとして認識可能なサブタイプの型指定子か、整数の有限値として認識可能なサブタイプの型指定子か、シンボルであるsigned-byte, unsigned-byteのうちのひとつか、あるいは:default。デフォルトはcharacter。
if-exists - :error, :new-version, :rename, :rename-and-delete, :overwrite, :append, :supersede, nilのどれか。デフォルトは、filespecのバージョンの要素が:newestのときは:new-version、それ以外のときは:error。
if-does-not-exist - :error, :create, nilのどれか。デフォルトは、もしdirectionが:inputであるか if-existsが:overwriteか:appendのときは:error。 directionが:outputか:ioでありかつ if-existsが:overwriteでも:appendでもないときは:create。 directionが:probeのときはnil。
external-format - 外部ファイルフォーマット指定子。デフォルトは:default。
stream - ファイルストリームか、nil

定義

openは、filespecによって指定されたファイルと接続したファイルストリームを作成し、開き、返却します。 filespecは開かれるファイルの名前です。もしfilespec指定子がストリームのとき、そのストリームは最初に閉じられたり、あるいはその他の影響を受けることはありません。

openのキーワード引数は、返却されるファイルストリームの特性と、どのようにエラーを扱うかを指定します。

directionが:inputか:probeのときか、あるいはif-existsが:new-versionではなく同時にfilespecのバージョン要素が:newestのときは、開かれたファイルはすでにファイルシステム内に存在しているので、そのバージョンはファイルシステム内の、他のパス名の要素がfilespecと同じである他のどんなファイルのものより大きなバージョンになります。

実装はopenの全てのキーワードオプションを識別し、ホストオペレーティングシステムの構造上で適切な処理を行うよう要求されます。例えば、もしファイルシステムがファイルのバージョンの区別をサポートせず、さらに削除と抹消（deletingとexpunging）の表記を区別できないとき、 :new-versionは:renameか:supersedeと同じように扱われ、 :rename-and-deleteは:supersedeと同じように扱われることが考えられます。

:direction
- directionで使用可能な値を示します。これは作成されるstreamの性質に対してどのような影響があるかを指定します。
- :input
  - 入力ファイルストリームの生成を行います。
- :output
  - 出力ファイルストリームの生成を行います。
- :io
  - 双方向ファイルストリームの生成を行います。
- 「非方向性」ファイルストリームの生成を行います。この効果は、ファイルストリームが生成されてから、 openによって返却される前にクローズされます。
:element-type
- element-typeはファイルストリームのデータの単位を指定します。もし:defaultが指定されたとき、その単位はファイルシステムによって決まり、可能であればファイルを元に決定されます。
:if-exists
- if-existsは、directionが:outputか:ioであり、 filespecの名前のファイルがすでに存在しているときに実行する動作を指定します。もしdirectionが:inputか、指定されなかったか、あるいは:probeのとき、 if-existsは無視されます。 openの結果はif-existsの次の値によって変更されます。
- :error
  - 型file-errorのエラーが通知されます。
- :new-version
  - 新しいファイルがもっとも大きなバージョン値で生成されます。
- :rename
  - 存在しているファイルを何か他の名前に変更してから新しいファイルを作成します。
- :rename-and-delete
  - 存在しているファイルを何か他の名前に変更し、それを抹消expungingではなく削除deletingし、そして新しいファイルを生成します。
- :overwrite
  - ストリームの出力操作において、存在するファイルを破壊的に修正します。 directionが:ioであり、ファイルが読み込みと書き込みの両方を許可する双方向モードとして開かれたとき、そのファイルポインターは初期状態ではファイルの最初に位置します。しかしファイルが開かれたときに、ファイルは長さ0として前方に切り捨てられることはありません。
- :append
  - ストリームの出力操作において、存在するファイルを破壊的に修正します。そのファイルポインターは初期状態ではファイルの最後に位置します。
    directionが:ioのとき、ファイルが読み込みと書き込みの両方を許可する双方向モードとして開かれます。
- :supersede
  - 存在しているファイルは別のものに変えられます。つまり同じ名前の新しいファイルが古いファイルとして作成さえれます。もし可能であれば、実装は新しいストリームを閉じるまで古いファイルを破壊するべきではありません。
- nil
  - ファイルもストリームも生成されません。代わりに失敗を示すnilが返却されます。
:if-does-not-exist
- if-does-not-existsは、 filespecの名前のファイルがまだ存在してないときに実行する動作を指定します。 openの結果はif-does-not-existsの次の値によって変更されます。
- :error
  - 型file-errorのエラーが通知されます。
- :create
  - 空のファイルが作成されます。ファイルがすでに存在しているときは処理が継続されますが、 if-existsの方向による操作によっては処理しません。
- nil
  - ファイルもストリームも生成されません。代わりに失敗を示すnilが返却されます。
:external-format
- このオプションはファイルの外部ファイルフォーマットを選択します。このオプションの標準の値はただひとつ:defaultですが、実装は追加の外部ファイルフォーマットを定義することが許されており、 stream-external-formatによって返却される実装依存の値を仕様に適合したプログラムで使用することができます。
  
  external-formatは、characterのサブタイプである要素の型のファイルストリームに対して意味があります。このオプションは、これらの値に意味を持たないストリームに対しては無視されます。しかし実装は意味を持つ他の要素の型を定義することができます。もし指定した外部ファイルフォーマットによって表現できない文字を書き込んだ時の結果は指定されていません。

ファイルが開かれたとき、ファイルストリームは Lisp環境においてファイルシステムに仕える代理人として構築され、ファイルストリームへの操作は対象のファイルシステム内の指定したファイル上の操作として反映されます。

ファイルはopenによって、削除、名前の変更、破壊的な修正が行われます。

openとパス名の関係については、19.2.3. パス名のマージをご確認ください。

例文

(open filespec :direction :probe)  =>  #<Closed Probe File Stream...>
(setq q (merge-pathnames (user-homedir-pathname) "test"))
=>  #<PATHNAME :HOST NIL :DEVICE device-name :DIRECTORY directory-name
   :NAME "test" :TYPE NIL :VERSION :NEWEST>
(open filespec :if-does-not-exist :create) =>  #<Input File Stream...>
(setq s (open filespec :direction :probe)) =>  #<Closed Probe File Stream...>
(truename s) =>  #<PATHNAME :HOST NIL :DEVICE device-name :DIRECTORY
   directory-name :NAME filespec :TYPE extension :VERSION 1>
(open s :direction :output :if-exists nil) =>  NIL 

影響

ホストコンピューターのファイルシステムの性質と状態

例外

if-existsが:errorのとき（上記のリストにあるif-existsの意味の制約に従い）、型file-errorのエラーが発生します。

if-does-not-existが:errorのとき（上記のリストにあるif-does-not-existの意味の制約に従い）、型file-errorのエラーが発生します。

ここで指定された何かの挙動において実装が何らかのオプションを処理できなかったときは、型errorのエラーが通知されるかもしれません。

(wild-pathname-p filespec)がtrueのとき、型file-errorのエラーが発生します。

実装がexternal-formatを解釈できなかったときは、型errorのエラーが発生します。

現在存在する様々なファイルシステムは大きく異なった機能を持っており、あるファイルシステムの様相はここで定義された仕様の範囲を超えています。実装はこれらの全てのオプションについて規定された動作を正確にサポートできないかもしれません。実装はこれらの全てのキーワードオプションを認識し、ホストファイルシステムの環境上において「適切な」何らかの挙動を試行することが求められます。ファイルシステムに適合させるために必要であれば、実装はここで指定された意味からわずかに逸脱しても、仕様に適合した実装として失格とみなされることはありません。もし、あるオプションをここで指定されたものと同様の方法で処理することが実装上まったく不可能な場合は、単にエラーが通知されます。

:element-typeオプションに関して、ファイルシステムでサポートされていない型が指定されたとき、そのような型をアップグレードした型を代用することが許されます。最小の要求としては、あるファイルに対して指定した要素の型で出力ストリームを開き、後で同じファイルに対して同じ要素の型で入力ストリームを開いたときに矛盾なく動作することが求められます。

参考

with-open-file, close, pathname, logical-pathname, 19.2.3. パス名のマージ, 19.1.2. ファイル名としてのパス名

備考

openは、異常な退出が生じたときに自動的にはファイルをクローズしません。

element-typeがcharacterのサブタイプのとき、 read-charとwrite-charが結果のファイルストリームで使用できます。

element-typeが整数のサブタイプのとき、 read-byteとwrite-byteが結果のファイルストリームで使用できます。

element-typeが:defaultのとき、その型はstream-element-typeを使うことで決定することができます。

TOP, Github

This site is open source. Improve this page.