The locators Module

Introduction

The Locators module provides Dylan programs with a portable, flexible, and uniform facility for locating files.

The LOCATORS module

<locator> Open Abstract Class
Superclasses:<object>

This is the base class for all locators. This is the usual locator class for coercion (using as) or instantiation (using make) of new locators. Situations where this class is not appropriate are ones where there is not enough information provided to select the appropriate concrete class. For example, it is not appropriate to coerce a string representing a portion of a URL without a scheme, such as as(<locator>, "toothpaste.html"), because this would likely result in the instantiation of a native locator instead of the desired URL locator class.

<physical-locator> Open Abstract Class
Superclasses:<locator>

A physical locator is a locator which refers to an object (such as a file or directory) in a physical file system. This locator class is useful for coercing an abstract locator into its corresponding physical counterpart.

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

<directory-locator> Open Abstract Class
Superclasses:<physical-locator>

A directory locator is a locator that refers to a directory as distinct from a file. This is important in file systems which can view a directory as either a file or a directory. This locator class is useful for coercing a file locator into a form where it can be manipulated as a directory (e.g. for constructing a locator to a file in a directory).

<native-directory-locator> Constant

This is bound to the native directory locator type for the host platform. On Windows, this is typically <microsoft-directory-locator> while on POSIX platforms, it is <posix-directory-locator>.

<file-locator> Open Abstract Class
Superclasses:<physical-locator>

A file locator is a locator which refers to a file as distinct from a directory. This is important in file systems which can view a directory as either a file or a directory. This locator class is useful for coercing a directory locator into a form where it can be manipulated as a file.

<native-file-locator> Constant

This is bound to the native file locator type for the host platform. On Windows, this is typically <microsoft-file-locator> while on POSIX platforms, it is <posix-file-locator>.

<locator-error> Class
Superclasses:<format-string-condition>, <error>
<server-locator> Open Abstract Class
Superclasses:<locator>
list-locator Open Generic function

Return a sequence of locators that are children of the given locator.

Signature:

list-locator (locator) => (locators)

Parameters:
Values:
Discussion:

Return a sequence of locators that are children of the given locator.

Note that this should only be called on a locator for which supports-list-locator? returns true.

See also:

list-locator(<file-system-directory-locator>) Method

Returns a sequence of locators for the files and directories within the directory specified by the directory locator.

Parameters:
  • locator – An instance of <file-system-directory-locator>.
Values:
Discussion:

Returns a sequence of locators for the files and directories within the directory specified by the directory locator.

Instances of <file-system-file-locator> for files and symbolic links. subdirectory-locator will be called to create locators for any directories.

See also:

locator-address Generic function
Signature:

locator-address (object) => (#rest results)

Parameters:
Values:
  • #rest results – An instance of <object>.
locator-as-string Open Generic function
Signature:

locator-as-string (class locator) => (string)

Parameters:
  • class – An instance of subclass(<string>).
  • locator – An instance of <locator>.
Values:
locator-base Open Generic function
Signature:

locator-base (locator) => (base)

Parameters:
Values:
  • base – An instance of false-or(<string>).
locator-directory Open Generic function
Signature:

locator-directory (locator) => (directory)

Parameters:
Values:
  • directory – An instance of false-or(<directory-locator>).
locator-error Function
Signature:

locator-error (format-string #rest format-arguments) => (#rest results)

Parameters:
  • format-string – An instance of <string>.
  • format-arguments (#rest) – An instance of <object>.
Values:
  • #rest results – An instance of <object>.
locator-extension Open Generic function
Signature:

locator-extension (locator) => (extension)

Parameters:
Values:
  • extension – An instance of false-or(<string>).
locator-file Generic function
Signature:

locator-file (object) => (#rest results)

Parameters:
Values:
  • #rest results – An instance of <object>.
locator-host Open Generic function
Signature:

locator-host (locator) => (host)

Parameters:
Values:
  • host – An instance of false-or(<string>).
locator-name Generic function
Signature:

locator-name (locator) => (#rest results)

Parameters:
Values:
  • #rest results – An instance of <object>.
locator-path Open Generic function
Signature:

locator-path (locator) => (path)

Parameters:
Values:
locator-relative? Open Generic function
Signature:

locator-relative? (locator) => (relative?)

Parameters:
Values:
locator-server Open Generic function
Signature:

locator-server (locator) => (server)

Parameters:
Values:
  • server – An instance of false-or(<server-locator>).
locator-volume Open Generic function
Signature:

locator-volume (locator) => (volume)

Parameters:
Values:
  • volume – An instance of false-or(<string>).
merge-locators Open Generic function
Signature:

merge-locators (locator from-locator) => (merged-locator)

Parameters:
Values:
open-locator Open Generic function
Signature:

open-locator (locator #key #all-keys) => (stream)

Parameters:
Values:
relative-locator Open Generic function
Signature:

relative-locator (locator from-locator) => (relative-locator)

Parameters:
Values:
simplify-locator Open Generic function
Signature:

simplify-locator (locator) => (simplified-locator)

Parameters:
Values:
string-as-locator Open Generic function
Signature:

string-as-locator (class string) => (locator)

Parameters:
  • class – An instance of subclass(<locator>).
  • string – An instance of <string>.
Values:
subdirectory-locator Open Generic function

Returns a directory locator for a subdirectory of a given directory.

Signature:

subdirectory-locator (locator #rest sub-path) => (subdirectory)

Parameters:
Values:
Example:
let build-dir = subdirectory-locator(working-directory(), "_build");
supports-list-locator? Open Generic function

Returns whether or not a given locator supports the list-locator operation.

Signature:

supports-list-locator? (locator) => (listable?)

Parameters:
Values:
See also:

supports-list-locator?(<file-system-directory-locator>) Method

Returns true if the directory locator is not relative.

Parameters:
  • locator – An instance of <file-system-directory-locator>.
Values:
See also:

supports-open-locator? Open Generic function

Returns whether or not a given locator supports the open-locator operation.

Signature:

supports-open-locator? (locator) => (openable?)

Parameters:
Values: