Url (class)
public abstract sealed Url {inherits Serializable}
Package: CURL.IO.FILE
Direct Known Subclasses: PrivilegedUrl

The Url class is Curl's way of naming resources. It gives an abstract and consistent way to refer to resources such as:

Description

A Url is generally created by means of url, abs-url, or parse-url, or by using various methods on an existing Url.

When the system constructs a Url, it can choose how to split its argument into a Directory portion and a stem String. Generally, the first Directory for which the concept of "parent-directory" makes no sense is chosen for this purpose. As a side-effect of this, the stem generally knows everything there is to know about the syntax of its leaf, so parsing the leaf does not have to be performed recursively.

A Url uses an encoding scheme to escape certain characters that might otherwise be interpreted as having special meanings. For example, a '#' character is interpreted as marking the start of an anchor. Also, it is possible to encode characters that are outside of the ASCII range, causing them to be represented as ASCII characters, which can be used when non-ASCII characters might cause some confusion. All of the methods and getters on Url use and return strings encoded in this manner, except for Url.local-filename, which returns a String in some host specific form. See url-encode-string and url-decode-string for details on the encoding.

A Url consists of four parts:

stem
The Directory which, given a name, returns the object that name refers to. Different classes of Directory have the option of choosing how this parsing is done. This is the mechanism by which Curl implements it distributed naming syntax.
leaf
A String, which can be resolved by the stem to return the object that this Url denotes.
query
A query. This field has a non-empty value if the Url's scheme supports a query-string and the URL contains one. This value includes the delimiter (usually '?') that separates the query from the rest of the URL.
anchor
An anchor. This field contains any destination within the resource that this Url denotes. This field has a non-empty value if the URL's scheme supports an anchor-string and the URL contains an anchor. This value includes the anchor delimiter (usually '#') that separates the anchor from the rest of the URL.


Together, the stem and the leaf comprise an unambiguous way to access the resource denoted by this Url.

For example, {url "http://www.curl.com/foo/bar.curl?query#anchor"} has a stem named http://www.curl.com, "foo/bar.curl" for its leaf, "?query" for its query-string and "#anchor" for its anchor.

Properties
anchor:The anchor portion of self, which will always be empty, or start with a '#' character.

For example, if self is http://www.curl.com/foo/bar.curl?query#anchor, then self.anchor is the String "#anchor".
accessor public abstract Url.anchor:String
basename:The basename portion of self.

For example, if self is http://www.curl.com/foo/bar.curl?query#anchor, then self.basename is the String "bar".
accessor public Url.basename:String
extension:The extension portion of self.

For example, if self is http://www.curl.com/foo/bar.curl?query#anchor, then self.extension is the String ".curl".
accessor public Url.extension:String
filename:The filename portion of self.

For example, if self is http://www.curl.com/foo/bar.curl?query#anchor, then self.filename is the String "bar.curl".
accessor public Url.filename:String
full-filename:The full-filename portion of self.

For example, if self is http://www.curl.com/foo/bar.curl?query#anchor, then self.full-filename is the String "http://www.curl.com/foo/bar.curl"
accessor public Url.full-filename:String
leaf:The relative path portion of self, which is interpreted with respect to self.stem.

For example, if self is http://www.curl.com/foo/bar.curl?query#anchor, then self.leaf is the String "foo/bar.curl".
accessor public abstract Url.leaf:#String
local-filename:If self denotes an object on the local filesystem, this accessor returns the native name of that object. Otherwise, this accessor returns null.

For example, if the host system is Windows and self is file:///c:/scratch/foo.curl, then self.local-filename is c:\scratch\foo.curl.

On the other hand, if self is http://www.curl.com/foo/bar.curl?query#anchor, then self.local-filename is null.
accessor public final Url.local-filename:#String
name:The printed representation of self.

For example, if self is http://www.curl.com/foo/bar.curl?query#anchor, then self.name is the String "http://www.curl.com/foo/bar.curl?query#anchor".
accessor public abstract Url.name:String
parent:The parent Url of self.
accessor public Url.parent:Url
parent-dir:The Directory that contains the object that self denotes.

