Filename API Functions

This document lists most useful (and most often needed) functions. Be aware, that there are many more to be found in either the class references or via the builtin class browser.

See also "File Operations" in Expecco_API.
Reference: Filename

Back to Useful API Functions

Construction

Filename homeDirectory => Filename

return a filename representing the user's home folder

Filename currentDirectory => Filename

return a filename representing the current directory

Filename tmpDirectory => Filename

return a filename representing the directory for temporary files (typically, that is determined by a shell variable named "TMPDIR" or similar).

aString asFilename => Filename

given a string, make a filename instance from it. "/"-characters in aString will be replaced by "\" on Windows.

aFilename / aString => Filename

allows for portable construction of a path. "/"-characters in aString will be replaced by "\" on Windows.

e.g. "Filename homeDirectory / 'myFiles' / 'foo'" or "Filename homeDirectory / 'myFiles/foo'" might generate a filename for "/usr/fritz/myFiles/foo" on Unix and "C:\Users\anton\myFiles\foo" on Windows.

Queries

aFilename exists

aFilename.exists()   [JS]

Returns true if the file exists.

Example:

'data.txt' asFilename exists
=> false

aFilename isReadable

aFilename isWritable

aFilename isExecutable

Returns a boolean.
Notice that "isExecutable" has a special meaning for folders (ie. can be visited - refer to your Unix/Windows operating system manual).

Example:

'data.txt' asFilename isReadable
=> false

aFilename fileSize

Returns the file's size (in bytes). 0 if it does not exist (or is empty).

Example:

'data.txt' asFilename fileSize
=> 0

aFilename modificationTime

aFilename creationTime

aFilename accessTime

Returns the time of the last modification, initial creation and last access of the file.

Notice that Unix operating systems do not record a file's creationTime (in contrast to Windows). There, nil will be returned for creationTime.

Example:

'/etc' asFilename modificationTime
=> 2018-07-27 11:37:20

'c:\tmp\test.dat' asFilename modificationTime
=> 2010-01-27 22:37:20

Queries - Name & Path

aFilename baseName

aFilename.baseName() [JS]

Returns the filename's base name. This is the name without directory path - i.e. the file's name within its containing directory.

Examples:

'/etc/foo.txt' asFilename baseName

=> 'foo.txt'

'c:\foo\bar\bla.txt.dat' asFilename baseName

=> 'bla.txt.dat'

'foo' asFilename baseName

=> 'foo'

aFilename directory

aFilename directoryName

aFilename.directory() [JS]

aFilename.directoryName() [JS]

Returns the filename's containing directory either as a new filename instance (directory) or as string (directoryName). This is the directory part of the name.

Examples:

'/etc/foo.txt' asFilename directoryName

=> '/etc'

'c:\foo\bar\bla.txt.dat' asFilename directoryName

=> 'c:\foo\bar'

'foo' asFilename directoryName

=> '.'

'c:\foo\bar\bla.txt.dat' asFilename directory directory

=> Filename('c:\foo')

'/foo/bar/bla.txt.dat' asFilename directory directory

=> Filename('/foo')

aFilename suffix

aFilename.suffix() [JS]

Returns the filename's suffix, also called its filename extension. This is the part of the name after the last "." (period), except for the special case where the filename starts with a period.

Examples:

'foo.txt' asFilename suffix

=> 'txt'

'foo.txt.dat' asFilename suffix

=> 'dat'

'foo' asFilename suffix

=> ' ' (<- an empty string)

'.cvsignore' asFilename suffix

=> ' ' (<- an empty string)

aFilename hasSuffix: suffixString

aFilename.hasSuffix(suffixString) [JS]

aFilename hasSuffix: suffixString caseSensitive: aBoolean

aFilename.hasSuffix_caseSensitive(suffixString, aBoolean) [JS]

Returns true if the filename's suffix is the same as suffixString. The first variant (without casesensitive argument) cares for the operating system's behavior (i.e. insensitive on Windows, but case sensitive on Unix); the second variant compares as defined by the boolean argument.

Examples:

'foo.txt' asFilename hasSuffix:'txt'

=> true

'foo.txt.DAT' asFilename hasSuffix:'dat'

=> true on Windows, false on Unix

'foo.txt.DAT' asFilename hasSuffix:'dat' caseSensitive:false

=> false

aFilename withoutSuffix

aFilename.withoutSuffix() [JS]

Returns the filename without filename extension as filename instance.

That is: it returns the name before the last "." (period), except for the special case, where the name starts with a period.

Examples:

'/etc/foo.txt' asFilename withoutSuffix

=> '/etc/foo'

'c:\foo\bar\bla.txt.dat' asFilename withoutSuffix

=> Filename('c:\foo\bar\bla.txt')

'foo.exe' asFilename withoutSuffix

=> Filename('foo')

'.cvsignore' asFilename withoutSuffix

=> Filename('.cvsignore')

aFilename withSuffix: newSuffix

aFilename.withSuffix( newSuffix ) [JS]

This returns a new filename instance with a different filename extension after the last "." (period).

Examples:

'/etc/foo.txt' asFilename withSuffix:dat

=> Filename('/etc/foo.dat')

'c:\foo\bar\bla.txt.dat' asFilename withSuffix:'bbb'

=> Filename('c:\foo\bar\bla.txt.bbb')

'foo.exe' asFilename withSuffix:'dat'

=> Filename('foo.dat')

'foo' asFilename withSuffix:'dat'

=> Filename('foo.dat')

aFilename separator

Returns the directory separator, as a character.

Example:

'/foo' asFilename separator

=> $\ (on Windows)

