eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'Filename':

Home

Documentation
www.exept.de
Everywhere
for:
[back]

Class: Filename


Inheritance:

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

Package:
stx:libbasic
Category:
System-Support
Version:
rev: 1.678 date: 2024/03/25 11:52:30
user: stefan
file: Filename.st directory: libbasic
module: stx stc-classLibrary: libbasic

Description:


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

Instances of Filename do not necessarily 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 file's attributes, the class
protocol offers methods for filename completion, to construct paths
(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) spread 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).

copyright

COPYRIGHT (c) 1992 by Claus Gittinger All Rights Reserved This software is furnished under a license and may be used only in accordance with the terms of that license and with the inclusion of the above copyright notice. This software may not be provided or otherwise made available to, or used by, any other person. No title to or ownership of the software is hereby transferred.

Class protocol:

defaults
o  concreteClass
different subclasses of Filename are used for different OperatingSystems;
concreteClass is supposed to return an appropriate non-abstract class.
If I am already a concrete class (i.e. a subclass of Filename), return myself.

Usage example(s):

        Filename concreteClass
        UnixFilename concreteClass
        PCFilename concreteClass

o  defaultClass
marked as obsolete by Stefan Vogel at 22-Mrz-2024

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  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).

Usage example(s):

     Filename defaultTempDirectoryName

o  defaultVolumeName

encoding & decoding
o  decodeFromLiteralArray: anArray
redefined to always answer concrete instances.
There should never exist instances of the abstract class Filename.
- see also #literalAraryEncoding at the instance side

initialization
o  initialize
initialize for the OS we are running on

Usage example(s):

     self initialize

o  initializeConcreteClass
initialize for the OS we are running on

Usage example(s):

     self initializeConcreteClass

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

Usage example(s):

     self reinitialize

instance creation
o  applicationDataDirectory
return the directory, where user-and-application-specific private files are to be
located (ini-files, preferences etc.).
Under windows, something like 'C:\Users\Administrator\AppData\Roaming\<appName>'
is returned, under unix, we use ~/.<appName> (but see details in UnixOS).
For smalltalk itself (the IDE), 'smalltalk' is used as appName.
If the directory does not exist, it is created

Usage example(s):

     Filename applicationDataDirectory

o  applicationDataDirectoryFor: appName
return the directory, where user-and-application-specific private files are to be
located (ini-files, preferences etc.).
Under windows, something like 'C:\Users\Administrator\AppData\Roaming\<appName>'
is returned, under unix, we use ~/.<appName> (but see details in UnixOS).
If the directory does not exist, it is created

Usage example(s):

     Filename applicationDataDirectoryFor:'smalltalk'
     Filename applicationDataDirectoryFor:'expecco'

o  currentDirectory
return a filename for the current directory

Usage example(s):

     Filename currentDirectory

o  defaultDirectory
ST80 compatibility: same as currentDirectory

Usage example(s):

     Filename defaultDirectory

o  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:) whereas this is the OS's original default.
Use this for files which MUST remain the same (stx_sourceCache)

Usage example(s):

     Filename tempDirectory
     Filename defaultTempDirectory

o  desktopDirectory
return your desktop directory.
Under windows, that's the real desktop directory;
under other OperatingSystems, the home directory is returned.

Usage example(s):

     Filename desktopDirectory

o  documentsDirectory
return your documents directory.
Under windows, that's the real 'Documents' or 'My Documents';
under other OperatingSystems, the home directory is returned.

Usage example(s):

     Filename documentsDirectory

o  downloadsDirectory
return the downloads directory.
Some OperatingSystems do not support this - on those,
the documentsDirectory is returned.
Notice: services under windows do not have a user/home and therefore
no downloads directory.

Usage example(s):

     Filename downloadsDirectory

o  findDefaultDirectory
same as #defaultDirectory for ST80 compatibility

o  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.

Usage example(s):

     Filename fromComponents:#('/' 'foo' 'bar' 'baz')
     PCFilename fromComponents:#('/' 'foo' 'bar' 'baz')
     UnixFilename fromComponents:#('/' 'foo' 'bar' 'baz')
     OpenVMSFilename fromComponents:#('foo' 'bar' 'baz')

     Filename fromComponents:#('foo' 'bar' 'baz')
     Filename fromComponents:#('/')

     Filename fromComponents:
         (Filename components:('.' asFilename pathName))

     Filename fromComponents:
         (Filename components:('.' asFilename name))

o  fromUser
show a box to enter a filename.
Return a filename instance or nil (if cancel was pressed).

Usage example(s):

     Filename fromUser

o  homeDirectory
return your homeDirectory.
Some OperatingSystems do not support this - on those, the defaultDirectory
(which is the currentDirectory) is returned.
Notice: services under windows also do not have a home directory.

Usage example(s):

     Filename homeDirectory

o  named: aString
return a filename for a directory named aString.
This is the same as 'aString asFilename'.

Usage example(s):

     Filename named:'/tmp/fooBar'

o  newTemporary
DO NOT USE THIS - IT IS UNSECURE
use FileStream>>#newTemporary for plain files
or Filename >> #newTemporaryDirectory for directories.
(the insecurity is due to a small chance for some other program to open/create
the file, as only a name is generated here. However, chances are small as the name
is reasonably random - but for security critical applications, this may be relevant)

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 STX_TMPDIR, ST_TMPDIR, TMPDIR is set,
its value defines the temp directory.
Notice, that no file is created by this - only a unique name
is generated.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  newTemporaryDirectory
atomically create and return a new unique temporary directory.
The directories returned are named '/tmp/stxtmp_xx_nn'
where xx is our unix process id,
and nn is a unique number, changed 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.

o  newTemporaryDirectoryIn: aDirectoryOrNil
atomically create and return a new unique temporary directory
in another directory, or the current dir.
The directories returned are named '/tmp/stxtmp_xx_nn'
where xx is our unix process id,
and nn is a unique number, changed with every call to this method.

o  newTemporaryDirectoryIn: parentDirectoryNameOrNil nameTemplate: template
return a new unique temporary directory in another directory, or the current dir.
Use this for temporary directories.
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 STX_TMPDIR, ST_TMPDIR, TMPDIR... is set,
its value defines the temp directory.

Usage example(s):

temp directories in '/tmp':

     Filename newTemporaryDirectory
     Filename newTemporaryDirectoryIn:nil nameTemplate:'dir_%1_%2.dir'
     Filename newTemporaryDirectoryIn:(Filename tempDirectory) nameTemplate:'dir_%1_%2.dir'
     Filename newTemporaryDirectoryIn:(Filename tempDirectory) nameTemplate:'dir_%1.dir'

o  newTemporaryIn: aDirectoryOrNil
DO NOT USE THIS - IT IS UNSECURE
use FileStream>>#newTemporaryIn: for plain files
or Filename >> #newTemporaryDirectoryIn: for directories.
(the insecurity is due to a small chance for some other program to open/create
the file, as only a name is generated here. However, chances are small as the name
is reasonably random - but for security critical applications, this may be relevant)

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.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  newTemporaryIn: aDirectoryOrNil nameTemplate: template
DO NOT USE THIS - IT IS UNSECURE
use FileStream>>#newTemporaryIn:nameTemplate: for plain files
or Filename >> #newTemporaryDirectoryIn:nameTemplate: for directories.
(the insecurity is due to a small chance for some other program to open/create
the file, as only a name is generated here. However, chances are small as the name
is reasonably random - but for security critical applications, this may be relevant)

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.
If the template does not contain %-meta characters, and the file already exists,
a sequence of _1, _2,... is appended to the name. This is dangerous, as it does not prevent race
conditions (if two such files are created at the same time).

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.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  nullDevice
return the filename of the nullDevice (if available).
returns nil, if the OperatingSystem does not support this.

Usage example(s):

     Filename nullDevice
     UnixFilename nullDevice
     PCFilename nullDevice

o  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.

o  rootComponents: aCollectionOfDirectoryNames
create & return a new filename from components given in
aCollectionOfDirectoryNames.
An absolute path-filename is returned.

Usage example(s):

     Filename rootComponents:#('/' 'foo' 'bar' 'baz')

     Filename rootComponents:#('foo' 'bar' 'baz')
     PCFilename rootComponents:#('foo' 'bar' 'baz')
     UnixFilename rootComponents:#('foo' 'bar' 'baz')

     Filename rootComponents:#('/')

     Filename rootComponents:
         (Filename components:('.' asFilename pathName))

     Filename rootComponents:
         (Filename components:('.' asFilename name))

o  rootDirectory
return a filename for the root directory

Usage example(s):

     Filename rootDirectory

o  rootDirectoryOnVolume: aVolumeName
return a filename for the root directory on some volume

Usage example(s):

     Filename rootDirectoryOnVolume:'/phys/idefix'
     Filename rootDirectoryOnVolume:'d:'

o  tempDirectory
return the temp directory as a filename.
If any of the environment variables STX_TMPDIR, ST_TMPDIR, TMPDIR,...
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.

Usage example(s):

     Filename tempDirectory
     Filename tempDirectory pathName
     Filename tempDirectory exists
     Filename tempDirectory isWritable
     (Filename tempDirectory construct:'foo') makeDirectory
     (Filename tempDirectory construct:'foo') remove

o  tempDirectory: aFilename
set the default temporary directory.
This allows overwriting the automatically determined tmpDirectory
by a knowledgable stand alone startup program.
Do not use elsewhere (and only if absolutely required)

o  trashDirectoryOrNil
if the underlying OS uses/supports a trash folder,
return it. Otherwise return nil.
Asks the OS for the pathname; for example, on OSX, '~/.Trash' is returned.

Usage example(s):

     Filename trashDirectoryOrNil

o  usersPrivateSmalltalkDirectory
Filename usersPrivateSmalltalkDirectory

misc
o  filterSeps: aFilenameString
ST80 compatibility:
filter out (invalid) separators in aFilenameString.
We recommend using #makeLegalFilename

o  nameWithSpecialExpansions: aString
return the nameString, expanding any OS specific macros.
Here, a ~/ or ~user/ prefix is expanded to the user's home dir (as in csh, bash)

Usage example(s):

     Filename nameWithSpecialExpansions:'~'           
     Filename nameWithSpecialExpansions:'~/work'      
     Filename nameWithSpecialExpansions:'~exept/work'      
     Filename nameWithSpecialExpansions:'~root/work'      
     Filename nameWithSpecialExpansions:'~\work'      
     Filename nameWithSpecialExpansions:'~stefan'     
     Filename nameWithSpecialExpansions:'~stefan\work' 
     Filename nameWithSpecialExpansions:'~stefan/work'  
     Filename nameWithSpecialExpansions:'~foo'         
     Filename nameWithSpecialExpansions:'~foo\bar'     
     Filename nameWithSpecialExpansions:'~foo/bar'     

Usage example(s):

     UnixFilename nameWithSpecialExpansions:'~'
     UnixFilename nameWithSpecialExpansions:'~/work'
     UnixFilename nameWithSpecialExpansions:'~stefan'
     UnixFilename nameWithSpecialExpansions:'~stefan/work'
     UnixFilename nameWithSpecialExpansions:'~foo'
     UnixFilename nameWithSpecialExpansions:'~foo/bar'

Usage example(s):

     PCFilename nameWithSpecialExpansions:'~'
     PCFilename nameWithSpecialExpansions:'~\work'
     PCFilename nameWithSpecialExpansions:'~stefan'
     PCFilename nameWithSpecialExpansions:'~stefan\work'
     PCFilename nameWithSpecialExpansions:'~foo'
     PCFilename nameWithSpecialExpansions:'~foo\bar'

o  suggest: aFilenameString
return a fileNamestring based on the argument,
which is legal on the current platform.

queries
o  currentDirectoryName
return a filename for the current directory

Usage example(s):

     Filename currentDirectoryName

o  defaultDirectoryName
ST80 compatibility: return the defaultDirectories name (as a string)

Usage example(s):

     Filename defaultDirectoryName

o  directorySuffix
Return the OS dependent directory suffix string, or nil if there is none.
The default is nil here, redefined for VMS

o  errorReporter
who knows the signals to report errors?

o  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 ../)

Usage example(s):

     self 
        filenameCompletionFor:'/tm' 
        directory:nil 
        directoriesOnly:true 
        filesOnly:false 
        ifMultiple:[]

o  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 ../)

o  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.

Usage example(s):

     Filename filesMatching:'*'
     Filename filesMatching:'/*'
     Filename filesMatching:'/usr/local/*'

o  isAbstract
return true, if this is not a concrete class

o  isBadCharacter: aCharacter
return true, if aCharacter is unallowed in a filename.

o  isCaseSensitive
return true, if filenames are case sensitive.
We ask the OS about this, to be independent here.
This is not really correct, as the sensitivity may depend on
the paricular mounted file system (NFS, for example).
So we need a query on the instance side

o  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 ?

o  maxComponentLength
return the maximum number of characters a filename component may
be in size. This depends on the OperatingSystem.

o  maxLength
return the maximum number of characters a filename may be in size.
This depends on the OperatingSystem.

o  nullFilename
Return the OS dependent filename for /dev/null, or nil if there is none.
The default is nil here

o  parentDirectoryName
return the name used for the parent directory.
This is '..' for unix and dos-like systems.
(there may be more in the future.

Usage example(s):

     Filename parentDirectoryName

o  separator
return the file/directory separator.
This is to be redefined in concrete classes.

Usage example(s):

     Filename separator
     PCFilename separator

o  separatorString
return the file/directory separator as a string.

Usage example(s):

     Filename separatorString

o  suffixSeparator
return the filename suffix separator.
Usually, this is $. for unix-like and msdos systems
(there is currently no known system, where this differs)

Usage example(s):

      Filename suffixSeparator

o  tempFileNameTemplate
return a template for temporary files.
This is expanded with the current processID and a sequenceNumber
to generate a unique filename.

o  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).

Usage example(s):

     Filename volumes

utilities
o  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/..').