For example, if self is http://www.curl.com/foo/bar.curl?query#anchor, then self.parent-dir is the Directory http://www.curl.com/foo,
accessor public Url.parent-dir:Directory
parent-dir-name:The name of the Directory that contains the object that self denotes.

For example, if self is http://www.curl.com/foo/bar.curl?query#anchor, then self.parent-dir-name is the String "http://www.curl.com/foo",
accessor public Url.parent-dir-name:String
pathname:The pathname portion of self.

For example, if self is http://www.curl.com/foo/bar.curl?query#anchor, then self.pathname is the String "http://www.curl.com/foo/bar.curl?query"
accessor public Url.pathname:String
pathname-tail:The pathname-tail portion of self.

For example, if self is http://www.curl.com/foo/bar.curl?query#anchor, then self.pathname-tail is the String "bar.curl?query"
accessor deprecated public Url.pathname-tail:String
query:The query portion of self, which will always be empty, or start with a '?' character.

For example, if self is http://www.curl.com/foo/bar.curl?query#anchor, then self.query is the String "?query".
accessor public abstract Url.query:String
separator:The separator character which self.stem uses in parsing self.leaf.

Most of the time, '/' is the separator character.
accessor public Url.separator:char
stem:The Directory portion of self.

For example, if self is http://www.curl.com/foo/bar.curl?query#anchor, then self.stem would be the Directory http://www.curl.com.
accessor public abstract Url.stem:Directory
Methods
canonicalize:Resolves self as far as possible without going outside of the curl system. Returns the Url that provides the "lowest-level" name for the object denoted by self.
public {Url.canonicalize}:Url
concat:Concatenates a relative path onto self, creating a new Url.

For example, if self is http://www.curl.com/foo, then {self.concat "bar.curl"} is http://www.curl.com/foo/bar.curl.
public {Url.concat tail:String}:Url
instantiate-Directory:Returns the Directory named by self, without actually checking whether the actual underlying object exists.
public {Url.instantiate-Directory}:Directory
instantiate-File:Returns the File named by self, without actually checking whether the actual underlying object exists.
public {Url.instantiate-File}:File
merge:Merges a relative or absolute path with self, creating a new Url.

For example, if self is http://www.curl.com/foo/bar.curl, then {self.merge "zip.curl"} is http://www.curl.com/foo/zip.curl.