=> $/ (on Unix)

Queries - Contents

aFilename mimeTypeFromName

Tries to guess the mime type from the file's name. Either returns a MimeType instance or nil if it cannot be guessed.

Example:

'test.png' asFilename mimeTypeFromName => 'image/png'

aFilename mimeTypeOfContents

Tries to guess the mime type from the file's contents. Either returns a MimeType instance or nil if it cannot be guessed.

Directory Contents

aFilename files

aFilename.files() [JS]

Returns a collection of all files in a directory (folder). The returned collection will not include names of subdirectories.

Example:

'/etc' asFilename files

=> #( ... )

aFilename filesMatching: multiPattern

aFilename filesMatching: multiPattern caseSensitive: boolean

aFilename.filesMatching(multiPattern) [JS]

Returns a collection of all files in a directory (folder) whose name matches given GLOB multi pattern. The returned collection will not include names of subdirectories.

The multi pattern may consist of multiple GLOB patterns, separated by semicolon.

Examples:

'/etc' asFilename filesMatching: 'a*'

=> #( ... )

'/etc' asFilename filesMatching: 'a*;b*;x*'

=> #( ... )

'/tmp' asFilename filesMatching: '*.dat;*.txt'

=> #( ... )

aFilename directories

aFilename.directories() [JS]

Returns a collection of all sub directories in a directory (non-recursive). The returned collection will not include names of regular files.

Examples:

'/etc' asFilename directories

=> #( ... )

'c:\' asFilename directories

=> #( ... 'c:\Program Files' ...)

Enumerating Directory Contents

aFilename directoriesDo: aOneArgBlock

aFilename.directoriesDo(aOneArgLambdaOrFunction) [JS]

Enumerates the sub-directories into the argument non-recursive (i.e. calls the block/function for each direct sub-directory).

Examples:

'c:\' asFilename directoriesDo:[:eachDir | ... do something with eachDir ...]

"c:\".asFilename.directoriesDo( function(eachDir) { ... do something with eachDir ...} ) [JS]

aFilename allDirectoriesDo: aOneArgBlock

aFilename.allDirectoriesDo(aOneArgLambdaOrFunction) [JS]

Same as above, but recurses into sub-directories (i.e. the whole tree of directories is enumerated)

aFilename filesDo: aOneArgBlock

aFilename.filesDo(aOneArgLambdaOrFunction) [JS]

Enumerates the non-directories into the argument non-recursive (i.e. calls the block/function for each direct non-directory).

aFilename filesDo: aOneArgBlock

aFilename.filesDo(aOneArgLambdaOrFunction) [JS]

Enumerates the non-directories into the argument non-recursive (i.e. calls the block/function for each direct non-directory).

aFilename recursiveDirectoryContentsDo: aOneArgBlock filterForVisitingDirectories: filterOrNil

Recursively enumerates files and directories into aOneArgBlock. Subdirectories are only processed/enumerated if filterOrNil is either nil or returns true. The processing block is called once for each relative filename.

Example:

to enumerate all files and folders under a top folder, but not in folders named "*.tmp", you could write:

'c:\myDir' asFilename recursiveDirectoryContentsDo:[:eachFile | ... ] filterForVisitingDirectories:[:dir | (dir hasSuffix:'tmp') not]

to enumerate all files and folders under a top folder, but only in subfolders named "Font", you could write:

'c:\Windows' asFilename recursiveDirectoryContentsDo:[:eachFile | ... ] filterForVisitingDirectories:[:dir | dir baseName = 'Fonts']

Notice that there are many more enumeration/filter functions provided by the Filename class. Use a class browser or consult the full online documentation.

Contents

The following functions read/write the whole contents of a file as one possibly big data object.
You should not use them for very large files, as they might allocate/require large amounts of memory;
use stream functions instead (and process it linewise, blockwise or characterwise).

aFilename contents

Returns a collection of text-lines (i.e. an Array-like object where each element represents one line of text)

aFilename contentsAsString

Returns a single (possibly big) string, a collection of characters

aFilename binaryContents

Returns a single (possibly big) byte array, a collection of integers in the range 0..255

aFilename contents: aStringOrByteArrayOrCollectionOfLines

Creates (i.e. writes) the file.

Examples:

'foo1' asFilename contents:'Hello world'.

'foo2' asFilename contents:#[1 2 3 4 0xFF 0xFE 0xFD].

'foo3' asFilename contents:#('line1' 'line2' 'line3').

Streaming

aFilename readStream

aFilename writeStream

aFilename appendingWriteStream

Return a stream for reading or writing to the file.

See Stream API Functions on how to use streams.

Example:

|s|

s := 'test.dat' asFilename readStream.

firstLine := s nextLine.

nextChar := s next.

nextNumber := Number readFrom:s

s close

aFilename utf8ReadStream

aFilename utf8WriteStream

Return a stream for reading or writing to the file. The stream will automatically generate/convert utf8 code sequences; i.e. the stream will not deliver/expect escape sequences, but possibly character instances with codepoints above 0xFF.

Example:

Writing as UTF8, reading binary:

|s bytes|

s := 'test.dat' asFilename utf8WriteStream.

s nextPutLine:'αβγψω⮠'.

s close.

bytes := 'test.dat' asFilename binaryContents.

bytes.

=> #[206 177 206 178 206 179 207 136 207 137 226 174 160 10]

Reading UTF8:

|s text|

s := 'test.dat' asFilename utf8ReadStream.

text := s nextLine.

s close.

text.

=> 'αβγψω⮠' (a widestring)

---

Copyright © 2014-2024 eXept Software AG