The file-system Module#

The File-System module is part of the System library and provides a generic interface to the file system of the local machine. Remotely mounted file systems are also accessible using this module.

Types specific to file system operations#

The File-System module contains a number of types specifically designed for use by interfaces in the module.

<file-type>
<pathname>
<copy/rename-disposition>

Manipulating files#

The File-System module contains a number of interfaces that let you perform standard file management operations on files already resident on the filesystem. You can rename, copy, or delete any file, and you can set any available properties for the file.

copy-file
delete-file
rename-file
file-property-setter
expand-pathname
shorten-pathname
with-open-file

Manipulating directories#

The File-System module contains a number of interfaces that let you create and delete directories. These can be used in conjunction with the file manipulation operations described in Manipulating files to perform file management tasks at any position in the file system.

create-directory
delete-directory
directory-contents
ensure-directories-exist
do-directory
working-directory-setter
directory-empty?

Finding out file system information#

A number of functions return environment information regarding the directory structure of the file system. Each function takes no arguments, and returns a pathname or list of pathnames. The return values can be use in conjunction with other functions to perform file-based operations relative to the directories involved.

home-directory
root-directories
temp-directory
working-directory

Finding out file information#

Several interfaces in the File-System module allow you to interrogate files for information. You can find out whether a file exists, what its name is, or which directory it resides in, and you can find the current properties of the file.

file-exists?
file-properties
file-property
file-type
link-target

File system locators#

The module offers multiple classes that reference either a directory or a file within the file system.

<file-system-locator>
<file-system-file-locator>
<file-system-directory-locator>

digraph G {
fontname="Arial,sans-serif";
node [shape=box, color=gray];

physical_locator [label="<physical-locator>\noa", style=dashed];
file_locator [label="<file-locator>\noa", style=dashed];
directory_locator [label="<directory-locator>\noa",style=dashed];
file_system_locator [label="<file-system-locator>\noa", style=bold, color="#17594A"];
file_system_file_locator [label="<file-system-file-locator>", style=bold, color="#17594A"];
file_system_directory_locator [label="<file-system-directory-locator>", style=bold, color="#17594A"];

physical_locator -> file_system_locator;
physical_locator -> directory_locator;
physical_locator -> file_locator;
file_system_locator -> file_system_file_locator;
file_locator -> file_system_file_locator;
file_system_locator -> file_system_directory_locator;
directory_locator -> file_system_directory_locator;
} — File system locator class diagram. Dashed boxes are classes from module locators.#

On Posix systems:

<posix-file-system-locator>
<posix-directory-locator>
<posix-file-locator>

digraph G {
fontname="Arial,sans-serif";
node [shape=box, color=gray];

physical_locator [label="<physical-locator>\noa", style=dashed] ;
directory_locator [label="<directory-locator>\noa",style=dashed];

file_locator [label="<file-locator>\noa", style=dashed];
file_system_locator [label="<file-system-locator>\noa"];
file_system_file_locator [label="<file-system-file-locator>"];
file_system_directory_locator [label="<file-system-directory-locator>"] ;

posix_file_system_locator [label="<posix-file-system-locator>\noas", style=bold, color="#17594A"];
posix_directory_locator [label="<posix-directory-locator>\ns", style=bold, color="#17594A"] ;
posix_file_locator [label="<posix-file-locator>\ns", style=bold, color="#17594A"]

physical_locator -> file_locator;
physical_locator -> file_system_locator;
physical_locator -> directory_locator;
directory_locator -> file_system_directory_locator;
file_locator -> file_system_file_locator;
file_system_locator -> file_system_file_locator;
file_system_locator -> file_system_directory_locator;
file_system_locator -> posix_file_system_locator;
file_system_directory_locator -> posix_directory_locator;
file_system_file_locator -> posix_file_locator;
posix_file_system_locator -> posix_directory_locator;
posix_file_system_locator -> posix_file_locator;
} — Posix file system hierarchy. Dashed boxes are classes from module locators.#

On Microsoft systems:

<microsoft-server-locator>
<microsoft-unc-locator>
<microsoft-volume-locator>
<microsoft-file-system-locator>
<microsoft-directory-locator>
<microsoft-file-locator>