Usage example(s):

     Filename canonicalize:'\home\cg\..\'  
     Filename canonicalize:'\etc\..\etc'   
     Filename canonicalize:'\home\..\..'    

     Filename canonicalize:'/etc/../etc'
     Filename canonicalize:'/home/cg/../'  
     Filename canonicalize:'/home/cg/../././'
     Filename canonicalize:'./home/cg/../././'
     Filename canonicalize:'/home/././cg/../././'
     Filename canonicalize:'/home/././cg/././'
     Filename canonicalize:'/home/cg/../../..'
     Filename canonicalize:'cg/../../..'
     Filename canonicalize:'./'
     Filename canonicalize:'/home/.'
     Filename canonicalize:'/home/../..'
     Filename canonicalize:'//foo'
     Filename canonicalize:'///foo'
     Filename canonicalize:'//foo//bar'

o  canonicalizedNameComponents: aPathString
convert the argument, aPathString to a good format.
This should eliminate useless directory components (i.e. '././')
and useless tree walks (i.e. '../foo/..').

Answer a sequenceable collection of name components.

Usage example(s):

     Filename canonicalizedNameComponents:'/etc/../etc'
     Filename canonicalizedNameComponents:'/home/cg/../'
     Filename canonicalizedNameComponents:'/home/cg/../././'
     Filename canonicalizedNameComponents:'./home/cg/../././'
     Filename canonicalizedNameComponents:'/home/././cg/../././'
     Filename canonicalizedNameComponents:'/home/././cg/././'
     Filename canonicalizedNameComponents:'/home/cg/../../..'
     Filename canonicalizedNameComponents:'cg/../../..'
     Filename canonicalizedNameComponents:'/'
     Filename canonicalizedNameComponents:'./'
     Filename canonicalizedNameComponents:'/.'
     Filename canonicalizedNameComponents:'/home/.'
     Filename canonicalizedNameComponents:'/home'
     Filename canonicalizedNameComponents:'/home/../..'
     Filename canonicalizedNameComponents:'//foo'
     Filename canonicalizedNameComponents:'///foo'
     Filename canonicalizedNameComponents:'//foo//bar'

o  components: aString
separate the pathName given by aString into
a collection containing the directory components and the file's 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. '/').

o  filesMatchingGLOB: pattern
does a GLOB filename expansion.
Generates and returns a possibly empty list of files which match
the given glob pattern

Usage example(s):

     Filename filesMatchingGLOB:'./A*'
     Filename filesMatchingGLOB:'/etc/A*'
     Filename filesMatchingGLOB:'/*/A*'
     '.' asFilename filesMatchingGLOB:'A*'

o  makeLegalBasenameString: aString
convert aString to be a legal basename.
This removes/replaces invalid characters and/or compresses
the name as required by the OS.
It also replaces the directory separator (i.e. '/') by an underscore.
The implementation may change in the future to be more
OS specific.

Usage example(s):

     self makeLegalBasenameString:'hello world'
     self makeLegalBasenameString:c'abc\n' 
     self makeLegalBasenameString:c'a/b/c h i\n'
     self makeLegalBasenameString:c'a\b\c hi\n' 
     self makeLegalBasenameString:c'a\b\c (hi)\n' 
     self makeLegalBasenameString:c'abc_http://(foo bar)\n' 

o  makeLegalFilenameString: aString
convert aString 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.

Usage example(s):

     self makeLegalFilenameString:'hello world'
     self makeLegalFilenameString:'\a\b\c h i'
     self makeLegalFilenameString:'/a/b/c h i'
     self makeLegalFilenameString:c'abc\n' 

o  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.

Usage example(s):

     Filename nameFromComponents:#('/' 'foo' 'bar' 'baz')
     Filename nameFromComponents:#('foo' 'bar' 'baz')
     Filename nameFromComponents:#('/')

     |comps|
     comps := Filename components:'/foo/bar/baz'.
     Filename nameFromComponents:comps

     |comps|
     comps := Filename components:'\foo\bar\baz'.
     Filename nameFromComponents:comps

     |comps|
     comps := Filename components:'c:\foo\bar\baz'.
     Filename nameFromComponents:comps

     |comps|
     comps := Filename components:'foo\bar\baz'.
     Filename nameFromComponents:comps

     |comps|
     comps := Filename components:'foo'.
     Filename nameFromComponents:comps

     |comps|
     comps := Filename components:'\'.
     Filename nameFromComponents:comps

     |comps|
     comps := Filename components:'c:\'.
     Filename nameFromComponents:comps

o  possiblyQuotedPathname: aPath
return a filename path usable as command line argument,
by quoting in double quotes if there are any embedded special characters.
On Unix systems, special characters might also be prefixed by a backslash character.

Usage example(s):

     Filename possiblyQuotedPathname:'/tmp/bla'
     Filename possiblyQuotedPathname:'/tmp directory/bla'
     Filename possiblyQuotedPathname:'/tmp directory/bla file'

o  readingFile: aPathName do: aBlock
Create a read stream on a file, evaluate aBlock, passing that stream,
and return the block's value.
Ensures that the stream is closed.


Instance protocol:

Compatibility-VW5.4
o  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.

o  asLogicalFileSpecification

o  canBeWritten
same as isWritable - for ST-80 compatibility

Usage example(s):

     '/foo/bar' asFilename canBeWritten
     '/tmp' asFilename canBeWritten
     'Makefile' asFilename canBeWritten

o  definitelyExists
for now - a kludge

o  delete
remove the file - same as remove, for ST-80 compatibility

o  extension
return the receiver's extension;
that is the characters from and including
the last period or nil, if there is none.
SImilar to suffix, but includes the period in the returned string

Usage example(s):

     'foo.html' asFilename extension    
     'foo.bar' asFilename extension
     'foo.bar.baz' asFilename extension 
     'foo.' asFilename extension
     'foo' asFilename extension
     '.login' asFilename extension

o  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)

Usage example(s):

     Filename currentDirectory head
     'Makefile' asFilename head
     '/foo/bar/baz.st' asFilename head

o  tail
the file's name without directory prefix as a string.
An alias for baseName, for ST-80 compatiblity.

Usage example(s):

     Filename currentDirectory tail
     'Makefile' asFilename tail
     '/foo/bar/baz.st' asFilename tail

o  tail: nComponents
return the last n components of myself.
- that's 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.

Usage example(s):

     '/foo/bar' asFilename tail:1
     '/foo/bar' asFilename tail:2
     '/foo/bar' asFilename tail:3
     '/foo/bar.cc' asFilename tail:2
     '.' asFilename tail:3
     '..' asFilename tail:3
     '../..' asFilename tail:2
     '../../libbasic' asFilename tail:2
     '../../libbasic' asFilename asCanonicalizedFilename tail:2
     '../../libpr' asFilename tail:2
     '../../libbasic/Object.st' asFilename asCanonicalizedFilename tail:2
     '/' asFilename tail:2
     '\' asFilename tail:2
     'c:\' asFilename tail:2
     '\\idefix' asFilename tail:2

attribute setter
o  clearHidden
ignored here
- redefined for windows to clear the file's hidden flag

o  setHidden
ignored here
- redefined for windows to set the file's hidden flag

comparing
o  < aFilename
compare file names - used for sorting

o  = aFilename
return true, if the argument represents the same filename

o  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.

Usage example(s):

     |s|

     s := 'testFile1' asFilename writeStream.
     s nextPutAll:'11111'.
     s nextPutAll:'22222'.
     s nextPutAll:'33333'.
     s close.

     s := 'testFile2' asFilename writeStream.
     s nextPutAll:'11111'.
     s nextPutAll:'22222'.
     s nextPutAll:'33333'.
     s close.

     ('testFile1' asFilename contentsIsPrefixOf:'testFile2'  ) ifFalse:[self halt].

     s := 'testFile2' asFilename writeStream.
     s nextPutAll:'11111'.
     s nextPutAll:'22222'.
     s nextPutAll:'33333'.
     s nextPutAll:'44444'.
     s close.

     ('testFile1' asFilename contentsIsPrefixOf:'testFile2'  ) ifFalse:[self halt].

     s := 'testFile2' asFilename writeStream.
     s nextPutAll:'11111'.
     s nextPutAll:'22222'.
     s close.

     ('testFile1' asFilename contentsIsPrefixOf:'testFile2'  ) ifTrue:[self halt].

     s := 'testFile2' asFilename writeStream.
     s nextPutAll:'11111'.
     s nextPutAll:'22222'.
     s nextPutAll:'33334'.
     s close.

     ('testFile1' asFilename contentsIsPrefixOf:'testFile2'  ) ifTrue:[self halt].

o  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.

Usage example(s):

     |s|

     s := 'testFile1' asFilename writeStream.
     s nextPutAll:'11111'.
     s nextPutAll:'22222'.
     s nextPutAll:'33333'.
     s close.

     s := 'testFile2' asFilename writeStream.
     s nextPutAll:'11111'.
     s nextPutAll:'22222'.
     s nextPutAll:'33333'.
     s close.

     ('testFile2' asFilename contentsStartsWithContentsOf:'testFile1'  ) ifFalse:[self halt].

     s := 'testFile2' asFilename writeStream.
     s nextPutAll:'11111'.
     s nextPutAll:'22222'.
     s nextPutAll:'33333'.
     s nextPutAll:'44444'.
     s close.

     ('testFile2' asFilename contentsStartsWithContentsOf:'testFile1'  ) ifFalse:[self halt].

     s := 'testFile2' asFilename writeStream.
     s nextPutAll:'11111'.
     s nextPutAll:'22222'.
     s close.

     ('testFile2' asFilename contentsStartsWithContentsOf:'testFile1'  ) ifTrue:[self halt].

     s := 'testFile2' asFilename writeStream.
     s nextPutAll:'11111'.
     s nextPutAll:'22222'.
     s nextPutAll:'33334'.
     s close.

     ('testFile2' asFilename contentsStartsWithContentsOf:'testFile1'  ) ifTrue:[self halt].

o  hash
return an integer useful as a hash-key

Usage example(s):

We keep asUppercase for backward compatibility (maybe someone stored hash keys)

o  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 file's actual contents; not the filenames.

Usage example(s):

     'Make.proto' asFilename sameContentsAs:'Makefile'
     'Make.proto' asFilename sameContentsAs:'Make.proto'

Usage example(s):

     |s|

     s := 'testFile1' asFilename writeStream.
     s nextPutAll:'11111'.
     s nextPutAll:'22222'.
     s nextPutAll:'33333'.
     s close.

     s := 'testFile2' asFilename writeStream.
     s nextPutAll:'11111'.
     s nextPutAll:'22222'.
     s nextPutAll:'33333'.
     s close.

     ('testFile1' asFilename sameContentsAs:'testFile2'  ) ifFalse:[self halt].

     s := 'testFile2' asFilename writeStream.
     s nextPutAll:'11111'.
     s nextPutAll:'22222'.
     s nextPutAll:'33333'.
     s nextPutAll:'44444'.
     s close.

     ('testFile1' asFilename sameContentsAs:'testFile2'  ) ifTrue:[self halt].

     s := 'testFile2' asFilename writeStream.
     s nextPutAll:'11111'.
     s nextPutAll:'22222'.
     s close.

     ('testFile1' asFilename sameContentsAs:'testFile2'  ) ifTrue:[self halt].

     s := 'testFile2' asFilename writeStream.
     s nextPutAll:'11111'.
     s nextPutAll:'22222'.
     s nextPutAll:'33334'.
     s close.

     ('testFile1' asFilename sameContentsAs:'testFile2'  ) ifTrue:[self halt].

converting
o  absolutePathName
return the receiver's absolute pathname as a string.
This returns an absolute path even if the file does not exist
(in contrast to pathName, chich returns it unchanged in that case)

Usage example(s):

     '.' asFilename                        => PCFilename('.')
     '.' asFilename pathName               => 'C:\Users\mobile\cg_work\stx\projects\smalltalk'
     '.' asFilename asAbsoluteFilename     => PCFilename('C:\Users\mobile\cg_work\stx\projects\smalltalk')
     'c:' asFilename asAbsoluteFilename    => PCFilename('C:\Users\mobile\cg_work\stx\projects\smalltalk')
     'foo' asFilename                      => PCFilename('foo')
     'foo' asFilename asAbsoluteFilename   => PCFilename('C:\Users\mobile\cg_work\stx\projects\smalltalk\foo')
     './foo' asFilename                    => PCFilename('.\foo')
     './foo' asFilename asAbsoluteFilename => PCFilename('C:\Users\mobile\cg_work\stx\projects\smalltalk\foo')
     './foo' asFilename pathName           => '.\foo'
     '../foo/bar' asFilename               => PCFilename('..\foo\bar')
     '../../foo/bar' asFilename asAbsoluteFilename => PCFilename('C:\Users\mobile\cg_work\stx\foo\bar')
     '../../foo/bar' asFilename absolutePathName => 'C:\Users\mobile\cg_work\stx\foo\bar'
     '../../foo/bar' asFilename pathName         => '..\..\foo\bar'
     '~' asFilename pathName               => 'C:\Users\mobile'

    slash and backslash are both trated alike on windows:
     '~/foo' asFilename pathName           => 'C:\Users\mobile\foo'
     '~/foo' asFilename asAbsoluteFilename => PCFilename('C:\Users\mobile\foo')
     '.\foo' asFilename                    => PCFilename('.\foo')
     '.\foo' asFilename asAbsoluteFilename => PCFilename('C:\Users\mobile\cg_work\stx\projects\smalltalk\foo')
     '.\foo' asFilename pathName           => PCFi'.\foo'
     '~' asFilename pathName               => 'C:\Users\mobile'
     '~\foo' asFilename pathName           => 'C:\Users\mobile\foo'
     '~\foo' asFilename asAbsoluteFilename => PCFilename('C:\Users\mobile\foo')

o  asAbsoluteFilename
return the receiver converted to a filename with
an absolute pathname.

This makes sense, if you want to send #asString or #printString
or #hash or #= to it.

