The purl Reference Manual

Table of Contents

The purl Reference Manual

This is the purl Reference Manual, version 1.2, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 17:29:16 2021 GMT+0.

1 Introduction

purl

Description:

Provides a parser and defines a type for URLs as specified in RFC1738.

Current version is 1.2.

Documentation:

• API documentation
• Issues

Dependencies:

• maxpc
• percent-encoding

2 Systems

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

2.1 purl

Author

Max Rottenkolber <max@mr.gy>

License

GNU AGPL

Description

Parse and print URLs as described in RFC 1738.

Version

1.2

Dependencies

• maxpc
• percent-encoding
• uiop

Source

purl.asd (file)

Components

• package.lisp (file)
• grammar.lisp (file)
• purl.lisp (file)

3 Files

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

3.1 Lisp

3.1.1 purl.asd

Location

purl.asd

Systems

purl (system)

Packages

purl-asd

3.1.2 purl/package.lisp

Parent

purl (system)

Location

package.lisp

Packages

purl

3.1.3 purl/grammar.lisp

Dependency

package.lisp (file)

Parent

purl (system)

Location

grammar.lisp

Internal Definitions

• =common-address (function)
• =common-address-p (function)
• =credentials (function)
• =host (function)
• =password (function)
• =path (function)
• =port (function)
• =scheme (function)
• =url (function)
• =user (function)

3.1.4 purl/purl.lisp

Dependencies

• package.lisp (file)
• grammar.lisp (file)

Parent

purl (system)

Location

purl.lisp

Exported Definitions

• make-url (function)
• url (function)
• url (structure)
• url-address (function)
• url-decode (function)
• url-encode (function)
• url-host (function)
• url-p (function)
• url-password (function)
• url-path (function)
• url-port (function)
• url-scheme (function)
• url-string (function)
• url-user (function)
• url= (function)

Internal Definitions

• common-address (structure)
• common-address-host (function)
• (setf common-address-host) (function)
• common-address-p (function)
• common-address-password (function)
• (setf common-address-password) (function)
• common-address-path (function)
• (setf common-address-path) (function)
• common-address-port (function)
• (setf common-address-port) (function)
• common-address-string (function)
• common-address-user (function)
• (setf common-address-user) (function)
• copy-common-address (function)
• copy-url (function)
• encode-pathname (function)
• make-common-address (function)
• make-url% (function)
• malformed-url (condition)
• parse-common-address (function)
• parse-url (function)
• pathname-url-path (function)
• url-address% (function)
• (setf url-address%) (function)
• url-p% (function)
• url-scheme% (function)
• (setf url-scheme%) (function)
• url-scheme-string (function)

4 Packages

Packages are listed by definition order.

4.1 purl-asd

System definition for PURL.

Source

purl.asd

Use List

• asdf/interface
• common-lisp

4.2 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 (file)

Use List

• uiop/driver
• percent-encoding
• maxpc.digit
• maxpc.char
• maxpc
• common-lisp

Exported Definitions

• make-url (function)
• url (function)
• url (structure)
• url-address (function)
• url-decode (function)
• url-encode (function)
• url-host (function)
• url-p (function)
• url-password (function)
• url-path (function)
• url-port (function)
• url-scheme (function)
• url-string (function)
• url-user (function)
• url= (function)

Internal Definitions

• =common-address (function)
• =common-address-p (function)
• =credentials (function)
• =host (function)
• =password (function)
• =path (function)
• =port (function)
• =scheme (function)
• =url (function)
• =user (function)
• common-address (structure)
• common-address-host (function)
• (setf common-address-host) (function)
• common-address-p (function)
• common-address-password (function)
• (setf common-address-password) (function)
• common-address-path (function)
• (setf common-address-path) (function)
• common-address-port (function)
• (setf common-address-port) (function)
• common-address-string (function)
• common-address-user (function)
• (setf common-address-user) (function)
• copy-common-address (function)
• copy-url (function)
• encode-pathname (function)
• make-common-address (function)
• make-url% (function)
• malformed-url (condition)
• parse-common-address (function)
• parse-url (function)
• pathname-url-path (function)
• url-address% (function)
• (setf url-address%) (function)
• url-p% (function)
• url-scheme% (function)
• (setf url-scheme%) (function)
• url-scheme-string (function)

5 Definitions

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

5.1 Exported definitions

5.1.1 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 (file)

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 (file)

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 (file)

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 (file)

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 (file)

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 (file)

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 (file)

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 (file)

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 (file)

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 (file)

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 (file)

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 (file)

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 (file)

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 (file)

5.1.2 Structures

Structure: url ()

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

Package

purl

Source

purl.lisp (file)

Direct superclasses

structure-object (structure)

Direct methods