Furthermore, {self.merge "http://www.curl.com/"} is http://www.curl.com/.
public {Url.merge tail:String}:Url
name-relative-to-url:Computes name of the URL relative to directory-url.
public {Url.name-relative-to-url directory-url:Url}:String
resolve:Returns the object represented by self.
public {Url.resolve error-if-missing?:bool = true}:any
set-anchor:Returns a new Url which is the same as self, except that self.anchor has been replaced by anchor.
public {Url.set-anchor anchor:String}:Url
set-basename:Returns a new Url which is the same as self, except that self.basename has been replaced by basename.
public {Url.set-basename basename:String}:Url
set-extension:Returns a new Url which is the same as self, except that self.extension has been replaced by extension.
public {Url.set-extension extension:String}:Url
set-filename:Returns a new Url which is the same as self, except that self.filename has been replaced by filename.
public {Url.set-filename filename:String}:Url
set-leaf:Returns a new Url which is the same as self, except that self.leaf has been replaced by leaf.
public {Url.set-leaf leaf:#String}:Url
set-query:Returns a new Url which is the same as self, except that self.query has been replaced by query.
public {Url.set-query query:String}:Url
underneath?:Determine if this URL is underneath dir.
public {Url.underneath? dir:Url}:bool
valid-separator?:Returns true if c can be used to parse self.leaf. It is generally the case that {self.valid-separator? self.separator} is true, however it is possible to have characters for which self.valid-separator? returns true, but which are not self.separator.

Most of the time, '/' is the only valid separator.
public {Url.valid-separator? c:char}:bool
Methods inherited from Object: object-describe, object-describe-for-debugging, object-serialize

Property Details
anchor (accessor)
accessor public abstract Url.anchor:String

The anchor portion of self, which will always be empty, or start with a '#' character.

For example, if self is http://www.curl.com/foo/bar.curl?query#anchor, then self.anchor is the String "#anchor".

Notes

self.anchor is never null -- if self does not have an anchor, the self.anchor is the empty string ("").

basename (accessor)
accessor public Url.basename:String

The basename portion of self.

For example, if self is http://www.curl.com/foo/bar.curl?query#anchor, then self.basename is the String "bar".


extension (accessor)
accessor public Url.extension:String

The extension portion of self.

For example, if self is http://www.curl.com/foo/bar.curl?query#anchor, then self.extension is the String ".curl".


filename (accessor)
accessor public Url.filename:String

The filename portion of self.

For example, if self is http://www.curl.com/foo/bar.curl?query#anchor, then self.filename is the String "bar.curl".


full-filename (accessor)
accessor public Url.full-filename:String

The full-filename portion of self.

For example, if self is http://www.curl.com/foo/bar.curl?query#anchor, then self.full-filename is the String "http://www.curl.com/foo/bar.curl"


leaf (accessor)
accessor public abstract Url.leaf:#String

The relative path portion of self, which is interpreted with respect to self.stem.

For example, if self is http://www.curl.com/foo/bar.curl?query#anchor, then self.leaf is the String "foo/bar.curl".

Notes

It is possible for self.leaf to be null.

local-filename (accessor)
accessor public final Url.local-filename:#String

If self denotes an object on the local filesystem, this accessor returns the native name of that object. Otherwise, this accessor returns null.

For example, if the host system is Windows and self is file:///c:/scratch/foo.curl, then self.local-filename is c:\scratch\foo.curl.

On the other hand, if self is http://www.curl.com/foo/bar.curl?query#anchor, then self.local-filename is null.

Notes

This is the only getter or method in Url that may return an un-encoded string. See url-encode-string and url-decode-string for details on the encoding scheme. See url-decode-filename and url-encode-filename for the minimal encoding needed to convert a local-filename into a valid url fragment.

name (accessor)
accessor public abstract Url.name:String

The printed representation of self.

For example, if self is http://www.curl.com/foo/bar.curl?query#anchor, then self.name is the String "http://www.curl.com/foo/bar.curl?query#anchor".


parent (accessor)
accessor public Url.parent:Url

The parent Url of self.

Description

The parent of a Url is generally the same as the result of calling Url.concat with "..".

For example, if self is http://www.curl.com/foo/bar.curl?query#anchor, then self.parent is http://www.curl.com/foo, and self.parent.parent is http://www.curl.com, and self.parent.parent.parent is also http://www.curl.com.

parent-dir (accessor)
accessor public Url.parent-dir:Directory

The Directory that contains the object that self denotes.

For example, if self is http://www.curl.com/foo/bar.curl?query#anchor, then self.parent-dir is the Directory http://www.curl.com/foo,


parent-dir-name (accessor)
accessor public Url.parent-dir-name:String

The name of the Directory that contains the object that self denotes.

For example, if self is http://www.curl.com/foo/bar.curl?query#anchor, then self.parent-dir-name is the String "http://www.curl.com/foo",


pathname (accessor)
accessor public Url.pathname:String

The pathname portion of self.

For example, if self is http://www.curl.com/foo/bar.curl?query#anchor, then self.pathname is the String "http://www.curl.com/foo/bar.curl?query"


pathname-tail (accessor)
accessor deprecated public Url.pathname-tail:String

The pathname-tail portion of self.

For example, if self is http://www.curl.com/foo/bar.curl?query#anchor, then self.pathname-tail is the String "bar.curl?query"


query (accessor)
accessor public abstract Url.query:String

The query portion of self, which will always be empty, or start with a '?' character.

For example, if self is http://www.curl.com/foo/bar.curl?query#anchor, then self.query is the String "?query".

Notes

self.query is never null -- if self does not have a query-string, the self.query is the empty string ("").

separator (accessor)
accessor public Url.separator:char

The separator character which self.stem uses in parsing self.leaf.

Most of the time, '/' is the separator character.


stem (accessor)
accessor public abstract Url.stem:Directory

The Directory portion of self.

For example, if self is http://www.curl.com/foo/bar.curl?query#anchor, then self.stem would be the Directory http://www.curl.com.


Method Details
canonicalize (method)
public {Url.canonicalize}:Url

Resolves self as far as possible without going outside of the curl system. Returns the Url that provides the "lowest-level" name for the object denoted by self.


concat (method)
public {Url.concat tail:String}:Url

Concatenates a relative path onto self, creating a new Url.

For example, if self is http://www.curl.com/foo, then {self.concat "bar.curl"} is http://www.curl.com/foo/bar.curl.


instantiate-Directory (method)
public {Url.instantiate-Directory}:Directory

Returns the Directory named by self, without actually checking whether the actual underlying object exists.

Notes

Some of the specific subclasses of Directory that are returned like LocalDirectory or HttpDirectory have useful methods related to the particular type of resource that it represents.

instantiate-File (method)
public {Url.instantiate-File}:File

Returns the File named by self, without actually checking whether the actual underlying object exists.

Notes

Some of the specific subclasses of File that are returned like LocalFile or HttpFile have useful methods related to the particular type of resource that it represents.

merge (method)
public {Url.merge tail:String}:Url

Merges a relative or absolute path with self, creating a new Url.

For example, if self is http://www.curl.com/foo/bar.curl, then {self.merge "zip.curl"} is http://www.curl.com/foo/zip.curl.

Furthermore, {self.merge "http://www.curl.com/"} is http://www.curl.com/.


name-relative-to-url (method)
public {Url.name-relative-to-url directory-url:Url}:String

Computes name of the URL relative to directory-url.

Description

Computes a relative name for the URL relative to the given directory-url. The resulting name will produce the same URL if passed to parse-url with the same directory. That is, for a URL u, and a directory d, the following should be true:

u == {parse-url {u.name-relative-to-url d}, relative-url = d }

If it is not possible to produce a name relative to directory-url -- such as when the current and directory Urls do not share the same stem directory -- then self.name will be returned.

resolve (method)
public {Url.resolve error-if-missing?:bool = true}:any

Returns the object represented by self.

Description

This is the method that looks to see whether the object represented by self actually exists. If the object is in the local filesystem, this method looks at the location where the object is supposed to reside to verify its existence.

If the object is out on the network somewhere (in particular, if this is an http:// or https:// Url), this method assumes that the object is a file and exists, returning a File representing that object.
error-if-missing?: Specifies this method's behavior if self represents an object on the local filesystem and that object does not exist. In this case, when error-if-missing? is specified to be true (the default), this method throws a MissingFileException; otherwise null is returned.

Returns

Returns the object represented by self. If self represents an object on the local file system that does not exist, and error-if-missing? is specified to be false, this method returns null.

set-anchor (method)
public {Url.set-anchor anchor:String}:Url

Returns a new Url which is the same as self, except that self.anchor has been replaced by anchor.


set-basename (method)
public {Url.set-basename basename:String}:Url

Returns a new Url which is the same as self, except that self.basename has been replaced by basename.


set-extension (method)
public {Url.set-extension extension:String}:Url

Returns a new Url which is the same as self, except that self.extension has been replaced by extension.


set-filename (method)
public {Url.set-filename filename:String}:Url

Returns a new Url which is the same as self, except that self.filename has been replaced by filename.


set-leaf (method)
public {Url.set-leaf leaf:#String}:Url

Returns a new Url which is the same as self, except that self.leaf has been replaced by leaf.


set-query (method)
public {Url.set-query query:String}:Url

Returns a new Url which is the same as self, except that self.query has been replaced by query.


underneath? (method)
public {Url.underneath? dir:Url}:bool

Determine if this URL is underneath dir.

Introduced in: version 6.0

valid-separator? (method)
public {Url.valid-separator? c:char}:bool

Returns true if c can be used to parse self.leaf. It is generally the case that {self.valid-separator? self.separator} is true, however it is possible to have characters for which self.valid-separator? returns true, but which are not self.separator.

Most of the time, '/' is the only valid separator.