ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 11.0

# copy-uri

Function, net.uri package

Arguments: uri &key place scheme host port path query fragment plist

Copy the given uri. If place is given, its values should be a uri instance and it will be modified rather than a new one being created. Note: do not destructively modify interned URIs.

The scheme, host, port, path, query, fragment and plist keywords are used to initialize those slots of the new (or given) URI instance. See urn.

See also uri.html for general information on Universal Resource Indicator support in Allegro CL.

# do-all-uris

Macro, net.uri package

Arguments: (var &optional uri-space result) &body body

Bind var to all currently defined uris (in uri-space if specified) and evaluate body.

See also uri.html for general information on Universal Resource Indicator support in Allegro CL.

# enough-uri

Generic Function, net.uri package

Arguments: uri base

Like enough-namestring, enough-uri converts uri into a relative URI using base as the base URI.

See also uri.html for general information on Universal Resource Indicator support in Allegro CL.

# intern-uri

Generic Function, net.uri package

Arguments: uri-name &optional uri-space

Methods provides for strings and uri objects. If uri-name is a string, intern the URI specified by the string uri-name, which is first parsed into a URI object. If uri-name is a uri instance, intern it.

uri-space can be used to maintain separate spaces for interning of URIs.

See also uri.html for general information on Universal Resource Indicator support in Allegro CL.

# iri-p

Function, net.uri package

Arguments: object

This predicate function returns true if object is an instance of class iri.

See also the class uri and uri-p.

See also uri.html for general information on Universal Resource Indicator support in Allegro CL.

# iri-to-string

Generic Function, net.uri package

Arguments: iri

This generic function and the associated function string-to-iri are inverses. iri-to-string creates a string from the IRI passed in as the iri argument. The representation of the query field of the IRI in the string is not encoded. (How to properly encode a query is outside the bounds of RFC 3987.)

See also uri.html for general information on Universal and Internationalized Resource Indicator support in Allegro CL.

# make-uri-space

Function, net.uri package

Arguments: &key size

Make a new object to contain interned URIs. The object is a hash-table and so it will grow as needed if size is insufficient, but specifying a correct size in advance improves efficiency.

See also uri.html for general information on Universal Resource Indicator support in Allegro CL.

# merge-uris

Generic Function, net.uri package

Arguments: *uri base-uri8 &optional place

Return an absolute URI, based on uri, which can be relative, and base-uri which must be absolute. place can be used as storage for the result.

Note: bad things will happen if you use an interned URI as the result for merging. The result is not interned.

The rules for merging URIs are not the same as for merging pathnames. A simplified version of the merge rules from RFC2396 are (applied in order):

- If uri has no scheme, authority or path, then the query and fragment from uri are used, and all other slots are inherited from the base-uri.

- If uri has a scheme, then uri is returned. If it does not have a scheme, then it inherits one from the base-uri.

- If uri has a host, the unmodified uri is returned.

- If the path of uri is absolute (starts with a /), then the unmodified uri is returned.

- Otherwise, the path of base-uri and uri are concatenated into a uri path, and the new uri is returned.

One comment about error checking of URIs as a result of merging: RFC2396 says that an implementation may handle too many ..'s in a merge result "by retaining these components in the resolved path, by removing them from the resolved path, or by avoiding traversal of the reference." The examples in appendix C of RFC2396 imply that an implementation should retain these invalid elements, so that is what we do. For example,

    (merge-uris (parse-uri "../../../../g")
                (parse-uri "http://a/b/c/d;p?q"))

should return `#<uri "http://a/../../g">`, which is clearly a nonsense result, but this is what our implementation returns, instead of signaling an error.

See also uri.html for general information on Universal Resource Indicator support in Allegro CL.

# parse-uri

Function, net.uri package

