From 57a156351dae67ed3af0bea2cc39ebb56a1a2833 Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Thu, 19 Nov 2015 16:10:01 -0700 Subject: [PATCH] doc refinments and corrections Adjust docs to match the final, less exposed mechanism for initializing parameters from environment variables. --- net-doc/net/scribblings/url.scrbl | 71 +++++++++++++------------------ 1 file changed, 29 insertions(+), 42 deletions(-) diff --git a/net-doc/net/scribblings/url.scrbl b/net-doc/net/scribblings/url.scrbl index 04f951105e..409215bc25 100644 --- a/net-doc/net/scribblings/url.scrbl +++ b/net-doc/net/scribblings/url.scrbl @@ -479,8 +479,8 @@ connections. Each mapping is a list of three elements: @itemize[ - @item{the URL scheme, such as @racket["http"]; @racket[proxiable-url-schemes] lists the URL schemes - that can be proxied. Currently, the only proxiable scheme is @racket["http"].} + @item{the URL scheme, such as @racket["http"], where @racket[proxiable-url-schemes] lists the URL schemes + that can be proxied; currently, the only proxiable scheme is @racket["http"];} @item{the proxy server address; and} @@ -488,28 +488,26 @@ connections. Each mapping is a list of three elements: ] -@racket[current-proxy-servers] can be configured from the environment. If -it has no entry for a particular URL scheme, then the environment -variables @litchar["plt_http_proxy"] and @litchar["http_proxy"] are used. This is done via a promise -that is forced by @racket[proxy-server-for]. +The initial value of @racket[current-proxy-servers] is configured on demand from the +environment variables @indexed-envvar{plt_http_proxy} and @indexed-envvar{http_proxy}, +where the former takes precedence over the latter. +Each environment variable contains a single URL of the form +@litchar{http://}@nonterm{hostname}@litchar{:}@nonterm{portno}. If any other components of the URL are provided, +an error will be logged to a @racket[net/url] logger. -The environment variables contain a single URL of the form: -@litchar{http://hostname:portno}. If any other components of the URL are provided, -an error will be logged to the @racket[net/url] logger. +The default mapping is the empty list (i.e., no proxies).} -The default mapping is the empty list (i.e., no proxies). -} @defparam[current-no-proxy-servers dest-hosts-list (listof (or/c string? regexp?))]{ A parameter that determines which servers will be accessed directly -i.e. without resort to @racket[current-proxy-servers]. It is a list of: +i.e. without resort to @racket[current-proxy-servers]. It is a list of @itemize[ - @item{strings that match host names exactly} + @item{strings that match host names exactly; and} - @item{regexps that match host by pattern} + @item{regexps that match host by pattern.} ] @@ -518,49 +516,38 @@ host name is checked against @racket[current-no-proxy-servers]. The proxy is used if and only if the host name does not match (by the definition above) any in the list. -@racket[current-no-proxy-servers] can be configured from the environment. -The environment variables @litchar["plt_no_proxy"] and @litchar["no_proxy"] -are used. This is done via a promise that is forced by @racket[proxy-server-for]. - -These environment variables are comma-separated list of ``patterns''. -A pattern from an environment variable is one of: +The initial value of @racket[current-no-proxy-servers] is configured on demand from the +environment variables @indexed-envvar{plt_no_proxy} and @indexed-envvar{no_proxy}, +where the former takes precedence over the latter. +Each environment variable's value is parsed as a comma-separated list of ``patterns,'' +where a pattern is one of: + @margin-note{This parsing is consistent with the @litchar["no_proxy"] environment + variable used by other software, albeit not consistent with the regexps + stored in @racket[current-no-proxy-servers].} @itemize[ - @item{a string beginning with a @litchar{.} (period). This is converted to a - regexp which performs a suffix match on a destination host name, - e.g. @litchar[".racket-lang.org"] will match destinations of + @item{a string beginning with a @litchar{.} (period): converted to a + regexp that performs a suffix match on a destination host name; + e.g. @litchar[".racket-lang.org"] matches destinations of @litchar["doc.racket-lang.org"], @litchar["pkgs.racket-lang.org"], but neither @litchar["doc.bracket-lang.org"] nor - @litchar["pkgs.racket-lang.org.uk"]. - @margin-note{This is consistent with the @litchar["no_proxy"] environment - variable used by other software, albeit not consistent with the regexps - stored in @racket[current-no-proxy-servers]} + @litchar["pkgs.racket-lang.org.uk"]; } - @item{any other string -- is converted to a regexp which matches the string exactly} + @item{any other string: converted to a regexp that matches the string exactly.} ]} + @defproc[(proxy-server-for [url-schm string?] [dest-host-name (or/c false/c string?) #f]) - (list/c string? string? (integer-in 0 65535))]{ + (or/c (list/c string? string? (integer-in 0 65535)) #f)]{ + Returns the proxy server entry for the combination of @racket[url-schm] -and @racket[host], or @racket[#f] if no proxy is to be used. +and @racket[host], or @racket[#f] if no proxy is to be used.} -The process that loads environment variables into @racket[current-proxy-servers] -and @racket[current-no-proxy-servers] is held on a promise that is forced by -@racket[proxy-server-for]. This means that: - - @itemize[ - - @item{calling @racket[proxy-server-for] might change the list of - @racket[current-proxy-servers] and @racket[current-no-proxy-servers]} - - @item{to resolve proxy/no-proxy values from the environment, call @racket[(proxy-server-for #f)]} - -]} @defproc[(url-exception? [x any/c]) boolean?]{