Smalltalk/X Webserver

Documentation of class 'Filename':

Class: Filename

Inheritance
Description
Related information
Class protocol
Instance protocol
Examples

Inheritance:

   Object
   |
   +--Filename
      |
      +--AutoDeletedFilename
      |
      +--UnixFilename

Package:: stx:libbasic

Category:: System-Support

Version:: rev: 1.350 date: 2010/04/30 16:49:05; user: stefan; file: Filename.st directory: libbasic; module: stx stc-classLibrary: libbasic

Author:: Claus Gittinger

Description:

Filenames; originally added for ST-80 compatibility, is
taking over functionality from other classes (FileDirectory).

Instances of Filename do not nescessarily represent valid or existing
files - i.e. it is possible (and useful) to have instances for non-existing
files around. In other words: the name-string is not checked automatically
for being correct or existing.
Thus, it is possible to do queries such as:

    '/fee/foo/foe' asFilename exists     
    '/not_existing' asFilename isDirectory 
    '/foo/bar' asFilename isReadable 

(all of the above examples will probably return false on your machine ;-).

examples:

    'Makefile' asFilename readStream

    'newFile' asFilename writeStream

    Filename newTemporary writeStream

Beside lots of protocol to query for a files attributes, the class
protocol offers methods for filename completion, to construct pathes
(in an OS-independent way) and to create temporary files.
Especially the path-construction methods (i.e. #construct:) are highly
recommended in order to avoid having OS details (like directory separators
being slash or backslash) spreaded in your application.

Since Filenames have different semantics under different operating systems,
class methods are delegated to concrete implementations in various subclasses like
UnixFilename, PCFilename, ...
The delegation is implemented in a way, so that some methods of
specific OS Filenames might be used, even if ST/X is currently running 
on a different OS (as long as the method does not depend on the OperatingSystem class).

Related information:

    String
    FileStream
    DirectoryStream
    PipeStream
    Socket
    OperatingSystem
    Date
    Time

Class protocol:

defaults

concreteClass: different subclasses of Filename are used for different
OperatingSystems; concreteClass is supposed to return an appropriate class.
defaultClass: different subclasses of Filename are used for different
OperatingSystems; defaultClass is supposed to return an appropriate class
defaultTempDirectoryName: return the default temp directory as a filename.
This is used, if no special preferences were defined in
any of the TEMP-environment variables (see tempDirectory).

initialization

initialize: initialize for the OS we are running on
initializeConcreteClass: initialize for the OS we are running on
reinitialize: initialize for the OS we are running on (after a restart)

instance creation

currentDirectory: return a filename for the current directory
defaultDirectory: ST80 compatibility: same as currentDirectory
defaultTempDirectory: return the default temp directory as a filename.
That is the same as TempDirectory, except that TempDirectory can be changed
from the outside (via tempDirectory:).
Use this for files which MUST remain the same (stx_sourceCache)
desktopDirectory: return your desktop directory.
Under windows, thats the real desktop directory;
under other OperatingSystems, the home directory is returned.
documentsDirectory: return your documents directory.
Under windows, thats the real 'Documents' or 'My Documents';
under other OperatingSystems, the home directory is returned.
findDefaultDirectory: same as #defaultDirectory for ST80 compatibility
fromComponents: aCollectionOfDirectoryNames: create & return a new filename from components given in
aCollectionOfDirectoryNames. If the first component is the name of the
root directory (i.e. '/') an absolute path-filename is returned.
fromUser: show a box to enter a filename.
Return a filename instance or nil (if cancel was pressed).
homeDirectory: return your homeDirectory.
Some OperatingSystems do not support this - on those, the defaultDirectory
(which is the currentDirectory) is returned.
named: aString: return a filename for a directory named aString.
This is the same as 'aString asFilename'.
newTemporary: return a new unique filename - use this for temporary files.
The filenames returned are '/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 ST_TMPDIR or TMPDIR is set,
its value defines the temp directory.
Notice, that no file is created by this - only a unique name
is generated.
newTemporaryDirectory: return a new unique temporary directory - use this for temporary files.
The directories returned are '/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 ST_TMPDIR or TMPDIR is set,
its value defines the temp directory.
newTemporaryDirectoryIn: aDirectoryOrNil: return a new unique temporary directory in another directory, or the current dir.
Use this for temporary files.
The directories returned are '/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 ST_TMPDIR or TMPDIR is set,
its value defines the temp directory.
newTemporaryIn: aDirectoryOrNil: return a new unique filename - use this for temporary files.
The filenames returned are 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.
Notice: only a unique filename object is created and returned - no physical
file is created by this method (i.e. you have to send #writeStream or
whatever to it in order to really create something).
See also: #newTemporary which looks for a good temp directory.
newTemporaryIn: aDirectoryOrNil nameTemplate: template: return a new unique filename - use this for temporary files.
The filenames returned are 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.
Notice: only a unique filename object is created and returned - no physical
file is created by this method (i.e. you have to send #writeStream or
whatever to it in order to really create something).
See also: #newTemporary which looks for a good temp directory.
nullDevice: return the filename of the nullDevice (if available).
returns nil, if the OperatingSystem does not support this.
remoteHost: remoteHostString rootComponents: aCollectionOfDirectoryNames: create & return a new filename from components given in
aCollectionOfDirectoryNames on a host named remoteHostString.
An absolute network-filename is returned.
rootComponents: aCollectionOfDirectoryNames: create & return a new filename from components given in
aCollectionOfDirectoryNames.
An absolute path-filename is returned.
rootDirectory: return a filename for the root directory
rootDirectoryOnVolume: aVolumeName: return a filename for the root directory on some volume
tempDirectory: return the temp directory as a filename.
If any of the environment variables STX_TMPDIR, ST_TMPDIR,
TMPDIR or TEMPDIR is set, its value defines the name,
otherwise, '/tmp' is used. (at least on unix ...).

Notice: do not hardcode '/tmp' into your programs - things may be
different on other operating systems. Also, the user may want to set the
TMPDIR environment variable to have her temp files somewhere else.
tempDirectory: aFilename: set the xdefault temporary directory pathname

misc

canonicalize: aPathString: convert the argument, aPathString to a good format.
This should eliminate useless directory components (i.e. '././')
and useless tree walks (i.e. '../foo/..').
filterSeps: aFilenameString: ST80 compatibility:
filter out (invalid) separators in aFilenameString.
We recommend using #makeLegalFilename
suggest: aFilenameString: return a fileNamestring based on the argument,
which is legal on the current platform.

queries

components: aString: separate the pathName given by aString into
a collection containing the directory components and the files name as
the final component.
If the argument names an absolute path, the first component will be the
name of the root directory (i.e. '/').
currentDirectoryName: return a filename for the current directory
defaultDirectoryName: ST80 compatibility: return the defaultDirectories name (as a string)
directorySuffix: Return the OS dependent directory suffix string, or nil if there is none.
The default is nil here, redefined for VMS
errorReporter: who knows the signals to report errors?
filenameCompletionFor: aString directory: inDirectory directoriesOnly: directoriesOnly filesOnly: filesOnly ifMultiple: aBlock: perform filename completion on aString in some directory;
return the longest matching filename prefix as a string.
The boolean directoriesOnly and filesOnly control respectively,
if only directories or only regular files are to be considered for completion.
If multiple files match, the exception block aBlock is evaluated with a
filename representing the directory (where the match was done) as argument.
(this may be different from the inDirectory argument, if aString is absolute
or starts with ../)
filenameCompletionFor: aString directory: inDirectory directoriesOnly: directoriesOnly filesOnly: filesOnly ifMultiple: aBlock forMultipleDo: aMultipleBlock: perform filename completion on aString in some directory;
return the longest matching filename prefix as a string.
The boolean directoriesOnly and filesOnly control respectively,
if only directories or only regular files are to be considered for completion.
If multiple files match, the exception block aBlock is evaluated with a
filename representing the directory (where the match was done) as argument and the aMultipleBlock
is evaluated with both the directory (where the match was done) and the matchSet
(list of matched filenames) as arguments.
(this may be different from the inDirectory argument, if aString is absolute
or starts with ../)
filesMatching: aPattern: return a collection of strings, representing the names
of files matching aPattern.
If aPattern contains a directory path, files are tried there;
otherwise, files from the currentDirectory are tried.
The returned strings are the expanded names, in the same form
as given in pattern.
The pattern should be a simple pattern.
isAbstract: return true, if this is not a concrete class
isBadCharacter: aCharacter: return true, if aCharacter is unallowed in a filename.
isCaseSensitive: return true, if filenames are case sensitive.
We ask the OS about this, to be independent here.
localNameStringFrom: aString: ST-80 compatibility.
what does this do ? (used in FileNavigator-goody).
GUESS:
does it strip off any volume characters and make a path relative ?
maxComponentLength: return the maximum number of characters a filename component may
be in size. This depends on the OperatingSystem.
maxLength: return the maximum number of characters a filename may be in size.
This depends on the OperatingSystem.
nullFilename: Return the OS dependent filename for /dev/null, or nil if there is none.
The default is nil here
parentDirectoryName: return the name used for the parent directory.
This is '..' for unix and dos-like systems.
(there may be more in the future.
separator: return the file/directory separator.
This is to be redefined in concrete classes;
the following default usually leads to a flat view of
the fileSystem (huh - BS2000 ?)
separatorString: return the file/directory separator as a string.
suffixSeparator: return the filename suffix separator.
Usually, this is $. for unix-like and msdos systems
(there is currently no known system, where this differs)
tempFileNameTemplate: return a template for temporary files.
This is expanded with the current processID and a sequenceNumber
to generate a unique filename.
volumes: ST-80 compatibility.
GUESS: does it return the available drives on MSDOS systems ?
Q: what does this do on Unix systems ? (used in FileNavigator-goody).

utilities

nameFromComponents: aCollectionOfDirectoryNames: return a filenameString from components given in aCollectionOfDirectoryNames.
If the first component is the name of the root directory (i.e. '/'),
an absolute path-string is returned.
readingFile: aPathName do: aBlock: create a read-stream on a file, evaluate aBlock, passing that stream,
and return the blocks value.
Ensures that the stream is closed.

Instance protocol:

Compatibility-VW5.4

asLogicalFileSpecification
canBeWritten: same as isWritable - for ST-80 compatibility
definitelyExists: for now - a kludge
extension: return the receiver's extension;
that is the characters from and including
the last period or nil, if there is none.

comparing

= aFilename: return true, if the argument represents the same filename
contentsIsPrefixOf: aFilename: return true if the contents of the file represented by the receiver
is the same as or a prefix of the contents of the file represented by the argument, aFilename.
This compares the files actual contents; not the filenames.
contentsStartsWithContentsOf: aFilename: return true if the contents of the file represented by aFilename
is the same as or a prefix of the contents of the file represented by the receiver.
This compares the files actual contents; not the filenames.
hash: return an integer useful as a hash-key
sameContentsAs: aFilename: return true if the file represented by the receiver has the
same contents as the file represented by the argument, aFilename.
This compares the files actual contents; not the filenames.

converting

asAbsoluteFilename: return the receiver converted to a filename with
an absolute pathname.
asAutoDeletedFilename
asCanonicalizedFilename: return the receiver converted to a filename without intermediate ..'s and .'s
(similar to an absolute pathname, but symlinks are not resolved).
asFilename: return the receiver converted to a filename; here, thats the receiver itself.
asString: return the receiver converted to a string
asURI: return the receiver converted to a string
components: return the receivers filename components - that is the name of each directory
along the pathName (that DOES include the root directory)
makeLegalFilename: convert the receivers name to be a legal filename.
This removes/replaces invalid characters and/or compresses
the name as required by the OS.
The implementation may change in the future to be more
OS specific.
withEncoding: encodingSymbol: dummy for now - for ST80 compatibility

enumerating-contents

allDirectoriesDo: aBlock: evaluate aBlock for all (recursive) directories contained in the directory represented by the receiver.
The block is invoked with a filename-arguments.
The enumerations order within a directory is undefined - i.e. usually NOT sorted by
filenames (but by creation time - on some systems).
This excludes entries for '.' or '..'.
NoOp for non-existing directories; however, this behavior
may be changed in the near future, to raise an exception instead.
So users of this method better test for existing directory before.
allParentDirectoriesDo: aBlock: evaluate aBlock for all (recursive) directories along the parent directory path.
The block is invoked with a filename-arguments.
directories: return a collection of directories contained in the directory represented by the receiver.
directoriesDo: aBlock: evaluate aBlock for directories contained in the directory represented by the receiver.
The block is invoked with a filename-arguments.
The enumerations order is undefined - i.e. usually NOT sorted by
filenames (but by creation time - on some systems).
This excludes entries for '.' or '..'.
NoOp for non-existing directories; however, this behavior
may be changed in the near future, to raise an exception instead.
So users of this method better test for existing directory before.
directoryContentsAsFilenamesDo: aBlock: evaluate aBlock for each file in the directory represented by the receiver.
The block is invoked with a filename-argument.
The enumerations order is undefined - i.e. usually NOT sorted by
filenames (but by creation time - on some systems).
This excludes entries for '.' or '..'.
NoOp for non-existing directories; however, this behavior
may be changed in the near future, to raise an exception instead.
So users of this method better test for existing directory before.
Notice: this enumerates fileName objects; see also
#directoryContentsDo:, which enumerates strings.
directoryContentsDo: aBlock: evaluate aBlock for each file in the directory represented by the receiver.
The block is invoked with a string as argument.
The enumerations order is undefined - i.e. usually NOT sorted by
filenames (but by creation time - on some systems).
This excludes entries for '.' or '..'.
An exception is raised it the directory does not exist..
So users of this method better test for existing directory before.
Notice: this enumerates strings; see also
#directoryContentsAsFilenamesDo:, which enumerates fileName objects.
files: return a collection of files contained in the directory represented by the receiver.
filesDo: aBlock: evaluate aBlock for all files contained in the directory represented by the receiver.
recursiveDirectoryContentsDo: aBlock: evaluate aBlock for all files and directories found under the receiver.
The block is invoked with a string-argument.
The walk is bread-first.
This excludes any entries for '.' or '..'.
Subdirectory files are included with a relative pathname.
Warning: this may take a long time to execute (especially with deep and/or remote fileSystems).
recursiveDirectoryContentsDo: aBlock directoryPrefix: aPrefix: evaluate aBlock for all files and directories found under the receiver.
The block is invoked with a string-argument.
The walk is breadth-first.
This excludes any entries for '.' or '..'.
Subdirectory files are included with a relative pathname.
A proceedable exception is raised forn non-accessable directories.
Warning: this may take a long time to execute (especially with deep and/or remote fileSystems).
withAllDirectoriesDo: aBlock: evaluate aBlock for myself and all (recursive) directories contained in the directory represented by the receiver.
The block is invoked with a filename-arguments.
The enumerations order within a directory is undefined - i.e. usually NOT sorted by
filenames (but by creation time - on some systems).
This excludes entries for '.' or '..'.
NoOp for non-existing directories; however, this behavior
may be changed in the near future, to raise an exception instead.
So users of this method better test for existing directory before.

error handling

accessDeniedError: filename: report an error that access to some file was denied
fileCreationError: filename: report an error that some file could not be created
fileNotFoundError: filename: report an error that some file was not found
removeError: filename: report an error that some file could not be removed
reportError: string with: filename: report an error

file access

appendStream: return a stream for appending to the file represented by the receiver.
If the file does not already exist, it is created.
Same as #appendingWriteStream for ST-80 compatibility.
appendingWriteStream: return a stream for appending to the file represented by the receiver.
If the file does not already exist, it is created;
if it does exist, writes are appended at the end.
newReadWriteStream: return a stream for read/write the file represented by the receiver.
If the file does not already exist, it is created;
if it does exist, it is truncated.
readStream: return a stream for reading from the file represented by the receiver.
Raises an error if the file does not exist.
readWriteStream: return a stream for read/write the file represented by the receiver.
If the file does not already exist, it is created.
If the file does exist, it is NOT truncated, but rewritten at the beginning.
writeStream: return a stream for writing to the file represented by the receiver.
If the file does not already exist, it is created;
if it does exist, it is truncated.

file access - migration

appendingWriteStreamOrNil: return a stream for appending to the file represented by the receiver.
If the file does not already exist, it is created;
if it does exist, writes are appended at the end.

Return nil, if the file cannot be opened.
Use this method for migration of old smalltalk code that expects a nil return code
instead of an exception when an error occurs.
newReadWriteStreamOrNil: return a stream for read/write the file represented by the receiver.
If the file does not already exist, it is created;
if it does exist, it is truncated.

Return nil, if the file cannot be opened.
Use this method for migration of old smalltalk code that expects a nil return code
instead of an exception when an error occurs.
readStreamOrNil: return a stream for reading from the file represented by the receiver.
If the file does not already exist, nil is returned.

Return nil, if the file cannot be opened.
Use this method for migration of old smalltalk code that expects a nil return code
instead of an exception when an error occurs.
readWriteStreamOrNil: return a stream for read/write the file represented by the receiver.
If the file does not already exist, it is created.
If the file does exist, it is NOT truncated, but rewritten at the beginning

Return nil, if the file cannot be opened.
Use this method for migration of old smalltalk code that expects a nil return code
instead of an exception when an error occurs.
writeStreamOrNil: return a stream for writing to the file represented by the receiver.
If the file does not already exist, it is created;
if it does exist, it is truncated.

Return nil, if the file cannot be opened.
Use this method for migration of old smalltalk code that expects a nil return code
instead of an exception when an error occurs.

file accessRights

accessRights: return the access rights of the file as opaque data
(SmallInteger in unix/linux)
accessRights: opaqueData: set the access rights of the file to opaqueData,
which is normally retrieved by Filename>>#accessRights.
addAccessRights: aCollection: add the access rights as specified in aCollection for the file represented
by the receiver. The argument must be a collection of symbols,
such as #readUser, #writeGroup etc.
makeExecutable: make the file executable - you must have permission to do so.
For directories, execution means: 'allow changing into it'
makeExecutableForAll: make the file executable for all - you must have permission to do so.
For directories, execution means: 'allow changing into it'
makeExecutableForGroup: make the file executable for the group - you must have permission to do so.
For directories, execution means: 'allow changing into it'
makeReadable: make the file readable for the owner - you must have permission to do so.
makeReadableForAll: make the file readable for all - you must have permission to do so.
makeReadableForGroup: make the file readable for the group - you must have permission to do so.
makeUnwritable: make the file unwritable for all - you must have permission to do so.
makeWritable: make the file writableable for all - you must have permission to do so.
makeWritableForAll: make the file writable for all - you must have permission to do so.
makeWritableForGroup: make the file writable for the group - you must have permission to do so.
removeAccessRights: aCollection: remove the access rights as specified in aCollection for the file represented
by the receiver. The argument must be a collection of symbols,
such as #readUser, #writeGroup etc.
Raises an exception if not successful.
symbolicAccessRights: return the access rights of the file as a aCollection of access symbols.
The returned collection consists of symbols like:
#readUser, #writeGroup etc.
symbolicAccessRights: aCollectionOfSymbols: set the access rights of the file given a aCollection of access symbols.
The collection must consist of symbols like:
#readUser, #writeGroup etc.

file operations

appendTo: newNameOrStream: append the file - the argument must be convertable to a filename.
Raises an exception, if an error occurs.
basicMakeDirectory: create a directory with the receivers name.
Return true if successful, false if not.
copyTo: newNameArg: Copy the files contents into another file.
The argument must be convertable to a filename.
Raises an exception, if an error occurs.
createAsEmptyFile: create an empty file with the receivers name.
Raises an exception if not successful
(either already existing or creation not possible)
delete: remove the file - same as remove, for ST-80 compatibility
makeDirectory: create a directory with the receivers name.
Raises an exception if not successful
moveFileTo: newName: copy the file represented by the receiver, then delete it.
This is different to renaming in case of cross device moves.
Raise an exception if not successful.
(Notice, that a rename is tried first, in case of non-cross device move)
moveTo: newName: copy the file represented by the receiver, then delete it.
This is different to renaming in case of cross device moves.
Raise an exception if not successful.
(Notice, that a rename is tried first, in case of non-cross device move)
recursiveCopyTo: destination: if I represent a regular file, copy it.
Otherwise, copy the directory and recursively
and recursively all of its subfiles/subdirectories.
Raises an exception if not successful.
recursiveCopyWithoutOSCommandTo: destination: if I represent a regular file, copy it.
Otherwise, copy the directory and all of its subfiles/subdirectories.
This one walks down the directory hierarchy, not using any OS command to do the copy.
Raises an exception if not successful.
recursiveMakeDirectory: create a directory with the receivers name and all required intermediate
directories.
Raises an exception if not successful.
recursiveMoveDirectoryTo: newName: recursively copy the directory represented by the receiver, then delete it.
This is different to renaming in case of cross device moves.
Raise an exception if not successful.
(Notice, that a rename is tried first, in case of non-cross device move)
recursiveRemove: if I represent a regular file, remove it.
Otherwise, remove the directory and all of its subfiles/subdirectories.
Raise an exception if not successful.
recursiveRemoveWithoutOSCommand: if I represent a regular file, remove it.
Otherwise, remove the directory and all of its subfiles/subdirectories.
Raise an error if not successful.
This one walks down the directory hierarchy, not using any OS
command to do the remove.
remove: remove the file/directory.
Raises an exception if not successful.
Use #recursiveRemove in order to (recursively) remove non empty directories.
removeDirectory: remove the directory.
Raises an exception if not successful (or if its not a directory).
Use #remove if it is not known if the receiver is a directory or file.
Use #recursiveRemove in order to (recursively) remove non empty directories.
removeFile: remove the file.
Raises an exception if not successful (or if its not a file).
Use #remove if it is not known if the receiver is a directory or file.
Use #recursiveRemove in order to (recursively) remove non empty directories.
renameOrCopyTo: newName: rename or copy the file - the argument must be convertable to a String.
Raises an exception if not successful.
This does basically the same as #renameTo:, with one exception:
if, under unix, the new fileName is on another device, a rename operation
fails, and #renameTo: raises an exception;
in contrast, this method falls back to copying the file.
renameTo: newName: rename the file - the argument must be convertable to a String.
Raises an exception if not successful.
truncateTo: newSize: change the files size.
This may not be supported on all operating systems
(raises an exception, if not)

file queries

accessTime: return a timeStamp containing the files last access time.
creationTime: return a timeStamp containing the files creation time.
NOTICE: only windoof distinguishes creation from modification;
under unix, nil is returned (callers should fall back and use mod-time then
dates: return the files modification and access times as an object (currently a dictionary)
that responds to the at: message with arguments
#modified, #accessed or #statusChanged.
fileSize: return the size of the file in bytes
fileType: this returns a string describing the type of contents of
the file. This is done using the unix 'file' command,
(which usually is configurable by /etc/magic).
On non-unix systems, this may simply return 'file',
not knowning about the contents.
Warning:
Since the returned string differs among systems (and language settings),
it is only useful for user-information;
NOT as a tag to be used by a program.
id: return the files/directories file-id (inode number)
info: return some object filled with the files info;
the info (for which corresponding access methods are understood by
the returned object) is:

type - a symbol giving the files fileType
mode - numeric access mode
uid - owners user id
gid - owners group id
size - files size
id - files number (i.e. inode number)
accessed - last access time (as osTime-stamp)
modified - last modification time (as osTime-stamp)
statusChanged - last staus change (as osTime-stamp)

Some of the fields may be returned as nil on systems which do not provide
all of the information.
The minimum returned info (i.e. on all OS's) will consist of at least:
modified
size
type

Dont expect things like uid/gid/mode to be non-nil; write your application
to either handle nil values,
or (better) use one of isXXXX query methods. (Be prepared for DOS ...)
(i.e. instead of:
someFilename type == #directory
use
someFilename isDirectory
linkInfo: return the files info. If it is a symbolic link return the info of the link itself
instead of the link's target.
The information is the same as returned by #info, except that if the
receiver represents a symbolic link, the links information
is returned
(while in this case, #info returns the info of the target file,
which is accessed via the symbolic link).

In addition to the normal entries, Unix returns an additional entry:
path -> the target files pathname

See the comment in #info for more details.
modificationTime: return a timeStamp containing the files modification time.
type: return the symbolic type of the file

file utilities

edit: start an editView on the file represented by the receiver
fileIn: load smalltalk code from the file

instance creation

/ subname: Same as construct: Taking the receiver as a directory name, construct a new
filename for an entry within this directory
(i.e. for a file or a subdirectory in that directory).
The argument may not specify an absolute path name.
Please do not use this to create filenames with suffixes,
since some systems require special naming conventions.
See also: #withSuffix: (which is different, but often needed).
Thanks to Jan Vrany for this idea.
construct: subname: taking the receiver as a directory name, construct a new
filename for an entry within this directory
(i.e. for a file or a subdirectory in that directory).
The argument may not specify an absolute path name.
Please do not use this to create filenames with suffixes,
since some systems require special naming conventions.
See also: #withSuffix: (which is different, but often needed).
constructDirectory: subname: same as #construct: on most systems.
(may allow different/relaxed name syntax of the argument on some systems)
constructDirectoryString: subName: same as #constructString: on most systems.
(may allow different/relaxed name syntax of the argument on some systems)
constructString: subName: taking the receiver as a directory name, construct a new
filename-string for an entry within this directory
(i.e. for a file or a subdirectory in that directory).
The argument may not specify an absolute path name.
The code below works for UNIX & MSDOS;
other filename classes (i.e. VMS) may want to redefine this method.
filenameFor: fileName: return a filename representing the argument, fileName
either in myself (if the arg is a releative path) or absolute otherwise.
secureConstruct: subname: taking the receiver as a directory name, construct a new
filename for an entry within this directory
(i.e. for a file or a subdirectory in that directory).
The argument may not specify an absolute path name.
Please do not use this to create filenames with suffixes,
since some systems require special naming conventions.
See also: #withSuffix: (which is different, but often needed).

This method differs from #construct:, by not permitting subName
to navigate above (via ..) the current filename.
secureConstructString: subName: taking the receiver as a directory name, construct a new
filename-string for an entry within this directory
(i.e. for a file or a subdirectory in that directory).

This method differs from #constructString, by not permitting subName
to navigate above (via ..) the current filename.

The code below works for UNIX & MSDOS;
other filename classes (i.e. VMS) may want to redefine this method.

misc

, aString: this allows filenames to understand how names are concatenated.
Returns a string consisting of the receivers name, concatenated
by aString. Notice this is NOT the same as construct:, which inserts
a directory delimiter and returns a new fileName instance.
See also: #withSuffix: which is new and better.

** This is an obsolete interface - do not use it (it may vanish in future versions) **
canonicalize: normalize a filename by removing all empty path components or dots,
and by resolving parent directory '..' references.

The code below works for UNIX & MSDOS;
other filename classes (i.e. VMS) may want to redefine this method.

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 printed representation of the receiver to aStream,
which allows reconstructing it via readFrom:

private-accessing

getName: get the raw filename
setName: aString: set the filename

queries

exists: return true, if such a file exists.
filenamesMatching: aPattern: VW compatibility
filesMatching: aPattern: given the receiver, representing a directory;
return a collection of files matching a pattern.
The pattern may be a simple matchPattern, or a set of
multiple patterns separated by semicolons.
filesMatchingWithoutDotDirs: aPattern: given the receiver, representing a directory;
return a collection of files matching a pattern.
Exclude '.' and '..' from the returned list.
The pattern may be a simple matchPattern, or a set of
multiple patterns separated by semicolons.
fullAlternativePathName
isExecutable: return true, if such a file exists and is executable (by Unix's definition).
For directories, true is returned if the directory can be entered.
See isExecutableProgram for a related check.
isExecutableProgram: return true, if such a file exists and is an executable program.
(i.e. for directories, false is returned.)
isHidden: return true, if the receiver represents a hidden file.
The definitions of hidden files depends on the OS used;
on UNIX, a name starting with a period is considered hidden;
on MSDOS, the files hidden attribute is also used.
VMS has no concept of hidden files.
isMountPoint: aPathName: return true, if I represent a mount-point.
Warning:
the receiver must be an absolute pathname,
because a realPath is not used/generated for the query (to avoid automounting).
Aka: do not ask: '../../' asFilename isMountPoint;
isReadable: return true, if such a file exists and is readable.
isSharedLibrary: return true, if such a file exists and is a shared library.
isWritable: return true, if such a file exists and is writable.
nameWithSpecialExpansions: aString: return the nameString, expanding any OS specific macros.
Here, a ~\ prefix is expanded to the users home dir (as in csh)
separator: return the directory-separator character
species
withSpecialExpansions: return a new filename, expanding any OS specific macros.
Here, a ~\ prefix is expanded to the users home dir (as in csh)

queries-contents

mimeTypeFromName: return the mimeType as guessed from the files name/and or extension.
This could be less accurate than mimeTypeOfContents, but avoids
reading the file (is therefore much faster).
Also it works with non-existing files.
Returns nil for directories and other non-regular files.
mimeTypeOfContents: this tries to guess the mime type of contents of
the file. Returns nil, if the file is unreadable, not a plain file
or the contents is unknown.
This is done using some heuristics, and may need some improvement

queries-path & name

baseName: return my baseName as a string.
- thats the file/directory name without leading parent-dirs.
(i.e. '/usr/lib/st/file' asFilename baseName -> 'file'
and '/usr/lib' asFilename baseName -> lib).
This method does not check if the path is valid.
The code here should work for Unix and MSDOS, but needs to be redefined
for VMS (and maybe others as well).
See also: #pathName, #directoryName and #directoryPathName.
Compatibility note: use #tail for ST-80 compatibility.
directory: return the directory name part of the file/directory as a new filename.
- thats a filename for the directory where the file/dir represented by
the receiver is contained in.
(this is almost equivalent to #directoryName or #head, but returns
a Filename instance instead of a string ).
directoryName: return the directory name part of the file/directory as a string.
- thats the name of the directory where the file/dir represented by
the receiver is contained in.
This method does not check if the path is valid.

(i.e. '/usr/lib/st/file' asFilename directoryName -> '/usr/lib/st'
and '/usr/lib' asFilename directoryName -> /usr').

(this is almost equivalent to #directory, but returns
a string instead of a Filename instance).

See also: #pathName, #directoryPathName and #baseName.
Compatibility note: use #head for ST-80 compatibility.
directoryPathName: return the full directory pathname part of the file/directory as a string.
- thats the full pathname of the directory where the file/dir represented by
the receiver is contained in.
See also: #pathName, #directoryName, #directory and #baseName
filenameCompletion: try to complete the receiver filename.
BAD DESIGN: has side effect on the receiver.
This method has both a return value and a side effect on the receiver:
it returns a collection of matching filename objects,
and changes the receivers filename-string to the longest common
match.
If none matches, the returned collection is empty and the recevier is unchanged.
If there is only one match, the size of the returned collection is exactly 1,
containing the fully expanded filename and the receivers name is changed to it.
filenameCompletionIn: aDirectory: try to complete the receiver filename.

BAD DESIGN: has side effect on the receiver.
This method has both a return value and a side effect on the receiver:
it returns a collection of matching filename objects,
and changes the receiver's filename-string to the longest common match.
If none matches, the returned collection is empty and the receiver is unchanged.
If there is only one match, the size of the returned collection is exactly 1,
containing the fully expanded filename and the receiver's name is changed to it.
An empty baseName pattern (i.e. giving the name of a directory) will also return an empty matchset.
head: return the directory name as a string.
An alias for directoryName, for ST-80 compatiblity.
(this is almost equivalent to #directory, but returns
a string instead of a Filename instance)
isAbsolute: return true, if the receiver represents an absolute pathname
(in contrast to one relative to the current directory).
isExplicitRelative: return true, if this name is an explicit relative name
(i.e. starts with './' or '../', to avoid path-prepending)
isImplicit: return true, if the receiver represents a builtin file.
The definitions of builtin files depends on the OS used;
on UNIX, '.' and '..' are builtin names.
isParentDirectoryOf: aFilenameOrString: warning: may lead to automounting
isRelative: return true, if this name is interpreted relative to some
directory (opposite of absolute)
isRootDirectory: return true, if I represent the root directory
(i.e. I have no parentDir)
isVolumeAbsolute: return true, if the receiver represents an absolute pathname
on some disk volume (MSDOS only)
localPathName: return the full pathname of the file represented by the receiver,
but without any volume information.
Only makes a difference on MSDOS & VMS systems.
name: return the name of the file represented by the receiver as a string.
This may or may not be a relative name (i.e. include ..'s).
See also: pathName
nameString: raw access to nameString - req'd for xml-store/reload
nameString: aString: raw access to nameString - req'd for xml-store/reload
pathName: return the full pathname of the file represented by the receiver,
as a string. This will not include ..'s.
If the path represented by the receiver does NOT represent a valid path,
no compression will be done (for now; this may change).
See also: name
physicalFilename: return the fileName representing the physical file as represented by the receiver,
If the receiver represents a symbolic link, thats the fileName of the
final target. Otherwise, its the receivers pathName itself.
If any file along the symbolic path does not exist (i.e. is a broken link),
nil is returned.
physicalPathName: return the full pathname of the physical file represented by the receiver,
If the receiver represents a symbolic link, thats the fileName of the
final target. Otherwise, its the receivers pathName itself.
If any file along the symbolic path does not exist (i.e. is a broken link),
nil is returned.
tail: the files name without directory prefix as a string.
An alias for baseName, for ST-80 compatiblity.
tail: nComponents: return the last n components of myself.
- thats the file/directory name without leading parent-dirs.
(i.e. '/usr/lib/st/file' asFilename tail:2 -> 'st/file'
and '/usr/lib' asFilename tail:1 -> lib).
This method does not check if the path is valid.
The code here should work for Unix and MSDOS, but needs to be redefined
for VMS (and maybe others as well).
See also: #pathName, #directoryName and #directoryPathName.
volume: return the disc volume part of the name or an empty string.
This is only used with MSDOS and VMS filenames
- by default (and on unix), an empty string is returned

queries-type

isDirectory: return true, if the receiver represents an existing,
readable directories pathname.
isNonEmptyDirectory: return true, if the receiver represents an existing,
readable directories pathname, and the directory is not empty.
isRegularFile: return true, if the receiver represents a plain, regular file
isSpecialFile: return true, if the receiver represents a socket, named pipe, fifo
or device special file (i.e. anything non regular and non-directory)
isSymbolicLink: return true, if the file represented by the receiver is a symbolic
link. Notice that not all OS's support symbolic links; those that do
not will always return false.

reading-directories

directoryContents: return the contents of the directory as a collection of strings.
This excludes any entries for '.' or '..'.
Returns nil for non-existing directories; however, this behavior
may be changed in the near future, to raise an exception instead.
So users of this method better test for existing directory before.
Notice:
this returns the file-names as strings;
see also #directoryContentsAsFilenames, which returns fileName instances.
directoryContentsAsFilenames: return the contents of the directory as a collection of filenames.
This excludes any entries for '.' or '..'.
Returns nil for non-existing directories; however, this behavior
may be changed in the near future, to raise an exception instead.
So users of this method better test for existing directory before.
Notice:
this returns the file-names as fileName instances;
see also #directoryContents, which returns strings.
fullDirectoryContents: return the full contents of the directory as a collection of strings.
This is much like #directoryContents, but includes an entry for the
parent directory, if there is one.
Returns nil for non-existing directories; however, this behavior
may be changed in the near future, to raise an exception instead.
So users of this method better test for existing directory before.
recursiveDirectoryContents: return the contents of the directory and all subdirectories
as a collection of strings.
This excludes any entries for '.' or '..'.
Subdirectory files are included with a relative pathname.
Notice:
this returns the file-names as strings;
see also #recursiveDirectoryContentsAsFilenames, which returns fileName instances.

Warning: this may take a long time to execute.
recursiveDirectoryContentsAsFilenames: return the contents of the directory and all subdirectories
as a collection of filenames.
This excludes any entries for '.' or '..'.
Returns nil for non-existing directories; however, this behavior
may be changed in the near future, to raise an exception instead.
So users of this method better test for existing directory before.
Notice:
this returns the file-names as fileName instances;
see also #recursiveDirectoryContents, which returns strings.

Warning: this may take a long time to execute.

reading-files

binaryContentsOfEntireFile: return the binary contents of the file (as a byteArray);
Raises an error, if the file is unreadable/non-existing.
contents: return the contents of the file as a collection of lines;
Raises an error, if the file is unreadable/non-existing.
See also #contentsOfEntireFile, which returns a string for textFiles.
CAVEAT: bad naming - but req'd for VW compatibility.
contentsAsString: to compensate for the bad naming, use this to make things explicit.
See also #contents, which returns the lines as stringCollection for textFiles.
contentsOfEntireFile: return the contents of the file as a string;
Raises an error, if the file is unreadable/non-existing.
See also #contents, which returns the lines as stringCollection for textFiles.
CAVEAT: bad naming - but req'd for VW compatibility.
readingFileDo: aBlock: create a read-stream on the receiver file, evaluate aBlock, passing that stream as arg,
and return the blocks value.
If the file cannot be opened, an exception is raised or
(old behavior, will vanish:)the block is evaluated with a nil argument.
Ensures that the stream is closed.
readingLinesDo: aBlock: create a read-stream on the receiver file,
evaluate aBlock for each line read from the stream.
If the file cannot be opened, an error is raised.
Ensures that the stream is closed.

special accessing

osName: special - return the OS's name for the receiver.
osNameForAccess: internal - return the OS's name for the receiver to
access its fileInfo.
This may be redefined for systems, where a special suffix must be
added in order to access directories (or others) as a file.
(i.e. under VMS, a '.dir' suffix is added to access directories)
osNameForDirectory: internal - return the OS's name for the receiver to
access it as a directory.
osNameForDirectoryContents: internal - return the OS's name for the receiver to
access it as a directory when reading its contents.
osNameForFile: internal - return the OS's name for the receiver to
access it as a file.

suffixes

addSuffix: aSuffix: return a new filename for the receivers name with a different suffix.
If the name already has a suffix, the new suffix replaces it;
otherwise, the new suffix is simply appended to the name.
hasSuffix: aSuffixString: return true if my suffix is the same as aString.
This cares for systems, where case is ignored in filenames
nameWithoutSuffix: return the receivers name without the suffix.
If the name has no suffix, the original name is returned.
prefix: return my prefix.
The suffix is the namepart after the final period character,
or the empty string, if the name does not contain a period.
prefixAndSuffix: return an array consisting of my prefix and suffix.
The suffix is the namepart after the final period character,
the prefix everything before, except for the period.
The directory name part is stripped off (i.e. the returned prefix
will consist of the files basename only.)
(on some systems, the suffix-character may be different from a period).
For example, foo.bar.baz has a prefix of 'foo.bar' and a suffix of '.baz'.
An exception to the above: if the name starts with the suffixCharacter,
that part is NOT considered a suffix. Thus, '.foorc' has no suffix and a prefix of
'.foorc'.
See also: #withoutSuffix and #withSuffix
Notice:
there is currently no known system which uses other than
the period character as suffixCharacter.
suffix: return my suffix.
The suffix is the namepart after the final period character,
or the empty string, if the name does not contain a period.
withSuffix: aSuffix: return a new filename for the receivers name with a different suffix.
If the name already has a suffix, the new suffix replaces it;
otherwise, the new suffix is simply appended to the name.
withoutSuffix: return a new filename for the receivers name without the suffix.
If the name has no suffix, a filename representing the same file as the receiver is returned.

testing

isFilename: return true, if the receiver is some kind of filename;
false is returned here - the method is redefined from Object.

writing-files

contents: aStringOrCollectionOfLines: create (or overwrite) a file given its contents as a collection of lines.
Raises an error, if the file is unwritable.
writingFileDo: aBlock: create a write-stream on the receiver file, evaluate aBlock, passing that stream as arg,
and return the blocks value.
If the file cannot be opened, an exception is raised.
Ensures that the stream is closed.

Examples:

does a file/directory exist ?:


    |f|

    f := 'foobar' asFilename.
    ^ f exists

is it a directory ?:


    |f|

    f := '/tmp' asFilename.
    ^ f isDirectory.

get the working directory:


    ^ Filename defaultDirectory

get a files full pathname (caring for relative names or symbolic links):


    |f|

    f := '..' asFilename.
    ^ f pathName

get a directories directory:


    |f|

    f := Filename defaultDirectory.
    ^ f directory

get a files directory:


    |f|

    f := './smalltalk' asFilename.
    ^ f directory

getting access & modification times:


    |f|

    f := '/tmp' asFilename.
    ^ f dates

access time only:


    |f|

    f := '/tmp' asFilename.
    ^ f dates at:#accessed

getting all information on a file/directory:


    |f|

    f := '/tmp' asFilename.
    ^ f info

getting a temporary file (unique name):


    |f|

    f := Filename newTemporary.
    ^ f

creating, writing, reading and removing a temporary file:


    |f writeStream readStream|

    f := Filename newTemporary.
    writeStream := f writeStream.
    writeStream nextPutAll:'hello world'.
    writeStream cr.
    writeStream close.

    'contents (as seen by unix''s cat command:' printNL.
    OperatingSystem executeCommand:('cat ' , f pathName).

    readStream := f readStream.
    Transcript showCR:'contents as seen by smalltalk:'.
    Transcript showCR:(readStream upToEnd).
    readStream close.

    f delete.

getting a directories contents:


    |f files|

    f := Filename currentDirectory.
    files := f directoryContents.
    Transcript showCR:'the files are:'.
    Transcript showCR:(files printString).

editing a file:


    |f|

    f := Filename newTemporary.
    (f writeStream) nextPutAll:'hello world'; close.

    f edit

ST/X 6.1.1; WebServer 1.620 at exept:8081; Mon, 21 May 2012 16:38:18 GMT