digraph G {
fontname="Arial,sans-serif";
node [shape=box, color=gray];

locator [label="<locator>\noa",style=dashed];
physical_locator [label="<physical-locator>\noa", style=dashed] ;
directory_locator [label="<directory-locator>\noa",style=dashed];
server_locator [label="<server-locator>\noa",style=dashed];

file_locator [label="<file-locator>\noa", style=dashed];
file_system_locator [label="<file-system-locator>\noa"];

microsoft_file_system_locator [label="<microsoft-file-system-locator>\na", style=bold, color="#17594A"];
microsoft_server_locator [label="<microsoft-server-locator>\nas", style=bold, color="#17594A"];
microsoft_unc_locator [label="<microsoft-unc-locator>\ns", style=bold, color="#17594A"];
microsoft_volume_locator [label="<microsoft-volume-locator>\ns", style=bold, color="#17594A"];
microsoft_directory_locator [label="<microsoft-directory-locator>", style=bold, color="#17594A"];
microsoft_file_locator [label="<microsoft-file-locator>", style=bold, color="#17594A"];

locator -> server_locator;
locator -> physical_locator;
physical_locator -> file_locator;
physical_locator -> file_system_locator;
physical_locator -> directory_locator;
server_locator -> microsoft_server_locator;
directory_locator -> microsoft_directory_locator;
file_locator -> microsoft_file_locator;
file_system_locator -> microsoft_file_system_locator;
microsoft_file_system_locator -> microsoft_directory_locator;
microsoft_file_system_locator -> microsoft_file_locator;
microsoft_server_locator -> microsoft_unc_locator;
microsoft_server_locator -> microsoft_volume_locator;
} — Microsoft file system hierarchy. Dashed boxes are classes from module locators.#

Native locators, which are bound to the host platform:

<native-file-system-locator>

File streams#

File streams are intended only for accessing the contents of files. More general file handling facilities, such as renaming, deleting, moving, and parsing directory names, are provided by this module.

The make method on <file-stream> does not create direct instances of <file-stream>, but instead an instance of a subclass determined by type-for-file-stream. See make and Options when creating file streams below.

Options when creating file streams#

When creating file streams, you can supply the following init-keywords to make in addition to those described in File streams:

if-exists: An action to take if the file already exists.
if-does-not-exist: An action to take if the file does not already exist.
element-type: How the elements of the underlying file are accessed.
asynchronous?: Allows asynchronous writing of stream data to disk.
share-mode: How the file can be accessed while the stream is operating on it.

The if-exists: init-keyword allows you to specify an action to take if the file named by filename already exists. The options are:

#f The file is opened with the stream position at the beginning. This is the default when the stream’s direction is #"input" or #"input-output".
#"new-version" If the underlying file system supports file versioning, a new version of the file is created. This is the default when the stream’s direction is #"output". If the file system does not support file versioning, the default is #"replace" when the direction of the stream is #"output".
#"overwrite" Set the stream’s position to the beginning of the file, but preserve the current contents of the file. This is useful when the direction is #"input-output" or #"output" and you want to overwrite an existing file.
#"replace" Delete the existing file and create a new file.
#"append" Set the stream’s initial position to the end of the existing file so that all new output occurs at the end of the file. This option is only useful if the file is writeable.
#"truncate" If the file exists, it is truncated, setting the size of the file to 0. If the file does not exist, create a new file.
#"signal" Signal a <file-exists-error> condition.

The if-does-not-exist: init-keyword allows you to specify an action to take if the file named by filename does not exist. The options are:

#f No action.
#"signal" Signal a <file-does-not-exist-error> condition. This is the default when the stream’s direction is #"input".
#"create" Create a new zero-length file. This is the default when the stream’s direction is #"output" or #"input-output".

Because creating a file stream always involves an attempt to open the underlying file, the aforementioned error conditions will occur during file stream instance initialization.

File permissions are checked when creating and opening file streams, and if the user attempts to open a file for input, and has no read permission, or to open a file for output, and has no write permission, then an <invalid-file-permissions-error> condition is signalled at the time the file stream is created.

The element-type: init-keyword controls how the elements of the underlying file are accessed. The three possible element types are:

<byte-character> The file is accessed as a sequence of 8-bit characters.
<unicode-character> The file is accessed as a sequence of 16-bit Unicode characters.
<byte> The file is accessed as a sequence of unsigned 8-bit integers.

