diff options
author | Andy Wingo <wingo@pobox.com> | 2013-01-15 10:45:39 +0100 |
---|---|---|
committer | Andy Wingo <wingo@pobox.com> | 2013-01-15 10:45:39 +0100 |
commit | b4fa6cc90961c87b28e26b469863f19a1be26ce2 (patch) | |
tree | e2db30c88db958a1afffc94eeb2b3d01203eb2d3 /doc | |
parent | e0c211bb2e80605b4ae3fb121c34136f6e266b70 (diff) | |
parent | 18c5bffe96947ee82a29b115e758d7357cefbbe9 (diff) | |
download | guile-b4fa6cc90961c87b28e26b469863f19a1be26ce2.tar.gz |
Merge remote-tracking branch 'origin/stable-2.0'
There is a failing test due to a scm_from_utf8_stringn bug brought out
by the iconv test that will be fixed in the next commit.
Conflicts:
libguile/deprecated.h
module/ice-9/deprecated.scm
Diffstat (limited to 'doc')
-rw-r--r-- | doc/guile-api.alist | 1 | ||||
-rw-r--r-- | doc/ref/api-data.texi | 86 | ||||
-rw-r--r-- | doc/ref/api-procedures.texi | 22 | ||||
-rw-r--r-- | doc/ref/web.texi | 66 |
4 files changed, 144 insertions, 31 deletions
diff --git a/doc/guile-api.alist b/doc/guile-api.alist index 5f73cae3a..5830c917a 100644 --- a/doc/guile-api.alist +++ b/doc/guile-api.alist @@ -466,7 +466,6 @@ (char-ci=? (groups Scheme) (scan-data "#<primitive-procedure char-ci=?>")) (char-ci>=? (groups Scheme) (scan-data "#<primitive-procedure char-ci>=?>")) (char-ci>? (groups Scheme) (scan-data "#<primitive-procedure char-ci>?>")) -(char-code-limit (groups Scheme) (scan-data "")) (char-downcase (groups Scheme) (scan-data "#<primitive-procedure char-downcase>")) (char-is-both? (groups Scheme) (scan-data "#<primitive-procedure char-is-both?>")) (char-lower-case? (groups Scheme) (scan-data "#<primitive-procedure char-lower-case?>")) diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi index 6d8de2bd6..21398f48d 100644 --- a/doc/ref/api-data.texi +++ b/doc/ref/api-data.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Guile Reference Manual. -@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007, 2008, 2009, 2010, 2011, 2012 +@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. @@ -2881,6 +2881,7 @@ Guile provides all procedures of SRFI-13 and a few more. * Reversing and Appending Strings:: Appending strings to form a new string. * Mapping Folding and Unfolding:: Iterating over strings. * Miscellaneous String Operations:: Replicating, insertion, parsing, ... +* Representing Strings as Bytes:: Encoding and decoding strings. * Conversion to/from C:: * String Internals:: The storage strategy for strings. @end menu @@ -4163,6 +4164,76 @@ a predicate, if it is a character, it is tested for equality and if it is a character set, it is tested for membership. @end deffn +@node Representing Strings as Bytes +@subsubsection Representing Strings as Bytes + +Out in the cold world outside of Guile, not all strings are treated in +the same way. Out there there are only bytes, and there are many ways +of representing a strings (sequences of characters) as binary data +(sequences of bytes). + +As a user, usually you don't have to think about this very much. When +you type on your keyboard, your system encodes your keystrokes as bytes +according to the locale that you have configured on your computer. +Guile uses the locale to decode those bytes back into characters -- +hopefully the same characters that you typed in. + +All is not so clear when dealing with a system with multiple users, such +as a web server. Your web server might get a request from one user for +data encoded in the ISO-8859-1 character set, and then another request +from a different user for UTF-8 data. + +@cindex iconv +@cindex character encoding +Guile provides an @dfn{iconv} module for converting between strings and +sequences of bytes. @xref{Bytevectors}, for more on how Guile +represents raw byte sequences. This module gets its name from the +common @sc{unix} command of the same name. + +Note that often it is sufficient to just read and write strings from +ports instead of using these functions. To do this, specify the port +encoding using @code{set-port-encoding!}. @xref{Ports}, for more on +ports and character encodings. + +Unlike the rest of the procedures in this section, you have to load the +@code{iconv} module before having access to these procedures: + +@example +(use-modules (ice-9 iconv)) +@end example + +@deffn string->bytevector string encoding [conversion-strategy] +Encode @var{string} as a sequence of bytes. + +The string will be encoded in the character set specified by the +@var{encoding} string. If the string has characters that cannot be +represented in the encoding, by default this procedure raises an +@code{encoding-error}. Pass a @var{conversion-strategy} argument to +specify other behaviors. + +The return value is a bytevector. @xref{Bytevectors}, for more on +bytevectors. @xref{Ports}, for more on character encodings and +conversion strategies. +@end deffn + +@deffn bytevector->string bytevector encoding [conversion-strategy] +Decode @var{bytevector} into a string. + +The bytes will be decoded from the character set by the @var{encoding} +string. If the bytes do not form a valid encoding, by default this +procedure raises an @code{decoding-error}. As with +@code{string->bytevector}, pass the optional @var{conversion-strategy} +argument to modify this behavior. @xref{Ports}, for more on character +encodings and conversion strategies. +@end deffn + +@deffn call-with-output-encoded-string encoding proc [conversion-strategy] +Like @code{call-with-output-string}, but instead of returning a string, +returns a encoding of the string according to @var{encoding}, as a +bytevector. This procedure can be more efficient than collecting a +string and then converting it via @code{string->bytevector}. +@end deffn + @node Conversion to/from C @subsubsection Conversion to/from C @@ -4172,9 +4243,9 @@ important. In C, a string is just a sequence of bytes, and the character encoding describes the relation between these bytes and the actual characters -that make up the string. For Scheme strings, character encoding is -not an issue (most of the time), since in Scheme you never get to see -the bytes, only the characters. +that make up the string. For Scheme strings, character encoding is not +an issue (most of the time), since in Scheme you usually treat strings +as character sequences, not byte sequences. Converting to C and converting from C each have their own challenges. @@ -4305,6 +4376,9 @@ into @var{encoding}. If @var{lenp} is @code{NULL}, this function will return a null-terminated C string. It will throw an error if the string contains a null character. + +The Scheme interface to this function is @code{string->bytevector}, from the +@code{ice-9 iconv} module. @xref{Representing Strings as Bytes}. @end deftypefn @deftypefn {C Function} SCM scm_from_stringn (const char *str, size_t len, const char *encoding, scm_t_string_failed_conversion_handler handler) @@ -4313,6 +4387,9 @@ length in bytes of the C string is input as @var{len}. The encoding of the C string is passed as the ASCII, null-terminated C string @code{encoding}. The @var{handler} parameters suggests a strategy for dealing with unconvertable characters. + +The Scheme interface to this function is @code{bytevector->string}. +@xref{Representing Strings as Bytes}. @end deftypefn The following conversion functions are provided as a convenience for the @@ -4810,6 +4887,7 @@ the host's native endianness. Bytevector contents can also be interpreted as Unicode strings encoded in one of the most commonly available encoding formats. +@xref{Representing Strings as Bytes}, for a more generic interface. @lisp (utf8->string (u8-list->bytevector '(99 97 102 101))) diff --git a/doc/ref/api-procedures.texi b/doc/ref/api-procedures.texi index d77a2bdcc..e749fdc98 100644 --- a/doc/ref/api-procedures.texi +++ b/doc/ref/api-procedures.texi @@ -274,7 +274,9 @@ sense at certain points in the program, delimited by these Return an association list describing the arguments that @var{program} accepts, or @code{#f} if the information cannot be obtained. -For example: +The alist keys that are currently defined are `required', `optional', +`keyword', `allow-other-keys?', and `rest'. For example: + @example (program-arguments-alist (lambda* (a b #:optional c #:key (d 1) #:rest e) @@ -285,17 +287,19 @@ For example: (allow-other-keys? . #f) (rest . d)) @end example +@end deffn -The alist keys that are currently defined are `required', `optional', -`keyword', `allow-other-keys?', and `rest'. +@deffn {Scheme Procedure} program-lambda-list program [ip] +Return a representation of the arguments of @var{program} as a lambda +list, or @code{#f} if this information is not available. -@deffnx {Scheme Procedure} program-lambda-list program [ip] -Accessors for a representation of the arguments of a program, with both -names and types (ie. either required, optional or keywords) +For example: -@code{program-arguments-alist} returns this information in the form of -an association list while @code{program-lambda-list} returns the same -information in a form similar to a lambda definition. +@example +(program-lambda-alist + (lambda* (a b #:optional c #:key (d 1) #:rest e) + #t)) @result{} +@end example @end deffn @node Optional Arguments diff --git a/doc/ref/web.texi b/doc/ref/web.texi index e892453e3..0f69089d0 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. -@c Copyright (C) 2010, 2011, 2012 Free Software Foundation, Inc. +@c Copyright (C) 2010, 2011, 2012, 2013 Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. @node Web @@ -1388,23 +1388,59 @@ the lower-level HTTP, request, and response modules. Return an open input/output port for a connection to URI. @end deffn -@deffn {Scheme Procedure} http-get uri [#:port=(open-socket-for-uri uri)] [#:version='(1 . 1)] [#:keep-alive?=#f] [#:extra-headers='()] [#:decode-body?=#t] -Connect to the server corresponding to @var{uri} and ask for the -resource, using the @code{GET} method. If you already have a port open, -pass it as @var{port}. The port will be closed at the end of the -request unless @var{keep-alive?} is true. Any extra headers in the -alist @var{extra-headers} will be added to the request. +@deffn {Scheme Procedure} http-get uri arg... +@deffnx {Scheme Procedure} http-head uri arg... +@deffnx {Scheme Procedure} http-post uri arg... +@deffnx {Scheme Procedure} http-put uri arg... +@deffnx {Scheme Procedure} http-delete uri arg... +@deffnx {Scheme Procedure} http-trace uri arg... +@deffnx {Scheme Procedure} http-options uri arg... + +Connect to the server corresponding to @var{uri} and make a request over +HTTP, using the appropriate method (@code{GET}, @code{HEAD}, etc.). + +All of these procedures have the same prototype: a URI followed by an +optional sequence of keyword arguments. These keyword arguments allow +you to modify the requests in various ways, for example attaching a body +to the request, or setting specific headers. The following table lists +the keyword arguments and their default values. + +@table @code +@item #:body #f +@item #:port (open-socket-for-uri @var{uri})] +@item #:version '(1 . 1) +@item #:keep-alive? #f +@item #:headers '() +@item #:decode-body? #t +@item #:streaming? #f +@end table + +If you already have a port open, pass it as @var{port}. Otherwise, a +connection will be opened to the server corresponding to @var{uri}. Any +extra headers in the alist @var{headers} will be added to the request. + +If @var{body} is not #f, a message body will also be sent with the HTTP +request. If @var{body} is a string, it is encoded according to the +content-type in @var{headers}, defaulting to UTF-8. Otherwise +@var{body} should be a bytevector, or @code{#f} for no body. Although a +message body may be sent with any request, usually only @code{POST} and +@code{PUT} requests have bodies. If @var{decode-body?} is true, as is the default, the body of the response will be decoded to string, if it is a textual content-type. Otherwise it will be returned as a bytevector. -@end deffn -@deffn {Scheme Procedure} http-get* uri [#:port=(open-socket-for-uri uri)] [#:version='(1 . 1)] [#:keep-alive?=#f] [#:extra-headers='()] [#:decode-body?=#t] -Like @code{http-get}, but return an input port from which to read. When -@var{decode-body?} is true, as is the default, the returned port has its -encoding set appropriately if the data at @var{uri} is textual. Closing the -returned port closes @var{port}, unless @var{keep-alive?} is true. +However, if @var{streaming?} is true, instead of eagerly reading the +response body from the server, this function only reads off the headers. +The response body will be returned as a port on which the data may be +read. + +Unless @var{keep-alive?} is true, the port will be closed after the full +response body has been read. + +Returns two values: the response read from the server, and the response +body as a string, bytevector, #f value, or as a port (if +@var{streaming?} is true). @end deffn @code{http-get} is useful for making one-off requests to web sites. If @@ -1415,10 +1451,6 @@ fetcher, similar in structure to the web server (@pxref{Web Server}). Another option, good but not as performant, would be to use threads, possibly via par-map or futures. -More helper procedures for the other common HTTP verbs would be a good -addition to this module. Send your code to -@email{guile-user@@gnu.org}. - @node Web Server @subsection Web Server |