summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--doc/ref/web.texi80
1 files changed, 50 insertions, 30 deletions
diff --git a/doc/ref/web.texi b/doc/ref/web.texi
index 1e6087575..7d6bbf4cc 100644
--- a/doc/ref/web.texi
+++ b/doc/ref/web.texi
@@ -144,9 +144,9 @@ text. Let's make a new definition of @code{para}:
@end example
So we see in the second example that HTML elements cannot be unwittingly
-introduced into the output. However it is perfectly acceptable to pass
-SXML to @code{you-said}; in fact, that is the big advantage of SXML over
-everything-as-a-string.
+introduced into the output. However it is now perfectly acceptable to
+pass SXML to @code{you-said}; in fact, that is the big advantage of SXML
+over everything-as-a-string.
@example
(sxml->xml (you-said (you-said "<Hi!>")))
@@ -204,9 +204,13 @@ The following procedures can be found in the @code{(web uri)}
module. Load it into your Guile, using a form like the above, to have
access to them.
-@defun build-uri scheme [#:userinfo] [#:host] [#:port] [#:path] [#:query] [#:fragment] [#:validate?]
-Construct a URI object. If @var{validate?} is true, also run some
-consistency checks to make sure that the constructed URI is valid.
+@defun build-uri scheme [#:userinfo=@code{#f}] [#:host=@code{#f}] @
+ [#:port=@code{#f}] [#:path=@code{""}] [#:query=@code{#f}] @
+ [#:fragment=@code{#f}] [#:validate?=@code{#t}]
+Construct a URI object. @var{scheme} should be a symbol, and the rest
+of the fields are either strings or @code{#f}. If @var{validate?} is
+true, also run some consistency checks to make sure that the constructed
+URI is valid.
@end defun
@defun uri? x
@@ -217,45 +221,58 @@ consistency checks to make sure that the constructed URI is valid.
@defunx uri-path uri
@defunx uri-query uri
@defunx uri-fragment uri
-A predicate and field accessors for the URI record type.
+A predicate and field accessors for the URI record type. The URI scheme
+will be a symbol, and the rest either strings or @code{#f} if not
+present.
@end defun
-@defun declare-default-port! scheme port
-Declare a default port for the given URI scheme.
-
-Default ports are for printing URI objects: a default port is not
-printed.
+@defun string->uri string
+Parse @var{string} into a URI object. Return @code{#f} if the string
+could not be parsed.
@end defun
-@defun parse-uri string
-Parse @var{string} into a URI object. Returns @code{#f} if the string
-could not be parsed.
+@defun 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
+serialization.
@end defun
-@defun unparse-uri uri
-Serialize @var{uri} to a string.
+@defun declare-default-port! scheme port
+Declare a default port for the given URI scheme.
@end defun
-@defun uri-decode str [#:charset]
-Percent-decode the given @var{str}, according to @var{charset}.
+@defun uri-decode str [#:encoding=@code{"utf-8"}]
+Percent-decode the given @var{str}, according to @var{encoding}, which
+should be the name of a character encoding.
Note that this function should not generally be applied to a full URI
string. For paths, use split-and-decode-uri-path instead. For query
strings, split the query on @code{&} and @code{=} boundaries, and decode
the components separately.
-Note that percent-encoded strings encode @emph{bytes}, not characters.
-There is no guarantee that a given byte sequence is a valid string
-encoding. Therefore this routine may signal an error if the decoded
-bytes are not valid for the given encoding. Pass @code{#f} for
-@var{charset} if you want decoded bytes as a bytevector directly.
+Note also that percent-encoded strings encode @emph{bytes}, not
+characters. There is no guarantee that a given byte sequence is a valid
+string encoding. Therefore this routine may signal an error if the
+decoded bytes are not valid for the given encoding. Pass @code{#f} for
+@var{encoding} if you want decoded bytes as a bytevector directly.
+@xref{Ports, @code{set-port-encoding!}}, for more information on
+character encodings.
+
+Returns a string of the decoded characters, or a bytevector if
+@var{encoding} was @code{#f}.
@end defun
-@defun uri-encode str [#:charset] [#:unescaped-chars]
-Percent-encode any character not in @var{unescaped-chars}.
+Fixme: clarify return type. indicate default values. type of
+unescaped-chars.
-Percent-encoding first writes out the given character to a bytevector
-within the given @var{charset}, then encodes each byte as
+@defun uri-encode str [#:encoding=@code{"utf-8"}] [#:unescaped-chars]
+Percent-encode any character not in the character set,
+@var{unescaped-chars}.
+
+The default character set includes alphanumerics from ASCII, as well as
+the special characters @samp{-}, @samp{.}, @samp{_}, and @samp{~}. Any
+other character will be percent-encoded, by writing out the character to
+a bytevector within the given @var{encoding}, then encoding each byte as
@code{%@var{HH}}, where @var{HH} is the hexadecimal representation of
the byte.
@end defun
@@ -264,13 +281,16 @@ the byte.
Split @var{path} into its components, and decode each component,
removing empty components.
-For example, @code{"/foo/bar/"} decodes to the two-element list,
-@code{("foo" "bar")}.
+For example, @code{"/foo/bar%20baz/"} decodes to the two-element list,
+@code{("foo" "bar baz")}.
@end defun
@defun encode-and-join-uri-path parts
URI-encode each element of @var{parts}, which should be a list of
strings, and join the parts together with @code{/} as a delimiter.
+
+For example, the list @code{("scrambled eggs" "biscuits&gravy")} encodes
+as @code{"scrambled%20eggs/biscuits%26gravy"}.
@end defun
@node HTTP