The asynchronous?: init-keyword allows asynchronous writing of stream data to disk. If #f, whenever the stream has to write a buffer to disk, the thread which triggered the write must wait for the write to complete. If asynchronous? is #t, the write proceeds in parallel with the subsequent actions of the thread.

Note that asynchronous writes complicate error handling a bit. Any write error which occurs most likely occurs after the call which triggered the write. If this happens, the error is stored in a queue, and the next operation on that stream signals the error. If you close the stream with the wait? flag #f, the close happens asynchronously (after all queued writes complete) and errors may occur after close has returned. A method wait-for-io-completion is provided to catch any errors that may occur after close is called.

The share-mode: keyword determines how a file can be accessed by other streams while the stream has it open. The possible values are:

#"share-read" Allow other streams to be opened to the file for reading but not for writing.
#"share-write" Allow other streams to be opened for writing but not for reading.
#"share-read-write" Allow other streams to be opened for writing or reading.
#"exclusive" Do not allow other streams to be opened to this file.

Conditions#

The conditions signaled by this module are:

<file-system-error>
<file-error>
<file-exists-error>
<file-does-not-exist-error>
<invalid-file-permissions-error>

All errors directly signaled by this module are subclasses of <file-system-error>.

The file-error-locator provides extra details about the file locator that signals the condition. This function can be used on the class <file-error> and its subclasses.

The FILE-SYSTEM module reference#

This section contains a reference entry for each item included in the File-System module.

copy-file Function#

Creates a copy of a file.

Signature:

copy-file old-file new-file #key if-exists => ()

Parameters:

