From 836c717429785924929dc650171faa391489fee1 Mon Sep 17 00:00:00 2001 From: "Kevin M. Rosenberg" Date: Sat, 29 Aug 2015 18:40:09 -0600 Subject: [PATCH] Remove Franz documenation as is copyright by Franz --- README | 5 + debian/changelog | 7 + debian/control | 2 +- debian/rules | 2 +- uri.html | 406 ----------------------------------------------- 5 files changed, 14 insertions(+), 408 deletions(-) delete mode 100644 uri.html diff --git a/README b/README index 7ef3a63..fa5a7a1 100644 --- a/README +++ b/README @@ -17,6 +17,11 @@ SUPPORTED PLATFORMS ------------------- AllegroCL, CLISP, CMUCL, Lispworks, OpenMCL, SBCL +DOCUMENTATION +---------- +Franz, Inc. has online documenation for the URI package upon which +PURI is based: + http://franz.com/support/documentation/current/doc/uri.htm OVERVIEW -------- diff --git a/debian/changelog b/debian/changelog index 2adc0f9..0f4b685 100644 --- a/debian/changelog +++ b/debian/changelog @@ -1,3 +1,10 @@ +cl-puri (1:1.5.6-1) unstable; urgency=medium + + * Removed uri.htm from distribution as is copyright by Franz, Inc + * Added link to online documentation URL in README (closes:668918) + + -- Kevin M. Rosenberg Sat, 29 Aug 2015 18:35:14 -0600 + cl-puri (1.5.5-1) unstable; urgency=low * New upstream diff --git a/debian/control b/debian/control index 3c31ecb..5d382cf 100644 --- a/debian/control +++ b/debian/control @@ -4,7 +4,7 @@ Priority: optional Maintainer: Kevin M. Rosenberg Build-Depends-Indep: dh-lisp Build-Depends: debhelper (>= 7.0.0) -Standards-Version: 3.8.4.0 +Standards-Version: 3.9.5.0 Homepage: http://files.kpe.io/puri/ Vcs-Git: git://git.kpe.io/puri/ Vcs-Browser: http://git.kpe.io/puri/ diff --git a/debian/rules b/debian/rules index b98d601..356e30f 100755 --- a/debian/rules +++ b/debian/rules @@ -26,7 +26,7 @@ install: build binary-indep: install dh_testdir dh_testroot - dh_installdocs README uri.html + dh_installdocs README dh_installchangelogs dh_lisp dh_compress diff --git a/uri.html b/uri.html deleted file mode 100644 index 2cd92ff..0000000 --- a/uri.html +++ /dev/null @@ -1,406 +0,0 @@ - - - -URI support in Allegro CL - - - - -

URI support in Allegro CL

- -

This document contains the following sections:

1.0 Introduction
-2.0 The URI API definition
-3.0 Parsing, escape decoding/encoding and the path
-4.0 Interning URIs
-5.0 Allegro CL implementation notes
-6.0 Examples
-

- -

This version of the Allegro CL URI support documentation is for distribution with the -Open Source version of the URI code. Links to Allegro CL documentation other than -URI-specific files have been supressed. To see Allegro CL documentation, see http://www.franz.com/support/documentation/, -which is the Allegro CL documentation page of the franz inc. website. Links to Allegro CL -documentation can be found on that page.

- -

1.0 Introduction

- -