Usage example(s):

     '.' asFilename                        => PCFilename('.')
     '.' asFilename pathName               => 'C:\Users\mobile\cg_work\stx\projects\smalltalk'
     '.' asFilename asAbsoluteFilename     => PCFilename('C:\Users\mobile\cg_work\stx\projects\smalltalk')
     'c:' asFilename asAbsoluteFilename    => PCFilename('C:\Users\mobile\cg_work\stx\projects\smalltalk')
     'foo' asFilename                      => PCFilename('foo')
     'foo' asFilename asAbsoluteFilename   => PCFilename('C:\Users\mobile\cg_work\stx\projects\smalltalk\foo')
     './foo' asFilename                    => PCFilename('.\foo')
     './foo' asFilename asAbsoluteFilename => PCFilename('C:\Users\mobile\cg_work\stx\projects\smalltalk\foo')
     './foo' asFilename pathName           => PCFi'.\foo'
     '~' asFilename pathName               => 'C:\Users\mobile'
     '/..' asFilename name                 => '\..'
     '/..' asFilename pathName             => 'C:\'

    slash and backslash are both trated alike on windows:
     '~/foo' asFilename pathName           => 'C:\Users\mobile\foo'
     '~/foo' asFilename asAbsoluteFilename => PCFilename('C:\Users\mobile\foo')
     '.\foo' asFilename                    => PCFilename('.\foo')
     '.\foo' asFilename asAbsoluteFilename => PCFilename('C:\Users\mobile\cg_work\stx\projects\smalltalk\foo')
     '.\foo' asFilename pathName           => PCFi'.\foo'
     '~' asFilename pathName               => 'C:\Users\mobile'
     '~\foo' asFilename pathName           => 'C:\Users\mobile\foo'
     '~\foo' asFilename asAbsoluteFilename => PCFilename('C:\Users\mobile\foo')
     'c:\' asFilename asAbsoluteFilename   => PCFilename('c:\')
     'c:\..' asFilename asAbsoluteFilename => PCFilename('c:\')
     'c:\..\foo' asFilename asAbsoluteFilename => PCFilename('c:\foo')
     'c:\.\foo' asFilename asAbsoluteFilename  => PCFilename('c:\foo')

o  asAutoDeletedFilename
will automatically delete myself, when no longer referenced

o  asBackupFilename
return the receiver converted to a backup filename.

Usage example(s):

     'bla' asFilename asBackupFilename                          => PCFilename('bla.bak')
     '/home/user/directory/bla' asFilename asBackupFilename     => PCFilename('\home\user\directory\bla.bak') 
     'directory/bla' asFilename asBackupFilename                => PCFilename('directory\bla.bak')

o  asCanonicalizedFilename
return the receiver converted to a filename without intermediate ..'s and .'s
(similar to an absolute pathname, but symlinks are not resolved).

Usage example(s):

      'c:\test\work' asFilename asCanonicalizedFilename
      '/test/work' asFilename asCanonicalizedFilename

o  asFileURL
( an extension from the stx:libhtml package )
return a file URL-object from myself

o  asFilename
return the receiver converted to a filename; here, that's the receiver itself.

o  asNonBackupFilename
return the receiver converted to a backup filename.

Usage example(s):

     'bla.bak' asFilename asNonBackupFilename
     '/home/user/directory/bla.bak' asFilename asNonBackupFilename
     'directory/bla.bak' asFilename asNonBackupFilename
     'directory/bla~' asFilename asNonBackupFilename

o  asString
return the receiver converted to a string

o  asURI
return the receiver converted to a file URI

o  asURL
( an extension from the stx:libhtml package )
return an URL-object from myself.
The URL has nil as method instead of #file.

Usage example(s):

     '/tmp/index.html' asFilename asURL
     '/tmp/index.html' asFilename asFileURL

o  asUniqueFilename
If a file by my name already exists, return a new filename with a unique string appended.
Here, a somewhat naive strategy is performed, by trying _1, _2,...
until a new name is generated.

Usage example(s):

     'aaa.txt' asFilename contents:'bla'.
     'aaa.1.2.3.apk.txt' asFilename asUniqueFilename contents:'bla2'.
     'aaa.txt' asFilename asUniqueFilename contents:'bla3'.
     'aaa.txt' asFilename asUniqueFilename contents:'bla4'.
     #('aaa.txt' 'aaa_1.txt' 'aaa_2.txt' 'aaa_3.txt') do:[:f | f asFilename delete].  

o  components
return the receiver's filename components - that is the name of each directory
along the pathName (that DOES include the root directory)

Usage example(s):

     '.' asFilename asAbsoluteFilename components
     'Makefile' asFilename asAbsoluteFilename components

o  makeLegalBasename
convert the receiver's name to be a legal basename.
This removes/replaces invalid characters and/or compresses
the name as required by the OS.
It also replaces the directory separator (i.e. '/') by an underscore.
The implementation may change in the future to be more
OS specific.

o  makeLegalFilename
convert the receiver's 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.

Usage example(s):

     'hello world' asFilename makeLegalFilename
     '\a\b\c h i' asFilename makeLegalFilename
      ('abc' copyWith:Character return) asFilename makeLegalFilename

o  withEncoding: encodingSymbol
dummy for now - for ST80 compatibility

encoding & decoding
o  literalArrayEncoding
redefined, so that encoded values may be restored
appropriately on a different OS.
See also: Filename class >> #decodeFromLiteralArray:

Usage example(s):

     '.' asFilename literalArrayEncoding.
     '.' asFilename literalArrayEncoding decodeAsLiteralArray.

enumerating-contents
o  allDirectoriesDo: aOneArgBlock
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.

Usage example(s):

     '.' asFilename allDirectoriesDo:[:fn | Transcript showCR:fn name].
     '.' asFilename directoriesDo:[:fn | Transcript showCR:fn name].

o  allParentDirectoriesDo: aOneArgBlock
evaluate aBlock for all (recursive) directories along the parent directory path.
The block is invoked with a filename-arguments.

Usage example(s):

     '.' asFilename allParentDirectoriesDo:[:fn | Transcript showCR:fn pathName].

o  directoriesDo: aOneArgBlock
evaluate aBlock for directories contained 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 '..'.
OpenError is raised if I represent a non-existent or non-readable directories.
So users of this method better test for existing directory before.

Usage example(s):

     '.' asFilename directoriesDo:[:fn | Transcript showCR:fn baseName].

o  directoryContentsAsFilenamesDo: aOneArgBlock
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 '..'.
An OpenError exception is raised it the directory does not exist or is not readable.
So users of this method better test for existing directory before.
Notice: this enumerates fileName objects; see also
#directoryContentsDo:, which enumerates strings.

Usage example(s):

     '.' asFilename directoryContentsAsFilenamesDo:[:fn | Transcript showCR:fn pathName].

o  directoryContentsDo: aOneArgBlock
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 OpenError exception is raised it the directory does not exist or is not readable.
So users of this method better test for existing directory before.
Notice: this enumerates strings; see also
#directoryContentsAsFilenamesDo:, which enumerates fileName objects.

Usage example(s):

     '.' asFilename directoryContentsDo:[:fn | Transcript showCR:fn].


     'doeSnotExIST' asFilename directoryContentsDo:[:fn | Transcript showCR:fn].

     [
        'doeSnotExIST' asFilename directoryContentsDo:[:fn | Transcript showCR:fn].
     ] on:OpenError do:[:ex| ex proceed]

o  filesDo: aOneArgBlock
evaluate aBlock for all regular files (i.e. subdirs are ignored)
contained in the directory represented by the receiver.

Usage example(s):

     '.' asFilename filesDo:[:f | Transcript showCR:f].

o  filesMatchingGLOB: pattern do: aOneArgBlock
Interpreting pattern as a GLOB pattern,
evaluate aBlock for each file in me, which matches.
Returns the number of matches.

Usage example(s):

     '..' asFilename filesMatchingGLOB:'A*' do:[:fn | Transcript showCR:fn].
     '../..' asFilename filesMatchingGLOB:'lib*/*.st' do:[:fn | Transcript showCR:fn].
     '/Library/Java/JavaVirtualMachines' asFilename filesMatchingGLOB:'*.jdk' do:[:fn | Transcript showCR:fn].    

o  filesMatchingGLOBComponents: patternComponents do: aOneArgBlock
patternComponents is a component-collection with possible GLOB patterns.
Evaluate aBlock for each file in me, which matches.
Returns the number of matches

o  filesMatchingGLOBDo: aOneArgBlock
Interpreting myself as a GLOB pattern,
evaluate aBlock for each file which matches.

Usage example(s):

     '/etc/A*' asFilename filesMatchingGLOBDo:[:fn | Transcript showCR:fn].
     '/etc/a*' asFilename filesMatchingGLOBDo:[:fn | Transcript showCR:fn].
     '../A*' asFilename filesMatchingGLOBDo:[:fn | Transcript showCR:fn].
     '../../lib*/*.st' asFilename filesMatchingGLOBDo:[:fn | Transcript showCR:fn].
     '../../lib*/[A-D]*.st' asFilename filesMatchingGLOBDo:[:fn | Transcript showCR:fn].
     '../../*/[A-D]*.st' asFilename filesMatchingGLOBDo:[:fn | Transcript showCR:fn].
     '../../*/*/[A-D]*.st' asFilename filesMatchingGLOBDo:[:fn | Transcript showCR:fn].
     '../../*java*/*/[A-D]*.st' asFilename filesMatchingGLOBDo:[:fn | Transcript showCR:fn].
     '../../*java*/*/Ary.st' asFilename filesMatchingGLOBDo:[:fn | Transcript showCR:fn].
     '/*/A*' asFilename filesMatchingGLOBDo:[:fn | Transcript showCR:fn].
     '*/A*' asFilename filesMatchingGLOBDo:[:fn | Transcript showCR:fn].
     '../*/A*' asFilename filesMatchingGLOBDo:[:fn | Transcript showCR:fn].
     './*/A*' asFilename filesMatchingGLOBDo:[:fn | Transcript showCR:fn].
     './*/*' asFilename filesMatchingGLOBDo:[:fn | Transcript showCR:fn].
     '././A*' asFilename filesMatchingGLOBDo:[:fn | Transcript showCR:fn].

o  filesWithSuffix: suffix do: aOneArgBlock
evaluate aBlock for all regular files with a given suffix
contained in the directory represented by the receiver.
(i.e. subdirs are ignored)

Usage example(s):

     '.' asFilename filesWithSuffix:'so' do:[:f | Transcript showCR:f].

o  recursiveDirectoryContentsAsFilenamesDo: aOneArgBlock
evaluate aBlock for all files and directories found under the receiver.
The block is invoked with the filenames as 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).

Usage example(s):

     '.' asFilename recursiveDirectoryContentsAsFilenamesDo:[:f | Transcript showCR:f]

o  recursiveDirectoryContentsAsFilenamesDo: aOneArgBlock filterForVisitingDirectories: filterOrNil
evaluate aBlock for all files and directories found under the receiver.
The block is invoked with the filenames as argument.
The walk is bread-first.
This excludes any entries for '.' or '..'.
Subdirectory files are included with a relative pathname.
If filterOrNil is nonNil, it is passed every directory about to be walked into;
if it returns false, that directory is not entered.
Warning: this may take a long time to execute
(especially with deep and/or remote fileSystems).

Usage example(s):

     '.' asFilename recursiveDirectoryContentsAsFilenamesDo:[:f | Transcript showCR:f]

o  recursiveDirectoryContentsAsFilenamesDo: aOneArgBlock filterForVisitingDirectories: filterOrNil sortedBy: sortBlockOrNil
evaluate aBlock for all files and directories found under the receiver.
The block is invoked with the filenames as argument.
The walk is bread-first.
This excludes any entries for '.' or '..'.
Subdirectory files are included with a relative pathname.
If filterOrNil is nonNil, it is passed every directory about to be walked into;
if it returns false, that directory is not entered.
Warning: this may take a long time to execute
(especially with deep and/or remote fileSystems).

Usage example(s):

     '.' asFilename recursiveDirectoryContentsAsFilenamesDo:[:f | Transcript showCR:f]

o  recursiveDirectoryContentsDo: aOneArgBlock
evaluate aBlock for all files and directories found under the receiver.
The block is invoked with the relative filenames as 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).

Usage example(s):

     '.' asFilename recursiveDirectoryContentsDo:[:f | Transcript showCR:f]

o  recursiveDirectoryContentsDo: aOneArgBlock 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 '..'.
The argument to aBlock is a pathname relative to aPrefix.
A proceedable exception is raised forn non-accessible directories.
Warning: this may take a long time to execute (especially with deep and/or remote fileSystems).

Usage example(s):

     '.' asFilename recursiveDirectoryContentsDo:[:f | Transcript showCR:f]
     '/etc' asFilename recursiveDirectoryContentsDo:[:f | Transcript showCR:f]

o  recursiveDirectoryContentsDo: aOneArgBlock filterForVisitingDirectories: filterOrNil
evaluate aBlock for all files and directories found under the receiver.
The block is invoked with the relative filenames as string-argument.
The walk is bread-first.
This excludes any entries for '.' or '..'.
Subdirectory files are included with a relative pathname.
If filterOrNil is nonNil, it is passed every directory about to be walked into;
if it returns false, that directory is not entered.
Warning: this may take a long time to execute
(especially with deep and/or remote fileSystems).

Usage example(s):

     '.' asFilename recursiveDirectoryContentsDo:[:f | Transcript showCR:f]

o  recursiveDirectoryContentsDo: aOneArgBlock filterForVisitingDirectories: filterOrNil sortedBy: sortBlockOrNil
evaluate aBlock for all files and directories found under the receiver.
The block is invoked with the relative filenames as string-argument.
The walk is bread-first.
This excludes any entries for '.' or '..'.
Subdirectory files are included with a relative pathname.
If filterOrNil is nonNil, it is passed every directory about to be walked into;
if it returns false, that directory is not entered.
Warning: this may take a long time to execute
(especially with deep and/or remote fileSystems).