old-file – An instance of <pathname>.
new-file – An instance of <pathname>.
if-exists (#key) – An instance of <copy/rename-disposition>. Default value: #"signal".

Discussion:

Copies old-file to new-file. If new-file already exists, the action of this function is controlled by the value of if-exists. The default is to prompt you before overwriting an existing file.

See also:

<copy/rename-disposition>
rename-file

<copy/rename-disposition> Type#

The type that represents possible actions when overwriting existing files.

Equivalent:

one-of(#"signal", #"replace")

Discussion:

This type represents the acceptable values for the if-exists: argument to the copy-file and rename-file functions. Only two values are acceptable:

If #"signal" is used, then you are warned before a file is overwritten during a copy or move operation.
If #"replace" is used, then you are not warned before a file is overwritten during a copy or move operation.

Operations:

copy-file
rename-file

See also:

copy-file
rename-file

create-directory Function#

Creates a new directory in the specified parent directory.

Signature:

create-directory parent name => directory

Parameters:

parent – An instance of <pathname>.
name – An instance of <string>.

Values:

directory – An instance of <pathname>.

Discussion:

Creates directory in the specified parent directory. The return value of this function can be used with concatenate to create pathnames of entities in the new directory.

See also:

delete-directory

delete-directory Function#

Deletes the specified directory.

Signature:

delete-directory directory #key recursive? => ()

Parameters:

directory – An instance of <pathname>.
recursive? (#key) – An instance of <boolean>. Default value: #f

Discussion:

Deletes the specified directory. By default the directory may only be deleted if it is empty. Pass recursive?: #t to delete the directory and its contents recursively.

See also:

create-directory
delete-file

delete-file Function#

Deletes the specified file system entity.

Signature:

delete-file file => ()

Parameters:

file – An instance of <pathname>.

Discussion:

Deletes the file system entity specified by file. If file refers to a link, the link is removed, but the actual file that the link points to is not removed.

directory-contents Function#

Returns a sequence of files and subdirectories contained in a directory.

Signature:

directory-contents directory => locators

Parameters:

directory – An instance of <pathname>.

Values:

locators – A <sequence> of <locator>.

Discussion:

In the result, each file is represented by a <file-locator> and each directory is represented by a <directory-locator>. The “.” and “..” directories are not included in the result.

directory-empty? Generic function#

Checks whether a directory is empty or not.

Signature:

directory-empty? directory => empty?

Parameters:

directory – An instance of <pathname>,

Values:

empty? – An instance of <boolean>.

directory-empty?(<file-system-directory-locator>) Method#

Parameters:

directory – An instance of <file-system-directory>.

Values:

empty? – An instance of <boolean>.

do-directory Function#

Executes the supplied function once for each entity in the specified directory.

Signature:

do-directory function directory => ()

Parameters:

function – An instance of <function>.
directory – An instance of <pathname>.

Discussion:

Executes function once for each entity in directory.

The signature of function is:

*function* *directory* *name* *type* => ()

where directory is an instance of <pathname>, name is an instance of <byte-string>, and type is an instance of <file-type>.

Within function, the values of directory and name can be concatenated to generate a <pathname> suitable for use by the other functions in the module.

The following calls are equivalent:

do-directory(my-function, "C:\\USERS\\JOHN\\FOO.TEXT")

do-directory(my-function, "C:\\USERS\\JOHN\\")

as they both operate on the contents of C:\\USERS\\JOHN. The call:

do-directory(my-function, "C:\\USERS\\JOHN")

is not equivalent as it will operate on the contents of C:\\USERS.

ensure-directories-exist Function#

Ensures that all the directories in the pathname leading to a file exist, creating any that do not, as needed.

Signature:

ensure-directories-exist file => created?

Parameters:

file – An instance of <pathname>.

Values:

created? – An instance of <boolean>.

Discussion:

Ensures that all the directories in the pathname leading to a file exist, creating any that do not, as needed. The return value indicates whether or not any directory was created.

The following calls are equivalent:

ensure-directories-exist("C:\\USERS\\JOHN\\FOO.TEXT")
ensure-directories-exist("C:\\USERS\\JOHN\\")

as they will both create the directories USERS and JOHN if needed. The call:

ensure-directories-exist("C:\\USERS\\JOHN")

is not equivalent as it will only create USERS if needed.

Example:

ensure-directories-exist("C:\\USERS\\JOHN\\FOO.TEXT")

See also:

create-directory

expand-pathname Generic function#

Given a pathname, returns its fully expanded form.

Signature:

expand-pathname path => expanded-path

Parameters:

path – An instance of <pathname>.

Values:

expanded-path – An instance of <pathname>.

expand-pathname(<file-system-locator>) Method#

Expand a file path to its fully expanded form.

Parameters:

path – An instance of <file-system-locator>.

expand-pathname(<string>) Method#

Expands a pathname given as a string.

Parameters:

path – An instance of <string>.

file-error-locator Generic function#

Signature:

file-error-locator error => (locator)

Parameters:

error – An instance of <file-error>.

Values:

locator – An instance of <file-system-file-locator>.

Discussion:

Returns the file locator associated with the error.

<file-does-not-exist-error> Class#

Error type signaled accessing a file that do not exist.

Superclasses:: <file-error>
Discussion:: Signaled when trying to open a file and the file does not already exist.

<file-error> Class#

Error type signaled for all failed file operations.

Superclasses:

<file-system-error>

Init-Keywords:

locator – An instance of <file-system-file-locator>. Specifies the file locator related with the error.

Discussion:

Signaled when one of the file system functions triggers an error, such as a permissions error when trying to delete or rename a file. It provides information about the file locator.

See also:

<file-system-error>
<file-system-file-locator>
<locator>

<file-exists-error> Class#

Error type signaled when a file already exists.

Superclasses:: <file-error>
Discussion:: Signaled when an attempt is made to create a file and it already exists.

file-exists? Function#

Returns #t if the specified file exists.

Signature:

file-exists? file #key follow-links? => exists?

Parameters:

file – An instance of <pathname>.
follow-links? – An instance of <boolean>. Defaults to #t.

Values:

exists? – An instance of <boolean>.

Discussion:

Returns #t if file exists. If the file refers to a symbolic link, the behavior depends on the value of follow-links?. If follow-links? is true (the default) the target of the link is checked; otherwise the link itself is checked.

file-properties Function#

Returns all the properties of a file system entity.

Signature:

file-properties file => properties

Parameters:

file – An instance of <pathname>.

Values:

properties – An instance of a concrete subclass of <explicit-key-collection>.

Discussion:

Returns all the properties of file. The keys to the properties collection are the same as those use by file-property, above.

Example:

file-properties() [#"size"]

See also:

file-property
file-property-setter

file-property Sealed Generic function#

Returns the specified property of a file system entity.

Signature:

file-property file #key key => property

Parameters:

file – An instance of <pathname>.
key (#key) – One of #"author", #"size", #"creation-date", #"access-date", #"modification-date", #"readable?", #"writeable?", #"executable?".

Values:

property – The value of the property specified by key. The type of the value returned depends on the value of key: see the description for details.

Discussion:

Returns the property of file specified by key. The value returned depends on the value of key, as shown in Table Return value types of file-property.

Return value types of `file-property`#
Value of key	Type of return value
`#"author"`	`false-or(<string>)`
`#"size"`	`<integer>`
`#"creation-date"`	`<date>`
`#"access-date"`	`<date>`
`#"modification-date"`	`<date>`
`#"readable?"`	`<boolean>`
`#"writeable?"`	`<boolean>`
`#"executable?"`	`<boolean>`

Not all platforms implement all of the above keys. Some platforms may support additional keys. The #"author" key is supported on all platforms but may return #f if it is not meaningful on a given platform. Use of an unsupported key signals an error.

All keys listed above are implemented by Win32, though note that #"author" always returns #f.

See also:

file-property-setter
file-properties

file-property-setter Sealed Generic function#

Sets the specified property of a file system entity to a given value.

Signature:

file-property-setter new-value file key => new-value

Parameters:

new-value – The type of this depends on the value of key. See the description for details.
file – An instance of <pathname>.
key – One of #"author", #"size", #"creation-date", #"access-date", #"modification-date", #"readable?", #"writeable?", #"executable?".

Values:

new-value – The type of this depends on the value of key. See the description for details.

Discussion:

Sets the property of file specified by key to new-value. The type of new-value depends on the property specified by key, as shown in Table New value types of file-property-setter below.

New value types of *file-property-setter*#
Value of key	Type of new-value
`#"author"`	`false-or(<string>)`
`#"size"`	`<integer>`
`#"creation-date"`	`<date>`
`#"access-date"`	`<date>`
`#"modification-date"`	`<date>`
`#"readable?"`	`<boolean>`
`#"writeable?"`	`<boolean>`
`#"executable?"`	`<boolean>`

Note that file-property-setter returns the value that was set, and so return values have the same types as specified values, depending on the value of key.

Not all platforms implement all of the above keys. Some platforms may support additional keys. Use of an unsupported key signals an error.

The only property that can be set on Win32 is #"writeable?".

See also:

file-property
file-properties

<file-system-error> Class#

Error type signaled when any other functions in the File-System module signal an error.

Superclasses:: <error>, <simple-condition>
Discussion:: Signaled when one of the file system functions triggers an error, such as a permissions error when trying to delete or rename a file.

<file-system-locator> Open Abstract Class#

Superclasses:: <physical-locator>

A file system locator is a locator that refers to either a directory or a file within the file system.

<file-system-file-locator> Class#

Superclasses:: <file-system-locator>, <file-locator>

This locator refers to a non-directory file within a file system.

<file-system-directory-locator> Class#

Superclasses:: <file-system-locator>, <directory-locator>

This locator refers to a directory within a file system.

file-system-separator Function#

Returns the character used to separate the directory components in a file path.

Signature:

file-system-separator => separator

Values:

separator – An instance of <character>.

Discussion:

The character separator used in a file system is determined by the specific file system and operating system. Open Dylan offers modules that transparently provide the appropriate separator for Posix and Microsoft systems.

file-type Function#

Returns the type of the specified file system entity.

Signature:

file-type file => file-type

Parameters:

file – An instance of <pathname>.

Values:

file-type – An instance of <file-type>.

Discussion:

Returns the type of file, the specified file system entity. A file system entity can either be a file, a directory, or a link to another file or directory.

<file-type> Type#

The type representing all possible types of a file system entity.

Equivalent:

one-of(#"file", #"directory", #"link")

Discussion:

The type representing all possible types of a file system entity. An entity on the file system can either be a file, a directory or folder, or a link to another file or directory. The precise terminology used to refer to these different types of entity depends on the operating system you are working in.

Operations:

do-directory

home-directory Function#

Returns the current value of the home directory.

Signature:

home-directory () => home-directory

Values:

home-directory – An instance of <pathname>.

Discussion:

Returns the current value of the home directory. The return value of this function can be used with concatenate to create pathnames of entities in the home directory.

<invalid-file-permissions-error> Class#

Signals an error when the user has no permission to create, delete, read or write a file.

Superclasses:: <file-error>
Discussion:: Signals an error when you attempt to perform an operation on a file or directory that requires certain permissions, but the permissions set on the file are incorrect or insufficient for your operation.

link-target Function#

Returns the target of a symbolic link.

Signature:

link-target file => target

Parameters:

file – An instance of type <pathname>.

Values:

target – An instance of type <pathname>.

Discussion:

Repeatedly follows symbolic links starting with file until it finds a non-link file or directory, or a non-existent link target.

make(<file-stream>) Method#

Creates and opens a stream over a file.

Signature:

make file-stream-class #key filename direction if-exists if-does-not-exist buffer-size element-type => file-stream-instance

Parameters:

file-stream-class – The class <file-stream>.
locator (#key) – An instance of <object>.
direction (#key) – One of #"input", #"output", or #"input-output". The default is #"input".
if-exists (#key) – One of #f, #"new-version", #"overwrite", #"replace", #"append", #"truncate", #"signal". Default value: #f.
if-does-not-exist (#key) – One of #f, #"signal", or #"create". Default value: depends on the value of direction.
buffer-size (#key) – An instance of <integer>.
element-type (#key) – One of <byte-character>, <unicode-character>, or <byte>, or #f.

Values:

file-stream-instance – An instance of <file-stream>.

Discussion:

Creates and opens a stream over a file.

Returns a new instance of a concrete subclass of <file-stream> that streams over the contents of the file referenced by filename. To determine the concrete subclass to be instantiated, this method calls the generic function type-for-file-stream.

The locator init-keyword should be a <file-locator> or a <string> that can be coerced to one.

The direction init-keyword specifies the direction of the stream. This can be one of #"input", #"output", or #"input-output". The default is #"input".

The if-exists and if-does-not-exist init-keywords specify actions to take if the file named by filename does or does not already exist when the stream is created. These init-keywords are discussed in more detail in Options when creating file streams.

The buffer-size init-keyword can be used to suggest the size of a stream’s buffer. See <buffered-stream>.

The element-type init-keyword specifies the type of the elements in the file named by filename. This allows file elements to be represented abstractly; for instance, contiguous elements could be treated as a single database record. This init-keyword defaults to something useful, potentially based on the properties of the file; byte-character and unicode-character are likely choices. See Options when creating file streams.

See also:

<microsoft-server-locator> Abstract Sealed Class#

The abstract superclass of all servers using Microsoft protocols.

Superclasses:: <server-locator>
See also:: <microsoft-unc-locator> <microsoft-volume-locator>

<microsoft-unc-locator> Sealed Class#

A server located using Microsoft’s Univeral Naming Convention, for example \\ComputerName\Share

Superclasses:: <microsoft-server-locator>

<microsoft-volume-locator> Sealed Class#

A server located using a volume name (drive letter) on a Microsoft system, for example C.

Superclasses:: <microsoft-server-locator>

<microsoft-file-system-locator> Abstract Class#

The abstract superclass of files and directories on Microsoft file systems.

Superclasses:: <file-system-locator>

<microsoft-directory-locator> Class#

A directory on a Microsoft file system.

Superclasses:

<microsoft-file-system-locator>, <directory-locator>

Slots:

locator-server – the server which holds this directory.

<microsoft-file-locator> Class#

A file on a Microsoft file system.

Superclasses:

<microsoft-file-system-locator>, <file-locator>

Slots:

locator-directory – the directory that holds this file.
locator-base – the file name without extension.
locator-extension – the file extension.

<native-file-system-locator> Constant#

File system locator bound to the host system locator.

Discussion:

A native file system locator is specific to the host system it is running on. For example, if the host system is Posix, the file locator is bound to <posix-file-system-locator>, and if the host system is Microsoft, it is bound to <microsoft-file-system-locator>.

See also:

<posix-file-system-locator>
<microsoft-file-system-locator>

<pathname> Type#

The type representing a file system entity.

Equivalent:

type-union(<string>, <file-system-locator>)

Discussion:

A type that identifies a file system entity. This can be either a <string> or a <file-system-locator>.

Operations:

copy-file
create-directory
delete-directory
delete-file
do-directory
ensure-directories-exist
file-exists?
file-properties
file-property
file-property-setter
file-type
home-directory
link-target
rename-file

<posix-file-system-locator> Abstract Sealed Class#

The abstract superclass of files and directories on a posix-like file system.

Superclasses:: <file-system-locator>

<posix-directory-locator> Sealed Class#

A directory on a posix-like file system.

Superclasses:: <file-system-directory-locator>, <posix-file-system-locator>

<posix-file-locator> Sealed Class#

A file on a posix-like file system.

Superclasses:

<file-system-file-locator>, <posix-file-system-locator>

Slots:

locator-directory – the directory that holds this file.
locator-base – the file name without extension.
locator-extension – the file extension.

rename-file Function#

Renames a specified file.

Signature:

rename-file old-file new-file #key if-exists => ()

Parameters:

old-file – An instance of <pathname>.
new-file – An instance of <pathname>.
if-exists – An instance of <copy/rename-disposition>. Default value: #"signal".

Discussion:

Renames old-file to new-file. If new-file already exists, the action of this function is controlled by the value of if-exists. The default is to prompt you before overwriting an existing file.

This operation may fail if the source and destination are not on the same file system.

See also:

copy-file
<copy/rename-disposition>

root-directories Function#

Returns a sequence containing the pathnames of the root directories of the file systems on the local machine.

Signature:

root-directories () => roots

Values:

roots – An instance of <sequence>.

Discussion:

Returns a sequence containing the pathnames of the root directories of the file systems on the local machine.

shorten-pathname Generic function#

Given a pathname, returns the shortest equivalent form.

Signature:

shorten-pathname path => shortened-path

Parameters:

path – An instance of <pathname>.

Values:

shorten-pathname – An instance of <pathname>.

Discussion:

Given a pathname, returns the shortest equivalent form. For instance a DOS pathname on Windows.

shorten-pathname(<file-system-locator>) Method#

A specialization of shorten-pathname.

Parameters:

path – An instance of <file-system-locator>

temp-directory Function#

Returns the pathname of the temporary directory in use.

Signature:

temp-directory () => temp-directory

Values:

temp-directory – An instance of <pathname>, or false.

Discussion:

Returns the pathname of the temporary directory in use. The return value of this function can be used with concatenate to create pathnames of entities in the temporary directory. If no temporary directory is defined, temp-directory returns #f. On Windows the temporary directory is specified by the TMP environment variable.

with-open-file Statement Macro#

Runs a body of code within the context of a file stream.

Macro Call:

with-open-file (stream-var = filename, #rest keys)
  body
end => values

Parameters:

stream-var – An Dylan variable-name bnf.
filename – An instance of <string>.
keys – Instances of <object>.
body – A Dylan body bnf.

Values:

values – Instances of <object>.

Discussion:

Provides a safe mechanism for working with file streams. The macro creates a file stream and binds it to stream-var, evaluates a body of code within the context of this binding, and then closes the stream. The macro calls close upon exiting body.

The values of the last expression in body are returned.

Any keys are passed to the make method on <file-stream>.

Example:

The following expression yields the contents of file foo.text as a <byte-vector>:

with-open-file (fs = "foo.text", element-type: <byte>)
  read-to-end(fs)
end;

It is roughly equivalent to:

begin
  let hidden-fs = #f; // In case the user bashes fs variable
  block ()
    hidden-fs := make(<file-stream>,
                      locator: "foo.text", element-type: <byte>);
    let fs = hidden-fs;
    read-to-end(fs);
  cleanup
    if (hidden-fs) close(hidden-fs) end;
  end block;
end;

See also:

working-directory Function#

Returns the working directory for the current process.

Signature:

working-directory () => working-directory

Values:

working-directory – An instance of <pathname>.

Discussion:

Returns the <pathname> of the current working directory in the current process on the local machine. You can use the return value of working-directory in conjunction with concatenate to specify pathnames of entities in the working directory.

See also:

working-directory-setter

working-directory-setter Function#

Sets the working directory for the current process.

Signature:

working-directory-setter directory => directory

Parameters:

directory – An instance of <pathname>.

Values:

directory – An instance of <pathname>.

Discussion:

Sets the working directory for the current process.

Note that the following calls are equivalent

working-directory() := "C:\\USERS\\JOHN\\FOO.TEXT";
working-directory() := "C:\\USERS\\JOHN\\";

as they will both set the working directory to C:\USERS\JOHN. The call

working-directory() := "C:\\USERS\\JOHN";

is not equivalent as it sets the working directory to C:\USERS.

Example:

working-directory() := "C:\\USERS\\JOHN\\";

See also:

working-directory