|
Class: FileStream
Object
|
+--Stream
|
+--PeekableStream
|
+--PositionableStream
|
+--WriteStream
|
+--ReadWriteStream
|
+--ExternalStream
|
+--FileStream
|
+--DirectoryStream
|
+--SoundStream
- Package:
- stx:libbasic
- Category:
- Streams-External
- Version:
- rev:
1.214
date: 2019/06/28 06:48:43
- user: cg
- file: FileStream.st directory: libbasic
- module: stx stc-classLibrary: libbasic
- Author:
- Claus Gittinger
This class provides access to the operating systems underlying file
system (i.e. its an interface to the stdio library).
Notice, that on some systems, the standard I/O library has performance
problems when a file is opened for readwrite.
For best results, open files either readonly or writeonly.
Also notice, that some OperatingSystems do not fully support
positioning a file stream.
For example, poor VMS does not allow positioning onto arbitrary
byte boundaries if the file is a variable-record-RMS file.
(stupid enough, this is the default for textfiles as created by some tools ...)
Therefore, the instance variable canPosition is set according to
this and an error is raised, if a position: is attemted.
I know, this is ugly, but what else could we do ?
Late note: who cares for VMS these days?
(and how much useless effort has been put in the past,
to support lousy operating systems?)
[instance variables:]
pathName <String> the file's path (if known)
canPosition <Boolean> positionable - read above comment
Filename
DirectoryStream
PipeStream
Socket
Compatibility-ANSI
-
write: filename
-
return a FileStream for new file named filename, aString.
If the file exists, it is truncated, otherwise created.
The file is opened for read/write access.
Same as newFileNamed: for ANSI compatibilily
Compatibility-Dolphin
-
read: filename text: text
-
return a readonly FileStream for the existing file named filename, aString.
If the argument, text is false, the stream is setup to read binary bytes,
if false, it reads characters.
-
write: filename mode: modeSymbol
-
return a writable FileStream for the file named filename, aString.
The modeSymbol controls how the file is opened; currently supported are:
#append
-
write: filename text: textModeBoolean
-
return a writable FileStream for the file named filename, aString.
If the argument, text is false, the stream is setup to write binary bytes,
if false, it writes characters.
Compatibility-Squeak
-
fileIn: aPath
-
-
forceNewFileNamed: filename
-
return a writing FileStream for new file named filename, aString.
If it already exists, it is overwritten silently.
-
readOnlyFileNamed: filename
-
return a readonly FileStream for the existing file named filename, aString.
-
readOnlyFileNamed: filename do: aBlock
-
open a readonly stream on filename and evaluate aBlock with it.
Return the value from aBlock.
Ensures that the stream is closed afterwards
-
readonlyFileNamed: filename do: aBlock ( an extension from the stx:libcompat package )
-
open a readonly stream on filename and evaluate aBlock with it.
Ensures that the stream is closed afterwards
Compatibility-VW
-
badArgumentsSignal
-
Signal constants
-
userInitiatedFileSaveQuerySignal
-
return the query signal, which is raised before a user-initiated
file-save / file-saveAs operation is performed.
The query will be invoked with the fileName which is about to be
written to.
The default signal here returns true, which will grant the save.
End-user applications may want to catch this signal,
and only return true for certain directories.
initialization
-
initialize
-
(comment from inherited method)
self patchByteOrderOptimizedMethods
instance creation
-
appendingOldFileNamed: filename
-
return a FileStream for existing file named filename, aString.
The file is opened for writeonly access.
usage example(s):
FileStream appendingOldFileNamed:'adasdasasd'
|
-
appendingOldFileNamed: filename in: aDirectory
-
return a FileStream for existing file named filename, aString
in aDirectory, a FileDirectory.
The file is opened for writeonly access.
-
fileNamed: filename
-
return a stream on file filename - if the file does not
already exist, create it.
The file is opened for read/write access.
-
fileNamed: filename in: aDirectory
-
return a stream on file filename - if the file does not
already exist, create it.
The file is opened for read/write access.
-
newFileForWritingNamed: filename
-
return a FileStream for new file named filename, aString.
If the file exists, it is truncated, otherwise created.
The file is opened for writeonly access.
-
newFileForWritingNamed: filename in: aDirectory
-
return a FileStream for new file named filename, aString
in aDirectory, a FileDirectory.
If the file exists, it is truncated, otherwise created.
The file is opened for writeonly access.
-
newFileNamed: filename
-
return a FileStream for new file named filename, aString.
If the file exists, it is truncated, otherwise created.
The file is opened for read/write access.
-
newFileNamed: filename in: aDirectory
-
return a FileStream for new file named filename, aString
in aDirectory, a FileDirectory.
If the file exists, it is truncated, otherwise created.
The file is opened for read/write access.
-
newTemporary
-
create atomically a new file and return the file stream - use this for temporary files.
The created file has the name '/tmp/stxtmp_xx_nn' where xx is our
unix process id, and nn is a unique number, incremented with every call to this method.
If any of the environment variables STX_TMPDIR, ST_TMPDIR, TMPDIR is set,
its value defines the temp directory.
usage example(s):
FileStream newTemporary
FileStream newTemporary
|
-
newTemporaryIn: aDirectoryOrNil
-
create atomically a new file and return the file stream - use this for temporary files.
The created file is in aDirectoryPrefix and named 'stxtmp_xx_nn',
where xx is our unix process id, and nn is a unique number, incremented
with every call to this method.
usage example(s):
temp files somewhere
(not recommended - use above since it can be controlled via shell variables):
FileStream newTemporaryIn:'/tmp'
FileStream newTemporaryIn:'/tmp'
FileStream newTemporaryIn:'/usr/tmp'
FileStream newTemporaryIn:'/'
|
usage example(s):
a local temp file:
FileStream newTemporaryIn:''
FileStream newTemporaryIn:nil
FileStream newTemporaryIn:'.'
FileStream newTemporaryIn:('source' asFilename)
|
-
newTemporaryIn: aDirectoryOrNil nameTemplate: template
-
create atomically a new file and return the file stream - use this for temporary files.
The created file is in aDirectoryOrNil and named after the given template,
in which %1 and %2 are expanded to the unix process id, and a unique number, incremented
with every call to this method respectively.
See also: #newTemporary which looks for a good temp directory.
usage example(s):
temp files in '/tmp':
FileStream newTemporaryIn:'/tmp' asFilename nameTemplate:'foo%1_%2'
This must fail on the second try:
FileStream newTemporaryIn:'/tmp' asFilename nameTemplate:'foo'
FileStream newTemporaryIn:'c:\temp' asFilename nameTemplate:'foo'
|
usage example(s):
temp files somewhere
(not recommended - use above since it can be controlled via shell variables):
FileStream newTemporaryIn:'/tmp' nameTemplate:'foo%1_%2'
FileStream newTemporaryIn:'/tmp' nameTemplate:'foo%1_%2'
FileStream newTemporaryIn:'/usr/tmp' nameTemplate:'foo%1_%2'
FileStream newTemporaryIn:'/' nameTemplate:'foo%1_%2'
|
usage example(s):
a local temp file:
FileStream newTemporaryIn:'' nameTemplate:'foo%1_%2'
FileStream newTemporaryIn:nil nameTemplate:'foo%1_%2'
FileStream newTemporaryIn:'.' nameTemplate:'foo%1_%2'
FileStream newTemporaryIn:('source' asFilename) nameTemplate:'foo%1_%2'
|
-
newTemporaryIn: aDirectoryOrNil withSuffix: aSuffixString
-
create atomically a new file and return the file stream - use this for temporary files.
The created file is in aDirectoryPrefix and named 'stxtmp_xx_nn',
where xx is our unix process id, and nn is a unique number, incremented
with every call to this method.
usage example(s):
FileStream newTemporaryWithSuffix:'txt'
FileStream newTemporaryIn:'/tmp' withSuffix:'txt'
|
-
newTemporaryWithSuffix: aString
-
create atomically a new file and return the file stream - use this for temporary files.
The created file has the name '/tmp/stxtmp_xx_nn' where xx is our
unix process id, and nn is a unique number, incremented with every call to this method.
If any of the environment variables STX_TMPDIR, ST_TMPDIR, TMPDIR is set,
its value defines the temp directory.
usage example(s):
FileStream newTemporaryWithSuffix:'txt'
|
-
oldFileNamed: filename
-
return a FileStream for existing file named filename, aString.
The file is opened for read/write access.
Raises an error if the file does not exist.
usage example(s):
'/tmp/dAsGiBtEsNiChT' asFilename remove.
FileStream oldFileNamed:'/tmp/dAsGiBtEsNiChT'
|
-
oldFileNamed: filename in: aDirectory
-
return a FileStream for existing file named filename, aString
in aDirectory, a FileDirectory.
The file is opened for read/write access.
Raises an error if the file does not exist.
usage example(s):
FileStream oldFileNamed:'dAsGiBtEsNiChT' in:'/'
|
-
open: aFilenameString withMode: anArrayOrString
-
The argument de
The file is opened for read/write access.
-
readonlyFileNamed: filename
-
Return a readonly FileStream for existing file named filename, a String.
Raises an error if the file does not exist.
usage example(s):
FileStream readonlyFileNamed:'dAsGiBtEsNiChT'
|
-
readonlyFileNamed: filename in: aDirectory
-
return a readonly FileStream for existing file named filename, aString
in aDirectory, a fileName or string instance representing a directory.
Raises an error if the file does not exist.
usage example(s):
FileStream readonlyFileNamed:'dAsGiBtEsNiChT' in:'/'
FileStream readonlyFileNamed:'dAsGiBtEsNiChT' in:'/' asFilename
|
Compatibility-Squeak
-
fullName
-
Squeak compatibility: return the full pathname
access rights
-
accessRights
-
return the access rights of the file as opaque data
(SmallInteger in unix/linux)
usage example(s):
'Make.proto' asFilename readingFileDo:[:s|
s accessRights
]
|
-
accessRights: opaqueData
-
set the access rights of the file to opaqueData,
which is normally retrieved by Filename>>#accessRights
or FileStreamm>>#accessRights.
usage example(s):
'Make.proto' asFilename readingFileDo:[:s|
s accessRights:s accessRights
]
|
usage example(s):
'/' asFilename readingFileDo:[:s|
s accessRights:s accessRights
]
|
accessing
-
asFilename
-
return the file name
-
baseName
-
return my name without leading direcory-path (i.e. the plain fileName)
as a string
-
contentsOfEntireFile
-
ST-80 compatibility: return contents as a String (or byteArray, if in binary mode).
See also #contents, which returns the lines as stringCollection for text files.
-
directoryName
-
return the name of the directory I'm in as a string
-
fileName
-
return the file name - same as pathName for compatibility with
other smalltalks
-
name
-
return my path name as a string
-
pathName
-
return the pathname
-
removeOnClose: aBoolean
-
set/clear the removeOnClose flag.
If set, the file will be removed when closed.
Provided mostly for OS's which do not allow an
open file to be removed (i.e. non unixes),
when a fileStream for a tempFile is used.
Especially, the CVS-SourceCodeManager returns
this kind of file-handles occasionally.
This is an ST/X special feature which is not portable
to other systems.
-
store: something
-
what really should this do
error handling
-
openError: errorNumber
-
report an error, that file open failed
finalization
-
executor
-
keep the pathname for any FileStream
inspecting
-
inspectorExtraMenuOperations ( an extension from the stx:libtool package )
-
extra operation-menu entries to be shown in an inspector.
Answers a collection of pairs contining aString and action aBlock.
aString is the label of the menu item.
aBlock is evaluated when the menu item is selected.
To be redefined in objects which think that it makes sense to offer
often used operations in an inspector.
See SerialPort as an example.
misc functions
-
copy: numberOfBytesOrNil into: outStream bufferSize: bufferSize
-
read from the receiver, and write numberOfBytes data to another aWriteStream.
Return the number of bytes which have been transferred.
If nuberOfBytesOrNil is nil, copy until the end of myself.
Redefined to use operating system features to do a fast copy.
-
syncFileSystem
-
sync the filesystem containing this FileStream
-
truncateTo: newSize
-
truncate the underlying OS file to newSize.
Warning: this may not be implemented on all platforms.
positioning
-
position
-
return the read/write position in the file
-
position: newPos
-
set the read/write position in the file
-
reset
-
additionaly to setting the position to the beginning of the file,
re-open a previously closed file. This behavior is compatible
with other Smalltalk dialects
-
setToEnd
-
set the read/write position in the file to be at the end of the file
-
slowPosition: newPos
-
position the file by re-reading everything up-to newPos.
The effect is the same as that of #position:, but its much slower.
This is required to reposition nonPositionable streams, such
as tape-streams or variable-record-RMS files under VMS.
Caveat:
This should really be done transparently by the stdio library.
printing & storing
-
printOn: aStream
-
append a user printed representation of the receiver to aStream.
The format is suitable for a human - not meant to be read back.
-
storeOn: aStream
-
append a representation of the receiver to aStream,
from which a copy can be reconstructed later.
private
-
protected closeFile
-
low level close - may be redefined in subclasses.
Don't send this message, send #close instead
-
createForReadWrite
-
create/truncate the file for read/write.
If the file existed, it's truncated; otherwise it's created.
-
createForWriting
-
create/truncate the file for writeonly.
If the file existed, it's truncated; otherwise it's created.
-
openFile: pathName withMode: openmode attributes: attributeSpec
-
open the file;
openmode is the string defining the way to open as defined by the stdio library
(i.e. the 2nd fopen argument).
attributeSpec is an additional argument, only used with VMS - it allows a file to
be created as fixedRecord, variableRecord, streamLF, streamCR, ...
In VMS, if nonNil, it must consist of an array of strings (max:10), giving additional
attributes (see fopen description).
Passing a nil specifies the default format (streamLF) - ST/X always invokes this with nil.
This argument is ignored in UNIX & MSDOS systems.
This is a private entry, but maybe useful to open/create a file in a special mode,
which is proprietrary to the operatingSystem.
-
openForAppending
-
open the file for writeonly appending to the end.
If the file does not exist, raise OpenError;
otherwise return the receiver.
-
openForReadWrite
-
open the file for read/write.
If the file does not exist, raise OpenError;
otherwise return the receiver.
-
openForReading
-
open the file for readonly.
If the file does not exist, raise OpenError;
otherwise return the receiver.
-
openForWriting
-
open the file writeonly. The contents of the file is preserved.
If the file does not exist, raise OpenError;
otherwise return the receiver.
-
openWithMode: openmode
-
open the file;
openmode is the string defining the way to open as defined by the stdio library
(i.e. the 2nd fopen argument).
This is a private entry, but maybe useful to open a file in a special mode,
which is proprietrary to the operatingSystem.
-
openWithMode: openmode attributes: attributeSpec
-
open the file;
openmode is the string defining the way to open as defined by the stdio library
(i.e. the 2nd fopen argument).
attributeSpec is an additional argument, only used with VMS - it allows a file to
be created as fixedRecord, variableRecord, streamLF, streamCR, ...
In VMS, if nonNil, it must consist of an array of strings (max:10), giving additional
attributes (see fopen description).
Passing a nil specifies the default format (streamLF) - ST/X always invokes this with nil.
This argument is ignored in UNIX & MSDOS systems.
This is a private entry, but maybe useful to open/create a file in a special mode,
which is proprietrary to the operatingSystem.
-
pathName: filename
-
set the pathname
-
pathName: filename in: aDirectory
-
set the pathname starting at aDirectory, a FileDirectory
-
reOpen
-
USERS WILL NEVER INVOKE THIS METHOD
sent after snapin to reopen streams.
-
setMode: aModeSymbol
-
-
setPathName: pathNameString removeOnClose: aBoolean
-
private fileIn
-
fileInNotifying: notifiedLoader passChunk: passChunk
-
central method to file in from the receiver, i.e. read chunks and evaluate them -
return the value of the last chunk.
Someone (which is usually some codeView) is notified of errors.
queries
-
collectionSize
-
common stream protocol: return the size of the stream;
that's the number of bytes of the file.
-
fileSize
-
return the size in bytes of the file
-
isDirectory
-
-
isEmpty
-
common stream protocol: are there no bytes in the file?
-
remainingSize
-
return the number of remaining elements in the streamed collection.
-
size
-
common stream protocol: return the size of the stream;
that's the number of bytes of the file.
rel5 protocol
-
positionFile: handle position: newPos
-
for migration to rel5 only
testing
-
isFileStream
-
return true, if the receiver is some kind of fileStream.
redefined from Object
for VMS users only:
The #openWithMode:attributes: entry allows additional RMS attributes
to be passed in the second argument, which must be an array of strings
as described in the 'creat' RTL Library documentation.
For example, to create a file with fixed records and recordLength of 100,
use:
|newFile|
newFile := FileStream new pathName:'<nameOfFile>'.
newFile setMode:#writeonly.
newFile openWithMode:'w' attributes:#('rfm=fix' 'fsz=100').
since all of the above is private protocol, and it is considered bad style to
access these from user programs, we recommend subclassing FileStream as
something like VMSFixedRecordFileStream, and redefine the instance creation
method(s) there as appropriate.
This will retain VMS specifics in one place and enhance maintanability.
|