Usage example(s):

     '.' asFilename recursiveDirectoryContentsDo:[:f | Transcript showCR:f]

o  recursiveDirectoryContentsWithPrefix: aPrefix filesDo: fileBlock directoriesDo: dirBlock
evaluate aBlock for all files and directories found under the receiver.
The blocks are invoked with a relative pathname as string-argument.
The walk is breadth-first (first files, then directories).
This excludes any entries for '.' or '..'.
A proceedable exception is raised for non-accessible directories.
Warning: this may take a long time to execute
(especially with deep and/or remote fileSystems).

Usage example(s):

     '.' asFilename 
        recursiveDirectoryContentsWithPrefix:'bla'
        filesDo:[:f | Transcript show:'file: '; showCR:f]
        directoriesDo:[:f | Transcript show:'dir: '; showCR:f]

o  recursiveDirectoryContentsWithPrefix: aPrefix filesDo: fileBlock directoriesDo: dirBlock filterForVisitingDirectories: filterOrNil
evaluate aBlock for all files and directories found under the receiver.
The blocks are invoked with a relative pathname as string-argument.
The walk is breadth-first (first files, then directories).
This excludes any entries for '.' or '..'.
A proceedable exception is raised for non-accessible directories.
If filterOrNil is nonNil, it is passed every directory about to be walked into;
if it returns false, that directory is not entered.

Warning: this may take a long time to execute
(especially with deep and/or remote fileSystems).

Usage example(s):

     '.' asFilename 
        recursiveDirectoryContentsWithPrefix:'bla'
        filesDo:[:f | Transcript show:'file: '; showCR:f]
        directoriesDo:[:f | Transcript show:'dir: '; showCR:f]

o  recursiveDirectoryContentsWithPrefix: aPrefix filesDo: fileBlock directoriesDo: dirBlock filterForVisitingDirectories: filterOrNil sortedBy: sortByBlockOrNil
evaluate aBlock for all files and directories found under the receiver.
The blocks are invoked with a relative pathname as string-argument.
The walk is breadth-first (first files, then directories).
This excludes any entries for '.' or '..'.
A proceedable exception is raised for non-accessible directories.
If filterOrNil is nonNil, it is passed every directory about to be walked into;
if it returns false, that directory is not entered.

By default, names are enumerated in the order they appear in the folder,
(which is not required to be sorted).
If sortedByBlock is non nil, it is applied with the fileNames to sort them
(usually a block is provided to sort by name, aka [:a :b | a name < b name]
or by caseless name, like [:a :b | a name caselessBefore: b name]
or by fileSize, like [:a :b | a fileSize < b fileSize] )
or by modificationTime)

Warning: this may take a long time to execute
(especially with deep and/or remote fileSystems).

Usage example(s):

     '.' asFilename 
        recursiveDirectoryContentsWithPrefix:''
        filesDo:[:f | Transcript show:'file: '; showCR:f]
        directoriesDo:[:f | Transcript show:'dir: '; showCR:f]
        filterForVisitingDirectories:[:f | (f baseName = 'CVS') not]
        sortedBy:[:a :b | a baseName < b baseName]

o  recursiveFilesDo: fileBlock directoriesDo: dirBlock filterForVisitingDirectories: filterOrNil
evaluate aBlock for all files and directories found under the receiver.
The blocks are invoked with a relative pathname as string-argument.
The walk is depth-first (but files first, then directories).
This excludes any entries for '.' or '..'.
A proceedable exception is raised for non-accessible directories.
If filterOrNil is nonNil, it is passed every directory about to be walked into;
if it returns false, that directory is not entered.
Warning: this may take a long time to execute
(especially with deep and/or remote fileSystems).
Names are enumerated in the order they appear in the folder,
(which is not required to be sorted).

Usage example(s):

     '.' asFilename 
        recursiveFilesDo:[:f | Transcript show:'file: '; showCR:f]
        directoriesDo:[:f | Transcript show:'dir: '; showCR:f]
        filterForVisitingDirectories:nil

o  recursiveFilesDo: fileBlock directoriesDo: dirBlock filterForVisitingDirectories: filterOrNil sortedBy: sortedByBlock
evaluate aBlock for all files and directories found under the receiver.
The blocks are invoked with a relative pathname as string-argument.

The walk is breadth-first (files first, then directories).
This excludes any entries for '.' or '..'.
A proceedable exception is raised for non-accessible directories.

If filterOrNil is nonNil, it is passed every directory about to be walked into;
if it returns false, that directory is not entered.

By default, names are enumerated in the order they appear in the folder,
(which is not required to be sorted).
If sortedByBlock is non nil, it is applied with the fileNames to sort them
(usually a block is provided to sort by name, aka [:a :b | a name < b name]
or by caseless name, like [:a :b | a name caselessBefore: b name]
or by fileSize, like [:a :b | a fileSize < b fileSize] )
or by modificationTime)

Warning: this may take a long time to execute
(especially with deep and/or remote fileSystems).

Usage example(s):

     '.' asFilename 
        recursiveFilesDo:[:f | Transcript show:'file: '; showCR:f]
        directoriesDo:[:f | Transcript show:'dir: '; showCR:f]
        filterForVisitingDirectories:nil
        sortedBy:[:a :b | a name caselessBefore: b name]

     '.' asFilename 
        recursiveFilesDo:[:f | Transcript showCR:f]
        directoriesDo:[:f | Transcript showCR:f]
        filterForVisitingDirectories:nil
        sortedBy:[:a :b | a name caselessBefore: b name]

     '../../..' asFilename 
        recursiveFilesDo:[:f | Transcript show:'file: '; showCR:f]
        directoriesDo:[:f | Transcript show:'dir: '; showCR:f]
        filterForVisitingDirectories:nil
        sortedBy:[:a :b | a name caselessBefore: b name]

     '../../..' asFilename 
        recursiveFilesDo:[:f | Transcript show:'file: '; showCR:f]
        directoriesDo:[:f | Transcript show:'dir: '; showCR:f]
        filterForVisitingDirectories:nil
        sortedBy:nil

o  withAllDirectoriesDo: aOneArgBlock
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 '..'.
OpenError is raised if the name I represent does not exist or is not readable.
So users of this method better test for existing directory before.

Usage example(s):

     '.' asFilename withAllDirectoriesDo:[:fn | Transcript showCR:fn name].
     'IdoNOTexist' asFilename withAllDirectoriesDo:[:fn | Transcript showCR:fn name].
     '/etc/hosts' asFilename withAllDirectoriesDo:[:fn | Transcript showCR:fn name].

error handling
o  fileCreationError: filename
report an error that some file could not be created

o  reportError: string with: filenameOrNilForSelf
report an error

file access
o  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.

Usage example(s):

     |s|

     s := '/tmp/foo' asFilename writeStream.
     s nextPutAll:'1234567890'.
     s close.

     s := '/tmp/foo' asFilename appendingWriteStream.
     s nextPutAll:'abcdef'.
     s close.

     '/tmp/foo' asFilename contents

o  existingReadWriteStream
return a stream for read/write the file represented by the receiver.
If the file does not already exist, an exception is raised.

Usage example(s):

     '/tmp/blaFaselQuall666666' asFilename remove.
     '/tmp/blaFaselQuall666666' asFilename existingReadWriteStream.

Usage example(s):

     |s|
     s := '/tmp/foo' asFilename readWriteStream.
     s nextPutAll:'1234567890'; close.
     s := '/tmp/foo' asFilename existingReadWriteStream.
     s nextPutAll:'abcdef'; close.

     '/tmp/foo' asFilename contents inspect.
     '/tmp/foo' asFilename remove

o  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.

Usage example(s):

     |s|

     s := '/tmp/foo' asFilename writeStream.
     s nextPutAll:'1234567890'.
     s close.

     s := '/tmp/foo' asFilename newReadWriteStream.
     s nextPutAll:'12345'.
     s close.

     '/tmp/foo' asFilename contents

o  openWithMode: anArrayOrString
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.

Usage example(s):

     |s|

     s := '/tmp/foo' asFilename openWithMode:'r+'.
     s nextPutAll:'1234567890'.
     s close.


     '/tmp/foo' asFilename contents

o  readStream
Return a stream for reading from the file represented by the receiver.
Raises an error if the file does not exist.

Usage example(s):

      '/tmp/foo' asFilename readStream

o  readStreamIfAbsent: errorAction
Return a stream for reading from the file represented by the receiver.
Return the value from errorAction if the file does not exist.

Usage example(s):

     '/tmp/foo' asFilename readStreamIfAbsent:[nil]  

o  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.

Usage example(s):

     |s|

     s := '/tmp/foo' asFilename writeStream.
     s nextPutAll:'1234567890'.
     s close.

     s := '/tmp/foo' asFilename readWriteStream.
     s nextPutAll:'abcdef'.
     s close.

     '/tmp/foo' asFilename contents
     '/tmp/foo' asFilename remove

o  utf8ReadStream
Return a stream for reading UTF from the file represented by the receiver.
Raises an error if the file does not exist.

Usage example(s):

      '/tmp/foo' asFilename utf8ReadStream

o  utf8WriteStream
return a stream for writing UTF to the file represented by the receiver.
If the file does not already exist, it is created;
if it does exist, it is truncated.

Usage example(s):

     |s|

     s := '/tmp/foo' asFilename utf8WriteStream.
     s nextPut:(Character value: 16r2f25 ).
     s nextPut:(Character value: 16r20ac ).
     s close.

o  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.

Usage example(s):

     '/tmp/foo' asFilename writeStream

Usage example(s):

     |s|

     s := '/tmp/foo' asFilename writeStream.
     s nextPutAll:'1234567890'.
     s close.

     s := '/tmp/foo' asFilename writeStream.
     s nextPutAll:'12345'.
     s close.

     '/tmp/foo' asFilename contents

file access - backward compatibility
o  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.

o  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.

o  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.

Usage example(s):

     '/tmp/foo' asFilename readStreamOrNil
     '/tmp/foo' asFilename readStream

o  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.

o  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.

Usage example(s):

     '/etc/foo' asFilename writeStreamOrNil

file access rights
o  accessRights
return the access rights of the file as opaque data
(SmallInteger in unix/linux)

Usage example(s):

     'Make.proto' asFilename accessRights printStringRadix:8
     'foo' asFilename accessRights printStringRadix:8

o  accessRights: opaqueData
set the access rights of the file to opaqueData,
which is normally retrieved by Filename>>#accessRights.

Usage example(s):

     |rights|

     rights := 'Make.proto' asFilename accessRights.
     'Make.proto' asFilename accessRights:rights.

o  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.

Usage example(s):

     'foo' asFilename writeStream close.
     'foo' asFilename addAccessRights:#(readUser readGroup readOthers).
     'foo' asFilename addAccessRights:#(writeUser writeGroup writeOthers).
     'foo' asFilename addAccessRights:#(executeUser executeGroup executeOthers).

o  makeExecutable
make the file executable - you must have permission to do so.
For directories, execution means: 'allow changing into it'

o  makeExecutableForAll
make the file executable for all - you must have permission to do so.
For directories, execution means: 'allow changing into it'

o  makeExecutableForGroup
make the file executable for the group - you must have permission to do so.
For directories, execution means: 'allow changing into it'

o  makeReadable
make the file readable for the owner - you must have permission to do so.

o  makeReadableForAll
make the file readable for all - you must have permission to do so.

o  makeReadableForGroup
make the file readable for the group - you must have permission to do so.

o  makeUnwritable
make the file unwritable for all - you must have permission to do so.

o  makeWritable
make the file writableable for all - you must have permission to do so.

o  makeWritableForAll
make the file writable for all - you must have permission to do so.

o  makeWritableForGroup
make the file writable for the group - you must have permission to do so.

o  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.

Usage example(s):

     'foo' asFilename writeStream close.
     'foo' asFilename removeAccessRights:#(readUser readGroup readOthers).
     'foo' asFilename removeAccessRights:#(writeUser writeGroup writeOthers).
     'foo' asFilename removeAccessRights:#(executeUser executeGroup executeOthers).

o  symbolicAccessRights
return the access rights of the file as a aCollection of access symbols.
The returned collection consists of symbols like:
#readUser, #writeGroup etc.

Usage example(s):

     'Make.proto' asFilename symbolicAccessRights

o  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.

Usage example(s):

     |rights|

     rights := 'Make.proto' asFilename symbolicAccessRights.
     'Make.proto' asFilename symbolicAccessRights:(rights , #(executeOthers)).

file operations
o  appendTo: streamOrNewName
append the contents of the file to another file or write stream.
The argument must be a stream or convertable to a filename.
Raises an exception, if an error occurs.

Usage example(s):

     'Make.proto' asFilename appendTo:'/tmp/Makefile.foo'.
     'Make.proto' asFilename appendTo:Transcript.
     'Make.proto' asFilename appendTo:'/tmp/Makefile.foo' asFilename
     'Make.proto' asFilename appendTo:'/dev/null'

o  copyTo: streamOrNewFileOrDirectoryName
Copy the file's contents into another file or stream.
The argument must be a stream or convertable to a filename.
Raises an exception, if an error occurs.

Usage example(s):

     'Make.proto' asFilename copyTo:'/tmp/Makefile.foo'
     'Make.proto' asFilename copyTo:'/tmp'
     'Make.proto' asFilename copyTo:Transcript
     'smalltalk' asFilename copyTo:'/dev/null'

o  copyToStream: outStream
Copy the file's contents into outStream.
Raises an exception, if an error occurs.

Usage example(s):

     |out|
     out := FileStream newTemporary.
     'Make.proto' asFilename copyToStream:out.
     out reset; contents

o  createAsEmptyFile
create an empty file with the receiver's name.
Raises an exception if not successful
(either already existing or creation not possible)

o  createAsHardLinkTo: linkFilenameString
create a directory with the receiver's name.
Raises an exception if not successful

Usage example(s):

        '/tmp/link' asFilename createAsHardLinkTo:'bla'

o  createAsSymbolicLinkTo: linkFilenameString
create a symbolic link named linkFilenameString which points to me
Raises an exception if not successful

Usage example(s):

        '/tmp/link' asFilename createAsSymbolicLinkTo:'bla'

o  makeDirectory
create a directory with the receiver's name.
No error is raised, if a directory with this name does already exist.
Otherwise an exception is raised if not successful.
Use #makeNewDirectory if the directory must no exists before.

o  makeNewDirectory
create a directory that must not already exist with the receiver's name.
Raises an exception if not successful.

o  moveFileTo: newNameArg
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)

