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:

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:
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 (mailto) => (address)

Parameters:
Values:
Discussion:

Returns the email address specified by the mailto locator.

locator-as-string Open Generic function
Signature:

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

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

locator-base (locator) => (base)

Parameters:
Values:
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:
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:
Values:
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:
Values:
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:
Values:
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:
Values:
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:
locator-name(<mailto-locator>) Method

Returns the email address of this locator.

Parameters:

  • locator – an instance of <mailto-locator>

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

Returns the drive letter of this locator.

Parameters:
Values:
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:
Values:
locator-path Open Generic function

Returns the directory path of a locator.

Signature:

locator-path (locator) => (path)

Parameters:
Values:
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:
Values:
locator-server Open Generic function
Signature:

locator-server (locator) => (server)

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

locator-volume (locator) => (volume)

Parameters:
Values:
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

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

Signature:

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

Parameters:
Values:
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:
Values:
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:
Values:
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:
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:
Values:
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:
Values:
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:
Values:
See also:

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

Returns true if the directory locator is not relative.

Parameters:
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:
<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:
Values:
locator-index Function

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

Signature:

locator-index(locator) => (string)

Parameters:
Values:
<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:
Values:
Example:

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