Arguments: string-or-uri &key (class 'uri) (escape t)

If string-or-uri is a uri instance, return it unmodified. If string-or-uri is a string, parse it into a URI object. Escaped encodings of the form % are properly converted into single characters except the characters #+, #= and #& are not decoded if they are percent encoded. This means %2b, for example, will not be converted to "+". This is contrary to RFC 3986, but otherwise there is no way to pass these characters as field values.

The class keyword allows creation of subclasses of uri.

If the result is a URN (that is, an object of class urn), urn-nid and urn-nss access the Namespace Identifier and the Namespace Specific String of the URN, while urn-q-component, urn-r-component, and urn-f-component access the q, r, and f components.

The escape keyword argument defaults to `t` and when true, percent-encoded characters are decoded into raw characters in places where they can legally appear. Note that percent-encoded characters stay encoded when they are reserved for the component in which they appear. When escape is nil, no decoding happens. Sometimes escape must be specified nil. Consider this case:

    (enough-uri
      (parse-uri "http://localhost:8900/foo/bar%20-%25%20baz.zip")
      (parse-uri "http://localhost:8900/foo/"))
    => #<uri bar%20-%%20baz.zip>

The above is wrong because "%" was not transformed back into "%25". This does the job correctly, however:

    (enough-uri
      (parse-uri "http://localhost:8900/foo/bar%20-%25%20baz.zip" :escape nil)
      (parse-uri "http://localhost:8900/foo/" :escape nil))
    => #<uri bar%20-%25%20baz.zip>

The operator string-to-uri also takes a URI and returns a string. Warning: parse-uri and render-uri are paired as are string-to-uri and uri-to-string. Users ahould never apply an operator from one pair to the return value of an operator from the other pair. The consequences of doing so are undefined.

See also uri.html for general information on Universal Resource Indicator support in Allegro CL.

# pathname-to-uri

Function, net.uri package

Arguments: pathname

Converts an absolute pathname to `file` scheme URI. This function and the related uri-to-pathname are designed to handle URIs with a scheme of `file` and no host. It is an error for pathname to name a relative pathname.

### Examples

    ;;  On UNIX:

    cl-user(1): (net.uri:uri-to-pathname (parse-uri "file:///foo/bar.cl"))
    #p"/foo/bar.cl"
    cl-user(2): (net.uri:pathname-to-uri *)
    #<uri file:///foo/bar.cl>

    ;; On Windows:

    cl-user(1): (net.uri:uri-to-pathname (parse-uri "file:///d:/foo/bar.cl"))
    #p"d:\\foo\\bar.cl"
    cl-user(2): (net.uri:pathname-to-uri *)
    #<uri file:///d:/foo/bar.cl>

See also uri.html for general information on Universal Resource Indicator support in Allegro CL.

# render-uri

Function, net.uri package

Arguments: uri stream

Print to stream the printed representation of uri. This is how the print-object method for uri calls it:

    (defmethod print-object ((uri uri) stream)
       (if* *print-escape* then
             (format stream "#<~a ~a>" 'uri (render-uri uri nil))
         else (render-uri uri stream)))

The operator uri-to-string also takes a URI and returns a string. Warning: parse-uri and render-uri are paired as are string-to-uri and uri-to-string. Users ahould never apply an operator from one pair to the return value of an operator from the other pair. The consequences of doing so are undefined.

See also uri.html for general information on Universal Resource Indicator support in Allegro CL.

# string-to-iri

Function, net.uri package

Arguments: string

This function and the associated generic function iri-to-string are inverses. string-to-iri parses string as a n IRI and returns the IRI object or, if string cannot be parsed, signals an error. The representation of the query field of the IRI in the string is not decoded. (How to properly decode a query is outside the bounds of RFC 3987.)

See also uri.html for general information on Universal and Internationalized Resource Indicator support in Allegro CL.

# string-to-uri

Function, net.uri package

Arguments: string

This function and the associated generic function uri-to-string are inverses. string-to-uri parses string as a URI and returns the URI object or, if string cannot be parsed, signals an error. The representation of the query field of the URI in the string is not decoded. (How to properly decode a query is outside the bounds of RFC 3986.)

The operator parse-uri also takes a string and returns a URI and, with the exceptions listed in the description of the function, does decode the query field. Its inverse is render-uri. Warning: string-to-uri and uri-to-string are paired as are parse-uri and render-uri. Users ahould never apply an operator from one pair to the return value of an operator from the other pair. The consequences of doing so are undefined.

See also uri.html for general information on Universal and Internationalized Resource Indicator support in Allegro CL.

# unintern-uri

Function, net.uri package

Arguments: uri &optional uri-space

Unintern the uri object specified or all uri objects (in uri-space if specified) if uri is `t`.

See also uri.html for general information on Universal Resource Indicator support in Allegro CL.

# uri

Generic Function, net.uri package

Arguments: object

Three methods are defined: when object is a uri (instance of class uri), it is returned. When object is a string, parse-uri is applied to create a uri from the string. A method on type `t` signals an error.

See also uri.html for general information on Universal Resource Indicator support in Allegro CL.

# uri-authority

Function, net.uri package

Arguments: uri-object

Returns the authority of uri-object. The authority combines the host and port. (See uri-host and uri-port.)

See also uri.html for general information on Universal Resource Indicator support in Allegro CL.

# uri-fragment

Generic Function, net.uri package

Arguments: uri-object

Returns the value of the `fragment` slot of uri-object. See uri.

See also uri.html for general information on Universal Resource Indicator support in Allegro CL.

# uri-host

Generic Function, net.uri package

Arguments: uri-object

Returns the value of the `host` slot of uri-object. See uri.

uri-authority returns an object which combines the `host` and `port` values.

    cl-user(2): (setq u (net.uri:parse-uri "https://[::1%25en0]/foo.cl"))
    #<uri https://[::1%25en0]/foo.cl>
    cl-user(3): (net.uri:uri-ipv6 u)
    "::1"
    cl-user(4): (net.uri:uri-zone-id u)
    "en0"
    cl-user(5): (net.uri:uri-host u)
    "::1%en0"
    cl-user(6):

The value from net.uri:uri-host differs from the syntax used in the URI. The value from net.uri:uri-host is intended to be suitable for programs and APIs that require valid IPv6 addresses.

See also uri.html for general information on Universal Resource Indicator support in Allegro CL.

# uri-ipv6

Generic Function, net.uri package

Arguments: uri-object

Returns the value of the `ipv6` slot of uri-object. See uri.

    cl-user(2): (setq u (net.uri:parse-uri "https://[::1%25en0]/foo.cl"))
    #<uri https://[::1%25en0]/foo.cl>
    cl-user(3): (net.uri:uri-ipv6 u)
    "::1"
    cl-user(4): (net.uri:uri-zone-id u)
    "en0"
    cl-user(5): (net.uri:uri-host u)
    "::1%en0"
    cl-user(6):

See also uri.html for general information on Universal Resource Indicator support in Allegro CL.

# uri-p

Function, net.uri package

Arguments: object

This predicate function returns true if object is an instance of class uri.

Because the iri class (the class of Internationalized Resource Identifiers or IRIs) is a subclass of the uri class, this function will return true when applied to an iri object. However, although every URI is an IRI, not every IRI is a URI so this function cannot be used to identify objects as strict URIs. A function which would do so would be like:

    (defun strict-uri-p (object)
       (and (uri-p object) (null (iri-p object))))

See also the class iri and iri-p.

See also uri.html for general information on Universal Resource Indicator support in Allegro CL.

# uri-parsed-path

Generic Function, net.uri package

Arguments: uri

Return the parsed representation of the path portion of uri (as returned by uri-path). This is setf'able.

The parsed path representation is a list (the path is a string). A parsed path has the following form:

    ([:absolute | :relative] component1 [component2...])

where components are:

    element | (element param1 [param2 ...])

and element is a path element, and the param's are path element parameters. For example, the result of

    (uri-parsed-path (parse-uri "foo;10/bar:x;y;z/baz.htm"))

is

    (:relative ("foo" "10")
               ("bar:x" "y" "z")
               "baz.htm")

There is a certain amount of canonicalization that occurs when parsing:

- A path of `(:absolute)` or `(:absolute "")` is equivalent to a `nil` path. That is, `http://a/` is parsed with a `nil` path and printed as `http://a`.

- Escaped characters that are not reserved are not escaped upon printing. For example, `"foob%61r"` is parsed into `"foobar"` and appears as `"foobar"` when the URI is printed.

See Parsing, escape decoding/encoding and the path in uri.html for a discussion of encoding and decoding. The example above is repeated there.

See also uri.html for general information on Universal Resource Indicator support in Allegro CL.

# uri-path

Generic Function, net.uri package

Arguments: uri-object

Returns the value of the `path` slot of uri-object. See uri.

See also uri.html for general information on Universal Resource Indicator support in Allegro CL.

# uri-plist

Generic Function, net.uri package

Arguments: uri-object

Returns the value of the `plist` slot of uri-object. Note that the plist slot contains a Lisp plist and is not part of the URI specification. See uri.

See also uri.html for general information on Universal Resource Indicator support in Allegro CL.

# uri-port

Generic Function, net.uri package

Arguments: uri-object

Returns the value of the `port` slot of uri-object. See uri.

uri-authority returns an object which combines the `host` and `port` values.

See also uri.html for general information on Universal Resource Indicator support in Allegro CL.

# uri-query

Generic Function, net.uri package

Arguments: uri-object

Returns the value of the `query` slot of uri-object. See uri.

See also uri.html for general information on Universal Resource Indicator support in Allegro CL.

# uri-scheme

Generic Function, net.uri package

Arguments: uri-object

Returns the value of the `scheme` slot of uri-object. See uri.

See also uri.html for general information on Universal Resource Indicator support in Allegro CL.

# uri-space

Function, net.uri package

Arguments:

Return the object into which URIs are currently being interned. This is setf'able.

See also uri.html for general information on Universal Resource Indicator support in Allegro CL.

# uri-to-pathname

Function, net.uri package

Arguments: uri

Converts a file scheme URI to a pathname. This function and the related pathname-to-uri are designed to handle URIs with a scheme of `file` and no host. It is an error for uri not to be a `file` scheme URI or not to specify a pathname.

### Examples

    ;;  On UNIX:

    cl-user(1): (net.uri:uri-to-pathname (parse-uri "file:///foo/bar.cl"))
    #p"/foo/bar.cl"
    cl-user(2): (net.uri:pathname-to-uri *)
    #<uri file:///foo/bar.cl>

    ;; On Windows:

    cl-user(1): (net.uri:uri-to-pathname (parse-uri "file:///d:/foo/bar.cl"))
    #p"d:\\foo\\bar.cl"
    cl-user(2): (net.uri:pathname-to-uri *)
    #<uri file:///d:/foo/bar.cl>

See also uri.html for general information on Universal Resource Indicator support in Allegro CL.

# uri-to-string

Generic Function, net.uri package

Arguments: uri

This generic function and the associated function string-to-uri are inverses. uri-to-string creates a string from the URI passed in as the uri argument. The representation of the query field of the URI in the string is not encoded. (How to properly encode a query is outside the bounds of RFC 3986.)

The operator render-uri also takes a URI and returns a string. Its inverse is parse-uri, which does decode the query field. Warning: string-to-uri and uri-to-string are paired as are parse-uri and render-uri. Users ahould never apply an operator from one pair to the return value of an operator from the other pair. The consequences of doing so are undefined.

See also uri.html for general information on Universal and Internationalized Resource Indicator support in Allegro CL.

# uri-userinfo

Function, net.uri package

Arguments: uri-object

Returns the value of the `userinfo` slot of uri-object. See uri.

See also uri.html for general information on Universal Resource Indicator support in Allegro CL.

# uri-zone-id

Generic Function, net.uri package

Arguments: uri-object

Returns the value of the `zone-id` slot of uri-object. See uri.

    cl-user(2): (setq u (net.uri:parse-uri "https://[::1%25en0]/foo.cl"))
    #<uri https://[::1%25en0]/foo.cl>
    cl-user(3): (net.uri:uri-ipv6 u)
    "::1"
    cl-user(4): (net.uri:uri-zone-id u)
    "en0"
    cl-user(5): (net.uri:uri-host u)
    "::1%en0"
    cl-user(6):

See also uri.html for general information on Universal Resource Indicator support in Allegro CL.

# uri=

Function, net.uri package

Arguments: uri1 uri2

Returns true if uri1 and uri2 are equivalent. Of course, if the URIs are interned, then you can use eq to test for equivalence.

See also uri.html for general information on Universal Resource Indicator support in Allegro CL.

# urn-f-component

Generic Function, net.uri package

Arguments: urn-uri

URN's are a subset of URI's. URN objects are members of the urn class. The Namespace ID determines the syntactic interpretation of the Namespace Specific String of an URN. Thus:

    cg-user(13): (setq urn (net.uri:parse-uri "urn:foo:10?+rrr?=qqq#fff"))
    #<urn urn:foo:10?+rrr?=qqq#fff>
    cg-user(14): (net.uri:urn-nid urn)
    "foo"
    cg-user(15): (net.uri:urn-nss urn)
    "10"
    cg-user(16): (net.uri:urn-r-component urn)
    "rrr"
    cg-user(17): (net.uri:urn-q-component urn)
    "qqq"
    cg-user(18): (net.uri:urn-f-component urn)
    "fff"
    cg-user(19):

See also uri.html for general information on Universal Resource Indicator support in Allegro CL. URN syntax is described in RFC8141 (https://tools.ietf.org/html/rfc8141)

# urn-nid

Generic Function, net.uri package

Arguments: urn-uri

URN's are a subset of URI's. URN objects are members of the urn class. The Namespace ID determines the syntactic interpretation of the Namespace Specific String of an URN. Thus:

    cg-user(13): (setq urn (net.uri:parse-uri "urn:foo:10?+rrr?=qqq#fff"))
    #<urn urn:foo:10?+rrr?=qqq#fff>
    cg-user(14): (net.uri:urn-nid urn)
    "foo"
    cg-user(15): (net.uri:urn-nss urn)
    "10"
    cg-user(16): (net.uri:urn-r-component urn)
    "rrr"
    cg-user(17): (net.uri:urn-q-component urn)
    "qqq"
    cg-user(18): (net.uri:urn-f-component urn)
    "fff"
    cg-user(19):

See also uri.html for general information on Universal Resource Indicator support in Allegro CL. URN syntax is described in RFC8141 (https://tools.ietf.org/html/rfc8141)

# urn-nss

Generic Function, net.uri package

Arguments: urn-uri

URN's are a subset of URI's. URN objects are members of the urn class. This function accesses the NSS of an URN. Thus:

    cg-user(13): (setq urn (net.uri:parse-uri "urn:foo:10?+rrr?=qqq#fff"))
    #<urn urn:foo:10?+rrr?=qqq#fff>
    cg-user(14): (net.uri:urn-nid urn)
    "foo"
    cg-user(15): (net.uri:urn-nss urn)
    "10"
    cg-user(16): (net.uri:urn-r-component urn)
    "rrr"
    cg-user(17): (net.uri:urn-q-component urn)
    "qqq"
    cg-user(18): (net.uri:urn-f-component urn)
    "fff"
    cg-user(19):

See also uri.html for general information on Universal Resource Indicator support in Allegro CL. URN syntax is described in RFC8141 (https://tools.ietf.org/html/rfc8141)

# urn-q-component

Generic Function, net.uri package

Arguments: urn-uri

URN's are a subset of URI's. URN objects are members of the urn class. The Namespace ID determines the syntactic interpretation of the Namespace Specific String of an URN. Thus:

    cg-user(13): (setq urn (net.uri:parse-uri "urn:foo:10?+rrr?=qqq#fff"))
    #<urn urn:foo:10?+rrr?=qqq#fff>
    cg-user(14): (net.uri:urn-nid urn)
    "foo"
    cg-user(15): (net.uri:urn-nss urn)
    "10"
    cg-user(16): (net.uri:urn-r-component urn)
    "rrr"
    cg-user(17): (net.uri:urn-q-component urn)
    "qqq"
    cg-user(18): (net.uri:urn-f-component urn)
    "fff"
    cg-user(19):

See also uri.html for general information on Universal Resource Indicator support in Allegro CL. URN syntax is described in RFC8141 (https://tools.ietf.org/html/rfc8141)

# urn-r-component

Generic Function, net.uri package

Arguments: urn-uri

URN's are a subset of URI's. URN objects are members of the urn class. The Namespace ID determines the syntactic interpretation of the Namespace Specific String of an URN. Thus:

    cg-user(13): (setq urn (net.uri:parse-uri "urn:foo:10?+rrr?=qqq#fff"))
    #<urn urn:foo:10?+rrr?=qqq#fff>
    cg-user(14): (net.uri:urn-nid urn)
    "foo"
    cg-user(15): (net.uri:urn-nss urn)
    "10"
    cg-user(16): (net.uri:urn-r-component urn)
    "rrr"
    cg-user(17): (net.uri:urn-q-component urn)
    "qqq"
    cg-user(18): (net.uri:urn-f-component urn)
    "fff"
    cg-user(19):

See also uri.html for general information on Universal Resource Indicator support in Allegro CL. URN syntax is described in RFC8141 (https://tools.ietf.org/html/rfc8141)

Copyright (c) Franz Inc. Lafayette, CA., USA. All rights reserved.

ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 11.0