o  moveTo: newNameArg
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)

Usage example(s):

     '/tmp/foo'asFilename contents:'abc'.    
     '/tmp/foo' asFilename moveTo:'/var/tmp/bar'

Usage example(s):

        '___TempBla' asFilename 
                        remove;
                        createAsEmptyFile;
                        renameTo:'T:\bla'.

        '___TempBla' asFilename 
                        remove;
                        createAsEmptyFile;
                        moveTo:'T:\bla'.

Usage example(s):

     |f s|

     f := '/tmp/foo' asFilename.
     s := f writeStream.
     s nextPutLine:'hello'.
     s close.
     f moveTo:'./foo'

o  recursiveCopyTo: destination
if I represent a regular file, copy it.
Otherwise, copy the directory and recursively
all of its subfiles/subdirectories.

Raises an exception if not successful.
Do not resolve symbolic links.
If a whole directory is to be copied and the destination directory
does not exist, it will be created.

Usage example(s):

        '.' asFilename recursiveCopyTo:'/temp/xxx'.

o  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.

Do not resolve symbolic links.
If a whole directory is to be copied and the destination directory
does not exist, it will be created.

Usage example(s):

     '.' asFilename recursiveCopyWithoutOSCommandTo:'/tmp/xxx'.
     'smalltalk.rc' asFilename recursiveCopyWithoutOSCommandTo:'/tmp/xxx'.

o  recursiveMakeDirectory
create a directory with the receiver's name and all required intermediate
directories.
Nothing is done if the directory does alread exist.
Raises an exception if not successful.

Usage example(s):

        '/tmp/veryNewBla/bla/bla' asFilename recursiveMakeDirectory.
        '/tmp/veryNewBla' asFilename recursiveRemoveAll.
        '/noSuchNameDoesExist/bla/bla/bla' asFilename recursiveMakeDirectory.
        '/' asFilename recursiveMakeDirectory.

Usage example(s):

        'C:\windows\bla\xx' asFilename recursiveMakeDirectory
        'C:\windows\bla' asFilename recursiveRemoveAll

o  recursiveMakeDirectoryForEachCreatedDo: aOneArgBlock
create a directory with the receiver's name and all required intermediate directories.
For each created directory evaluate aOneArgBlock with the
filename of the created directory.

Raises an exception if not successful.

Usage example(s):

        '/tmp/bla/fasel/murks' asFilename recursiveMakeDirectoryForEachCreatedDo:[:name| Transcript show:'Created: '; showCR:name].
        '/tmp/bla' asFilename recursiveRemove.

        'k:\bla\quark' asFilename recursiveMakeDirectory

o  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)

o  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.

Usage example(s):

     'foo/bar' asFilename recursiveMakeDirectory.
     'foo' asFilename remove.
     self assert:('foo' asFilename exists not).


     'foo' asFilename recursiveRemove.
     'foo/bar' asFilename recursiveMakeDirectory.
     'foo' asFilename recursiveRemove.
     self assert:('foo' asFilename exists not).

o  recursiveRemoveAll
Remove all of my subfiles/subdirectories.
Raise an error if not successful.
This one walks down the directory hierarchy, not using any OS
command to do the remove.

o  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.

Usage example(s):

     'foo' asFilename makeDirectory.
     'foo/bar' asFilename writeStream close.
     'foo' asFilename recursiveRemoveWithoutOSCommand

o  remove
remove the file/directory.
Raises an exception if not successful (but not if it did not exist in the first place).
Use #recursiveRemove in order to (recursively) remove non empty directories.

Usage example(s):

     (FileStream newFileNamed:'foo') close.
     'foo' asFilename remove

Usage example(s):

     'foo' asFilename makeDirectory.
     'foo/bar' asFilename writeStream close.
     'foo' asFilename remove.   'expect an exception'
     'foo' asFilename recursiveRemove.