print-object (method)

Direct slots

Slot: scheme%

Type

keyword

Readers

url-scheme% (function)

Writers

(setf url-scheme%) (function)

Slot: address%

Type

(or string purl::common-address)

Readers

url-address% (function)

Writers

(setf url-address%) (function)

5.2 Internal definitions

5.2.1 Functions

Function: =common-address ()

Parser for common address.

Package

purl

Source

grammar.lisp (file)

Function: =common-address-p ()

Parser for URI address type.

Package

purl

Source

grammar.lisp (file)

Function: =credentials ()

Parser for user credentials.

Package

purl

Source

grammar.lisp (file)

Function: =host ()

Parser for host.

Package

purl

Source

grammar.lisp (file)

Function: =password ()

Parser for password.

Package

purl

Source

grammar.lisp (file)

Function: =path ()

Parser for path.

Package

purl

Source

grammar.lisp (file)

Function: =port ()

Parser for port.

Package

purl

Source

grammar.lisp (file)

Function: =scheme ()

Parser for URL scheme.

Package

purl

Source

grammar.lisp (file)

Function: =url ()

Parser for URL.

Package

purl

Source

grammar.lisp (file)

Function: =user ()

Parser for user.

Package

purl

Source

grammar.lisp (file)

Function: common-address-host INSTANCE

Function: (setf common-address-host) VALUE INSTANCE

Package

purl

Source

purl.lisp (file)

Function: common-address-p OBJECT

Package

purl

Source

purl.lisp (file)

Function: common-address-password INSTANCE

Function: (setf common-address-password) VALUE INSTANCE

Package

purl

Source

purl.lisp (file)

Function: common-address-path INSTANCE

Function: (setf common-address-path) VALUE INSTANCE

Package

purl

Source

purl.lisp (file)

Function: common-address-port INSTANCE

Function: (setf common-address-port) VALUE INSTANCE

Package

purl

Source

purl.lisp (file)

Function: common-address-string COMMON-ADDRESS

Return string for COMMON-ADDRESS.

Package

purl

Source

purl.lisp (file)

Function: common-address-user INSTANCE

Function: (setf common-address-user) VALUE INSTANCE

Package

purl

Source

purl.lisp (file)

Function: copy-common-address INSTANCE

Package

purl

Source

purl.lisp (file)

Function: copy-url INSTANCE

Package

purl

Source

purl.lisp (file)

Function: encode-pathname PATH

URL encode physical PATH.

Package

purl

Source

purl.lisp (file)

Function: make-common-address &key (USER USER) (PASSWORD PASSWORD) (HOST HOST) (PORT PORT) (PATH PATH)

Package

purl

Source

purl.lisp (file)

Function: make-url% &key (SCHEME% SCHEME%) (ADDRESS% ADDRESS%)

Package

purl

Source

purl.lisp (file)

Function: parse-common-address URL-ADDRESS

Parse COMMON-ADDRESS structure from URL-ADDRESS.

Package

purl

Source

purl.lisp (file)

Function: parse-url STRING

Return URL structure for STRING.

Package

purl

Source

purl.lisp (file)

Function: pathname-url-path PATH

Return URL path part for PATH.

Package

purl

Source

purl.lisp (file)

Function: url-address% INSTANCE

Function: (setf url-address%) VALUE INSTANCE

Package

purl

Source

purl.lisp (file)

Function: url-p% OBJECT

Package

purl

Source

purl.lisp (file)

Function: url-scheme% INSTANCE

Function: (setf url-scheme%) VALUE INSTANCE

Package

purl

Source

purl.lisp (file)

Function: url-scheme-string SCHEME

Return string for SCHEME.

Package

purl

Source

purl.lisp (file)

5.2.2 Conditions

Condition: malformed-url ()

Condition signaling a malformed URL string.

Package

purl

Source

purl.lisp (file)

Direct superclasses

error (condition)

Direct slots

Slot: message

Error description.

Initargs

:message

Initform

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

5.2.3 Structures

Structure: common-address ()

Common address structure for IP-based protocols.

Package

purl

Source

purl.lisp (file)

Direct superclasses

structure-object (structure)

Direct slots

Slot: user

Type

(or string null)

Readers

common-address-user (function)

Writers

(setf common-address-user) (function)

Slot: password

Type

(or string null)

Readers

common-address-password (function)

Writers

(setf common-address-password) (function)

Slot: host

Type

(or string null)

Readers

common-address-host (function)

Writers

(setf common-address-host) (function)

Slot: port

Type

(or unsigned-byte null)

Readers

common-address-port (function)

Writers

(setf common-address-port) (function)

Slot: path

Type

(or string null)

Readers

common-address-path (function)

Writers

(setf common-address-path) (function)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types