URI stands for Universal Resource Identifier. For a description of -URIs, see RFC2396, which can be found in several places, including the IETF web site (http://www.ietf.org/rfc/rfc2396.txt) and -the UCI/ICS web site (http://www.ics.uci.edu/pub/ietf/uri/rfc2396.txt). -We prefer the UCI/ICS one as it has more examples.

- -

URIs are a superset in functionality and syntax to URLs (Universal Resource Locators) -and URNs (Universal Resource Names). That is, RFC2396 updates and merges RFC1738 and -RFC1808 into a single syntax, called the URI. It does exclude some portions of RFC1738 -that define specific syntax of individual URL schemes.

- -

In URL slang, the scheme is usually called the `protocol', but it is called -scheme in RFC1738. A URL `host' corresponds to the URI `authority.' The URL slang -`bookmark' or `anchor' is `fragment' in URI lingo.

- -

The URI facility was available as a patch to Allegro CL 5.0.1 and is included with -release 6.0. the URI facility might not be in an Allegro CL image. Evaluate (require -:uri) to ensure the facility is loaded (that form returns nil if the -URI module is already loaded).

- -

Broadly, the URI facility creates a Lisp object that represents a URI, and provides -setters and accessors to fields in the URI object. The URI object can also be interned, -much like symbols in CL are. This document describes the facility and the related -operators.

- -

Aside from the obvious slots which are called out in the RFC, URIs also have a property -list. With interning, this is another similarity between URIs and CL symbols.

- -

2.0 The URI API definition

- -

Symbols naming objects (functions, variables, etc.) in the uri module are -exported from the net.uri package.

- -

URIs are represented by CLOS objects. Their slots are:

- -

-scheme 
-host 
-port 
-path 
-query
-fragment 
-plist 
-

- -

The host and port slots together correspond to the authority -(see RFC2396). There is an accessor-like function, uri-authority, -that can be used to extract the authority from a URI. See the RFC2396 specifications -pointed to at the beginning of the 1.0 Introduction for details -of all the slots except plist. The plist slot contains a -standard Common Lisp property list.

- -

All symbols are external in the net.uri package, unless otherwise noted. -Brief descriptions are given in this document, with complete descriptions in the -individual pages. - -

uri: the class of URI objects.
urn: the class of URN objects.
uri-p
Arguments: object
-
Returns true if object is an instance of class uri. -
-
copy-uri
Arguments: uri &key - place scheme host port path query fragment plist
-
Copies the specified URI object. See the description page for information on the - keyword arguments.
-
uri-scheme
- uri-host
- uri-port
- uri-path
- uri-query
- uri-fragment
- uri-plist
-
Arguments: uri-object
-
These accessors return the value of the associated slots of the uri-object
-
uri-authority
Arguments: uri-object -
-
Returns the authority of uri-object. The authority combines the host and port.
-
render-uri
Arguments: uri - stream
-
Print to stream the printed representation of uri.
-
parse-uri
Arguments: string &key - (class 'uri)
-
Parse string into a URI object.
-
merge-uris
Arguments: uri - base-uri &optional place
-
Return an absolute URI, based on uri, which can be relative, and base-uri - which must be absolute.
-
enough-uri
Arguments: uri - base
-
Converts uri into a relative URI using base as the base URI.
-
uri-parsed-path
Arguments: uri -
-
Return the parsed representation of the path.
-
uri
Arguments: object
-
Defined methods: if argument is a uri object, return it; create a uri object if - possible and return it, or error if not possible.
-

- -

3.0 Parsing, escape decoding/encoding and the path

- -

The method uri-path returns the path -portion of the URI, in string form. The method uri-parsed-path -returns the path portion of the URI, in list form. This list form is discussed below, -after a discussion of decoding/encoding.

- -

RFC2396 lays out a method for inserting into URIs reserved characters. You do -this by escaping the character. An escaped character is defined like this:

- -

-escaped = "%" hex hex 
-
-hex = digit | "A" | "B" | "C" | "D" | "E" | "F" | "a" | "b" | "c" | "d" | "e" | "f" 
-

- -

In addition, the RFC defines excluded characters:

- -

-"<" | ">" | "#" | "%" | <"> | "{" | "}" | "|" | "\" | "^" | "[" | "]" | "`" 
-

- -

The set of reserved characters are:

- -

-";" | "/" | "?" | ":" | "@" | "&" | "=" | "+" | "$" | "," 
-

- -

with the following exceptions: - -

within the authority component, the characters ";", ":", - "@", "?", and "/" are reserved.
within a path segment, the characters "/", ";", "=", and - "?" are reserved.
within a query component, the characters ";", "/", "?", - ":", "@", "&", "=", "+", - ",", and "$" are reserved.

- -

From the RFC, there are two important rules about escaping and unescaping (encoding and -decoding): - -

decoding should only happen when the URI is parsed into component parts;
encoding can only occur when a URI is made from component parts (ie, rendered for - printing).

- -

The implication of this is that to decode the URI, it must be in a parsed state. That -is, you can't convert %2f (the escaped form of -"/") until the path has been parsed into its component parts. Another important -desire is for the application viewing the component parts to see the decoded values of the -components. For example, consider:

- -

-http://www.franz.com/calculator/3%2f2 
-

- -

This might be the implementation of a calculator, and how someone would execute 3/2. -Clearly, the application that implements this would want to see path components of -"calculator" and "3/2". "3%2f2" would not be useful to the -calculator application.

- -

For the reasons given above, a parsed version of the path is available and 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")) 
-

- -

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

- -

4.0 Interning URIs

- -

This section describes how to intern URIs. Interning is not mandatory. URIs can be used -perfectly well without interning them.

- -

Interned URIs in Allegro are like symbols. That is, a string representing a URI, when -parsed and interned, will always yield an eq object. For example:

- -

-(eq (intern-uri "http://www.franz.com") 
-    (intern-uri "http://www.franz.com")) 
-

- -

is always true. (Two strings with identical contents may or may not be eq -in Common Lisp, note.)

- -

The functions associated with interning are: - -

make-uri-space
Arguments: &key - size
-
Make a new hash-table object to contain interned URIs.
-
uri-space
Arguments:
-
Return the object into which URIs are currently being interned.
-
uri=
Arguments: uri1 uri2
-
Returns true if uri1 and uri2 are equivalent.
-
intern-uri
Arguments: uri-name - &optional uri-space
-
Intern the uri object specified in the uri-space specified. Methods exist for strings - and uri objects.
-
unintern-uri
Arguments: uri - &optional uri-space
-
Unintern the uri object specified or all uri objects (in uri-space if specified) - if uri is t.
-
do-all-uris
Arguments: (var &optional - uri-space result) &body body
-
Bind var to all currently defined uris (in uri-space if specified) and - evaluate body.
-

- -

5.0 Allegro CL implementation notes

- -

The following are true:
- (uri= (parse-uri "http://www.franz.com/")
- (parse-uri "http://www.franz.com"))
- (eq (intern-uri "http://www.franz.com/")
- (intern-uri "http://www.franz.com"))
-
The following is true:
- (eq (intern-uri "http://www.franz.com:80/foo/bar.htm")
- (intern-uri "http://www.franz.com/foo/bar.htm"))
- (I.e. specifying the default port is the same as specifying no port at all. This is - specific in RFC2396.)
The scheme and authority are case-insensitive. In Allegro CL, the - scheme is a keyword that appears in the normal case for the Lisp in which you are - executing.
#u"..." is shorthand for (parse-uri "...") - but if an existing #u dispatch macro definition exists, it will not be - overridden.
The interaction between setting the scheme, host, port, path, query, and fragment slots - of URI objects, in conjunction with interning URIs will have very bad and unpredictable - results.
The printable representation of URIs is cached, for efficiency. This caching is undone - when the above slots are changed. That is, when you create a URI the printed - representation is cached. When you change one of the above mentioned slots, the printed - representation is cleared and calculated when the URI is next printed. For example:

- -

-user(10): (setq u #u"http://foo.bar.com/foo/bar") 
-#<uri http://foo.bar.com/foo/bar> 
-user(11): (setf (net.uri:uri-host u) "foo.com") 
-"foo.com" 
-user(12): u 
-#<uri http://foo.com/foo/bar> 
-user(13): 
-

- -

This allows URIs behavior to follow the principle of least surprise.

- -

6.0 Examples

- -

-uri(10): (use-package :net.uri)
-t
-uri(11): (parse-uri "foo")
-#<uri foo>
-uri(12): #u"foo"
-#<uri foo>
-uri(13): (setq base (intern-uri "http://www.franz.com/foo/bar/"))
-#<uri http://www.franz.com/foo/bar/>
-uri(14): (merge-uris (parse-uri "foo.htm") base)
-#<uri http://www.franz.com/foo/bar/foo.htm>
-uri(15): (merge-uris (parse-uri "?foo") base)
-#<uri http://www.franz.com/foo/bar/?foo>
-uri(16): (setq base (intern-uri "http://www.franz.com/foo/bar/baz.htm"))
-#<uri http://www.franz.com/foo/bar/baz.htm>
-uri(17): (merge-uris (parse-uri "foo.htm") base)
-#<uri http://www.franz.com/foo/bar/foo.htm>
-uri(18): (merge-uris #u"?foo" base)
-#<uri http://www.franz.com/foo/bar/?foo>
-uri(19): (describe #u"http://www.franz.com")
-#<uri http://www.franz.com> is an instance of #<standard-class net.uri:uri>:
- The following slots have :instance allocation:
-  scheme        :http
-  host          "www.franz.com"
-  port          nil
-  path          nil
-  query         nil
-  fragment      nil
-  plist         nil
-  escaped       nil
-  string        "http://www.franz.com"
-  parsed-path   nil
-  hashcode      nil
-uri(20): (describe #u"http://www.franz.com/")
-#<uri http://www.franz.com> is an instance of #<standard-class net.uri:uri>:
- The following slots have :instance allocation:
-  scheme        :http
-  host          "www.franz.com"
-  port          nil
-  path          nil
-  query         nil
-  fragment      nil
-  plist         nil
-  escaped       nil
-  string        "http://www.franz.com"
-  parsed-path   nil
-  hashcode      nil
-uri(21): #u"foobar#baz%23xxx"
-#<uri foobar#baz#xxx>
-

- -

- - -- 2.34.1