The locators Module

The Locators module provides Dylan programs with a portable, flexible, and uniform facility for locating files and other objects on the internet.

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.

Note

Locator classes representing file system objects are documented in The file-system Module.

<directory-locator> Open Abstract Class

Superclasses:

<physical-locator>

Slots:

• locator-relative? – #t if the locator is relative, #f if it is absolute.

• locator-path – the path to the directory.

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

All errors raised by the locator system should be instances of this error.

Superclasses:

<format-string-condition>, <error>

<server-locator> Open Abstract Class

The abstract superclass of locators for servers.

Superclasses:

<locator>

See also:

• <server-url>

• <microsoft-server-locator>

list-locator Open Generic function

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

Signature:

list-locator (locator) => (locators)

Parameters:

• locator – An instance of <locator>.

Values:

• locators – An instance of <sequence>.

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:

• supports-list-locator?

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:

• locators – An instance of <sequence>.

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:

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

• do-directory

locator-address Generic function

Signature:

locator-address (mailto) => (address)

Parameters:

• mailto – An instance of <mail-to-locator>.

Values:

• address – An instance of <string>.

Discussion:

Returns the email address specified by the mailto locator.

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:

• string – An instance of <string>.

locator-base Open Generic function

Signature:

locator-base (locator) => (base)

Parameters:

• locator – An instance of <locator>.

Values:

• base – An instance of false-or(<string>).

Discussion:

Returns the locator name without extension. For example, if a file locator’s path was a/b/c.txt, the locator-base would be c.

locator-directory Open Generic function

Signature:

locator-directory (locator) => (directory)

Parameters:

• locator – An instance of <locator>.

Values:

• directory – An instance of false-or(<directory-locator>).

Discussion:

Returns the enclosing directory of a locator, or #f if it is not in a directory.

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:

• locator – An instance of <locator>.

Values:

• extension – An instance of false-or(<string>).

Discussion:

Returns the extension part of the locator name. For example, if a file locator’s path was a/b/c.txt, the locator-extension would be txt. Returns #f if the locator does not have an extension.

locator-file Generic function

Signature:

locator-file (url) => (file)

Parameters:

• url – An instance of <file-index-url> or <cgi-url>.

Values:

• file – An instance of <file-url>.

Discussion:

Returns the file URL of a file index or CGI URL. For example, the locator-file of http://example.com/index.html#tag or http://example.com/index.html?q=text would be http://example.com/index.html

locator-host Open Generic function

Returns the host name.

Signature:

locator-host (locator) => (host)

Parameters:

• locator – An instance of <locator>.

Values:

• host – An instance of false-or(<string>).

Discussion:

Returns the computer host name of a <server-url> or <microsoft-unc-locator>.

locator-name Generic function

Returns the name of this locator.

Signature:

locator-name (locator) => (name)

Parameters:

• locator – An instance of <locator>.

Values:

• name – An instance of false-or(<string>).

Discussion:

This is typically the last component of the locator’s path but can be different for some specializations.

locator-name(<mailto-locator>) Method

Returns the email address of this locator.

Parameters:

• locator – an instance of <mailto-locator>

Values:

• name – An instance of <string>

locator-name(<mailto-locator>) Method

Returns the email address of this locator.

Parameters:

• locator – an instance of <mailto-locator>

Values:

• name – An instance of <string>

locator-name(<microsoft-volume-locator>) Method

Returns the drive letter of this locator.

Parameters:

• locator – an instance of <microsoft-volume-locator>

Values:

• name – An instance of <string>

Discussion:

The drive is returned as a single letter, for example, ‘A’

locator-name(<microsoft-unc-locator>) Method

Returns the server name of this locator.

Parameters:

• locator – an instance of <microsoft-unc-locator>

Values:

• name – An instance of <string>

locator-path Open Generic function

Returns the directory path of a locator.

Signature:

locator-path (locator) => (path)

Parameters:

• locator – An instance of <directory-locator>.

Values:

• path – An instance of <sequence>.

Discussion:

Returns the directory path as a sequence of strings, each being the name of a path element.

Example:

locator-path(as(<file-locator>, "/a/b/c.d")) => #["a", "b"]

locator-relative? Open Generic function

Signature:

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

Parameters:

• locator – An instance of <locator>.

Values:

• relative? – An instance of <boolean>.

locator-server Open Generic function

Signature:

locator-server (locator) => (server)

Parameters:

• locator – An instance of <locator>.

Values:

• server – An instance of false-or(<server-locator>).

locator-volume Open Generic function

Signature:

locator-volume (locator) => (volume)

Parameters:

• locator – An instance of <locator>.

Values:

• volume – An instance of false-or(<string>).

merge-locators Open Generic function

Signature:

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

Parameters:

• locator – An instance of <physical-locator>.

• from-locator – An instance of <physical-locator>.

Values:

• merged-locator – An instance of <physical-locator>.

open-locator Open Generic function

Signature:

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

Parameters:

• locator – An instance of <locator>.

Values:

• stream – An instance of <stream>.

relative-locator Open Generic function

