[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Guile-commits] 01/02: Document support for URI references.
From: |
Andy Wingo |
Subject: |
[Guile-commits] 01/02: Document support for URI references. |
Date: |
Mon, 09 Feb 2015 21:43:39 +0000 |
wingo pushed a commit to branch master
in repository guile.
commit d64146f2101ba4e3afacd5e724d038f20f42e26e
Author: Andy Wingo <address@hidden>
Date: Sun Feb 8 13:12:27 2015 +0100
Document support for URI references.
* doc/ref/web.texi (URIs): Update for URI reference changes.
---
doc/ref/web.texi | 40 +++++++++++++++++++++++++++++++---------
1 files changed, 31 insertions(+), 9 deletions(-)
diff --git a/doc/ref/web.texi b/doc/ref/web.texi
index c59f958..300b456 100644
--- a/doc/ref/web.texi
+++ b/doc/ref/web.texi
@@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
address@hidden Copyright (C) 2010, 2011, 2012, 2013 Free Software Foundation,
Inc.
address@hidden Copyright (C) 2010, 2011, 2012, 2013, 2015 Free Software
Foundation, Inc.
@c See the file guile.texi for copying conditions.
@node Web
@@ -184,6 +184,13 @@ URIs have a scheme and a path (though the path might be
empty). Some
URIs have a host, and some of those have ports and userinfo. Any URI
might have a query part or a fragment.
+There is also a ``URI-reference'' data type, which is the same as a URI
+but where the scheme is optional. In this case, the scheme is taken to
+be relative to some other related URI. A common use of URI references
+is when you want to be vague regarding the choice of HTTP or HTTPS --
+serving a web page referring to @code{/foo.css} will use HTTPS if loaded
+over HTTPS, or HTTP otherwise.
+
Userinfo is something of an abstraction, as some legacy URI schemes
allowed userinfo of the form @address@hidden:@var{passwd}}. But
since passwords do not belong in URIs, the RFC does not want to condone
@@ -217,6 +224,16 @@ also run some consistency checks to make sure that the
constructed URI
is valid.
@end deffn
address@hidden {Scheme Procedure} build-uri-reference [#:address@hidden@
+ [#:address@hidden [#:address@hidden [#:address@hidden @
+ [#:address@hidden""}] [#:address@hidden [#:address@hidden @
+ [#:address@hidden
+Like @code{build-uri}, but with an optional scheme.
address@hidden deffn
+
+In Guile, both URI and URI reference data types are represented in the
+same way, as URI objects.
+
@deffn {Scheme Procedure} uri? obj
@deffnx {Scheme Procedure} uri-scheme uri
@deffnx {Scheme Procedure} uri-userinfo uri
@@ -226,8 +243,10 @@ is valid.
@deffnx {Scheme Procedure} uri-query uri
@deffnx {Scheme Procedure} uri-fragment uri
A predicate and field accessors for the URI record type. The URI scheme
-will be a symbol, the port either a positive, exact integer or @code{#f},
-and the rest either strings or @code{#f} if not present.
+will be a symbol, or @code{#f} if the object is a URI reference but not
+a URI. The port will be either a positive, exact integer or @code{#f},
+and the rest of the fields will be either strings or @code{#f} if not
+present.
@end deffn
@deffn {Scheme Procedure} string->uri string
@@ -235,6 +254,11 @@ Parse @var{string} into a URI object. Return @code{#f} if
the string
could not be parsed.
@end deffn
address@hidden {Scheme Procedure} string->uri-reference string
+Parse @var{string} into a URI object, while not requiring a scheme.
+Return @code{#f} if the string could not be parsed.
address@hidden deffn
+
@deffn {Scheme Procedure} uri->string uri
Serialize @var{uri} to a string. If the URI has a port that is the
default port for its scheme, the port is not included in the
@@ -266,9 +290,6 @@ Returns a string of the decoded characters, or a bytevector
if
@var{encoding} was @code{#f}.
@end deffn
-Fixme: clarify return type. indicate default values. type of
-unescaped-chars.
-
@deffn {Scheme Procedure} uri-encode str [#:address@hidden"utf-8"}]
[#:unescaped-chars]
Percent-encode any character not in the character set,
@var{unescaped-chars}.
@@ -975,9 +996,10 @@ The entity-tag of the resource.
@end example
@end deftypevr
address@hidden {HTTP Header} URI location
-A URI on which a request may be completed. Used in combination with a
-redirecting status code to perform client-side redirection.
address@hidden {HTTP Header} URI-reference location
+A URI reference on which a request may be completed. Used in
+combination with a redirecting status code to perform client-side
+redirection.
@example
(parse-header 'location "http://example.com/other")
@result{} #<uri ...>