o  removeDirectory
remove the directory.
No error is raised, if the directory does not exist in the first place.
Raises an exception if not successful (or if it's 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.

Usage example(s):

     (FileStream newFileNamed:'foo') close.
     'foo' asFilename removeDirectory

Usage example(s):

     'foo' asFilename writeStream close.
     'foo' asFilename removeDirectory

o  removeFile
remove the file.
No error is raised, if the file does not exist in the first place.
Raises an exception if not successful (or if it's 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.

Usage example(s):

     (FileStream newFileNamed:'foo') close.
     'foo' asFilename removeFile

Usage example(s):

     'foo' asFilename makeDirectory.
     'foo' asFilename removeFile

o  renameTo: newName
rename the file - the argument must be convertable to a filename.
Raises an exception if not successful.
If newName already exists, it will be replaced by myself.

Usage example(s):

     '/tmp/foo'asFilename contents:'abc'.    
     '/tmp/foo' asFilename renameTo:'/tmp/bar'.
     '/tmp/bar' asFilename renameTo:'/var/tmp/bar'
     
     '/tmp/' asFilename renameTo:'/etc/bar'
     'C:\windows' asFilename renameTo:'C:\win'

o  renameTo: newName overwrite: overwrite
rename the file to newName. newName must be convertable to a filename.
Raises an exception if not successful.
If newName already exists, it will be replaced by myself.

'overwrite'
if newName exists and overwrite == false, this method will fail (only on windows os).
If overwrite == true, the rename will replace an existing newName target file.

Usage example(s):

     '/tmp/foo' asFilename renameTo:'/tmp/bar'
     '/tmp/' asFilename renameTo:'/etc/bar'
     'C:\windows' asFilename renameTo:'C:\win'

o  safeCopyTo: newNameArg
Copy the file's contents into another file.
Do it safe in an atomic operation which makes sure that no partially written file appears.
The argument must be convertable to a filename.
Raises an exception, if an error occurs.

Usage example(s):

     'Make.proto' asFilename safeCopyTo:'/tmp/Makefile.foo'
     'Make.proto' asFilename safeCopyTo:'/'
     'smalltalk' asFilename safeCopyTo:'/xxxxxxxxxxxxxxxx/bla'
     'blaFaselQuall.ccccccc' asFilename safeCopyTo:'/xxxxxxxxxxxxxxxx/bla'

o  truncateTo: newSize
change the file's size.
This may not be supported on all operating systems
(raises an exception, if not)

Usage example(s):

     |s|

     s := 'test' asFilename writeStream.
     s next:1000 put:$1.
     s close.
     ('test' asFilename fileSize) printCR.
     'test' asFilename truncateTo:100.
     ('test' asFilename fileSize) printCR.

file queries
o  accessTime
return a timeStamp containing the file's last access time.

Usage example(s):

     Filename currentDirectory accessTime

o  creationTime
return a timeStamp containing the file's creation time.
NOTICE: only windoof distinguishes creation from modification;
under unix, nil is returned (callers should fall back and use mod-time then

Usage example(s):

     Filename currentDirectory creationTime

o  dates
return the file's modification and access times as an object (currently a dictionary)
that responds to the at: message with arguments
#modified, #accessed or #statusChanged.

Usage example(s):

maybe this is a symbolic link with a broken link target.
         Answer the dates of the link itself

Usage example(s):

     Filename currentDirectory dates
     '../regression' asFilename dates

o  fileSize
return the size of the file in bytes.
Returns 0 if it does not exist.

o  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.

Usage example(s):

     'Makefile' asFilename fileType
     '.' asFilename fileType
     '/dev/null' asFilename fileType
     '/usr/tmp' asFilename fileType
     '/tmp/.X11-unix/X0' asFilename fileType
     'smalltalk.rc' asFilename fileType
     'bitmaps/SBrowser.xbm' asFilename fileType

o  id
return the file's/directory's file-id (inode number)

Usage example(s):

     Filename currentDirectory id

o  info
return some object filled with the file's info, or nil if the file does not exist.
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
fileSize - files size
id - files number (i.e. inode number)
accessed - last access time (as osTime-stamp)
modified - last modification time (as osTime-stamp)
statusChangeTime - last status 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

Don't 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

Usage example(s):

     Filename currentDirectory info
     '/dev/null' asFilename info
     'Make.proto' asFilename info
     'source/Point.st' asFilename info
     'source/Point.st' asFilename linkInfo
     '../../libbasic/Point.st' asFilename info
     '.' asFilename info
     '..' asFilename info
     '..\..' asFilename info
     '..\..\..' asFilename info
     '..\..\..\..' asFilename info
     'c:\' asFilename info

o  linkInfo
return the file's info or nil if the file does not exist.
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.

Usage example(s):

     Filename currentDirectory linkInfo
     '/dev/null' asFilename linkInfo
     'Make.proto' asFilename linkInfo
     'Make.proto' asFilename linkInfo path
     'source/Point.st' asFilename linkInfo
     '../../libbasic/Point.st' asFilename linkInfo
     '/usr/tmp' asFilename linkInfo

o  linkTarget
if the receiver represents a symbolic link, return the target file
as filename. Otherwise return nil

Usage example(s):

     Filename currentDirectory linkTarget
     'C:\Users\cg\Links\work.lnk' asFilename linkTarget

     'C:\Users\cg\Links\work.lnk' asFilename type
     'C:\Users\cg\Links\work.lnk' asFilename isRegularFile
     'C:\Users\cg\Links\work.lnk' asFilename isDirectory
     'C:\Users\cg\Links\work.lnk' asFilename isSymbolicLink

o  modificationTime
return a timeStamp containing the file's modification time.

Usage example(s):

     Filename currentDirectory modificationTime

o  type
return the symbolic type of the file or nil if the file does not exist.
For symbolic links it is the type of the linked-to file.

Usage example(s):

     Filename currentDirectory type
     '++++noNadaNul+++++++' asFilename type

file times
o  setAccessTime: aTimestampOrNow
set the last access time of the file to aTimestampOrNow.
aTimestampOrNow maybe either a Timestamp or the symbol #now.

Usage example(s):

     '/tmp/blaFile.bla' asFilename
        contents:'';
        setAccessTime:(Timestamp readFrom:'1980-07-01').

o  setModificationTime: aTimestampOrNow
set the modification time of the file to aTimestampOrNow.
aTimestampOrNow maybe either a Timestamp or the symbol #now.

Usage example(s):

     '/tmp/blaFile.bla' asFilename
        createAsEmpty;
        setModificationTime:(Timestamp readFrom:'1980-07-01').

      FileStream newTemporary close asFilename 
        setModificationTime:(Timestamp readFrom:'1980-07-01');
        inspect.

file utilities
o  edit
start an editView on the file represented by the receiver

Usage example(s):

     'smalltalk.rc' asFilename edit

o  fileIn
load code from the file

o  fileInToPackage: package
load code from the file.
Code will be installed into the given package.

inspecting
o  inspector2TabContentsView
( an extension from the stx:libtool package )
provide an additional tab, which presents the file's contents.
'.' asFilename inspect
'smalltalk.rc' asFilename inspect

o  inspectorExtraMenuOperations
( an extension from the stx:libtool package )
extra operation-menu entries to be shown in an inspector.
Answers a collection of pairs containing aString and action aBlock.
aString is the label of the menu item.
aBlock is evaluated when the menu item is selected.

instance creation
o  / 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.

Usage example(s):

     '/tmp' asFilename / 'foo'
     '/' asFilename / 'foo' / 'bar' / 'baz'
     '/foo/bar' asFilename / ('baz' asFilename)

     Bad example; works on UNIX, but may not on others:
       'foo/bar.baz' / '.suff'

o  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).

Usage example(s):

     '/tmp' asFilename construct:'foo'
     '/tmp' asFilename construct:('foo' asFilename)
     '/' asFilename construct:'foo'
     '/usr/tmp' asFilename construct:'foo'
     '/foo/bar' asFilename construct:'baz'
     '/foo/bar' asFilename construct:'baz' asFilename

     Bad example; works on UNIX, but may not on others:
       'foo/bar.baz' asFilename construct:'.suff'

o  constructDirectory: subname
same as #construct: on most systems.
(may allow different/relaxed name syntax of the argument on some systems)

o  constructDirectoryString: subName
same as #constructString: on most systems.
(may allow different/relaxed name syntax of the argument on some systems)

o  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.

Usage example(s):

     '/tmp' asFilename constructString:'foo'
     '/tmp' asFilename constructString:'/foo'
     '/tmp' asFilename constructString:('foo' asFilename)
     '/' asFilename constructString:'foo'
     '/usr/tmp' asFilename constructString:'foo'
     '/foo/bar' asFilename constructString:'baz'
     '' asFilename constructString:'baz'

o  filenameFor: fileName
return a filename representing the argument, fileName
either in myself (if the arg is a releative path) or absolute otherwise.

Usage example(s):

     '/tmp' asFilename filenameFor:'foo'
     '/tmp' asFilename filenameFor:'/foo'

o  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 the current filename (via '..') and is used eg.
by the documentation viewer and other services to prevent remote
access outside some predefined root folder.

Usage example(s):

     '/tmp' asFilename secureConstruct:'foo'
     '/tmp' asFilename secureConstruct:'../foo'
     '/tmp' asFilename secureConstruct:'/./foo'
     '/tmp' asFilename secureConstruct:'foo/../bar'
     '/' asFilename secureConstruct:'foo'
     '/usr/tmp' asFilename secureConstruct:'foo'
     '/foo/bar' asFilename secureConstruct:'baz'
     '/foo/bar' asFilename secureConstruct:'baz' asFilename

     Bad example; works on UNIX, but may not on others:
       'foo/bar.baz' secureConstruct:'.suff'

o  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 the current filename (via '..') and is used eg.
by the documentation viewer and other services to prevent remote
access outside some predefined root folder.

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

Usage example(s):

     '/tmp' asFilename secureConstructString:'fooŠ'
     '/tmp' asFilename secureConstructString:'../foo'
     '/tmp' asFilename secureConstructString:'foo/../bla'
     '/tmp' asFilename secureConstructString:'foo/./bla'
     '/tmp' asFilename secureConstructString:'/bla/foo/../../foo'
     '/' asFilename secureConstructString:'foo'
     '/usr/tmp' asFilename secureConstructString:'foo'
     '/foo/bar' asFilename secureConstructString:'baz'
     '' asFilename secureConstructString:'baz'
     '' asFilename secureConstructString:'/baz'

misc
o  , aString
this allows filenames to understand how names are concatenated.
Returns a string consisting of the receiver's 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) **

o  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.

Usage example(s):

        '/tmp/bla' asFilename canonicalize.
        '/tmp/bla/../fasel' asFilename canonicalize.
        '/tmp/bla/.././/fasel' asFilename canonicalize.
        '..' asFilename canonicalize.
        'bla/../fasel' asFilename canonicalize.
        '//bla/../fasel' asFilename canonicalize.

os shell
o  openApplication
open the OS application associated with this type of file
(i.e. like a double click on the file in the desktop)

Usage example(s):

     Filename currentDirectory openApplication

o  openExplorer
open a file-explorer on the directory represented by the receiver.
On osx systems, a finder is opened.
On other systems, a filebrowser is opened

Usage example(s):

     Filename currentDirectory openExplorer

o  openFinder
open a finder on the directory represented by the receiver.
On non-osx systems, an error is raised

o  openTerminal
open a terminal window on the directory represented by the receiver;
on osx, a terminal app is opened,
on windows a cmd.exe window,
on unix, an xterm is opened.

Usage example(s):

        'C:\windows' asFilename openTerminal

printing & storing
o  displayOn: aStream
append a user printed representation of the receiver to aStream.
The format is suitable for a human - not meant to be read back.

o  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.
Here, I print myself as a string, so I can be easily embedded in bind-with strings.

o  storeOn: aStream
append a printed representation of the receiver to aStream,
which allows reconstructing it via readFrom:

private-accessing
o  getName
get the raw filename

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  nameString
raw access to nameString - req'd for xml-store/reload

o  nameString: aString
raw access to nameString - req'd for xml-store/reload

o  setName: aString
set the filename

queries
o  directories
return a collection of directories contained in the directory represented by the receiver.

Usage example(s):

     '.' asFilename directories.

o  exists
return true, if such a file exists.

Usage example(s):

     '/foo/bar' asFilename exists
     '/tmp' asFilename exists
     'Makefile' asFilename exists

o  filenamesMatching: aPattern
VW compatibility

Usage example(s):

     '/etc' asFilename filenamesMatching:'a*;c*'

o  files
return a collection of regular files
contained in the directory represented by the receiver.

Usage example(s):

     '.' asFilename files.

o  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.

Usage example(s):

     '/etc' asFilename filesMatching:'a*;c*'

o  filesMatching: aPattern caseSensitive: caseSensitive
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.

Usage example(s):

     '/etc' asFilename filesMatching:'a*;c*' caseSensitive:false

o  filesMatching: aPattern caseSensitive: caseSensitive do: aBlock
given the receiver, representing a directory;
evaluate aBlock for files which match a pattern.
The pattern may be a simple matchPattern, or a set of
multiple patterns separated by semicolons.

Usage example(s):

     '/etc' asFilename filesMatching:'a*;c*' do:[:f | Transcript showCR:f]

o  filesMatching: aPattern do: aBlock
given the receiver, representing a directory;
evaluate aBlock for files which match a pattern.
The pattern may be a simple matchPattern, or a set of
multiple patterns separated by semicolons.

Usage example(s):

     '/etc' asFilename filesMatching:'a*;c*' do:[:f | Transcript showCR:f]
     '/etc' asFilename filesMatching:'a*;c*'

o  filesMatchingGLOB
Interpreting myself as a GLOB pattern,
Return filenames matching me

Usage example(s):

     '../../*/A*' asFilename filesMatchingGLOB.

o  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.

Usage example(s):

     Filename currentDirectory filesMatching:'.*'
     Filename currentDirectory filesMatchingWithoutDotDirs:'*.*'
     '/etc' asFilename filesMatchingWithoutDotDirs:'*'

o  filesMatchingWithoutDotDirs: aPattern caseSensitive: caseSensitive do: aBlock
given the receiver, representing a directory;
evaluate aBlock for files matching a pattern.
Exclude '.' and '..'.
The pattern may be a simple matchPattern, or a set of
multiple patterns separated by semicolons.

o  filesMatchingWithoutDotDirs: aPattern do: aBlock
given the receiver, representing a directory;
evaluate aBlock for files matching a pattern.
Exclude '.' and '..'.
The pattern may be a simple matchPattern, or a set of
multiple patterns separated by semicolons.

o  filesWithSuffix: suffix
return a collection of regular files (i.e. not subdirectories)
with a given suffix which are contained in the directory
represented by the receiver.

Usage example(s):

     '.' asFilename filesWithSuffix:'so'.
     'packages' asFilename filesWithSuffix:'so'.

o  fullAlternativePathName
some filesystems (aka: windows) have alternative (short) filenames.
Those systems redefine this method to return it.
Otherwise, the same as the regular name is returned here

o  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.

Usage example(s):

     '/foo/bar' asFilename isExecutable
     '/tmp' asFilename isExecutable
     'Makefile' asFilename isExecutable
     '/bin/ls' asFilename isExecutable

o  isExecutableProgram
return true, if such a file exists and is an executable program.
(i.e. for directories, false is returned.)

Usage example(s):

     '/tmp' asFilename isExecutable
     '/bin/ls' asFilename isExecutable
     '/tmp' asFilename isExecutableProgram
     '/bin/ls' asFilename isExecutableProgram
     
     'ls' asFilename isExecutableProgram
     OperatingSystem canExecuteCommand:'ls'

o  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 file's hidden attribute is also used.
VMS has no concept of hidden files.

o  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;

o  isReadable
return true, if such a file exists and is readable.

Usage example(s):

     '/foo/bar' asFilename isReadable
     '/tmp' asFilename isReadable
     'Makefile' asFilename isReadable

o  isSharedLibrary
return true, if such a file exists and is a shared library.

Usage example(s):

     'libstx_libbasic.so' asFilename isSharedLibrary
     'libstx_libbasic.dll' asFilename isSharedLibrary
     '/tmp' asFilename isSharedLibrary
     '/tmp.dll' asFilename isSharedLibrary

o  isValidFilename
return true, if the name is a valid filename.
This does NOT check for existance - only for the name
(i.e. it checks for invalid characters in the filename)

Usage example(s):

     'abc' asFilename isValidFilename
     'abc/' asFilename isValidFilename
     c'abc\n' asFilename isValidFilename
     '' asFilename isValidFilename

o  isWritable
return true, if such a file exists and is writable.

Usage example(s):

     '/foo/bar' asFilename isWritable
     '/tmp' asFilename isWritable
     'Makefile' asFilename isWritable

o  isWritableDirectory
return true, if such a directory exists and is writable.
Don't believe #isWritable, since on an NFS mounted filesystem
with UID mapping and attribute cache enabled, there may be false negatives.

Usage example(s):

     '/foo/bar' asFilename isWritableDirectory
     '/tmp' asFilename isWritableDirectory
     '/etc' asFilename isWritableDirectory
     'Makefile' asFilename isWritableDirectory
     '/net/exeptn/home2/office' asFilename isWritable
     '/net/exeptn/home2/office' asFilename isWritableDirectory

o  separator
return the directory-separator character

Usage example(s):

     UnixFilename separator 
     PCFilename separator

o  species
create only new instances of the concrete OS specific class.
Redefined in AutoDeletedFilename, to not create AutoDeleted instances
per default (from directories etc.)

Usage example(s):

        '/etc' asFilename species
        'c:\windows' asFilename species

o  withSpecialExpansions
return a new filename, expanding any OS specific macros.
Here, ~/ and ~user/ prefixes are expanded to the user's home dir (as in csh, bash)

Usage example(s):

     '~' asFilename withSpecialExpansions
     '~/Desktop' asFilename withSpecialExpansions
     '~stefan' asFilename withSpecialExpansions
     '~stefan/Desktop' asFilename withSpecialExpansions

queries-contents
o  mimeTypeFromName
return the mimeType as guessed from the file's 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.

Usage example(s):

     'Makefile' asFilename mimeTypeFromName
     '.' asFilename mimeTypeFromName
     '/dev/null' asFilename mimeTypeFromName
     '/tmp/.X11-unix/X0' asFilename mimeTypeFromName
     'smalltalk.rc' asFilename mimeTypeFromName
     'bitmaps/SBrowser.xbm' asFilename mimeTypeFromName
     '../../rules/stmkmf' asFilename mimeTypeFromName
     '/bläh' asFilename mimeTypeFromName
     '/x.zip' asFilename mimeTypeFromName
     '/x.gz' asFilename mimeTypeFromName

o  mimeTypeFromNameIfUnknown: fallBack
return the mimeType as guessed from the file's 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.

Usage example(s):

     'Makefile' asFilename mimeTypeFromName 
     '.' asFilename mimeTypeFromName       
     '.' asFilename mimeTypeFromNameIfUnknown:'unknown'       

o  mimeTypeOfContents
this tries to guess the mime type of contents of the file.
Returns nil, if the file is unreadable, is not a plain file
or the contents is unknown.
This is done using some heuristics, and may need some improvement

Usage example(s):

     'Makefile' asFilename mimeTypeOfContents
     '.' asFilename mimeTypeOfContents
     '/dev/null' asFilename mimeTypeOfContents
     '/tmp/.X11-unix/X0' asFilename mimeTypeOfContents
     'smalltalk.rc' asFilename mimeTypeOfContents
     'bitmaps/SBrowser.xbm' asFilename mimeTypeOfContents
     '../../rules/stmkmf' asFilename mimeTypeOfContents
     '/bläh' asFilename mimeTypeOfContents
     'C:\Dokumente und Einstellungen\cg\Favoriten\languages.lnk' asFilename mimeTypeOfContents
     'G:\A\A01.TOP' asFilename mimeTypeOfContents
     '~/work/exept/expecco/plugin/labView/docs/labview_help_371361t/lvcomm.chm' asFilename mimeTypeOfContents

queries-path & name
o  baseName
return my baseName as a string.
- that's 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.

Usage example(s):

     '/foo/bar' asFilename baseName
     '/foo/bar.cc' asFilename baseName
     '.' asFilename baseName
     '..' asFilename baseName
     '../..' asFilename baseName
     '../../libbasic' asFilename baseName
     '../../libpr' asFilename baseName
     '../../libbasic/Object.st' asFilename baseName
     '/' asFilename baseName
     '\' asFilename baseName
     'c:\' asFilename baseName
     '\\idefix' asFilename baseName

o  directory
return the directory name part of the file/directory as a new filename.
- that's 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 ).

Usage example(s):

     '/foo/bar' asFilename directory
     '/foo/bar' asFilename directoryName
     '/foo/bar' asFilename head

     '.' asFilename directory
     '..' asFilename directory
     '../..' asFilename directory

o  directoryName
return the directory name part of the file/directory as a string.
- that's 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.

Usage example(s):

'/foo/bar/.' asFilename directoryName    

Usage example(s):

"/ '/foo/bar/../' asFilename directoryName    

Usage example(s):

"/ '/foo/../' asFilename directoryName    

Usage example(s):

"/ './../' asFilename directoryName    

Usage example(s):

"/ '/../' asFilename directoryName        

Usage example(s):

"/ '/..' asFilename directoryName    

Usage example(s):

"/ '..' asFilename directoryName    

Usage example(s):

     '../..' asFilename directoryName 
     '/home' asFilename directoryName  
     '/foo/bar/' asFilename directoryName  
     '/foo/bar/' asFilename directory     
     '../foo/bar/' asFilename directory     
     '../foo/bar/' asFilename directory directory     
     '../foo/bar/' asFilename directory directory directory    

     '/foo/bar' asFilename directoryName
     'bitmaps' asFilename directoryName
     'bitmaps' asFilename directoryPathName
     '.' asFilename directoryName
     '.' asFilename directoryPathName
     '..' asFilename directoryName
     '..' asFilename directoryPathName
     '../..' asFilename directoryName
     '../..' asFilename directoryPathName
     '/foo/bar/baz/..' asFilename directoryName
     '/foo/bar/baz/.' asFilename directoryName
     'c:\' asFilename directoryName

o  directoryPathName
return the full directory pathname part of the file/directory as a string.
- that's the full pathname of the directory where the file/dir represented by
the receiver is contained in.
See also: #pathName, #directoryName, #directory and #baseName

Usage example(s):

     '/foo/bar/' asFilename directoryPathName
     '/foo/bar' asFilename directoryPathName

     '.' asFilename directoryPathName
     '.' asFilename directoryName
     '.' asFilename directory

     '..' asFilename directoryPathName
     '..' asFilename directoryName
     '..' asFilename directory

     '../..' asFilename directoryPathName

o  encodedNameString
answer the name as passed to OS system calls

o  endsWith: aStringOrChar
return true, if the receiver's name ends with something, aStringOrChar.
If aStringOrChar is an empty string, true is returned

Usage example(s):

     'foo.bar' asFilename endsWith:'.bar'   => true
     'foo.bar' asFilename endsWith:''       => true
     'foo.bar' asFilename endsWith:'xxx'    => false

o  endsWith: aStringOrChar caseSensitive: caseSensitive
return true, if the receiver's name ends with something, aStringOrChar.
If aStringOrChar is an empty string, true is returned

Usage example(s):

     'foo.BAR' asFilename endsWith:'.bar' caseSensitive:false
     'foo.BAR' asFilename endsWith:'.bar' caseSensitive:true

o  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 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.

Usage example(s):

     'mak' asFilename filenameCompletion
     'Make' asFilename filenameCompletion
     'Makef' asFilename filenameCompletion;yourself
     '/u' asFilename filenameCompletion
     '../../libpr' asFilename inspect filenameCompletion

o  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.

o  isAbsolute
return true, if the receiver represents an absolute pathname
(in contrast to one relative to the current directory).

Usage example(s):

     '/foo/bar' asFilename isAbsolute
     '~/bla' asFilename isAbsolute
     '..' asFilename isAbsolute
     '..' asFilename asAbsoluteFilename isAbsolute
     'source/SBrowser.st' asFilename isAbsolute
     'source/SBrowser.st' asFilename isRelative
     'SBrowser.st' asFilename isRelative

o  isBackupFilename
return true, if this name is an for a backup file

o  isExplicitRelative
return true, if this name is an explicit relative name
(i.e. starts with './' or '../', to avoid path-prepending)

o  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.

o  isNetworkDrive
return true, if I represent an network drive

o  isParentDirectoryOf: aFilenameOrString
Answer true, if myself is a parent directory of aFilenameOrString.
Unexpected results may be returned, if one of myself or aFilenameOrString does
not exist and relative and absolute path names are mixed
('/' asFilename isParentDirectoryOf:'../noExistent' -> false)

Warning: maybe symbolic links must be resolved which could lead to automounting

Usage example(s):

     '/etc' asFilename isParentDirectoryOf:'/etc/passwd'
     'etc' asFilename isParentDirectoryOf:'etc/passwd'
     '/etc' asFilename isParentDirectoryOf:'/etc/'
     '/etc' asFilename isParentDirectoryOf:'/etc'
     '/et' asFilename isParentDirectoryOf:'/etc'
     '/home' asFilename isParentDirectoryOf:Filename currentDirectory
     '~' asFilename isParentDirectoryOf:Filename currentDirectory
     '~' asFilename isParentDirectoryOf:'.'
     '~' asFilename isParentDirectoryOf:'..'
     '~' asFilename isParentDirectoryOf:'../smalltalk'
     '../..' asFilename isParentDirectoryOf:'../nonExistent'
     '..' asFilename isParentDirectoryOf:'../../nonExistent'
     '/' asFilename isParentDirectoryOf:'../nonExistent'
     '/' asFilename isParentDirectoryOf:'/phys/qnx'

o  isRelative
return true, if this name is interpreted relative to some
directory (opposite of absolute)

Usage example(s):

     './foo/bar' asFilename isRelative
     '../../foo/bar' asFilename isRelative
     '/foo/bar' asFilename isRelative
     'bar' asFilename isRelative

o  isRemote
answer true, if I am a file on a network drive

o  isRootDirectory
return true, if I represent the root directory
(i.e. I have no parentDir)

o  isVolumeAbsolute
return true, if the receiver represents an absolute pathname
on some disk volume (MSDOS only)

o  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.

o  name
return the name of the file represented by the receiver as a string.
This is the name given when the filename was created - not neccessarily its pathname
(although it may). Thus, this may or may not be a relative name (i.e. include ..'s).
See also: pathName

Usage example(s):

     '/foo/bar' asFilename name
     '/foo/bar' asFilename pathName
     '.' asFilename name
     '.' asFilename pathName
     '../..' asFilename name
     '../..' asFilename pathName
     'bitmaps' asFilename name
     'bitmaps' asFilename pathName
     '/tmp/../usr' asFilename name
     '/tmp/../usr' asFilename pathName
     'source/..' asFilename name
     'source/..' asFilename pathName
     '/tmp/..' asFilename name
     '/tmp/..' asFilename pathName

o  pathName
return the full absolute pathname of the file represented by the receiver,
as a string. This will not include ..'s.
Symbolic links in the path will be resolved.

If the file does not exist or is not accessible, a simple compression
(compressing '.' and '..') will be done, but relative names will not be
returned as absolute name.
This is by purpose, so that a relative pathname remains as such when used
in the context of another user or other current-directory.

See also: name

Usage example(s):

     '/foo/bar' asFilename pathName
     '/foo/./bar' asFilename pathName
     'foo/bar' asFilename pathName
     '.' asFilename pathName
     '../..' asFilename pathName
     '../..' asFilename name
     '/tmp/../usr' asFilename pathName
     '/././usr' asFilename pathName
     '~/..' asFilename pathName
     '../foo' asFilename pathName         => '..\foo'
     '../foo' asFilename absolutePathName => 'C:\Users\mobile\cg_work\stx\projects\foo' 
     '$JAVA_HOME/bin/java' asFilename pathName

o  pathNameRelativeFrom: anotherDirectoriesFilename
return the pathname of the receiver,
but relative from another directory.
I.e. if the receiver is /a/b/c
and the argument is /a/x/y,
then the relative path to the receiver as seen from the argument is ../../b/c

Usage example(s):

     self assert:('/' asFilename pathNameRelativeFrom:'/a') = '..\.'.
     self assert:('/a' asFilename pathNameRelativeFrom:'/') = 'a'.  
     self assert:('/a/b' asFilename pathNameRelativeFrom:'/') = 'a/b'.

     self assert:('/a' asFilename pathNameRelativeFrom:'/a') = '.'  
     self assert:('/a/b' asFilename pathNameRelativeFrom:'/a') = 'b'  
     self assert:('/a/b/c' asFilename pathNameRelativeFrom:'/a') = 'b/c'  

     self assert:('/a/' asFilename pathNameRelativeFrom:'/a') = '.'  
     self assert:('/a/b/' asFilename pathNameRelativeFrom:'/a') = 'b'  
     self assert:('/a/b/c/' asFilename pathNameRelativeFrom:'/a') = 'b/c'  

     self assert:('/a' asFilename pathNameRelativeFrom:'/a/') = '.'  
     self assert:('/a/b' asFilename pathNameRelativeFrom:'/a/') = 'b'  
     self assert:('/a/b/c' asFilename pathNameRelativeFrom:'/a/') = ''b/c''  

     self assert:('/a/' asFilename pathNameRelativeFrom:'/a/') = '.'  
     self assert:('/a/b/' asFilename pathNameRelativeFrom:'/a/') = 'b'  
     self assert:('/a/b/c/' asFilename pathNameRelativeFrom:'/a/') = 'b/c'  

     self assert:('/a' asFilename pathNameRelativeFrom:'/b') = '../a'  
     self assert:('/a/b/' asFilename pathNameRelativeFrom:'/b') = '../a/b'  
     self assert:('/a/b/c/' asFilename pathNameRelativeFrom:'/b') = '../a/b/c'  

     self assert:('/a/b/' asFilename pathNameRelativeFrom:'/a') = 'b'  
     self assert:('/a/b/c/' asFilename pathNameRelativeFrom:'/a') = 'b/c'  

     self assert:('/a/b/c/d' asFilename pathNameRelativeFrom:'/a/x/y/z') = '../../../b/c/d'  

o  physicalFilename
return the fileName representing the physical file as represented by the receiver,
If the receiver represents a symbolic link, that's the fileName of the
final target. Otherwise, its the receiver's pathName itself.
If any file along the symbolic path does not exist (i.e. is a broken link),
nil is returned.

Usage example(s):

     '/foo/bar' asFilename physicalFilename

o  physicalPathName
return the full pathname of the physical file represented by the receiver,
If the receiver represents a symbolic link, that's the fileName of the
final target. Otherwise, its the receiver's pathName itself.
If any file along the symbolic path does not exist (i.e. is a broken link),
nil is returned.

Usage example(s):

     '/foo/bar' asFilename physicalPathName
     '.' asFilename physicalPathName
     '../..' asFilename physicalPathName
     '/bin' asFilename physicalPathName
     '~stefan/../../bin' asFilename physicalPathName
     '/usr/java/default' asFilename physicalPathName

o  startsWith: aStringOrChar
return true, if the receiver's name starts with something, aStringOrChar.
If the argument is empty, true is returned.
Notice that this tests the file's basename (or whatever the filename was constructed from);
not neccessarily its full path

Usage example(s):

     'foo.bar' asFilename startsWith:'foo.'
     'foo.bar' asFilename startsWith:''

o  startsWith: aStringOrChar caseSensitive: caseSensitive
return true, if the receiver's name starts with something, aStringOrChar.
If the argument is empty, true is returned.
Notice that this tests the file's basename (or whatever the filename was constructed from);
not neccessarily its full path

Usage example(s):

     'foo.bar' asFilename startsWith:'foo.'
     'foo.bar' asFilename startsWith:''

o  startsWithAnyOf: aCollectionOfStringsOrChars
return true, if the receiver's name starts with any in aCollectionOfStringsOrChars.
Notice that this tests the file's basename (or whatever the filename was constructed from);
not neccessarily its full path

Usage example(s):

     'foo.bar' asFilename startsWithAnyOf:#('foo.' 'bar') => true
     'foo.bar' asFilename startsWithAnyOf:#('baz.' 'bar') => false

o  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
o  followSymbolicLink
if the receiver is an symbolic link
return the target as filename.
Otherwise return the receiver.

Usage example(s):

     '/var/run' asFilename followSymbolicLink
     'C:\Users\Stefan Reise\Desktop\test\a.lnk' asFilename followSymbolicLink    

o  isDirectory
return true, if the receiver represents an existing,
readable directories pathname.
Symbolic links pointing to a directory answer true.

Usage example(s):

     '/foo/bar' asFilename isDirectory
     '/tmp' asFilename isDirectory
     'Makefile' asFilename isDirectory
     'c:\' asFilename isDirectory
     'd:\' asFilename isDirectory
     '\\host\dir' asFilename isDirectory
     OperatingSystem isDirectory:'\\host\dir'

o  isNonEmptyDirectory
return true, if the receiver represents an existing,
readable directories pathname, and the directory is not empty.

Usage example(s):

     '/foo/bar' asFilename isNonEmptyDirectory
     '/tmp' asFilename isNonEmptyDirectory
     '/tmp/empty' asFilename makeDirectory; isNonEmptyDirectory.
     '/tmp/empty' asFilename removeDirectory.
     'Makefile' asFilename isNonEmptyDirectory
     'c:\' asFilename isNonEmptyDirectory
     'd:\' asFilename isNonEmptyDirectory

o  isPlainDirectory
return true, if the receiver represents an existing,
readable directories pathname.
Symbolic links pointing to a directory answer FALSE.

Usage example(s):

     '/foo/bar' asFilename isPlainDirectory
     '/tmp' asFilename isPlainDirectory
     '/usr/tmp' asFilename isPlainDirectory
     'Makefile' asFilename isPlainDirectory
     'c:\' asFilename isPlainDirectory
     'd:\' asFilename isPlainDirectory
     '\\host\dir' asFilename isPlainDirectory

o  isRegularFile
return true, if the receiver represents a plain, regular file.
Symbolic links pointing to a regular file answer true.

Usage example(s):

     '/foo/bar' asFilename isRegularFile
     '/tmp' asFilename isRegularFile
     'Makefile' asFilename isRegularFile
     'c:\' asFilename isRegularFile
     'd:\' asFilename isRegularFile
     '/dev/null' asFilename isRegularFile

     './Make.proto.link' asFilename createAsSymbolicLinkTo:'Make.proto'.
     './Make.proto.link' asFilename isRegularFile
     'C:\Users\cg\Links\work.lnk' asFilename type
     'C:\Users\cg\Links\work.lnk' asFilename isRegularFile
     'C:\Users\cg\Links\work.lnk' asFilename isDirectory
     'C:\Users\cg\Links\work.lnk' asFilename isSymbolicLink

o  isSpecialFile
return true, if the receiver represents a socket, named pipe, fifo
or device special file (i.e. anything non regular and non-directory).
Symbolic links pointing to a special file answer true.

Usage example(s):

     '/foo/bar' asFilename isSpecialFile
     '/tmp' asFilename isSpecialFile
     'Makefile' asFilename isSpecialFile
     'c:\' asFilename isSpecialFile
     'd:\' asFilename isSpecialFile
     '/dev/null' asFilename isSpecialFile

o  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.

Usage example(s):

     'Make.proto' asFilename isSymbolicLink
     'Makefile' asFilename isSymbolicLink

reading-directories
o  directoryContents
return the contents of the directory as a collection of strings.
This excludes any entries for '.' or '..'.
Raises an error if the receiver is a non-existing directory.
Notice:
this returns the file-names as strings;
see also #directoryContentsAsFilenames, which returns fileName instances.

Usage example(s):

     '.' asFilename directoryContents
     '/XXXdoesNotExist' asFilename directoryContents

o  directoryContentsAsFilenames
return the contents of the directory as a collection of filenames.
This excludes any entries for '.' or '..'.
Raises an error if the receiver is a non-existing directory.
Notice:
this returns the file-names as fileName instances;
see also #directoryContents, which returns strings.

Usage example(s):

     '.' asFilename directoryContentsAsFilenames
     '/XXXdoesNotExist' asFilename directoryContentsAsFilenames

o  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.
Raises an error if the receiver is a non-existing directory.

Usage example(s):

     '.' asFilename fullDirectoryContents
     '/XXXdoesNotExist' asFilename fullDirectoryContents
     'd:\FET' asFilename fullDirectoryContents

o  isEmptyDirectory
answer true, if this is an empty directory.
Raise an exception, if this is not a directory.

Usage example(s):

     '.' asFilename isEmptyDirectory
     'Make.proto' asFilename isEmptyDirectory
     '/XXXdoesNotExist' asFilename isEmptyDirectory

o  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.
Raises an error if the receiver is a non-existing directory.
Notice:
this returns the file-names as strings;
see also #recursiveDirectoryContentsAsFilenames, which returns fileName instances.

Warning: this may take a long time to execute.

Usage example(s):

     '.' asFilename recursiveDirectoryContents
     '../../clients' asFilename recursiveDirectoryContents

o  recursiveDirectoryContentsAsFilenames
return the contents of the directory and all subdirectories
as a collection of filenames.
This excludes any entries for '.' or '..'.
Raises an error if the receiver is a non-existing directory.
Notice:
this returns the file-names as fileName instances;
see also #recursiveDirectoryContents, which returns strings.

Warning: this may take a long time to execute.

Usage example(s):

     '.' asFilename recursiveDirectoryContentsAsFilenames
     '/XXXdoesNotExist' asFilename recursiveDirectoryContentsAsFilenames

reading-files
o  binaryContents
an alias.
return the binary contents of the file (as a byteArray);
Raises an error, if the file is unreadable/non-existing.

o  binaryContentsOfEntireFile
return the binary contents of the file (as a byteArray);
Raises an error, if the file is unreadable/non-existing.

Usage example(s):

     'Makefile' asFilename binaryContentsOfEntireFile
     'foobar' asFilename binaryContentsOfEntireFile

o  contents
Return the contents of the file as a collection of lines.
Raise 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.

Usage example(s):

     'Makefile' asFilename contents
     'foobar' asFilename contents

o  contentsAsString
to compensate for the bad naming, use this to make things explicit.
See also #contents, which returns the lines as stringCollection for textFiles.

Usage example(s):

     'Makefile' asFilename contentsAsString
     'foobar' asFilename contentsAsString

o  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.

Usage example(s):

     'Makefile' asFilename contentsOfEntireFile
     'smalltalk.rc' asFilename contentsOfEntireFile
     'foobar' asFilename contentsOfEntireFile

o  contentsUpTo: size binary: binary
common helper to read a part of the file;
used to peek into files to guess the mimetype or to show a preview.
May return a shorter buffer (if the file is shorter),
or raise a readError.

o  readingFileDo: aOneArgBlock
Create a read stream on the receiver file, evaluate aBlock, passing that stream as arg,
and return the block's value.
If the file cannot be opened, an exception is raised.
Ensures that the stream is closed.

o  readingFileWithEncoding: encodingNameSymbol do: aOneArgBlock
Create a read stream on the receiver file, evaluate aBlock, passing that stream as arg,
and return the block's value.
If the file cannot be opened, an exception is raised.
Ensures that the stream is closed.
The file is decoded on the fly.

Usage example(s):

     'Make.proto' asFilename 
        readingFileWithEncoding:#utf8 
        do:[:stream |
            stream upToEnd
        ]

o  readingLinesDo: aOneArgBlock
Create a read stream on the receiver file and
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.

Usage example(s):

    '/etc/passwd' asFilename
        readingLinesDo:[:eachLine |
            Transcript showCR:eachLine.
        ].

Usage example(s):

    '/etc/xxxxx' asFilename
        readingLinesDo:[:eachLine |
            Transcript showCR:eachLine.
        ].

special accessing
o  osName
special - return the OS's name for the receiver.
Note: this may return an absolute pathName, if there are
place holders in the name.
Otherwise it keeps the name relative or absolute as it is.

o  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)

o  osNameForDirectory
internal - return the OS's name for the receiver to
access it as a directory.
Note: this may return an absolute pathName, if there are
place holders in the name.
Otherwise it keeps the name relative or absolute as it is.

Usage example(s):

        '.' asFilename osNameForDirectory
        '.' asFilename pathName

o  osNameForDirectoryContents
internal - return the OS's name for the receiver to
access it as a directory when reading its contents.
Note: this may return an absolute pathName, if there are
place holders in the name.
Otherwise it keeps the name relative or absolute as it is.

o  osNameForFile
internal - return the OS's name for the receiver to
access it as a file.
Note: this may return an absolute pathName, if there are
place holders in the name.
Otherwise it keeps the name relative or absolute as it is.

suffixes
o  addSuffix: aSuffix
return a new filename for the receiver's name with a additional suffix.
The new suffix is simply appended to the name,
regardless whether there is already an existing suffix.
See also #withSuffix:

Usage example(s):

     'abc.st' asFilename addSuffix:nil
     'a.b.c' asFilename addSuffix:nil
     '.b.c.' asFilename addSuffix:nil
     '.b.c' asFilename addSuffix:nil
     '.c.' asFilename addSuffix:nil
     '.c' asFilename addSuffix:nil
     'c.' asFilename addSuffix:nil
     '.' asFilename addSuffix:nil

     'abc.st' asFilename addSuffix:'o'
     'abc' asFilename addSuffix:'o'
     'a.b.c' asFilename addSuffix:'o'
     'a.b.c.' asFilename addSuffix:'o'
     '.b.c.' asFilename addSuffix:'o'
     '.c.' asFilename addSuffix:'o'
     '.c' asFilename addSuffix:'o'
     'c.' asFilename addSuffix:'o'
     '.' asFilename addSuffix:'o'
     '/foo/bar/baz.st' asFilename addSuffix:'c'
     '/foo/bar/baz.c' asFilename addSuffix:'st'
     '/foo/bar.c/baz.c' asFilename addSuffix:'st'
     '/foo/bar.c/baz' asFilename addSuffix:'st'

o  hasSuffix: aSuffixString
return true if my suffix is the same as aString.
This cares for systems, where case is ignored in filenames

Usage example(s):

     'abc.st' asFilename hasSuffix:'st'
     'abc.ST' asFilename hasSuffix:'st'
     '.ST' asFilename hasSuffix:'st'              -- false expected here in Unix, true in Windows
     '.foorc' asFilename hasSuffix:'foorc'        -- false expected here
     '.foorc.sav' asFilename hasSuffix:'sav'

o  hasSuffix: aSuffixString caseSensitive: caseSensitive
return true if my suffix is the same as aString

Usage example(s):

     'abc.st' asFilename hasSuffix:'st'
     'abc.ST' asFilename hasSuffix:'st'
     '.ST' asFilename hasSuffix:'st'              -- false expected here in Unix, true in Windows
     '.foorc' asFilename hasSuffix:'foorc'        -- false expected here
     '.foorc.sav' asFilename hasSuffix:'sav'

o  nameWithoutSuffix
return the receiver's name without the suffix.
If the name has no suffix, the original name is returned.

Usage example(s):

     'abc.st' asFilename nameWithoutSuffix            => 'abc'
     'abc' asFilename nameWithoutSuffix               => 'abc'
     '/abc' asFilename nameWithoutSuffix              => '/abc'
     '/abc.d' asFilename nameWithoutSuffix            => '/abc'
     './abc' asFilename nameWithoutSuffix             => './abc'
     './abc.d' asFilename nameWithoutSuffix           => './abc'
     './.abc' asFilename nameWithoutSuffix            => './.abc'
     'a.b.c' asFilename nameWithoutSuffix             => 'a.b'
     'a.b.' asFilename nameWithoutSuffix              => 'a.b'
     '.b.c' asFilename nameWithoutSuffix              => '.b'
     '.b.' asFilename nameWithoutSuffix               => '.b'
     '.b' asFilename nameWithoutSuffix                => '.b'
     '/foo/bar/baz.c' asFilename nameWithoutSuffix    => '/foo/bar/baz'
     '/foo/bar.x/baz.c' asFilename nameWithoutSuffix  => '/foo/bar.x/baz'
     '/foo/bar.x/baz' asFilename nameWithoutSuffix    => '/foo/bar.x/baz'
     '/foo/bar/baz/foo.c/bar' asFilename nameWithoutSuffix      => '/foo/bar/baz/foo.c/bar'
     '/foo/bar/baz/foo.c/bar.c' asFilename nameWithoutSuffix    => '/foo/bar/baz/foo.c/bar'

o  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.

Usage example(s):

     'abc.st' asFilename prefix
     'abc' asFilename prefix
     'a.b.c' asFilename prefix
     'a.b.c' asFilename prefix
     'a.' asFilename prefix
     '.a' asFilename prefix

o  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 file's 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.

Usage example(s):

     'abc.st' asFilename prefixAndSuffix
     'abc' asFilename prefixAndSuffix
     'a.b.c' asFilename prefixAndSuffix
     '/foo/bar.c/baz.c' asFilename prefixAndSuffix
     'a.' asFilename prefixAndSuffix
     '.a' asFilename prefixAndSuffix

     |parts|
     parts := 'Object.st' asFilename prefixAndSuffix.
     ((parts at:1) , '.o') asFilename

o  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.

Usage example(s):

     'abc.st' asFilename suffix
     'abc' asFilename suffix
     'a.b.c' asFilename suffix
     'a.b.c' asFilename suffix
     'a.' asFilename suffix
     '.a' asFilename suffix

o  withSuffix: aSuffix
return a new filename for the receiver's 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.

Usage example(s):

     'abc.st' asFilename withSuffix:nil
     'a.b.c' asFilename withSuffix:nil
     '.b.c.' asFilename withSuffix:nil
     '.b.c' asFilename withSuffix:nil
     '.c.' asFilename withSuffix:nil
     '.c' asFilename withSuffix:nil
     'c.' asFilename withSuffix:nil
     '.' asFilename withSuffix:nil

     'abc.st' asFilename withSuffix:'o'
     'abc.st' asFilename withSuffix:$o
     'abc.st' asFilename withSuffix:''
     'abc' asFilename withSuffix:'o'
     'abc' asFilename withSuffix:''
     'a.b.c' asFilename withSuffix:'o'
     'a.b.c.' asFilename withSuffix:'o'
     '.b.c.' asFilename withSuffix:'o'
     '.c.' asFilename withSuffix:'o'
     '.c' asFilename withSuffix:'o'
     'c.' asFilename withSuffix:'o'
     '.' asFilename withSuffix:'o'
     '/foo/bar/baz.st' asFilename withSuffix:'c'
     '/foo/bar/baz.c' asFilename withSuffix:'.st'
     '/foo/bar.c/baz.c' asFilename withSuffix:'st'
     '/foo/bar.c/baz' asFilename withSuffix:'st'

o  withoutSuffix
return a new filename for the receiver's name without the suffix.
If the name has no suffix, a filename representing the same file as the receiver is returned.

Usage example(s):

     'abc.st' asFilename withoutSuffix
     'abc' asFilename withoutSuffix
     '/abc' asFilename withoutSuffix
     '/abc.d' asFilename withoutSuffix
     './abc' asFilename withoutSuffix
     './abc.d' asFilename withoutSuffix
     './.abc' asFilename withoutSuffix
     'a.b.c' asFilename withoutSuffix
     'a.b.' asFilename withoutSuffix
     '.b.c' asFilename withoutSuffix
     '.b.' asFilename withoutSuffix
     '.b' asFilename withoutSuffix
     '/foo/bar/baz.c' asFilename withoutSuffix
     '/foo/bar.x/baz.c' asFilename withoutSuffix
     '/foo/bar.x/baz' asFilename withoutSuffix
     '/foo/bar/baz/foo.c/bar' asFilename withoutSuffix
     '/foo/bar/baz/foo.c/bar.c' asFilename withoutSuffix

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

writing-files
o  appendingFileDo: aOneArgBlock
create a append-stream on the receiver file, evaluate aBlock, passing that stream as arg,
and return the block's value.
If the file cannot be opened, an exception is raised.
Ensures that the stream is closed.

Usage example(s):

     'ttt' asFilename appendingFileDo:[:s |
        s nextPutLine:'hello'.
        s nextPutLine:'world'.
     ]

o  contents: aStringOrByteArrayOrCollectionOfLines
create (or overwrite) a file given its contents as a collection of lines.
Raises an error, if the file is unwritable.

Usage example(s):

     'foo1' asFilename contents:#('one' 'two' 'three').
     'foo2' asFilename contents:'Hello world'.
     'foo3' asFilename contents:#[1 2 3 4 5].

     #(foo1 foo2 foo3) do:[:e | e asFilename remove].        

o  writingFileDo: aOneArgBlock
create a write-stream on the receiver file, evaluate aBlock,
passing that stream as arg,
and return the block's value.
If the file cannot be opened, an exception is raised.
Ensures that the stream is closed.

Usage example(s):

     'ttt' asFilename writingFileDo:[:s |
        s nextPutLine:'hello'.
        s nextPutLine:'world'.
     ]

o  writingFileDoSafe: aOneArgBlock
Safe writing to a file, so that an already existing file with my name will no be corrupted,
even when the operation fails or is could oherwise not be terminated.
This is thread safe: when two threads write to the same file, the contets will not be mixed,
but the last operation will prevail.
Create a temporary file and open a write-stream to it,
evaluate aBlock, passing that stream as arg.
When done close the stream and rename the temp file to myself.
Return the block's value.
To be even more safe (but slower), you can do a #syncData on the stream in the block.
If the file cannot be opened, an exception is raised.

Usage example(s):

     'ttt' asFilename writingFileDoSafe:[:s |
        s nextPutLine:'hello'.
        s nextPutLine:'world'.
        s syncData.
     ].
     'ttt' asFilename contents.
     'ttt' asFilename remove.

o  writingFileWithEncoding: encodingNameSymbolOrNil do: aOneArgBlock
create a write-stream on the receiver file, evaluate aBlock,
passing that stream as arg and return the block's value.
If the file cannot be opened, an exception is raised.
Ensures that the stream is closed.
If encodingNameSymbolOrNil is not nil, the data is encoded on the fly.

Usage example(s):

     '/tmp/ttt' asFilename writingFileWithEncoding:#utf8 do:[:s |
        s nextPutLine:'hello'.
        s nextPutLine:'world'.
        s nextPutLine:'ÄÖÜßßß'.
     ]


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 file's full pathname (caring for relative names or symbolic links):
    |f|

    f := '..' asFilename.
    ^ f pathName
get a directory's directory:
    |f|

    f := Filename defaultDirectory.
    ^ f directory
get a file's 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 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Thu, 10 Oct 2024 10:10:34 GMT