The purl Reference Manual

This is the purl Reference Manual, version 1.2, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Feb 26 17:37:50 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 purl

Parse and print URLs as described in RFC 1738.

Author

Max Rottenkolber <>

License

GNU AGPL

Version

1.2

Dependencies
  • maxpc (system).
  • percent-encoding (system).
  • uiop (system).
Source

purl.asd.

Child Components

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


3.1 Lisp


3.1.1 purl/purl.asd

Source

purl.asd.

Parent Component

purl (system).

ASDF Systems

purl.

Packages

purl-asd.


3.1.2 purl/package.lisp

Source

purl.asd.

Parent Component

purl (system).

Packages

purl.


3.1.3 purl/grammar.lisp

Dependency

package.lisp (file).

Source

purl.asd.

Parent Component

purl (system).

Internals

3.1.4 purl/purl.lisp

Dependencies
Source

purl.asd.

Parent Component

purl (system).

Public Interface
Internals

4 Packages

Packages are listed by definition order.


4.1 purl

Parse and print _Uniform Resource Locators_ as defined in
[RFC 1738](http://tools.ietf.org/html/rfc1738).

< URL Designators

A _url designator_ is a value accepted by the {url} _function_. E.g. a _url_, a _string_ or a _pathname_.

>

Source

package.lisp.

Use List
  • common-lisp.
  • maxpc.
  • maxpc.char.
  • maxpc.digit.
  • percent-encoding.
  • uiop/driver.
Public Interface
Internals

4.2 purl-asd

System definition for PURL.

Source

purl.asd.

Use List
  • asdf/interface.
  • common-lisp.

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


5.1 Public Interface


5.1.1 Ordinary functions

Function: make-url (scheme &key address user password host port path)

*Arguments and Values:*

_scheme_—a _keyword_ denoting a URL scheme.

_address_—a _string_ denoting a URL address for _scheme_ or {nil}. The
default is {nil}.

_user_, _password_, _host_—_strings_ denoting a user name, password or
hostname respectively or {nil}. The default is {nil}.

_path_—a _string_ or a _pathname_.

_port_—a positive _integer_ denoting a port number or {nil} . The
default is {nil}.

*Description*:

{make-url} returns a fresh _url_ of _scheme_. _Address_ is used as the
URL’s address if supplied. Otherwise the URL’s address will use
_Common Internet Scheme Syntax_¹ and its address is composed of the
_user_, _password_, _host_, _port_ and _path_ components.

*See Also:*

+ 1. [Common Internet Scheme Syntax](http://tools.ietf.org/html/rfc1738#section-3.1)

Package

purl.

Source

purl.lisp.

Function: url (urlspec)

*Arguments and Values:*

_urlspec_—a _string_, a _pathname_ or a _url_.

*Description*:

{url} returns the _url_ denoted by _urlspec_. When _urlspec_ is a string, {url} will attempt to parse _urlspec_ as a URL. When _urlspec_ is a _pathname_, {url} will return an equivalent _url_ using the {:file} scheme.

*Exceptional Situations:*

An error of _type_ {malformed-url} is signaled when _urlspec_ is a _string_ and can not be parsed as a URL.

An error of _type_ {type-error} is signaled when _urlspec_ is a _pathname_ using a host component which is not a defined logical host.

Package

purl.

Source

purl.lisp.

Function: url-address (url)

*Arguments and Values:*

_url_—a _url_ designator.

*Description*:

{url-address} returns a _string_ denoting the address part of _url_.

Package

purl.

Source

purl.lisp.

Function: url-decode (string)

*Arguments and Values:*

_string_—a _string.

*Description*:

{url-decode} decodes encoded _string_ using _Percent-Encoding_¹.

*See Also:*

+ 1. [Percent-Encoding](http://tools.ietf.org/html/rfc3986#section-2.1)

Package

purl.

Source

purl.lisp.

Function: url-encode (string)

*Arguments and Values:*

_string_—a _string.

*Description*:

{url-encode} encodes _string_ using _Percent-Encoding_¹.

*See Also:*

+ 1. [Percent-Encoding](http://tools.ietf.org/html/rfc3986#section-2.1)

Package

purl.

Source

purl.lisp.

Function: url-host (url)

*Arguments and Values:*

_url_—a _url_ designator.

*Description*:

{url-host} returns a _string_ denoting the host part of _url_.

Package

purl.

Source

purl.lisp.

Function: url-p (object)

*Arguments and Values:*

_object_—an _object_.

*Description*:

{url-p} returns _true_ if _object_ is of _type_ {url}; otherwise, returns _false_.

Package

purl.

Source

purl.lisp.

Function: url-password (url)

*Arguments and Values:*

_url_—a _url_ designator.

*Description*:

{url-password} returns a _string_ denoting the password part of _url_.

Package

purl.

Source

purl.lisp.

Function: url-path (url)

*Arguments and Values:*

_url_—a _url_ designator.

*Description*:

{url-path} returns a _string_ denoting the path part of _url_.

Package

purl.

Source

purl.lisp.

Function: url-port (url)

*Arguments and Values:*

_url_—a _url_ designator.

*Description*:

{url-port} returns a non-negative _integer_ denoting the port part of _url_.

Package

purl.

Source

purl.lisp.

Function: url-scheme (url)

*Arguments and Values:*

_url_—a _url_ designator.

*Description*:

{url-scheme} returns a _keyword_ denoting the scheme part of _url_.

Package

purl.

Source

purl.lisp.

Function: url-string (url)

*Arguments and Values:*

_url_—a _url_ designator.

*Description*:

{url-string} returns a _string_ representation of _url_.

Package

purl.

Source

purl.lisp.

Function: url-user (url)

*Arguments and Values:*

_url_—a _url_ designator.

*Description*:

{url-user} returns a _string_ denoting the user part of _url_.

Package

purl.

Source

purl.lisp.

Function: url= (url1 url2)

*Arguments and Values:*

_url1_, _url2_—_urls_.

*Description*:

{url=} returns _true_ if _url1_ and _url2_ are equal; otherwise, returns _false_.

Package

purl.

Source

purl.lisp.


5.1.2 Standalone methods

Method: print-object ((url url) stream)
Source

purl.lisp.


5.1.3 Structures

Structure: url

A _url_ is a structured _object_ which represents a _Uniform Resource Locator_ (URL).

Package

purl.

Source

purl.lisp.

Direct superclasses

structure-object.

Direct methods

print-object.

Direct slots
Slot: scheme%
Type

keyword

Readers

url-scheme%.

Writers

(setf url-scheme%).

Slot: address%
Type

(or string purl::common-address)

Readers

url-address%.

Writers

(setf url-address%).


5.2 Internals


5.2.1 Ordinary functions

Function: =common-address ()

Parser for common address.

Package

purl.

Source

grammar.lisp.

Function: =common-address-p ()

Parser for URI address type.

Package

purl.

Source

grammar.lisp.

Function: =credentials ()

Parser for user credentials.

Package

purl.

Source

grammar.lisp.

Function: =host ()

Parser for host.

Package

purl.

Source

grammar.lisp.

Function: =password ()

Parser for password.

Package

purl.

Source

grammar.lisp.

Function: =path ()

Parser for path.

Package

purl.

Source

grammar.lisp.

Function: =port ()

Parser for port.

Package

purl.

Source

grammar.lisp.

Function: =scheme ()

Parser for URL scheme.

Package

purl.

Source

grammar.lisp.

Function: =url ()

Parser for URL.

Package

purl.

Source

grammar.lisp.

Function: =user ()

Parser for user.

Package

purl.

Source

grammar.lisp.

Reader: common-address-host (instance)
Writer: (setf common-address-host) (instance)
Package

purl.

Source

purl.lisp.

Target Slot

host.

Function: common-address-p (object)
Package

purl.

Source

purl.lisp.

Reader: common-address-password (instance)
Writer: (setf common-address-password) (instance)
Package

purl.

Source

purl.lisp.

Target Slot

password.

Reader: common-address-path (instance)
Writer: (setf common-address-path) (instance)
Package

purl.

Source

purl.lisp.

Target Slot

path.

Reader: common-address-port (instance)
Writer: (setf common-address-port) (instance)
Package

purl.

Source

purl.lisp.

Target Slot

port.

Function: common-address-string (common-address)

Return string for COMMON-ADDRESS.

Package

purl.

Source

purl.lisp.

Reader: common-address-user (instance)
Writer: (setf common-address-user) (instance)
Package

purl.

Source

purl.lisp.

Target Slot

user.

Function: copy-common-address (instance)
Package

purl.

Source

purl.lisp.

Function: copy-url (instance)
Package

purl.

Source

purl.lisp.

Function: encode-pathname (path)

URL encode physical PATH.

Package

purl.

Source

purl.lisp.

Function: make-common-address (&key user password host port path)
Package

purl.

Source

purl.lisp.

Function: make-url% (&key scheme% address%)
Package

purl.

Source

purl.lisp.

Function: parse-common-address (url-address)

Parse COMMON-ADDRESS structure from URL-ADDRESS.

Package

purl.

Source

purl.lisp.

Function: parse-url (string)

Return URL structure for STRING.

Package

purl.

Source

purl.lisp.

Function: pathname-url-path (path)

Return URL path part for PATH.

Package

purl.

Source

purl.lisp.

Reader: url-address% (instance)
Writer: (setf url-address%) (instance)
Package

purl.

Source

purl.lisp.

Target Slot

address%.

Function: url-p% (object)
Package

purl.

Source

purl.lisp.

Reader: url-scheme% (instance)
Writer: (setf url-scheme%) (instance)
Package

purl.

Source

purl.lisp.

Target Slot

scheme%.

Function: url-scheme-string (scheme)

Return string for SCHEME.

Package

purl.

Source

purl.lisp.


5.2.2 Conditions

Condition: malformed-url

Condition signaling a malformed URL string.

Package

purl.

Source

purl.lisp.

Direct superclasses

error.

Direct slots
Slot: message

Error description.

Initform

(quote (error "must supply message."))

Initargs

:message


5.2.3 Structures

Structure: common-address

Common address structure for IP-based protocols.

Package

purl.

Source

purl.lisp.

Direct superclasses

structure-object.

Direct slots
Slot: user
Type

(or string null)

Readers

common-address-user.

Writers

(setf common-address-user).

Slot: password
Type

(or string null)

Readers

common-address-password.

Writers

(setf common-address-password).

Slot: host
Type

(or string null)

Readers

common-address-host.

Writers

(setf common-address-host).

Slot: port
Type

(or unsigned-byte null)

Readers

common-address-port.

Writers

(setf common-address-port).

Slot: path
Type

(or string null)

Readers

common-address-path.

Writers

(setf common-address-path).


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   (   =  
C   E   F   M   P   U  
Index Entry  Section

(
(setf common-address-host): Private ordinary functions
(setf common-address-password): Private ordinary functions
(setf common-address-path): Private ordinary functions
(setf common-address-port): Private ordinary functions
(setf common-address-user): Private ordinary functions
(setf url-address%): Private ordinary functions
(setf url-scheme%): Private ordinary functions

=
=common-address: Private ordinary functions
=common-address-p: Private ordinary functions
=credentials: Private ordinary functions
=host: Private ordinary functions
=password: Private ordinary functions
=path: Private ordinary functions
=port: Private ordinary functions
=scheme: Private ordinary functions
=url: Private ordinary functions
=user: Private ordinary functions

C
common-address-host: Private ordinary functions
common-address-p: Private ordinary functions
common-address-password: Private ordinary functions
common-address-path: Private ordinary functions
common-address-port: Private ordinary functions
common-address-string: Private ordinary functions
common-address-user: Private ordinary functions
copy-common-address: Private ordinary functions
copy-url: Private ordinary functions

E
encode-pathname: Private ordinary functions

F
Function, (setf common-address-host): Private ordinary functions
Function, (setf common-address-password): Private ordinary functions
Function, (setf common-address-path): Private ordinary functions
Function, (setf common-address-port): Private ordinary functions
Function, (setf common-address-user): Private ordinary functions
Function, (setf url-address%): Private ordinary functions
Function, (setf url-scheme%): Private ordinary functions
Function, =common-address: Private ordinary functions
Function, =common-address-p: Private ordinary functions
Function, =credentials: Private ordinary functions
Function, =host: Private ordinary functions
Function, =password: Private ordinary functions
Function, =path: Private ordinary functions
Function, =port: Private ordinary functions
Function, =scheme: Private ordinary functions
Function, =url: Private ordinary functions
Function, =user: Private ordinary functions
Function, common-address-host: Private ordinary functions
Function, common-address-p: Private ordinary functions
Function, common-address-password: Private ordinary functions
Function, common-address-path: Private ordinary functions
Function, common-address-port: Private ordinary functions
Function, common-address-string: Private ordinary functions
Function, common-address-user: Private ordinary functions
Function, copy-common-address: Private ordinary functions
Function, copy-url: Private ordinary functions
Function, encode-pathname: Private ordinary functions
Function, make-common-address: Private ordinary functions
Function, make-url: Public ordinary functions
Function, make-url%: Private ordinary functions
Function, parse-common-address: Private ordinary functions
Function, parse-url: Private ordinary functions
Function, pathname-url-path: Private ordinary functions
Function, url: Public ordinary functions
Function, url-address: Public ordinary functions
Function, url-address%: Private ordinary functions
Function, url-decode: Public ordinary functions
Function, url-encode: Public ordinary functions
Function, url-host: Public ordinary functions
Function, url-p: Public ordinary functions
Function, url-p%: Private ordinary functions
Function, url-password: Public ordinary functions
Function, url-path: Public ordinary functions
Function, url-port: Public ordinary functions
Function, url-scheme: Public ordinary functions
Function, url-scheme%: Private ordinary functions
Function, url-scheme-string: Private ordinary functions
Function, url-string: Public ordinary functions
Function, url-user: Public ordinary functions
Function, url=: Public ordinary functions

M
make-common-address: Private ordinary functions
make-url: Public ordinary functions
make-url%: Private ordinary functions
Method, print-object: Public standalone methods

P
parse-common-address: Private ordinary functions
parse-url: Private ordinary functions
pathname-url-path: Private ordinary functions
print-object: Public standalone methods

U
url: Public ordinary functions
url-address: Public ordinary functions
url-address%: Private ordinary functions
url-decode: Public ordinary functions
url-encode: Public ordinary functions
url-host: Public ordinary functions
url-p: Public ordinary functions
url-p%: Private ordinary functions
url-password: Public ordinary functions
url-path: Public ordinary functions
url-port: Public ordinary functions
url-scheme: Public ordinary functions
url-scheme%: Private ordinary functions
url-scheme-string: Private ordinary functions
url-string: Public ordinary functions
url-user: Public ordinary functions
url=: Public ordinary functions