suzanne.soy/racket
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

A ton of @scheme*' -> @racket*' and related updates.

Browse Source 
Also, updates some of the mzlib files to point at `racket/*' libraries
rather than to `scheme/*' ones.

original commit: ac26fe7554
This commit is contained in:
Eli Barzilay 2011-06-24 15:08:24 -04:00
parent a8092eea36
commit 333c1506a9
21 changed files with 488 additions and 484 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
collects/net/scribblings/base64.scrbl
View File

@ -3,7 +3,7 @@
@title[#:tag "base64"]{Base 64: Encoding and Decoding}
@defmodule[net/base64]{The @schememodname[net/base64] library provides
@defmodule[net/base64]{The @racketmodname[net/base64] library provides
utilities for Base 64 (mime-standard) encoding and decoding.}
@section[#:tag "base64-procs"]{Functions}
@ -27,20 +27,20 @@ string.}
[newline-bstr bytes? #"\n"])
void?]{
Reads bytes from @scheme[in] and writes the encoded result to
@scheme[out], breaking the output into 72-character lines separated by
@scheme[newline-bstr], and ending with @scheme[newline-bstr] unless
the input stream is empty. Note that the default @scheme[newline-bstr]
is just @scheme[#"\n"], not @scheme[#"\r\n"]. The procedure returns when
it encounters an end-of-file from @scheme[in].}
Reads bytes from @racket[in] and writes the encoded result to
@racket[out], breaking the output into 72-character lines separated by
@racket[newline-bstr], and ending with @racket[newline-bstr] unless
the input stream is empty. Note that the default @racket[newline-bstr]
is just @racket[#"\n"], not @racket[#"\r\n"]. The procedure returns when
it encounters an end-of-file from @racket[in].}
@defproc[(base64-decode-stream [in input-port?]
[out output-port?])
void?]{
Reads a Base 64 encoding from @scheme[in] and writes the decoded
result to @scheme[out]. The procedure returns when it encounters an
end-of-file or Base 64 terminator @litchar{=} from @scheme[in].}
Reads a Base 64 encoding from @racket[in] and writes the decoded
result to @racket[out]. The procedure returns when it encounters an
end-of-file or Base 64 terminator @litchar{=} from @racket[in].}
@; ----------------------------------------
@ -50,7 +50,7 @@ end-of-file or Base 64 terminator @litchar{=} from @scheme[in].}
@defthing[base64@ unit?]{
Imports nothing, exports @scheme[base64^].}
Imports nothing, exports @racket[base64^].}
@; ----------------------------------------
@ -60,4 +60,4 @@ Imports nothing, exports @scheme[base64^].}
@defsignature[base64^ ()]{}
Includes everything exported by the @schememodname[net/base64] module.
Includes everything exported by the @racketmodname[net/base64] module.

30
collects/net/scribblings/cgi.scrbl
View File

@ -4,10 +4,10 @@
@title[#:tag "cgi"]{CGI Scripts}
@defmodule[net/cgi]{The @schememodname[net/cgi] module provides tools
@defmodule[net/cgi]{The @racketmodname[net/cgi] module provides tools
for scripts that follow the Common Gateway Interface @cite["CGI"].}
The @schememodname[net/cgi] library expects to be run in a certain
The @racketmodname[net/cgi] library expects to be run in a certain
context as defined by the CGI standard. This means, for instance,
that certain environment variables will be bound.
@ -18,7 +18,7 @@ bind @envvar{REQUEST_METHOD} and possibly also @envvar{QUERY_STRING}
to successfully employ the CGI library. The FastCGI library ought to
provide a way to extract the values bound to these variables; the user
can then put these into the CGI program's environment using the
@scheme[putenv] function.
@racket[putenv] function.
A CGI @deftech{binding} is an association of a form item with its
value. Some form items, such as checkboxes, may correspond to
@ -36,12 +36,12 @@ symbol or a string.
)]{
Returns the bindings that corresponding to the options specified by
the user. The @scheme[get-bindings/post] and
@scheme[get-bindings/get] variants work only when POST and GET forms
are used, respectively, while @scheme[get-bindings] determines the
the user. The @racket[get-bindings/post] and
@racket[get-bindings/get] variants work only when POST and GET forms
are used, respectively, while @racket[get-bindings] determines the
kind of form that was used and invokes the appropriate function.
These functions respect @scheme[current-alist-separator-mode].
These functions respect @racket[current-alist-separator-mode].
}
@ -58,15 +58,15 @@ key.}
[bindings (listof (cons/c (or/c symbol? string?) string?))])
string?]{
Like @scheme[extract-bindings], but for a key that has exactly one
Like @racket[extract-bindings], but for a key that has exactly one
association.}
@defproc[(output-http-headers) void?]{
Outputs all the HTTP headers needed for a normal response. Only
call this function if you are not using @scheme[generate-html-output] or
@scheme[generate-error-output].}
call this function if you are not using @racket[generate-html-output] or
@racket[generate-error-output].}
@defproc[(generate-html-output [title string?]
@ -101,12 +101,12 @@ text, and generates HTML corresponding to an anchor.}
The procedure takes a list of HTML strings representing the body,
prints them with the subject line "Internal error", and exits via
@scheme[exit].}
@racket[exit].}
@defproc[(get-cgi-method) (one-of/c "GET" "POST")]{
Returns either @scheme["GET"] or @scheme["POST"] when invoked inside a
Returns either @racket["GET"] or @racket["POST"] when invoked inside a
CGI script, unpredictable otherwise.}
@ -119,7 +119,7 @@ useful for debugging.}
@defstruct[cgi-error ()]{
A supertype for all exceptions thrown by the @schememodname[net/cgi]
A supertype for all exceptions thrown by the @racketmodname[net/cgi]
library.}
@ -144,7 +144,7 @@ query is invalid.}
@defthing[cgi@ unit?]{
Imports nothing, exports @scheme[cgi^].}
Imports nothing, exports @racket[cgi^].}
@; ----------------------------------------
@ -154,4 +154,4 @@ Imports nothing, exports @scheme[cgi^].}
@defsignature[cgi^ ()]{}
Includes everything exported by the @schememodname[net/cgi] module.
Includes everything exported by the @racketmodname[net/cgi] module.

78
collects/net/scribblings/cookie.scrbl
View File

@ -8,27 +8,31 @@
@title[#:tag "cookie"]{Cookie: HTTP Client Storage}
@defmodule[net/cookie]{The @schememodname[net/cookie] library provides
@defmodule[net/cookie]{The @racketmodname[net/cookie] library provides
utilities for using cookies as specified in RFC 2109 @cite["RFC2109"].}
@section[#:tag "cookie-procs"]{Functions}
@defproc[(cookie? [v any/c]) boolean?]{
Returns @scheme[#t] if @scheme[v] represents a cookie, @scheme[#f]
otherwise.}
Returns @racket[#t] if @racket[v] represents a cookie, @racket[#f]
otherwise.
}
@defproc[(valid-domain? [v any/c]) boolean?]{
Returns @scheme[#t] if @scheme[v] represents a valid domain, @scheme[#f] otherwise.
Returns @racket[#t] if @racket[v] represents a valid domain,
@racket[#f] otherwise.
}
@defproc[(cookie-name? [v any/c]) boolean?]{
Returns @scheme[#t] if @scheme[v] is a valid cookie name string, @scheme[#f] otherwise.
}
Returns @racket[#t] if @racket[v] is a valid cookie name string,
@racket[#f] otherwise.
}
@defproc[(cookie-value? [v any/c]) boolean?]{
Returns @scheme[#t] if @scheme[v] is a valid cookie value string, @scheme[#f] otherwise.
}
Returns @racket[#t] if @racket[v] is a valid cookie value string,
@racket[#f] otherwise.
}
@defproc[(set-cookie [name cookie-name?] [value cookie-value?]) cookie?]{
@ -37,64 +41,64 @@ Creates a new cookie, with default values for required fields.}
@defproc[(cookie:add-comment [cookie cookie?] [comment string?])
cookie?]{
Modifies @scheme[cookie] with a comment, and also returns
@scheme[cookie].}
Modifies @racket[cookie] with a comment, and also returns
@racket[cookie].}
@defproc[(cookie:add-domain [cookie cookie?] [domain valid-domain?])
cookie?]{
Modifies @scheme[cookie] with a domain, and also returns
@scheme[cookie]. The @scheme[domain] must match a prefix of the
Modifies @racket[cookie] with a domain, and also returns
@racket[cookie]. The @racket[domain] must match a prefix of the
request URI.}
@defproc[(cookie:add-max-age [cookie cookie?] [seconds exact-nonnegative-integer?])
cookie?]{
Modifies @scheme[cookie] with a maximum age, and also returns
@scheme[cookie]. The @scheme[seconds] argument is number of seconds
Modifies @racket[cookie] with a maximum age, and also returns
@racket[cookie]. The @racket[seconds] argument is number of seconds
that a client should retain the cookie.}
@defproc[(cookie:add-path [cookie cookie?] [path valid-path?])
cookie?]{
Modifies @scheme[cookie] with a path, and also returns
@scheme[cookie].}
Modifies @racket[cookie] with a path, and also returns
@racket[cookie].}
@defproc[(cookie:secure [cookie cookie?] [secure boolean?])
cookie?]{
Modifies @scheme[cookie] with a security flag, and also returns
@scheme[cookie].}
Modifies @racket[cookie] with a security flag, and also returns
@racket[cookie].}
@defproc[(cookie:version [cookie cookie?] [version exact-nonnegative-integer?])
cookie?]{
Modifies @scheme[cookie] with a version, and also returns
@scheme[cookie]. The default is the only known incarnation of HTTP
cookies: @scheme[1].}
Modifies @racket[cookie] with a version, and also returns
@racket[cookie]. The default is the only known incarnation of HTTP
cookies: @racket[1].}
@defproc[(print-cookie [cookie cookie?]) string?]{
Prints @scheme[cookie] to a string. Empty fields do not appear in the
Prints @racket[cookie] to a string. Empty fields do not appear in the
output except when there is a required default.}
@defproc[(get-cookie [name cookie-name?] [cookies string?]) (listof cookie-value?)]{
Returns a list with all the values (strings) associated with @scheme[name].
Returns a list with all the values (strings) associated with @racket[name].
The method used to obtain the @scheme["Cookie"] header depends on the
The method used to obtain the @racket["Cookie"] header depends on the
web server. It may be an environment variable (CGI), or you may have
to read it from the input port (FastCGI), or maybe it comes in an
initial-request structure, etc. The @scheme[get-cookie] and
@scheme[get-cookie/single] procedure can be used to extract fields
from a @scheme["Cookie"] field value.}
initial-request structure, etc. The @racket[get-cookie] and
@racket[get-cookie/single] procedure can be used to extract fields
from a @racket["Cookie"] field value.}
@defproc[(get-cookie/single [name cookie-name?] [cookies string?]) (or/c cookie-value? false/c)]{
Like @scheme[get-cookie], but returns the just first value string
associated to @scheme[name], or #f if no association is found.}
Like @racket[get-cookie], but returns the just first value string
associated to @racket[name], or #f if no association is found.}
@defstruct[(cookie-error exn:fail) ()]{
@ -105,7 +109,7 @@ Raised for errors when handling cookies.}
@subsection{Creating a cookie}
@schemeblock[
@racketblock[
(let ((c (cookie:add-max-age
(cookie:add-path
(set-cookie "foo" "bar")
@ -116,19 +120,19 @@ Raised for errors when handling cookies.}
Produces
@schemeblock[
@#,schemeresultfont{"foo=bar; Max-Age=3600; Path=/servlets; Version=1"}
@racketblock[
@#,racketresultfont{"foo=bar; Max-Age=3600; Path=/servlets; Version=1"}
]
To use this output in a ``regular'' CGI, instead of the last line use:
@schemeblock[
@racketblock[
(display (format "Set-Cookie: ~a" (print-cookie c)))
]
and to use with the PLT Web Server, use:
@schemeblock[
@racketblock[
(make-response/full code message (current-seconds) mime
(list (make-header #"Set-Cookie" (string->bytes/utf-8 (print-cookie c))))
body)
@ -172,7 +176,7 @@ won't have a cookie set then first arrive at your site.
@defthing[cookie@ unit?]{
Imports nothing, exports @scheme[cookie^].}
Imports nothing, exports @racket[cookie^].}
@; ----------------------------------------
@ -182,4 +186,4 @@ Imports nothing, exports @scheme[cookie^].}
@defsignature[cookie^ ()]{}
Includes everything exported by the @schememodname[net/cookie] module.
Includes everything exported by the @racketmodname[net/cookie] module.

14
collects/net/scribblings/dns.scrbl
View File

@ -3,7 +3,7 @@
@title[#:tag "dns"]{DNS: Domain Name Service Queries}
@defmodule[net/dns]{The @schememodname[net/dns] library provides
@defmodule[net/dns]{The @racketmodname[net/dns] library provides
utilities for looking up hostnames.
Thanks to Eduardo Cavazos and Jason Crowe for repairs and
@ -18,11 +18,11 @@ improvements.}
string?]{
Consults the specified nameserver (normally a numerical address like
@scheme["128.42.1.30"]) to obtain a numerical address for the given
@racket["128.42.1.30"]) to obtain a numerical address for the given
Internet address.
The query record sent to the DNS server includes the "recursive" bit,
but @scheme[dns-get-address] also implements a recursive search itself
but @racket[dns-get-address] also implements a recursive search itself
in case the server does not provide this optional feature.}
@ -31,7 +31,7 @@ in case the server does not provide this optional feature.}
string?]{
Consults the specified nameserver (normally a numerical address like
@scheme["128.42.1.30"]) to obtain a name for the given numerical
@racket["128.42.1.30"]) to obtain a name for the given numerical
address.}
@ -41,7 +41,7 @@ address.}
Consults the specified nameserver to obtain the address for a mail
exchanger the given mail host address. For example, the mail exchanger
for @scheme["ollie.cs.rice.edu"] might be @scheme["cs.rice.edu"].}
for @racket["ollie.cs.rice.edu"] might be @racket["cs.rice.edu"].}
@ -60,7 +60,7 @@ extract the first nameserver address. On Windows, it runs
@defthing[dns@ unit?]{
Imports nothing, exports @scheme[dns^].}
Imports nothing, exports @racket[dns^].}
@; ----------------------------------------
@ -70,4 +70,4 @@ Imports nothing, exports @scheme[dns^].}
@defsignature[dns^ ()]{}
Includes everything exported by the @schememodname[net/dns] module.
Includes everything exported by the @racketmodname[net/dns] module.

28
collects/net/scribblings/ftp.scrbl
View File

@ -3,7 +3,7 @@
@title[#:tag "ftp"]{FTP: Client Downloading}
@defmodule[net/ftp]{The @schememodname[net/ftp] library provides
@defmodule[net/ftp]{The @racketmodname[net/ftp] library provides
utilities for FTP client operations.
The library was written by Micah Flatt.}
@ -12,8 +12,8 @@ The library was written by Micah Flatt.}
@defproc[(ftp-connection? [v any/c]) boolean?]{
Returns @scheme[#t] if @scheme[v] represents an FTP connection as
returned by @scheme[ftp-establish-connection], @scheme[#f] otherwise.}
Returns @racket[#t] if @racket[v] represents an FTP connection as
returned by @racket[ftp-establish-connection], @racket[#f] otherwise.}
@defproc[(ftp-establish-connection [server string?]
@ -36,8 +36,8 @@ Closes an FTP connection.}
@defproc[(ftp-cd [ftp-conn ftp-connection?][new-dir string?]) void?]{
Changes the current directory on the FTP server to @scheme[new-dir].
The @scheme[new-dir] argument is not interpreted at all, but simply
Changes the current directory on the FTP server to @racket[new-dir].
The @racket[new-dir] argument is not interpreted at all, but simply
passed on to the server (encoded using the current locale's
encoding); it must not contain a newline.}
@ -51,11 +51,11 @@ the server, assuming that the server provides directory information in
the quasi-standard Unix format.
Each file or directory is represented by a list of three strings. The
first string is either @scheme["-"], @scheme["d"], or @scheme["l"],
first string is either @racket["-"], @racket["d"], or @racket["l"],
depending on whether the items is a file, directory, or link,
respectively. The second item is the file's date; to convert this
value to seconds consistent with @scheme[file-seconds], pass the date
string to @scheme[ftp-make-file-seconds], below. The third string is
value to seconds consistent with @racket[file-seconds], pass the date
string to @racket[ftp-make-file-seconds], below. The third string is
the name of the file or directory.
All strings are decoded from bytes using the current locale's
@ -64,17 +64,17 @@ encoding.}
@defproc[(ftp-make-file-seconds [ftp-date string?]) exact-integer?]{
Takes a date string produced by @scheme[ftp-directory-list] and
Takes a date string produced by @racket[ftp-directory-list] and
converts it to seconds (which can be used with
@scheme[seconds->date]).}
@racket[seconds->date]).}
@defproc[(ftp-download-file [ftp-conn ftp-connection?]
[local-dir path-string?]
[file string?]) void?]{
Downloads @scheme[file] from the server's current directory and puts
it in @scheme[local-dir] using the same name. If the file already
Downloads @racket[file] from the server's current directory and puts
it in @racket[local-dir] using the same name. If the file already
exists in the local directory, it is replaced, but only after the
transfer succeeds (i.e., the file is first downloaded to a temporary
file, then moved into place on success).}
@ -87,7 +87,7 @@ file, then moved into place on success).}
@defthing[ftp@ unit?]{
Imports nothing, exports @scheme[ftp^].}
Imports nothing, exports @racket[ftp^].}
@; ----------------------------------------
@ -97,4 +97,4 @@ Imports nothing, exports @scheme[ftp^].}
@defsignature[ftp^ ()]{}
Includes everything exported by the @schememodname[net/ftp] module.
Includes everything exported by the @racketmodname[net/ftp] module.

62
collects/net/scribblings/head.scrbl
View File

@ -7,7 +7,7 @@
@title[#:tag "head"]{Headers: Parsing and Constructing}
@defmodule[net/head]{The @schememodname[net/head] module provides
@defmodule[net/head]{The @racketmodname[net/head] module provides
utilities for parsing and constructing RFC 822 headers
@cite["RFC822"], which are used in protocols such as HTTP, SMTP, and
NNTP.}
@ -24,29 +24,29 @@ terminates the header).
@defthing[empty-header string?]{
The string @scheme["\r\n\r\n"], which corresponds to the empty header.
The string @racket["\r\n\r\n"], which corresponds to the empty header.
This value is useful for building up headers with
@scheme[insert-field] and @scheme[append-headers].}
@racket[insert-field] and @racket[append-headers].}
@defproc[(validate-header [candidate (or string? bytes?)]) void?]{
Checks that @scheme[candidate] matches RFC 822. If it does not, an
Checks that @racket[candidate] matches RFC 822. If it does not, an
exception is raised.}
@defproc[(extract-field [field (or/c string? bytes?)] [header (or/c string? bytes?)])
(or/c string? bytes? false/c)]{
Returns the header content for the specified field, or @scheme[#f] if
the field is not in the header. The @scheme[field] string should not
end with @scheme[":"], and it is used case-insensitively. The returned
Returns the header content for the specified field, or @racket[#f] if
the field is not in the header. The @racket[field] string should not
end with @racket[":"], and it is used case-insensitively. The returned
string will not contain the field name, color separator, or CRLF
terminator for the field; however, if the field spans multiple lines,
the CRLFs separating the lines will be intact.
The @scheme[field] and @scheme[header] arguments must be both strings
or both byte strings, and the result (if not @scheme[#f]) is of the
The @racket[field] and @racket[header] arguments must be both strings
or both byte strings, and the result (if not @racket[#f]) is of the
same type.
@examples[
@ -63,8 +63,8 @@ Returns an association-list version of the header; the case of the
field names is preserved, as well as the order and duplicate uses of a
field name.
The result provides strings if @scheme[header] is a string, byte
strings if @scheme[header] is a byte string.}
The result provides strings if @racket[header] is a string, byte
strings if @racket[header] is a byte string.}
@defproc[(remove-field [field (or/c string? bytes?)]
@ -72,11 +72,11 @@ strings if @scheme[header] is a byte string.}
(or/c string? bytes?)]{
Creates a new header by removing the specified field from
@scheme[header] (or the first instance of the field, if it occurs
multiple times). If the field is not in @scheme[header], then the
return value is @scheme[header].
@racket[header] (or the first instance of the field, if it occurs
multiple times). If the field is not in @racket[header], then the
return value is @racket[header].
The @scheme[field] and @scheme[header] arguments must be both strings
The @racket[field] and @racket[header] arguments must be both strings
or both byte strings, and the result is of the same type.}
@ -85,12 +85,12 @@ or both byte strings, and the result is of the same type.}
[header (or/c string? bytes?)])
(or/c string? bytes?)]{
Creates a new header by prefixing the given @scheme[header] with the
given @scheme[field]-@scheme[value] pair. The @scheme[value] string
Creates a new header by prefixing the given @racket[header] with the
given @racket[field]-@racket[value] pair. The @racket[value] string
should not contain a terminating CRLF, but a multi-line value (perhaps
created with @scheme[data-lines->data]) may contain separator CRLFs.
created with @racket[data-lines->data]) may contain separator CRLFs.
The @scheme[field], @scheme[value], and @scheme[header] arguments must
The @racket[field], @racket[value], and @racket[header] arguments must
be all strings or all byte strings, and the result is of the same
type.}
@ -100,8 +100,8 @@ type.}
[header (or/c string? bytes?)])
(or/c string? bytes?)]{
Composes @scheme[remove-field] and (if @scheme[value] is not
@scheme[#f]) @scheme[insert-field].}
Composes @racket[remove-field] and (if @racket[value] is not
@racket[#f]) @racket[insert-field].}
@defproc[(append-headers [header1 (or/c string? bytes?)]
[header2 (or/c string? bytes?)])
@ -109,7 +109,7 @@ Composes @scheme[remove-field] and (if @scheme[value] is not
Appends two headers.
The @scheme[header1] and @scheme[header2] arguments must be both
The @racket[header1] and @racket[header2] arguments must be both
strings or both byte strings, and the result is of the same type.}
@ -121,7 +121,7 @@ strings or both byte strings, and the result is of the same type.}
string?]{
Creates a standard mail header given the sender, various lists of
recipients, a subject. A @scheme["Date"] field is added to the header
recipients, a subject. A @racket["Date"] field is added to the header
automatically, using the current time.
The BCC recipients do not actually appear in the header, but they're
@ -140,17 +140,17 @@ adding CRLF-TAB separators.}
(or/c (listof string?)
(listof (list/c string? string? string?)))]{
Parses @scheme[string] as a list of comma-delimited mail addresses,
Parses @racket[string] as a list of comma-delimited mail addresses,
raising an exception if the list is ill-formed. This procedure can be
used for single-address strings, in which case the returned list
contains only one address.
The @scheme[kind] argument specifies which portion of an address
The @racket[kind] argument specifies which portion of an address
should be returned:
@itemize[
@item{@scheme['name] --- the free-form name in the address, or the
@item{@racket['name] --- the free-form name in the address, or the
address itself if no name is available.
@examples[
@ -162,7 +162,7 @@ should be returned:
'name)
]}
@item{@scheme['address] --- just the mailing address, without any free-form
@item{@racket['address] --- just the mailing address, without any free-form
names.
@examples[
@ -174,7 +174,7 @@ should be returned:
'address)
]}
@item{@scheme['full] --- the full address, essentially as it appears in the
@item{@racket['full] --- the full address, essentially as it appears in the
input, but normalized.
@examples[
@ -186,7 +186,7 @@ should be returned:
'full)
]}
@item{@scheme['all] --- a list containing each of the three possibilities:
@item{@racket['all] --- a list containing each of the three possibilities:
free-form name, address, and full address (in that
order).
@ -226,7 +226,7 @@ are comma-separated, and possibly broken into multiple lines.
@defthing[head@ unit?]{
Imports nothing, exports @scheme[head^].}
Imports nothing, exports @racket[head^].}
@; ----------------------------------------
@ -236,4 +236,4 @@ Imports nothing, exports @scheme[head^].}
@defsignature[head^ ()]{}
Includes everything exported by the @schememodname[net/head] module.
Includes everything exported by the @racketmodname[net/head] module.

148
collects/net/scribblings/imap.scrbl
View File

@ -39,7 +39,7 @@
@title[#:tag "imap"]{IMAP: Reading Mail}
@defmodule[net/imap]{The @schememodname[net/imap] module provides
@defmodule[net/imap]{The @racketmodname[net/imap] module provides
utilities for the client side of Internet Message Access Protocol
version 4rev1 @cite["RFC2060"].}
@ -49,8 +49,8 @@ version 4rev1 @cite["RFC2060"].}
@defproc[(imap-connection? [v any/c]) boolean?]{
Return @scheme[#t] if @scheme[v] is a IMAP-connection value (which is
opaque), @scheme[#f] otherwise.}
Return @racket[#t] if @racket[v] is a IMAP-connection value (which is
opaque), @racket[#f] otherwise.}
@defproc[(imap-connect [server string?]
[username (or/c string? bytes?)]
@ -66,21 +66,21 @@ The second and third return values indicate the total number of
messages in the mailbox and the number of recent messages (i.e.,
messages received since the mailbox was last selected), respectively.
See also @scheme[imap-port-number].
See also @racket[imap-port-number].
A user's primary mailbox is always called
@scheme["INBOX"]. (Capitalization doesn't matter for that mailbox
@racket["INBOX"]. (Capitalization doesn't matter for that mailbox
name.)
Updated message-count and recent-count values are available through
@scheme[imap-messages] and @scheme[imap-recent]. See also @scheme[imap-new?] and
@scheme[imap-reset-new!].}
@racket[imap-messages] and @racket[imap-recent]. See also @racket[imap-new?] and
@racket[imap-reset-new!].}
@defparam[imap-port-number k (integer-in 0 65535)]{
A parameter that determines the server port number. The initial value
is @scheme[143].}
is @racket[143].}
@defproc[(imap-connect* [in input-port?]
@ -90,7 +90,7 @@ is @scheme[143].}
[mailbox (or/c string? bytes?)])
(values imap-connection? exact-nonnegative-integer? exact-nonnegative-integer?)]{
Like @scheme[imap-connect], but given input and output ports (e.g.,
Like @racket[imap-connect], but given input and output ports (e.g.,
ports for an SSL session) instead of a server address.}
@ -116,15 +116,15 @@ counts for the new mailbox. Expunge and message-state information is
removed.
Do not use this procedure to poll a mailbox to see whether there are
any new messages. Use @scheme[imap-noop], @scheme[imap-new?], and
@scheme[imap-reset-new!] instead.}
any new messages. Use @racket[imap-noop], @racket[imap-new?], and
@racket[imap-reset-new!] instead.}
@defproc[(imap-examine [imap imap-connection?]
[mailbox (or/c string? bytes?)])
(values exact-nonnegative-integer? exact-nonnegative-integer?)]{
Like @scheme[imap-reselect], but the mailbox is selected as read-only.}
Like @racket[imap-reselect], but the mailbox is selected as read-only.}
@; ----------------------------------------
@ -135,9 +135,9 @@ Like @scheme[imap-reselect], but the mailbox is selected as read-only.}
Sends a ``no-op'' message to the server, typically to keep the session
alive. As for many commands, the server may report message-state
updates or expunges, which are recorded in @scheme[imap].
updates or expunges, which are recorded in @racket[imap].
The return information is the same as for @scheme[imap-reselect].}
The return information is the same as for @racket[imap-reselect].}
@defproc[(imap-poll [imap imap-connection?]) void?]{
@ -169,7 +169,7 @@ update this count during most any interaction.
Returns the number of ``unseen'' messages in the currently selected
mailbox, as most recently reported by the server. The server can
update this count during most any interaction. Old IMAP servers might
not report this value, in which case the result is @scheme[#f].
not report this value, in which case the result is @racket[#f].
@just-report[]}
@ -179,7 +179,7 @@ not report this value, in which case the result is @scheme[#f].
Returns the predicted next uid for a message in the currently selected
mailbox, as most recently reported by the server. The server can
update this count during most any interaction. Old IMAP servers might
not report this value, in which case the result is @scheme[#f].
not report this value, in which case the result is @racket[#f].
@just-report[]}
@ -189,24 +189,24 @@ not report this value, in which case the result is @scheme[#f].
Returns an id number that changes when all uids become invalid. The
server @emph{cannot} update this number during a session. Old IMAP
servers might not report this value, in which case the result is
@scheme[#f].
@racket[#f].
@just-report[]}
@defproc[(imap-new? [imap imap-connection?]) boolean?]{
Returns @scheme[#t] if the server has reported an increase in the
Returns @racket[#t] if the server has reported an increase in the
message count for the currently mailbox since the last call to
@scheme[imap-reset-new!]. Selecting a mailbox implicitly calls
@scheme[imap-reset-new!].
@racket[imap-reset-new!]. Selecting a mailbox implicitly calls
@racket[imap-reset-new!].
@just-report[]}
@defproc[(imap-reset-new! [imap imap-connection?]) void?]{
Resets the new flag for the session; see @scheme[imap-new?].
Resets the new flag for the session; see @racket[imap-new?].
This operation does not communicate with the server.}
@ -220,25 +220,25 @@ pending notifications. The result list is sorted, ascending.
The server can notify the client of newly deleted messages during most
other commands, but not asynchronously between commands. Furthermore,
the server cannot report new deletions during @scheme[imap-get-messages] or
@scheme[imap-store] operations.
the server cannot report new deletions during @racket[imap-get-messages] or
@racket[imap-store] operations.
Before calling any IMAP operation that works in terms of message
numbers, pending expunge notifications must be handled by calling
@scheme[imap-get-expunges].}
@racket[imap-get-expunges].}
@defproc[(imap-pending-expunges? [imap imap-connection?]) boolean?]{
Returns @scheme[#f] if @scheme[imap-get-expunges] would return an
empty list, @scheme[#t] otherwise.}
Returns @racket[#f] if @racket[imap-get-expunges] would return an
empty list, @racket[#t] otherwise.}
@defproc[(imap-get-updates [imap imap-connection?])
(listof (cons/c exact-nonnegative-integer?
(listof pair?)))]{
Returns information must like @scheme[imap-get-messages], but includes
Returns information must like @racket[imap-get-messages], but includes
information reported asynchronously by the server (e.g., to notify a
client with some other client changes a message attribute). Instead
of reporting specific requested information for specific messages, the
@ -251,18 +251,18 @@ connection after reporting it.
When a server reports information that supersedes old reported
information for a message, or if the server reports that a message has
been deleted, then old information for the message is
dropped. Similarly, if @scheme[imap-get-messages] is used to
dropped. Similarly, if @racket[imap-get-messages] is used to
explicitly obtain information, any redundant (or out-of-date)
information is dropped.
A client need not use @scheme[imap-get-updates] ever, but accumulated
A client need not use @racket[imap-get-updates] ever, but accumulated
information for the connection consumes space.}
@defproc[(imap-pending-updates? [imap imap-connection?]) boolean?]{
Returns @scheme[#f] if @scheme[imap-get-updates] would return an
list, @scheme[#t] otherwise.}
Returns @racket[#f] if @racket[imap-get-updates] would return an
list, @racket[#t] otherwise.}
@; ----------------------------------------
@ -277,32 +277,32 @@ list, @scheme[#t] otherwise.}
'flags))])
(listof list?)]{
Downloads information for a set of messages. The @scheme[msg-nums]
Downloads information for a set of messages. The @racket[msg-nums]
argument specifies a set of messages by their message positions (not
their uids). The @scheme[fields] argument specifies the type of
their uids). The @racket[fields] argument specifies the type of
information to download for each message. The available fields are:
@itemize[
@item{@scheme['uid] --- the value is an integer}
@item{@racket['uid] --- the value is an integer}
@item{@scheme['header] --- the value is a header (a string, but see
@schememodname[net/head])}
@item{@racket['header] --- the value is a header (a string, but see
@racketmodname[net/head])}
@item{@scheme['body] --- the value is a byte string, with
@item{@racket['body] --- the value is a byte string, with
CRLF-separated lines}
@item{@scheme['flags] --- the value is a list of symbols that
correspond to IMAP flags; see @scheme[imap-flag->symbol]}
@item{@racket['flags] --- the value is a list of symbols that
correspond to IMAP flags; see @racket[imap-flag->symbol]}
]
The return value is a list of entry items in parallel to
@scheme[msg-nums]. Each entry is itself a list containing value items
in parallel to @scheme[fields].
@racket[msg-nums]. Each entry is itself a list containing value items
in parallel to @racket[fields].
Pending expunges must be handled before calling this function; see
@scheme[imap-get-expunges].
@racket[imap-get-expunges].
@examples[
(eval:alts (imap-get-message imap '(1 3 5) '(uid header))
@ -318,8 +318,8 @@ Pending expunges must be handled before calling this function; see
An IMAP flag is a symbol, but it is generally not a convenient one to
use within a Scheme program, because it usually starts with a
backslash. The @scheme[imap-flag->symbol] and
@scheme[symbol->imap-flag] procedures convert IMAP flags to convenient
backslash. The @racket[imap-flag->symbol] and
@racket[symbol->imap-flag] procedures convert IMAP flags to convenient
symbols and vice-versa:
@flag-table[
@ -341,7 +341,7 @@ symbols and vice-versa:
)
]
The @scheme[imap-flag->symbol] and @scheme[symbol->imap-flag]
The @racket[imap-flag->symbol] and @racket[symbol->imap-flag]
functions act like the identity function when any other symbol is
provided.}
@ -357,22 +357,22 @@ flags are set:
@itemize[
@item{@scheme['+] --- add the given flags to each message}
@item{@racket['+] --- add the given flags to each message}
@item{@scheme['-] --- remove the given flags from each message}
@item{@racket['-] --- remove the given flags from each message}
@item{@scheme['!] --- set each message's flags to the given set}
@item{@racket['!] --- set each message's flags to the given set}
]
The @scheme[msg-nums] argument specifies a set of messages by their
message positions (not their uids). The @scheme[flags] argument
The @racket[msg-nums] argument specifies a set of messages by their
message positions (not their uids). The @racket[flags] argument
specifies the imap flags to add/remove/install.
Pending expunges must be handled before calling this function; see
@scheme[imap-get-expunges]. The server will not report back
@racket[imap-get-expunges]. The server will not report back
message-state changes (so they will not show up through
@scheme[imap-get-updates]).
@racket[imap-get-updates]).
@examples[
(eval:alts (imap-store imap '+ '(1 2 3) (list (symbol->imap-flag 'deleted)))
@ -386,7 +386,7 @@ message-state changes (so they will not show up through
@defproc[(imap-expunge [imap imap-connection?]) void?]{
Purges every message currently marked with the @scheme['|\Deleted|]
Purges every message currently marked with the @racket['|\Deleted|]
flag from the mailbox.}
@; ----------------------------------------
@ -402,7 +402,7 @@ Copies the specified messages from the currently selected mailbox to
the specified mailbox.
Pending expunges must be handled before calling this function; see
@scheme[imap-get-expunges].}
@racket[imap-get-expunges].}
@defproc[(imap-append [imap imap-connection?]
@ -410,7 +410,7 @@ Pending expunges must be handled before calling this function; see
[message (or/c string? bytes?)])
void?]{
Adds a new message (containing @scheme[message]) to the given
Adds a new message (containing @racket[message]) to the given
mailbox.}
@ -418,27 +418,27 @@ mailbox.}
[mailbox (or/c string? bytes?)]
[statuses (listof symbol?)])
list?]{
Requests information about a mailbox from the server, typically
@emph{not} the currently selected mailbox.
The @scheme[statuses] list specifies the request, and the return value
includes one value for each symbol in @scheme[statuses]. The allowed
The @racket[statuses] list specifies the request, and the return value
includes one value for each symbol in @racket[statuses]. The allowed
status symbols are:
@itemize[
@item{@scheme['messages] --- number of messages}
@item{@scheme['recent] --- number of recent messages}
@item{@scheme['unseen] --- number of unseen messages}
@item{@scheme['uidnext] --- uid for next received message}
@item{@scheme['uidvalidity] --- id that changes when all uids are changed}
@item{@racket['messages] --- number of messages}
@item{@racket['recent] --- number of recent messages}
@item{@racket['unseen] --- number of unseen messages}
@item{@racket['uidnext] --- uid for next received message}
@item{@racket['uidvalidity] --- id that changes when all uids are changed}
]
Use @scheme[imap-messages] to get the message count for the currently
selected mailbox, etc. Use @scheme[imap-new?] and
@scheme[imap-reset-new!] to detect when new messages are available in
Use @racket[imap-messages] to get the message count for the currently
selected mailbox, etc. Use @racket[imap-new?] and
@racket[imap-reset-new!] to detect when new messages are available in
the currently selected mailbox.}
@ -446,7 +446,7 @@ the currently selected mailbox.}
[mailbox (or/c string? bytes?)])
boolean?]{
Returns @scheme[#t] if @scheme[mailbox] exists, @scheme[#f]
Returns @racket[#t] if @racket[mailbox] exists, @racket[#f]
otherwise.}
@ -454,7 +454,7 @@ otherwise.}
[mailbox (or/c string? bytes?)])
void?]{
Creates @scheme[mailbox]. (It must not exist already.)}
Creates @racket[mailbox]. (It must not exist already.)}
@defproc[(imap-list-child-mailboxes [imap imap-connection?]
@ -463,9 +463,9 @@ Creates @scheme[mailbox]. (It must not exist already.)}
(imap-get-hierarchy-delimiter)])
(listof (list/c (listof symbol?) bytes?))]{
Returns information about sub-mailboxes of @scheme[mailbox]; if
@scheme[mailbox] is @scheme[#f], information about all top-level
mailboxes is returned. The @scheme[delimiter] is used to parse mailbox
Returns information about sub-mailboxes of @racket[mailbox]; if
@racket[mailbox] is @racket[#f], information about all top-level
mailboxes is returned. The @racket[delimiter] is used to parse mailbox
names from the server to detect hierarchy.
The return value is a list of mailbox-information lists. Each
@ -491,7 +491,7 @@ mailbox path names.}
(listof symbol?)]{
Returns a list of IMAP flags for the given mailbox. See also
@scheme[imap-flag->symbol].}
@racket[imap-flag->symbol].}
@; ----------------------------------------
@ -501,7 +501,7 @@ Returns a list of IMAP flags for the given mailbox. See also
@defthing[imap@ unit?]{
Imports nothing, exports @scheme[imap^].}
Imports nothing, exports @racket[imap^].}
@; ----------------------------------------
@ -511,4 +511,4 @@ Imports nothing, exports @scheme[imap^].}
@defsignature[imap^ ()]{}
Includes everything exported by the @schememodname[net/imap] module.
Includes everything exported by the @racketmodname[net/imap] module.

100
collects/net/scribblings/mime.scrbl
View File

@ -25,7 +25,7 @@
@title[#:tag "mime"]{MIME: Decoding Internet Data}
@defmodule[net/mime]{The @schememodname[net/mime] library provides
@defmodule[net/mime]{The @racketmodname[net/mime] library provides
utilities for parsing and creating MIME encodings as described in RFC
2045 through RFC 2049.
@ -39,15 +39,15 @@ The library was written by Francisco Solsona.}
[part? any/c])
message?]{
Parses @scheme[message-in] and returns the parsed result as a
@scheme[message] instance.}
Parses @racket[message-in] and returns the parsed result as a
@racket[message] instance.}
@defstruct[message ([version real?]
[entity entity]
[fields (listof string?)])]{
A decoded MIME message. The version is @scheme[1.0] by default. The
@scheme[entity] field represents the message data. The @scheme[fields]
A decoded MIME message. The version is @racket[1.0] by default. The
@racket[entity] field represents the message data. The @racket[fields]
field contains one string for each field in the message header.}
@defstruct[entity ([type symbol?]
@ -65,12 +65,12 @@ field contains one string for each field in the message header.}
Represents the content of a message or a sub-part.
Standard values for the @scheme[type] field include @scheme['text],
@scheme['image], @scheme['audio], @scheme['video],
@scheme['application], @scheme['message], and @scheme['multipart].
Standard values for the @racket[type] field include @racket['text],
@racket['image], @racket['audio], @racket['video],
@racket['application], @racket['message], and @racket['multipart].
Standard values for the @scheme[subtype] field depend on the
@scheme[type] field, and include the following:
Standard values for the @racket[subtype] field depend on the
@racket[type] field, and include the following:
@mime-table[
(
@ -123,36 +123,36 @@ Standard values for the @scheme[subtype] field depend on the
(quicktime "[Lindner]")
)]
Standard values for the @scheme[charset] field include
@scheme['us-ascii], which is the default.
Standard values for the @racket[charset] field include
@racket['us-ascii], which is the default.
Standard values for the @scheme[encoding] field are @scheme['7bit],
@scheme['8bit], @scheme['binary], @scheme['quoted-printable], and
@scheme['base64]. The default is @scheme['7bit].
Standard values for the @racket[encoding] field are @racket['7bit],
@racket['8bit], @racket['binary], @racket['quoted-printable], and
@racket['base64]. The default is @racket['7bit].
The @scheme[params] field contains a list of parameters from other
The @racket[params] field contains a list of parameters from other
MIME headers.
The @scheme[id] field is taken from the @scheme["Content-Id"] header
The @racket[id] field is taken from the @racket["Content-Id"] header
field.
The @scheme[description] field is taken from the
@scheme["Content-description"] header field.
The @racket[description] field is taken from the
@racket["Content-description"] header field.
The @scheme[other] field contains additional (non-standard) field
headers whose field names start with @scheme["Content-"].
The @racket[other] field contains additional (non-standard) field
headers whose field names start with @racket["Content-"].
The @scheme[fields] field contains additional field headers whose
field names @emph{do not} start with @scheme["Content-"].
The @racket[fields] field contains additional field headers whose
field names @emph{do not} start with @racket["Content-"].
The @scheme[parts] contains sub-parts from multipart MIME
messages. This list is non-empty only when @scheme[type] is
@scheme['multipart] or @scheme['message].
The @racket[parts] contains sub-parts from multipart MIME
messages. This list is non-empty only when @racket[type] is
@racket['multipart] or @racket['message].
The @scheme[body] field represents the body as a function that
The @racket[body] field represents the body as a function that
consumes an output out and writes the decoded message to the port. No
bytes are written if @scheme[type] is @scheme['multipart] or
@scheme['message]. All of the standard values of @scheme[encoding]
bytes are written if @racket[type] is @racket['multipart] or
@racket['message]. All of the standard values of @racket[encoding]
are supported. The procedure only works once (since the encoded body
is pulled from a stream).}
@ -164,26 +164,26 @@ is pulled from a stream).}
[size (or/c exact-nonnegative-integer? false/c)]
[params (listof (cons/c symbol? string?))])]{
Represents a @scheme["Content-Disposition"] header as defined in RFC
Represents a @racket["Content-Disposition"] header as defined in RFC
2183.
Standard values for the @scheme[type] field include @scheme['inline]
and @scheme['attachment].
Standard values for the @racket[type] field include @racket['inline]
and @racket['attachment].
The @scheme[filename] field is drawn from the @scheme["filename"]
parameter of the @scheme["Content-Disposition"] header, if included in
The @racket[filename] field is drawn from the @racket["filename"]
parameter of the @racket["Content-Disposition"] header, if included in
the message.
The @scheme[creation], @scheme[modification], and @scheme[read] fields
represent file timestamps as drawn from the @scheme["creation-date"],
@scheme["modification-date"], and @scheme["read-date"] attributes of
the @scheme["Content-Disposition"] header, if included in the message.
The @racket[creation], @racket[modification], and @racket[read] fields
represent file timestamps as drawn from the @racket["creation-date"],
@racket["modification-date"], and @racket["read-date"] attributes of
the @racket["Content-Disposition"] header, if included in the message.
The @scheme[size] field is drawn from the @scheme["size"] parameter of
the @scheme["Content-Disposition"] header, if included in the message.
The @racket[size] field is drawn from the @racket["size"] parameter of
the @racket["Content-Disposition"] header, if included in the message.
The @scheme[params] field stores any additional attribute bindings of
the @scheme["Content-Disposition"] header, if included in the message.}
The @racket[params] field stores any additional attribute bindings of
the @racket["Content-Disposition"] header, if included in the message.}
@; ----------------------------------------
@ -201,35 +201,35 @@ to RFC 2045 and friends.}
@defstruct[(missing-multipart-boundary-parameter mime-error) ()]{
Raised when a multipart type is specified, but no @scheme["Boundary"]
Raised when a multipart type is specified, but no @racket["Boundary"]
parameter is given or an end-of-file is encountered before the
boundary.}
@defstruct[(malformed-multipart-entity mime-error) ([msg string?])]{
Similar to @scheme[unexpected-termination], but used only while
Similar to @racket[unexpected-termination], but used only while
scanning parts of a multipart message.}
@defstruct[(empty-mechanism mime-error) ()]{
Raised when no transport encoding mechanism was provided with the
@scheme["Content-Transfer-Encoding"] field.}
@racket["Content-Transfer-Encoding"] field.}
@defstruct[(empty-type mime-error) ()]{
Raised when no type is specified for @scheme["Content-Type"], or when
Raised when no type is specified for @racket["Content-Type"], or when
the specification is incorrectly formatted.}
@defstruct[(empty-subtype mime-error) ()]{
Raised when no sub-type is specified for @scheme["Content-Type"], or
Raised when no sub-type is specified for @racket["Content-Type"], or
when the specification is incorrectly formatted.}
@defstruct[(empty-disposition-type mime-error) ()]{
Raised when type specified for the @scheme["Content-Disposition"]
Raised when type specified for the @racket["Content-Disposition"]
field, or when the specification is incorrectly formatted.}
@; ----------------------------------------
@ -240,7 +240,7 @@ field, or when the specification is incorrectly formatted.}
@defthing[mime@ unit?]{
Imports nothing, exports @scheme[mime^].}
Imports nothing, exports @racket[mime^].}
@; ----------------------------------------
@ -250,4 +250,4 @@ Imports nothing, exports @scheme[mime^].}
@defsignature[mime^ ()]{}
Includes everything exported by the @schememodname[net/mime] module.
Includes everything exported by the @racketmodname[net/mime] module.

4
collects/net/scribblings/net.scrbl
View File

@ -38,14 +38,14 @@
#:location "RFC"
#:url "http://www.ietf.org/rfc/rfc0822.txt"
#:date "1982")
(bib-entry #:key "RFC977"
#:title "Network News Transfer Protocol"
#:author "Brian Kantor and Phil Lapsley"
#:location "RFC"
#:url "http://www.ietf.org/rfc/rfc0977.txt"
#:date "1986")
(bib-entry #:key "RFC1738"
#:title "Uniform Resource Locators (URL)"
#:author "T. Berners-Lee, L. Masinter, and M. McCahill"

20
collects/net/scribblings/nntp.scrbl
View File

@ -3,7 +3,7 @@
@title[#:tag "nntp"]{NNTP: Newsgroup Protocol}
@defmodule[net/nntp]{The @schememodname[net/nntp] module provides
@defmodule[net/nntp]{The @racketmodname[net/nntp] module provides
tools to access Usenet group via NNTP @cite["RFC977"].}
@section{Connection and Operations}
@ -14,13 +14,13 @@ tools to access Usenet group via NNTP @cite["RFC977"].}
[port (integer-in 0 65535)])]{
Once a connection to a Usenet server has been established, its state
is stored in a @scheme[communicator], and other procedures take
is stored in a @racket[communicator], and other procedures take
communicators as an argument.}
@defproc[(connect-to-server [server string?] [port-number (integer-in 0 65535) 119])
communicator?]{
Connects to @scheme[server] at @scheme[port-number].}
Connects to @racket[server] at @racket[port-number].}
@defproc[(disconnect-from-server [communicator communicator?]) void?]{
@ -42,7 +42,7 @@ article, and the last available article.}
void?]{
Tries to authenticate a user with the original authinfo command (uses
cleartext). The @scheme[password] argument is ignored if the server
cleartext). The @racket[password] argument is ignored if the server
does not ask for it.}
@defproc[(head-of-message [communicator communicator?]
@ -69,8 +69,8 @@ Implements the @tt{NEWNEWS} command (often disabled on servers).}
[message-index exact-nonnegative-integer?])
(listof string?)]{
Useful primitive for implementing @scheme[head-of-message],
@scheme[body-of-message] and other similar commands.}
Useful primitive for implementing @racket[head-of-message],
@racket[body-of-message] and other similar commands.}
@defproc[(make-desired-header [tag-string string?])
regexp?]{
@ -82,7 +82,7 @@ Takes a header field's tag and returns a regexp to match the field}
(listof string?)]{
Given a list of header lines and of desired regexps, returns the
header lines that match any of the @scheme[desireds].}
header lines that match any of the @racket[desireds].}
@section{Exceptions}
@ -95,7 +95,7 @@ The supertype of all NNTP exceptions.}
[text string?])]{
Raised whenever an unexpected response code is received. The
@scheme[text] field holds the response text sent by the server.}
@racket[text] field holds the response text sent by the server.}
@defstruct[(bad-status-line nntp) ([line string?])]{
@ -139,7 +139,7 @@ Raised when the server reject an authentication attempt.}
@defthing[nntp@ unit?]{
Imports nothing, exports @scheme[nntp^].}
Imports nothing, exports @racket[nntp^].}
@; ----------------------------------------
@ -149,4 +149,4 @@ Imports nothing, exports @scheme[nntp^].}
@defsignature[nntp^ ()]{}
Includes everything exported by the @schememodname[net/nntp] module.
Includes everything exported by the @racketmodname[net/nntp] module.

32
collects/net/scribblings/pop3.scrbl
View File

@ -5,7 +5,7 @@
@title[#:tag "pop3"]{POP3: Reading Mail}
@defmodule[net/pop3]{The @schememodname[net/pop3] module provides
@defmodule[net/pop3]{The @racketmodname[net/pop3] module provides
tools for the Post Office Protocol version 3 @cite["RFC977"].}
@defstruct[communicator ([sender output-port?]
@ -15,31 +15,31 @@ tools for the Post Office Protocol version 3 @cite["RFC977"].}
[state (one-of/c 'disconnected 'authorization 'transaction)])]{
Once a connection to a POP-3 server has been established, its state is
stored in a @scheme[communicator] instance, and other procedures take
@scheme[communicator] instances as an argument.}
stored in a @racket[communicator] instance, and other procedures take
@racket[communicator] instances as an argument.}
@defproc[(connect-to-server [server string?]
[port-number (integer-in 0 65535) 110])
communicator?]{
Connects to @scheme[server] at @scheme[port-number].}
Connects to @racket[server] at @racket[port-number].}
@defproc[(disconnect-from-server [communicator communicator?])
void?]{
Disconnects @scheme[communicator] from the server, and sets
@scheme[communicator]'s state to @scheme['disconnected].}
Disconnects @racket[communicator] from the server, and sets
@racket[communicator]'s state to @racket['disconnected].}
@defproc[(authenticate/plain-text [user string?] [passwd string?]
[communicator communicator?])
void?]{
Authenticates using @scheme[user] and @scheme[passwd]. If
authentication is successful, @scheme[communicator]'s state is set to
@scheme['transaction].}
Authenticates using @racket[user] and @racket[passwd]. If
authentication is successful, @racket[communicator]'s state is set to
@racket['transaction].}
@defproc[(get-mailbox-status [communicator communicator?])
(values exact-nonnegative-integer? exact-nonnegative-integer?)]{
@ -83,8 +83,8 @@ Gets the server's unique id for a particular message.}
(listof (cons/c exact-integer? string?))]{
Gets a list of unique id's from the server for all the messages in the
mailbox. The @scheme[car] of each item in the result list is the
message number, and the @scheme[cdr] of each item is the message's
mailbox. The @racket[car] of each item in the result list is the
message number, and the @racket[cdr] of each item is the message's
id.}
@defproc[(make-desired-header [tag-string string?])
@ -97,7 +97,7 @@ Takes a header field's tag and returns a regexp to match the field}
(listof string?)]{
Given a list of header lines and of desired regexps, returns the
header lines that match any of the @scheme[desireds].}
header lines that match any of the @racket[desireds].}
@; ----------------------------------------
@ -151,7 +151,7 @@ Raised when the server produces a malformed response.}
@section{Example Session}
@schemeblock[
@racketblock[
#,pt (require net/pop3)
#,pt (define c (connect-to-server "cs.rice.edu"))
#,pt (authenticate/plain-text "scheme" "********" c)
@ -172,7 +172,7 @@ Raised when the server produces a malformed response.}
"Status: RO")
("some body" "text" "goes" "." "here" "." "")
#,pt (get-unique-id/single c 205)
@#,schemeerror{no message numbered 205 available for unique id}
@#,racketerror{no message numbered 205 available for unique id}
#,pt (list-tail (get-unique-id/all c) 194)
((195 . "e24d13c7ef050000") (196 . "3ad2767070050000"))
#,pt (get-unique-id/single c 196)
@ -188,7 +188,7 @@ Raised when the server produces a malformed response.}
@defthing[pop3@ unit?]{
Imports nothing, exports @scheme[pop3^].}
Imports nothing, exports @racket[pop3^].}
@; ----------------------------------------
@ -198,4 +198,4 @@ Imports nothing, exports @scheme[pop3^].}
@defsignature[pop3^ ()]{}
Includes everything exported by the @schememodname[net/pop3] module.
Includes everything exported by the @racketmodname[net/pop3] module.

22
collects/net/scribblings/qp.scrbl
View File

@ -3,7 +3,7 @@
@title[#:tag "qp"]{Quoted-Printable: Encoding and Decoding}
@defmodule[net/qp]{The @schememodname[net/qp] library provides
@defmodule[net/qp]{The @racketmodname[net/qp] library provides
utilities for quoted-printable (mime-standard) encoding and decoding
from RFC 2045 section 6.7.
@ -14,7 +14,7 @@ The library was written by Francisco Solsona.}
@defproc[(qp-encode [bstr bytes?]) bytes?]{
Consumes a byte string and returns its quoted printable representation
as a new string. The encoded string uses @scheme[#"\r\n"] where
as a new string. The encoded string uses @racket[#"\r\n"] where
necessary to create shorter lines.}
@ -30,12 +30,12 @@ whatever form they exist (CR, LR, or CRLF) in the input string.}
[newline-bstr bytes? #"\n"])
void?]{
Reads characters from @scheme[in] and writes the quoted printable
encoded result to @scheme[out].
Reads characters from @racket[in] and writes the quoted printable
encoded result to @racket[out].
The @scheme[newline-bstr] argument is used for soft line-breaks (after
@litchar{=}). Note that the default @scheme[newline-bstr] is just
@scheme[#"\n"], not @scheme[#"\r\n"].
The @racket[newline-bstr] argument is used for soft line-breaks (after
@litchar{=}). Note that the default @racket[newline-bstr] is just
@racket[#"\n"], not @racket[#"\r\n"].
Other line breaks are preserved in whatever form they exist (CR, LR,
or CRLF) in the input stream.}
@ -45,8 +45,8 @@ or CRLF) in the input stream.}
[out output-port?])
void?]{
Reads characters from @scheme[in] and writes de-quoted-printable
result to @scheme[out]. Non-soft line breaks are preserved in
Reads characters from @racket[in] and writes de-quoted-printable
result to @racket[out]. Non-soft line breaks are preserved in
whatever form they exist (CR, LR, or CRLF) in the input stream.}
@; ----------------------------------------
@ -70,7 +70,7 @@ backward compatibility.}
@defthing[qp@ unit?]{
Imports nothing, exports @scheme[qp^].}
Imports nothing, exports @racket[qp^].}
@; ----------------------------------------
@ -80,4 +80,4 @@ Imports nothing, exports @scheme[qp^].}
@defsignature[qp^ ()]{}
Includes everything exported by the @schememodname[net/qp] module.
Includes everything exported by the @racketmodname[net/qp] module.

16
collects/net/scribblings/sendmail.scrbl
View File

@ -4,10 +4,10 @@
@title[#:tag "sendmail"]{@exec{sendmail}: Sending E-Mail}
@defmodule[net/sendmail]{The @schememodname[net/sendmail] module
@defmodule[net/sendmail]{The @racketmodname[net/sendmail] module
provides tools for sending electronic mail messages using a
@exec{sendmail} program on the local system. See also the
@schememodname[net/smtp] package, which sends mail via SMTP.}
@racketmodname[net/smtp] package, which sends mail via SMTP.}
All strings used in mail messages are assumed to conform to their
corresponding SMTP specifications, except as noted otherwise.
@ -30,11 +30,11 @@ which must be provided as lines (not terminated by a linefeed or
carriage return) to include verbatim in the header.
The return value is an output port into which the client must write
the message. Clients are urged to use @scheme[close-output-port] on
the message. Clients are urged to use @racket[close-output-port] on
the return value as soon as the necessary text has been written, so
that the sendmail process can complete.
The @scheme[from] argument can be any value; of course, spoofing
The @racket[from] argument can be any value; of course, spoofing
should be used with care.}
@defproc[(send-mail-message [from string?]
@ -46,7 +46,7 @@ should be used with care.}
[extra-header string?] ...)
void?]{
Like @scheme[send-mail-message/port], but with @scheme[body] as a list
Like @racket[send-mail-message/port], but with @racket[body] as a list
of strings, each providing a line of the message body.
Lines that contain a single period do not need to be quoted.}
@ -55,7 +55,7 @@ Lines that contain a single period do not need to be quoted.}
@defstruct[(no-mail-recipients exn) ()]{
Raised when no mail recipients were specified for
@scheme[send-mail-message/port].}
@racket[send-mail-message/port].}
@ -67,7 +67,7 @@ Raised when no mail recipients were specified for
@defthing[sendmail@ unit?]{
Imports nothing, exports @scheme[sendmail^].}
Imports nothing, exports @racket[sendmail^].}
@; ----------------------------------------
@ -77,4 +77,4 @@ Imports nothing, exports @scheme[sendmail^].}
@defsignature[sendmail^ ()]{}
Includes everything exported by the @schememodname[net/sendmail] module.
Includes everything exported by the @racketmodname[net/sendmail] module.

62
collects/net/scribblings/sendurl.scrbl
View File

@ -3,11 +3,11 @@
@title[#:tag "sendurl"]{Send URL: Opening a Web Browser}
@defmodule[net/sendurl]{Provides @scheme[send-url] for opening a URL
@defmodule[net/sendurl]{Provides @racket[send-url] for opening a URL
in the user's chosen web browser.}
See also @schememodname[browser/external], which requires
@scheme[racket/gui], but can prompt the user for a browser if no
See also @racketmodname[browser/external], which requires
@racket[racket/gui], but can prompt the user for a browser if no
browser preference is set.
@ -15,40 +15,40 @@ browser preference is set.
[#:escape escape? any/c #t])
void?]{
Opens @scheme[str], which represents a URL, in a platform-specific
Opens @racket[str], which represents a URL, in a platform-specific
manner. For some platforms and configurations, the
@scheme[separate-window?] parameter determines if the browser creates
@racket[separate-window?] parameter determines if the browser creates
a new window to display the URL or not.
On Windows, @scheme[send-url] normally uses @scheme[shell-execute]
On Windows, @racket[send-url] normally uses @racket[shell-execute]
to launch a browser. (If the URL appears to contain a fragment, it may
use an intermediate redirecting file due to a bug in IE7.)
On Mac OS X, @scheme[send-url] runs @exec{osascript} to start the
On Mac OS X, @racket[send-url] runs @exec{osascript} to start the
user's chosen browser.
On Unix, @scheme[send-url] uses a user-preference, or when none is
On Unix, @racket[send-url] uses a user-preference, or when none is
set, it will look for a known browser. See the description of
@scheme[external-browser] for details.
@racket[external-browser] for details.
The @scheme[url] string is usually escaped to avoid dangerous shell
The @racket[url] string is usually escaped to avoid dangerous shell
characters (quotations, dollar signs, backslashes, and non-ASCII). Note
that it is a good idea to encode URLs before passing them to this
function.
On all platforms, @scheme[external-browser] parameter can be set to a
On all platforms, @racket[external-browser] parameter can be set to a
procedure to override the above behavior --- the procedure will be
called with the @scheme[url] string.}
called with the @racket[url] string.}
@defproc[(send-url/file [path path-string?] [separate-window? any/c #t]
[#:fragment fragment (or/c string? false/c) #f]
[#:query query (or/c string? false/c) #f])
void?]{
Similar to @scheme[send-url], but accepts a path to a file to be
Similar to @racket[send-url], but accepts a path to a file to be
displayed by the browser. Use this function when you want to display
a local file: it takes care of the peculiarities of constructing the
correct @litchar{file://} URL, and uses @scheme[send-url] to display
correct @litchar{file://} URL, and uses @racket[send-url] to display
the file. If you need to use an anchor fragment or a query string,
use the corresponding keyword arguments.}
@ -58,52 +58,52 @@ use the corresponding keyword arguments.}
[#:delete-at seconds (or/c number? false/c) #f])
void?]{
Similar to @scheme[send-url/file], but it consumes the contents of a
Similar to @racket[send-url/file], but it consumes the contents of a
page to show, and displayes it from a temporary file.
If @scheme[delete-at] is a number, the temporary file is removed after
If @racket[delete-at] is a number, the temporary file is removed after
this many seconds. The deletion happens in a thread, so if racket
exits before that it will not happen --- when this function is called
it scans old generated files (this happens randomly, not on every
call) and removes them to avoid cluttering the temporary directory.
If @scheme[delete-at] is @scheme[#f], no delayed deletion happens, but
If @racket[delete-at] is @racket[#f], no delayed deletion happens, but
old temporary files are still deleted as described above.}
@defparam[external-browser cmd browser-preference?]{
A parameter that can hold a procedure to override how a browser is
started, or @scheme[#f] to use the default platform-dependent command.
started, or @racket[#f] to use the default platform-dependent command.
On Unix, the command that is used depends on the
@scheme['external-browser] preference. If the preference is unset,
@scheme[send-url] uses the first of the browsers from
@scheme[unix-browser-list] for which the executable is found.
@racket['external-browser] preference. If the preference is unset,
@racket[send-url] uses the first of the browsers from
@racket[unix-browser-list] for which the executable is found.
Otherwise, the preference should hold a symbol indicating a known
browser (from the @scheme[unix-browser-list]), or it a pair of a prefix
and a suffix string that are concatenated around the @scheme[url] string
browser (from the @racket[unix-browser-list]), or it a pair of a prefix
and a suffix string that are concatenated around the @racket[url] string
to make up a shell command to run. In addition, the
@scheme[external-browser] paremeter can be set to one of these values,
and @scheme[send-url] will use it instead of the preference value.
@racket[external-browser] paremeter can be set to one of these values,
and @racket[send-url] will use it instead of the preference value.
Note that the URL is encoded to make it work inside shell double-quotes:
URLs can still hold characters like @litchar{#}, @litchar{?}, and
@litchar{&}, so if the @scheme[external-browser] is set to a pair of
@litchar{&}, so if the @racket[external-browser] is set to a pair of
prefix/suffix strings, they should use double quotes around the url.
If the preferred or default browser can't be launched,
@scheme[send-url] fails. See @scheme[get-preference] and
@scheme[put-preferences] for details on setting preferences.}
@racket[send-url] fails. See @racket[get-preference] and
@racket[put-preferences] for details on setting preferences.}
@defproc[(browser-preference? [a any/c]) boolean?]{
Returns @scheme[#t] if @scheme[v] is a valid browser preference,
@scheme[#f] otherwise. See @scheme[external-browser] for more
Returns @racket[#t] if @racket[v] is a valid browser preference,
@racket[#f] otherwise. See @racket[external-browser] for more
information.}
@defthing[unix-browser-list (listof symbol?)]{
A list of symbols representing Unix executable names that may be tried
in order by @scheme[send-url]. The @scheme[send-url] function
in order by @racket[send-url]. The @racket[send-url] function
internally includes information on how to launch each executable with
a URL.}

60
collects/net/scribblings/smtp.scrbl
View File

@ -4,16 +4,16 @@
@title[#:tag "smtp"]{SMTP: Sending E-Mail}
@defmodule[net/smtp]{The @schememodname[net/smtp] module provides
@defmodule[net/smtp]{The @racketmodname[net/smtp] module provides
tools for sending electronic mail messages using SMTP. The client must
provide the address of an SMTP server; in contrast, the
@schememodname[net/sendmail] module uses a pre-configured
@racketmodname[net/sendmail] module uses a pre-configured
@exec{sendmail} on the local system.}
The @schememodname[net/head] library defines the format of a
@tech{header} string, which is used by @scheme[send-smtp-message]. The
@schememodname[net/head] module also provides utilities to verify the
formatting of a mail address. The procedures of the @scheme[net/smtp]
The @racketmodname[net/head] library defines the format of a
@tech{header} string, which is used by @racket[send-smtp-message]. The
@racketmodname[net/head] module also provides utilities to verify the
formatting of a mail address. The procedures of the @racket[net/smtp]
module assume that the given string arguments are well-formed.
@ -42,59 +42,59 @@ module assume that the given string arguments are well-formed.
[port-no (integer-in 0 65535) port-no/k])
void?]{
Connects to the server at @scheme[server-address] and @scheme[port-no]
to send a message. The @scheme[from] argument specifies the mail
address of the sender, and @scheme[to] is a list of recipient
Connects to the server at @racket[server-address] and @racket[port-no]
to send a message. The @racket[from] argument specifies the mail
address of the sender, and @racket[to] is a list of recipient
addresses (including ``To:'', ``CC'', and ``BCC'' recipients).
The @scheme[header] argument is the complete message header, which
The @racket[header] argument is the complete message header, which
should already include ``From:'', ``To:'', and ``CC:'' fields
consistent with the given sender and recipients. See also the
@schememodname[net/head] library for header-creating utilities.
@racketmodname[net/head] library for header-creating utilities.
The @scheme[message] argument is the body of the message, where each
The @racket[message] argument is the body of the message, where each
string or byte string in the list corresponds to a single line of
message text. No string in @scheme[message] should contain a carriage
message text. No string in @racket[message] should contain a carriage
return or linefeed character.
The optional @scheme[port-no] argument---which can be specified either
with the @scheme[#:port-no] keyword or, for backward compatibility, as
The optional @racket[port-no] argument---which can be specified either
with the @racket[#:port-no] keyword or, for backward compatibility, as
an extra argument after keywords---specifies the IP port to use in
contacting the SMTP server.
The optional @scheme[#:auth-user] and @scheme[#:auth-passwd] keyword
The optional @racket[#:auth-user] and @racket[#:auth-passwd] keyword
argument supply a username and password for authenticated SMTP (using
the AUTH PLAIN protocol).
The optional @scheme[#:tcp-connect] keyword argument supplies a
connection procedure to be used in place of @scheme[tcp-connect]. For
example, use @scheme[ssl-connect] to connect to the server via SSL.
The optional @racket[#:tcp-connect] keyword argument supplies a
connection procedure to be used in place of @racket[tcp-connect]. For
example, use @racket[ssl-connect] to connect to the server via SSL.
If the optional @scheme[#:tls-encode] keyword argument supplies a
If the optional @racket[#:tls-encode] keyword argument supplies a
procedure instead of #f, then the ESMTP STARTTLS protocol is used to
initiate SSL communication with the server. The procedure given as the
#:tls-encode argument should be like @scheme[ports->ssl-ports]; it
#:tls-encode argument should be like @racket[ports->ssl-ports]; it
will be called as
@schemeblock[
@racketblock[
(encode r w #:mode 'connect #:encrypt 'tls #:close-original? #t)
]
and it should return two values: an input port and an export port.
All further SMTP communication uses the returned ports.
For encrypted communication, normally either @scheme[ssl-connect]
should be supplied for @scheme[#:tcp-connect], or
@scheme[ports->ssl-ports] should be supplied for
@scheme[#:tls-encode]---one or the other (depending on what the server
For encrypted communication, normally either @racket[ssl-connect]
should be supplied for @racket[#:tcp-connect], or
@racket[ports->ssl-ports] should be supplied for
@racket[#:tls-encode]---one or the other (depending on what the server
expects), rather than both.}
@defparam[smtp-sending-end-of-message proc (-> any)]{
A parameter that determines a send-done procedure to be called after
@scheme[smtp-send-message] has completely sent the message. Before the
@racket[smtp-send-message] has completely sent the message. Before the
send-done procedure is called, breaking the thread that is executing
@scheme[smtp-send-message] cancels the send. After the send-done
@racket[smtp-send-message] cancels the send. After the send-done
procedure is called, breaking may or may not cancel the send (and
probably will not).}
@ -106,7 +106,7 @@ probably will not).}
@defthing[smtp@ unit?]{
Imports nothing, exports @scheme[smtp^].}
Imports nothing, exports @racket[smtp^].}
@; ----------------------------------------
@ -116,4 +116,4 @@ Imports nothing, exports @scheme[smtp^].}
@defsignature[smtp^ ()]{}
Includes everything exported by the @schememodname[net/smtp] module.
Includes everything exported by the @racketmodname[net/smtp] module.

38
collects/net/scribblings/ssl-tcp-unit.scrbl
View File

@ -1,11 +1,11 @@
#lang scribble/doc
@(require "common.rkt" (for-label net/ssl-tcp-unit net/tcp-sig))
@title[#:tag "ssl-tcp-unit"]{SSL Unit: @scheme[tcp^] via SSL}
@title[#:tag "ssl-tcp-unit"]{SSL Unit: @racket[tcp^] via SSL}
@defmodule[net/ssl-tcp-unit]{The @schememodname[net/ssl-tcp-unit]
library provides a function for creating a @scheme[tcp^]
implementation with @schememodname[openssl] functionality.}
@defmodule[net/ssl-tcp-unit]{The @racketmodname[net/ssl-tcp-unit]
library provides a function for creating a @racket[tcp^]
implementation with @racketmodname[openssl] functionality.}
@defproc[(make-ssl-tcp@ [server-cert-file (or/c path-string? false/c)]
[server-key-file (or/c path-string? false/c)]
@ -16,39 +16,39 @@ implementation with @schememodname[openssl] functionality.}
[client-root-cert-files (listof path-string?)])
unit?]{
Returns a unit that implements @scheme[tcp^] using the SSL functions
from @schememodname[openssl]. The arguments to @scheme[make-ssl-tcp@]
Returns a unit that implements @racket[tcp^] using the SSL functions
from @racketmodname[openssl]. The arguments to @racket[make-ssl-tcp@]
control the certificates and keys uses by server and client
connections:
@itemize[
@item{@scheme[server-cert-file] --- a PEM file for a server's
certificate; @scheme[#f] means no certificate (which is unlikely
@item{@racket[server-cert-file] --- a PEM file for a server's
certificate; @racket[#f] means no certificate (which is unlikely
to work with any SSL client)}
@item{@scheme[server-key-file] --- a private key PEM to go with
@scheme[server-cert-file]; @scheme[#f] means no key (which is likely
@item{@racket[server-key-file] --- a private key PEM to go with
@racket[server-cert-file]; @racket[#f] means no key (which is likely
renders a certificate useless)}
@item{@scheme[server-root-cert-files] --- a list of PEM files for
trusted root certificates; @scheme[#f] disables verification of
@item{@racket[server-root-cert-files] --- a list of PEM files for
trusted root certificates; @racket[#f] disables verification of
peer client certificates}
@item{@scheme[server-suggest-auth-file] --- PEM file for root
@item{@racket[server-suggest-auth-file] --- PEM file for root
certificates to be suggested to peer clients that must supply
certificates}
@item{@scheme[client-cert-file] --- a PEM file for a client's
certificate; @scheme[#f] means no certificate (which is usually
@item{@racket[client-cert-file] --- a PEM file for a client's
certificate; @racket[#f] means no certificate (which is usually
fine)}
@item{@scheme[client-key-file] --- a private key PEM to go with
@scheme[client-cert-file]; @scheme[#f] means no key (which is likely
@item{@racket[client-key-file] --- a private key PEM to go with
@racket[client-cert-file]; @racket[#f] means no key (which is likely
renders a certificate useless)}
@item{@scheme[client-root-cert-files] --- a list of PEM files for
trusted root certificates; @scheme[#f] disables verification of
@item{@racket[client-root-cert-files] --- a list of PEM files for
trusted root certificates; @racket[#f] disables verification of
peer server certificates}
]}

16
collects/net/scribblings/tcp-redirect.scrbl
View File

@ -1,21 +1,21 @@
#lang scribble/doc
@(require "common.rkt" (for-label net/tcp-redirect net/tcp-sig))
@title[#:tag "tcp-redirect"]{TCP Redirect: @scheme[tcp^] via Channels}
@title[#:tag "tcp-redirect"]{TCP Redirect: @racket[tcp^] via Channels}
@defmodule[net/tcp-redirect]{The @schememodname[net/tcp-redirect]
@defmodule[net/tcp-redirect]{The @racketmodname[net/tcp-redirect]
library provides a function for directing some TCP port numbers to use
buffered channels instead of the TCP support from
@schememodname[racket/tcp].}
@racketmodname[racket/tcp].}
@defproc[(tcp-redirect [port-numbers (listof (integer-in 0 65535))])
unit?]{
Returns a unit that implements @scheme[tcp^]. For port numbers not
listed in @scheme[port-numbers], the unit's implementations are the
@schememodname[racket/tcp] implementations.
Returns a unit that implements @racket[tcp^]. For port numbers not
listed in @racket[port-numbers], the unit's implementations are the
@racketmodname[racket/tcp] implementations.
For the port numbers listed in @scheme[port-numbers] and for
connections to @scheme["127.0.0.1"], the unit's implementation does
For the port numbers listed in @racket[port-numbers] and for
connections to @racket["127.0.0.1"], the unit's implementation does
not use TCP connections, but instead uses internal buffered
channels. Such channels behave exactly as TCP listeners and ports.}

36
collects/net/scribblings/tcp.scrbl
View File

@ -5,16 +5,16 @@
@title[#:tag "tcp"]{TCP: Unit and Signature}
The @schememodname[net/tcp-sig] and @schememodname[net/tcp-unit]
libraries define a @scheme[tcp^] signature and @scheme[tcp@]
The @racketmodname[net/tcp-sig] and @racketmodname[net/tcp-unit]
libraries define a @racket[tcp^] signature and @racket[tcp@]
implementation, where the implementation uses
@schememodname[racket/tcp].
@racketmodname[racket/tcp].
Some units in the @filepath{net} collection import @scheme[tcp^], so
Some units in the @filepath{net} collection import @racket[tcp^], so
that they can be used with transports other than plain TCP. For
example, @scheme[url@] imports @scheme[tcp^].
example, @racket[url@] imports @racket[tcp^].
See also @scheme[tcp-redirect] and @scheme[make-ssl-tcp@].
See also @racket[tcp-redirect] and @racket[make-ssl-tcp@].
@section{TCP Signature}
@ -29,7 +29,7 @@ See also @scheme[tcp-redirect] and @scheme[make-ssl-tcp@].
[hostname (or/c string? false/c) #f])
@#,sigelem[tcp^ tcp-listener?]]{
Like @scheme[tcp-listen] from @schememodname[racket/tcp].}
Like @racket[tcp-listen] from @racketmodname[racket/tcp].}
@defproc[(tcp-connect [hostname string?]
[port-no (and/c exact-nonnegative-integer?
@ -41,7 +41,7 @@ Like @scheme[tcp-listen] from @schememodname[racket/tcp].}
#f])
(values input-port? output-port?)]{
Like @scheme[tcp-connect] from @schememodname[racket/tcp].}
Like @racket[tcp-connect] from @racketmodname[racket/tcp].}
@defproc[(tcp-connect/enable-break [hostname string?]
[port-no (and/c exact-nonnegative-integer?
@ -52,33 +52,33 @@ Like @scheme[tcp-connect] from @schememodname[racket/tcp].}
false/c)])
(values input-port? output-port?)]{
Like @scheme[tcp-connect/enable-break] from @schememodname[racket/tcp].}
Like @racket[tcp-connect/enable-break] from @racketmodname[racket/tcp].}
@defproc[(tcp-accept [listener @#,sigelem[tcp^ tcp-listener?]])
(values input-port? output-port?)]{
Like @scheme[tcp-accept] from @schememodname[racket/tcp].}
Like @racket[tcp-accept] from @racketmodname[racket/tcp].}
@defproc[(tcp-accept/enable-break [listener @#,sigelem[tcp^ tcp-listener?]])
(values input-port? output-port?)]{
Like @scheme[tcp-accept/enable-break] from @schememodname[racket/tcp].}
Like @racket[tcp-accept/enable-break] from @racketmodname[racket/tcp].}
@defproc[(tcp-accept-ready? [listener @#,sigelem[tcp^ tcp-listener?]]) boolean?]{
Like @scheme[tcp-accept-ready?] from @schememodname[racket/tcp].}
Like @racket[tcp-accept-ready?] from @racketmodname[racket/tcp].}
@defproc[(tcp-close [listener @#,sigelem[tcp^ tcp-listener?]]) void?]{
Like @scheme[tcp-close] from @schememodname[racket/tcp].}
Like @racket[tcp-close] from @racketmodname[racket/tcp].}
@defproc[(tcp-listener? [v any/c]) boolean?]{
Like @scheme[tcp-listener?] from @schememodname[racket/tcp].}
Like @racket[tcp-listener?] from @racketmodname[racket/tcp].}
@defproc[(tcp-abandon-port [tcp-port port?]) void?]{
Like @scheme[tcp-abandon-port] from @schememodname[racket/tcp].}
Like @racket[tcp-abandon-port] from @racketmodname[racket/tcp].}
@defproc[(tcp-addresses [tcp-port port?]
[port-numbers? any/c #f])
@ -86,7 +86,7 @@ Like @scheme[tcp-abandon-port] from @schememodname[racket/tcp].}
(values string? (integer-in 1 65535)
string? (integer-in 1 65535)))]{
Like @scheme[tcp-addresses] from @schememodname[racket/tcp].}
Like @racket[tcp-addresses] from @racketmodname[racket/tcp].}
}
@ -96,5 +96,5 @@ Like @scheme[tcp-addresses] from @schememodname[racket/tcp].}
@defthing[tcp@ unit?]{
Imports nothing and exports @scheme[tcp^], implemented using
@schememodname[racket/tcp].}
Imports nothing and exports @racket[tcp^], implemented using
@racketmodname[racket/tcp].}

24
collects/net/scribblings/uri-codec.scrbl
View File

@ -8,7 +8,7 @@
@title[#:tag "uri-codec"]{URI Codec: Encoding and Decoding URIs}
@defmodule[net/uri-codec]{The @schememodname[net/uri-codec] module
@defmodule[net/uri-codec]{The @racketmodname[net/uri-codec] module
provides utilities for encoding and decoding strings using the URI
encoding rules given in RFC 2396 @cite["RFC2396"], and to encode and
decode name/value pairs using the
@ -54,7 +54,7 @@ given in the HTML 4.0 spec are:
These rules differs slightly from the straight encoding in RFC 2396 in
that @litchar{+} is allowed, and it represents a space. The
@schememodname[net/uri-codec] library follows this convention,
@racketmodname[net/uri-codec] library follows this convention,
encoding a space as @litchar{+} and decoding @litchar{+} as a space.
In addtion, since there appear to be some brain-dead decoders on the
web, the library also encodes @litchar{!}, @litchar{~}, @litchar{'},
@ -106,7 +106,7 @@ Decode a string encoded using the
Encode an association list using the
@tt{application/x-www-form-urlencoded} encoding rules.
The @scheme[current-alist-separator-mode] parameter determines the
The @racket[current-alist-separator-mode] parameter determines the
separator used in the result.}
@ -117,7 +117,7 @@ Decode a string encoded using the
@tt{application/x-www-form-urlencoded} encoding rules into an
association list. All keys are case-folded for conversion to symbols.
The @scheme[current-alist-separator-mode] parameter determines the way
The @racket[current-alist-separator-mode] parameter determines the way
that separators are parsed in the input.}
@ -125,11 +125,11 @@ that separators are parsed in the input.}
(one-of/c 'amp 'semi 'amp-or-semi 'semi-or-amp)]{
A parameter that determines the separator used/recognized between
associations in @scheme[form-urlencoded->alist],
@scheme[alist->form-urlencoded], @scheme[url->string], and
@scheme[string->url].
associations in @racket[form-urlencoded->alist],
@racket[alist->form-urlencoded], @racket[url->string], and
@racket[string->url].
The default value is @scheme['amp-or-semi], which means that both
The default value is @racket['amp-or-semi], which means that both
@litchar{&} and @litchar{;} are treated as separators when parsing,
and @litchar{&} is used as a separator when encoding. The other modes
use/recognize only of the separators.
@ -137,19 +137,19 @@ use/recognize only of the separators.
@examples[
#:eval uri-codec-eval
(define ex '((x . "foo") (y . "bar") (z . "baz")))
(code:line (current-alist-separator-mode 'amp) (code:comment @#,t{try @scheme['amp]...}))
(code:line (current-alist-separator-mode 'amp) (code:comment @#,t{try @racket['amp]...}))
(form-urlencoded->alist "x=foo&y=bar&z=baz")
(form-urlencoded->alist "x=foo;y=bar;z=baz")
(alist->form-urlencoded ex)
(code:line (current-alist-separator-mode 'semi) (code:comment @#,t{try @scheme['semi]...}))
(code:line (current-alist-separator-mode 'semi) (code:comment @#,t{try @racket['semi]...}))
(form-urlencoded->alist "x=foo;y=bar;z=baz")
(form-urlencoded->alist "x=foo&y=bar&z=baz")
(alist->form-urlencoded ex)
(code:line (current-alist-separator-mode 'amp-or-semi) (code:comment @#,t{try @scheme['amp-or-semi]...}))
(code:line (current-alist-separator-mode 'amp-or-semi) (code:comment @#,t{try @racket['amp-or-semi]...}))
(form-urlencoded->alist "x=foo&y=bar&z=baz")
(form-urlencoded->alist "x=foo;y=bar;z=baz")
(alist->form-urlencoded ex)
(code:line (current-alist-separator-mode 'semi-or-amp) (code:comment @#,t{try @scheme['semi-or-amp]...}))
(code:line (current-alist-separator-mode 'semi-or-amp) (code:comment @#,t{try @racket['semi-or-amp]...}))
(form-urlencoded->alist "x=foo&y=bar&z=baz")
(form-urlencoded->alist "x=foo;y=bar;z=baz")
(alist->form-urlencoded ex)

154
collects/net/scribblings/url.scrbl
View File

@ -6,28 +6,28 @@
@title[#:tag "url"]{URLs and HTTP}
@defmodule[net/url]{The @schememodname[net/url] library provides
@defmodule[net/url]{The @racketmodname[net/url] library provides
utilities to parse and manipulate URIs, as specified in RFC 2396
@cite["RFC2396"], and to use the HTTP protocol.}
To access the text of a document from the web, first obtain its URL as
a string. Convert the address into a @scheme[url] structure using
@scheme[string->url]. Then, open the document using
@scheme[get-pure-port] or @scheme[get-impure-port], depending on
a string. Convert the address into a @racket[url] structure using
@racket[string->url]. Then, open the document using
@racket[get-pure-port] or @racket[get-impure-port], depending on
whether or not you wish to examine its MIME headers. At this point,
you have a regular input port with which to process the document, as with
any other file.
any other file.
Currently the only supported protocols are @scheme["http"],
@racket["https"], and sometimes @scheme["file"].
Currently the only supported protocols are @racket["http"],
@racket["https"], and sometimes @racket["file"].
@section{URL Structure}
@declare-exporting[net/url-structs net/url]
@defmodule*/no-declare[(net/url-structs)]{The URL structure types are
provided by the @schememodname[net/url-structs] library, and
re-exported by @schememodname[net/url].}
provided by the @racketmodname[net/url-structs] library, and
re-exported by @racketmodname[net/url].}
@; ----------------------------------------
@ -53,30 +53,30 @@ The basic structure for all URLs, which is explained in RFC 3986
7 = query, 8 = fragment
}|
The strings inside the @scheme[user], @scheme[path], @scheme[query],
and @scheme[fragment] fields are represented directly as Racket
The strings inside the @racket[user], @racket[path], @racket[query],
and @racket[fragment] fields are represented directly as Racket
strings, without URL-syntax-specific quoting. The procedures
@scheme[string->url] and @scheme[url->string] translate encodings such
@racket[string->url] and @racket[url->string] translate encodings such
as @litchar{%20} into spaces and back again.
By default, query associations are parsed with either @litchar{;} or
@litchar{&} as a separator, and they are generated with @litchar{&} as
a separator. The @scheme[current-alist-separator-mode] parameter
a separator. The @racket[current-alist-separator-mode] parameter
adjusts the behavior.
An empty string at the end of the @scheme[path] list corresponds to a
An empty string at the end of the @racket[path] list corresponds to a
URL that ends in a slash. For example, the result of
@scheme[(string->url "http://racket-lang.org/a/")] has a
@scheme[path] field with strings @scheme["a"] and @scheme[""], while
the result of @scheme[(string->url "http://racket-lang.org/a")] has a
@scheme[path] field with only the string @scheme["a"].
@racket[(string->url "http://racket-lang.org/a/")] has a
@racket[path] field with strings @racket["a"] and @racket[""], while
the result of @racket[(string->url "http://racket-lang.org/a")] has a
@racket[path] field with only the string @racket["a"].
When a @scheme["file"] URL is represented by a @scheme[url] structure,
the @scheme[path] field is mostly a list of path elements. For Unix
paths, the root directory is not included in @scheme[path]; its
presence or absence is implicit in the @scheme[path-absolute?] flag.
When a @racket["file"] URL is represented by a @racket[url] structure,
the @racket[path] field is mostly a list of path elements. For Unix
paths, the root directory is not included in @racket[path]; its
presence or absence is implicit in the @racket[path-absolute?] flag.
For Windows paths, the first element typically represents a drive, but
a UNC path is represented by a first element that is @scheme[""] and
a UNC path is represented by a first element that is @racket[""] and
then successive elements complete the drive components that are
separated by @litchar{/} or @litchar{\}.}
@ -96,28 +96,28 @@ fragment. An impure port is one that still has its MIME headers.
@defproc[(string->url [str string?]) url?]{
Parses the URL specified by @scheme[str] into a @scheme[url]
struct. The @scheme[string->url] procedure uses
@scheme[form-urlencoded->alist] when parsing the query, so it is
sensitive to the @scheme[current-alist-separator-mode] parameter for
Parses the URL specified by @racket[str] into a @racket[url]
struct. The @racket[string->url] procedure uses
@racket[form-urlencoded->alist] when parsing the query, so it is
sensitive to the @racket[current-alist-separator-mode] parameter for
determining the association separator.
If @scheme[str] starts with @scheme["file:"], then the path is always
If @racket[str] starts with @racket["file:"], then the path is always
parsed as an absolute path, and the parsing details depend on
@scheme[file-url-path-convention-type]:
@racket[file-url-path-convention-type]:
@itemize[
@item{@scheme['unix] : If @scheme["file:"] is followed by
@item{@racket['unix] : If @racket["file:"] is followed by
@litchar{//} and a non-@litchar{/}, then the first element
after the @litchar{//} is parsed as a host (and maybe port);
otherwise, the first element starts the path, and the host is
@scheme[""].}
@racket[""].}
@item{@scheme['windows] : If @scheme["file:"] is followed by
@item{@racket['windows] : If @racket["file:"] is followed by
@litchar{//}, then the @litchar{//} is stripped; the remainder
parsed as a Windows path. The host is always @scheme[""] and
the port is always @scheme[#f].}
parsed as a Windows path. The host is always @racket[""] and
the port is always @racket[#f].}
]}
@ -135,33 +135,33 @@ This function does not raise any exceptions.}
Turns a string into a URL, applying (what appear to be) Netscape's
conventions on automatically specifying the scheme: a string starting
with a slash gets the scheme @scheme["file"], while all others get the
scheme @scheme["http"].}
with a slash gets the scheme @racket["file"], while all others get the
scheme @racket["http"].}
@defproc[(url->string [URL url?]) string?]{
Generates a string corresponding to the contents of a @scheme[url]
struct. For a @scheme["file:"] URL, the URL must not be relative, the
Generates a string corresponding to the contents of a @racket[url]
struct. For a @racket["file:"] URL, the URL must not be relative, the
result always starts @litchar{file://}, and the interpretation of the
path depends on the value of @scheme[file-url-path-convention-type]:
path depends on the value of @racket[file-url-path-convention-type]:
@itemize[
@item{@scheme['unix] : Elements in @scheme[URL] are treated as path
@item{@racket['unix] : Elements in @racket[URL] are treated as path
elements. Empty strings in the path list are treated like
@scheme['same].}
@racket['same].}
@item{@scheme['windows] : If the first element is @scheme[""] then
@item{@racket['windows] : If the first element is @racket[""] then
the next two elements define the UNC root, and the rest of the
elements are treated as path elements. Empty strings in the
path list are treated like @scheme['same].}
path list are treated like @racket['same].}
]
The @scheme[url->string] procedure uses
@scheme[alist->form-urlencoded] when formatting the query, so it is
sensitive to the @scheme[current-alist-separator-mode] parameter for
The @racket[url->string] procedure uses
@racket[alist->form-urlencoded] when formatting the query, so it is
sensitive to the @racket[current-alist-separator-mode] parameter for
determining the association separator. The default is to separate
associations with a @litchar{&}.}
@ -169,21 +169,21 @@ associations with a @litchar{&}.}
@defproc[(path->url [path (or/c path-string? path-for-some-system?)])
url?]{
Converts a path to a @scheme[url].}
Converts a path to a @racket[url].}
@defproc[(url->path [URL url?]
[kind (one-of/c 'unix 'windows) (system-path-convention-type)])
path-for-some-system?]{
Converts @scheme[URL], which is assumed to be a @scheme["file"] URL,
Converts @racket[URL], which is assumed to be a @racket["file"] URL,
to a path.}
@defparam[file-url-path-convention-type kind (one-of/c 'unix 'windows)]{
Determines the default conversion to and from strings for
@scheme["file"] URLs. See @scheme[string->url] and @scheme[url->string].}
@racket["file"] URLs. See @racket[string->url] and @racket[url->string].}
@deftogether[(
@ -198,13 +198,13 @@ Determines the default conversion to and from strings for
input-port?]
)]{
Initiates a GET/HEAD/DELETE request for @scheme[URL] and returns a
Initiates a GET/HEAD/DELETE request for @racket[URL] and returns a
@tech{pure port} corresponding to the body of the response. The
optional list of strings can be used to send header lines to the
server.
The GET method is used to retrieve whatever information is identified
by @scheme[URL].
by @racket[URL].
The HEAD method is identical to GET, except the server must not return
a message body. The meta-information returned in a response to a HEAD
@ -212,9 +212,9 @@ request should be identical to the information in a response to a GET
request.
The DELETE method is used to delete the entity identified by
@scheme[URL].
@racket[URL].
@bold{Beware:} By default, @scheme["https"] scheme handling does not
@bold{Beware:} By default, @racket["https"] scheme handling does not
verify a server's certificate (i.e., it's equivalent of clicking
through a browser's warnings), so communication is safe, but the
identity of the server is not verified. To validate the server's
@ -222,8 +222,8 @@ certificate, set @racket[current-https-protocol] to a context created
with @racket[ssl-make-client-context], and enable certificate validation
in the context with @racket[ssl-set-verify!].
The @scheme["file"] scheme for URLs is handled only by
@scheme[get-pure-port], which uses @scheme[open-input-file], does not
The @racket["file"] scheme for URLs is handled only by
@racket[get-pure-port], which uses @racket[open-input-file], does not
handle exceptions, and ignores the optional strings.}
@deftogether[(
@ -238,9 +238,9 @@ handle exceptions, and ignores the optional strings.}
input-port?]
)]{
Like @scheme[get-pure-port], etc., but the resulting @tech{impure
Like @racket[get-pure-port], etc., but the resulting @tech{impure
port} contains both the returned headers and the body. The
@scheme["file"] URL scheme is not handled by these functions.}
@racket["file"] URL scheme is not handled by these functions.}
@deftogether[(
@defproc[(post-pure-port [URL url?]
@ -253,13 +253,13 @@ port} contains both the returned headers and the body. The
input-port?]
)]{
Initiates a POST/PUT request for @scheme[URL] and sends the
@scheme[post] byte string. The result is a @tech{pure port}, which
Initiates a POST/PUT request for @racket[URL] and sends the
@racket[post] byte string. The result is a @tech{pure port}, which
contains the body of the response is returned. The optional list of
strings can be used to send header lines to the server.
@bold{Beware:} See @racket[get-pure-port] for warnings about
@scheme["https"] certificate validation.}
@racket["https"] certificate validation.}
@deftogether[(
@ -273,7 +273,7 @@ strings can be used to send header lines to the server.
input-port?]
)]{
Like @scheme[post-pure-port] and @scheme[put-pure-port], but the
Like @racket[post-pure-port] and @racket[put-pure-port], but the
resulting @tech{impure port} contains both the returned headers and
body.}
@ -292,15 +292,15 @@ something like @litchar{1.0} or @litchar{1.1}, @nonterm{code} is an
exact integer for the response code, and @nonterm{message} is
arbitrary text without a return or newline.
The @schememodname[net/head] library provides procedures, such as
@scheme[extract-field] for manipulating the header.
The @racketmodname[net/head] library provides procedures, such as
@racket[extract-field] for manipulating the header.
Since web servers sometimes return mis-formatted replies,
@scheme[purify-port] is liberal in what it accepts as a header. as a
@racket[purify-port] is liberal in what it accepts as a header. as a
result, the result string may be ill formed, but it will either be the
empty string, or it will be a string matching the following regexp:
@schemeblock[
@racketblock[
#rx"^HTTP/.*?(\r\n\r\n|\n\n|\r\r)"
]}
@ -315,18 +315,18 @@ empty string, or it will be a string matching the following regexp:
[header (listof string?)])
any])]{
Given a URL and a @scheme[connect] procedure like
@scheme[get-pure-port] to convert the URL to an input port (either a
@tech{pure port} or @tech{impure port}), calls the @scheme[handle]
Given a URL and a @racket[connect] procedure like
@racket[get-pure-port] to convert the URL to an input port (either a
@tech{pure port} or @tech{impure port}), calls the @racket[handle]
procedure on the port and closes the port on return. The result of the
@scheme[handle] procedure is the result of @scheme[call/input-url].
@racket[handle] procedure is the result of @racket[call/input-url].
When a @scheme[header] argument is supplied, it is passed along to the
@scheme[connect] procedure.
When a @racket[header] argument is supplied, it is passed along to the
@racket[connect] procedure.
The connection is made in such a way that the port is closed before
@scheme[call/input-url] returns, no matter how it returns. In
particular, it is closed if @scheme[handle] raises an exception, or if
@racket[call/input-url] returns, no matter how it returns. In
particular, it is closed if @racket[handle] raises an exception, or if
the connection process is interruped by an asynchronous break
exception.}
@ -338,7 +338,7 @@ connections. Each mapping is a list of three elements:
@itemize[
@item{the URL scheme, such as @scheme["http"];}
@item{the URL scheme, such as @racket["http"];}
@item{the proxy server address; and}
@ -346,7 +346,7 @@ connections. Each mapping is a list of three elements:
]
Currently, the only proxiable scheme is @scheme["http"]. The default
Currently, the only proxiable scheme is @racket["http"]. The default
mapping is the empty list (i.e., no proxies).}
@defparam[current-https-protocol protocol (or/c ssl-client-context? symbol?)]{
@ -387,9 +387,9 @@ Note that @racket[net/url] does not provide the
@defsignature[url^ ()]{
Includes everything exported by the @schememodname[net/url] module
Includes everything exported by the @racketmodname[net/url] module
except @racket[current-https-protocol]. Note that the exports of
@schememodname[net/url] and the @racket[url^] signature do not include
@racketmodname[net/url] and the @racket[url^] signature do not include
@racket[current-connect-scheme].}
@defsignature[url+scheme^ (url^)]{

4
collects/net/scribblings/websocket.scrbl
View File

@ -34,7 +34,7 @@ This module provides the exports from @racketmodname[net/websocket/client] and @
Connects to the WebSocket server specified by @racket[u], providing @racket[headers] as additional headers.
Returns the connection handle.
}
This module also provides the exports from @racketmodname[net/websocket/conn].
@section{Server API}
@ -64,7 +64,7 @@ This module also provides the exports from @racketmodname[net/websocket/conn].
sole control until the WebSocket connection completes.
All other arguments are used as in a @secref["dispatch-server-unit" #:doc '(lib "web-server/scribblings/web-server-internal.scrbl")].
The @racket[#:tcp@] keyword is provided for building an SSL server.
}