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.

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

<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");
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>

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

  • locator-name – the file name.

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

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