Returns a locator relative to another locator which references the same file as this locator.

Signature:

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

Parameters:

• locator – An instance of <physical-locator>.

• from-locator – An instance of <physical-locator>.

Values:

• relative-locator – An instance of <physical-locator>.

Example:

If self is ‘/a/b/c/d.txt’ and root is ‘/a/b’

let rel = relative-locator(self, root);

Then rel is ‘c/d.txt’

simplify-locator Open Generic function

Simplifies a locator by removing redundant elements from its path.

Signature:

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

Parameters:

• locator – An instance of <physical-locator>.

Values:

• simplified-locator – An instance of <physical-locator>.

resolve-locator Open Generic function

Resolves all links, parent references (..), self references (.), and removes unnecessary path separators. Similar to simplify-locator except that it consults the file system to resolve links. A <file-system-error> is signaled if for any reason the path can’t be resolved. Examples include non-existent directory components, access denied, I/O error, etc. In short, this function follows the semantics of POSIX realpath(3).

Signature:

resolve-locator (locator) => (resolved-locator)

Parameters:

• locator – An instance of <physical-locator>.

Values:

• simplified-locator – An instance of <physical-locator>.

string-as-locator Open Generic function

Parse a string and create a locator.

Signature:

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

Parameters:

• class – An instance of subclass(<locator>).

• string – An instance of <string>.

Values:

• locator – An instance of <locator>.

Discussion:

This method should be specialized for each new locator class. It should return an instance of class, or raise a condition of type <locator-error>.

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:

• locator – An instance of <directory-locator>.

• sub-path (#rest) – An instance of <object>.

Values:

• subdirectory – An instance of <directory-locator>.

Example:

let build-dir = subdirectory-locator(working-directory(), "_build");

file-locator Open Generic function

Returns a file locator for a file in a subdirectory of the given directory.

Signature:

file-locator (directory, name, #rest more-names) => (file)

Parameters:

• directory – An instance of <directory-locator>.

• name – An instance of <string>.

• more-names (#rest) – Instances of <string>.

Values:

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

Example:

let temp = file-locator(temp-directory(), "my-subdir", "my-test.json");
ensure-directories-exist(temp);  // Create "my-subdir" directory.

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:

• locator – An instance of <locator>.

Values:

• listable? – An instance of <boolean>.

See also:

• list-locator

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:

• listable? – An instance of <boolean>.

See also:

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

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:

• locator – An instance of <locator>.

Values:

• openable? – An instance of <boolean>.

<web-locator> Abstract Class

Superclasses:

<locator>

The abstract superclass of locators that access a resource via web protocols, such as ftp or http.

<url> Abstract Sealed Class

Superclasses:

<web-locator>, <physical-locator>

The abstract superclass of web locators that reference a physical object. Use as(<url>, "...") to create an appropriate concrete subclass.

See also:

<file-url> <directory-url> <cgi-url> <file-index-url>

<directory-url> Class

Superclasses:

<url>, <directory-locator>

Represents directories that are accessible via web protocols.

<file-url> Class

Superclasses:

<url>, <file-locator>

Represents files that are accessible via web protocols.

<file-index-url> Class

Superclasses:

<url>

Represents a URL that has a fragment part, for example http://www.example.com/path/file.txt#fragment.

<cgi-url> Class

Superclasses:

<url>

Represents a URL that has a query part, for example http://www.example.com/path/file.txt?query=text.

locator-cgi-string Function

Return the query part of a <cgi-url>.

Signature:

locator-cgi-string(locator) => (string)

Parameters:

• locator – an instance of <cgi-url>

Values:

• string – an instance of <string>

locator-index Function

Return the fragment part of a :class:<file-index-url>

Signature:

locator-index(locator) => (string)

Parameters:

• locator – an instance of <file-index-url>

Values:

• string – an instance of <string>

<mail-to-locator> Class

Superclasses:

<url>

Represents a locator which is an email address.

<server-url> Abstract Class

Represents a locator which is a machine accessible via web protocols.

Superclasses:

<url>, <server-locator>

Slots:

• locator-host – The computer host

• locator-username – The user identifier

• locator-password – The user password

Operations:

locator-port, locator-default-port

The locator includes information on the protocol, host-name, port, user and password of the machine.

See also:

<http-server> <https-server> <ftp-server> <file-server>

<http-server> Sealed Class

A server for the http protocol.

Superclasses:

<server-url>

<https-server> Sealed Class

A server for the https protocol.

Superclasses:

<server-url>

<ftp-server> Sealed Class

A server for the ftp protocol.

Superclasses:

<server-url>

<file-server> Sealed Class

A locator using the file protocol.

Superclasses:

<server-url>

locator-default-port Generic function

Return the default port associated with the locator’s protocol.

Signature:

locator-default-port(locator) => (port)

Parameters:

• locator – An instance of <server-url>

Values:

• port – An instance of false-or(<integer>)

Example:

let locator = as(<server-url>, "http://www.example.com");
let default-port = locator-default-port(locator);
// Result: default-port = 80