finish up SRFI-98: docs and R6RS
svn: r17302
This commit is contained in:
parent
8996c49ee9
commit
9d9e586123
12
collects/srfi/%3a98.ss
Normal file
12
collects/srfi/%3a98.ss
Normal file
|
@ -0,0 +1,12 @@
|
|||
#lang scheme/base
|
||||
(require srfi/98
|
||||
scheme/mpair)
|
||||
|
||||
(provide get-environment-variable
|
||||
(rename-out (mpair:get-environment-variables
|
||||
get-environment-variables)))
|
||||
|
||||
(define (mpair:get-environment-variables)
|
||||
(list->mlist (map (lambda (pair)
|
||||
(mcons (car pair) (cdr pair)))
|
||||
(get-environment-variables))))
|
|
@ -1,76 +1,76 @@
|
|||
;; Copyright (c) 2009 Derick Eddington. All rights reserved.
|
||||
|
||||
;; Permission is hereby granted, free of charge, to any person obtaining a
|
||||
;; copy of this software and associated documentation files (the "Software"),
|
||||
;; to deal in the Software without restriction, including without limitation
|
||||
;; the rights to use, copy, modify, merge, publish, distribute, sublicense,
|
||||
;; and/or sell copies of the Software, and to permit persons to whom the
|
||||
;; Software is furnished to do so, subject to the following conditions:
|
||||
|
||||
;; The above copyright notice and this permission notice shall be included in
|
||||
;; all copies or substantial portions of the Software.
|
||||
|
||||
;; Except as contained in this notice, the name(s) of the above copyright
|
||||
;; holders shall not be used in advertising or otherwise to promote the sale,
|
||||
;; use or other dealings in this Software without prior written authorization.
|
||||
|
||||
;; THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
;; IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
;; FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
|
||||
;; THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
;; LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
|
||||
;; FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
|
||||
;; DEALINGS IN THE SOFTWARE.
|
||||
|
||||
;; Inspired by Danny Yoo's get-environment PLaneT package.
|
||||
|
||||
#lang scheme/base
|
||||
|
||||
(require scheme/foreign)
|
||||
(provide (rename-out (getenv get-environment-variable))
|
||||
get-environment-variables)
|
||||
|
||||
(unsafe!)
|
||||
|
||||
(define (get-environment-variables)
|
||||
(define (split-strings l)
|
||||
(for/list ([next (in-list l)])
|
||||
(let loop ((i 0) (len (string-length next)))
|
||||
(if (< i len)
|
||||
(if (char=? #\= (string-ref next i))
|
||||
(cons (substring next 0 i)
|
||||
(substring next (+ 1 i) len))
|
||||
(loop (+ 1 i) len))
|
||||
(cons next #f)))))
|
||||
(case (system-type)
|
||||
[(windows)
|
||||
(let ([get (get-ffi-obj "GetEnvironmentStringsW" #f (_fun #:abi 'stdcall -> _bytes))]
|
||||
[free (get-ffi-obj "FreeEnvironmentStringsW" #f (_fun #:abi 'stdcall _pointer -> _void))])
|
||||
(let* ([strs (get)]
|
||||
[len (let loop ([i 0])
|
||||
(if (and (= 0 (ptr-ref strs _byte i))
|
||||
(= 0 (ptr-ref strs _byte (+ i 1)))
|
||||
(= 0 (ptr-ref strs _byte (+ i 2)))
|
||||
(= 0 (ptr-ref strs _byte (+ i 3))))
|
||||
(+ i 4)
|
||||
(loop (+ i 2))))]
|
||||
[strs (cast strs _pointer (_bytes o len))])
|
||||
(begin0
|
||||
(split-strings
|
||||
(let loop ([pos 0])
|
||||
(let ([m (regexp-match-positions #rx"(?:..)*?\0\0" strs pos)])
|
||||
(if m
|
||||
(if (= (cdar m) (+ pos 2))
|
||||
null
|
||||
(cons (cast (ptr-add strs pos) _pointer _string/utf-16)
|
||||
(loop (cdar m))))
|
||||
null))))
|
||||
(free strs))))]
|
||||
[else
|
||||
(let ([environ (get-ffi-obj "environ" (ffi-lib #f) _pointer)])
|
||||
(split-strings
|
||||
(let loop ([i 0])
|
||||
(let ((next (ptr-ref environ _string/locale i)))
|
||||
(if next
|
||||
(cons next (loop (+ 1 i)))
|
||||
null)))))]))
|
||||
;; Copyright (c) 2009 Derick Eddington. All rights reserved.
|
||||
|
||||
;; Permission is hereby granted, free of charge, to any person obtaining a
|
||||
;; copy of this software and associated documentation files (the "Software"),
|
||||
;; to deal in the Software without restriction, including without limitation
|
||||
;; the rights to use, copy, modify, merge, publish, distribute, sublicense,
|
||||
;; and/or sell copies of the Software, and to permit persons to whom the
|
||||
;; Software is furnished to do so, subject to the following conditions:
|
||||
|
||||
;; The above copyright notice and this permission notice shall be included in
|
||||
;; all copies or substantial portions of the Software.
|
||||
|
||||
;; Except as contained in this notice, the name(s) of the above copyright
|
||||
;; holders shall not be used in advertising or otherwise to promote the sale,
|
||||
;; use or other dealings in this Software without prior written authorization.
|
||||
|
||||
;; THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
;; IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
;; FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
|
||||
;; THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
;; LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
|
||||
;; FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
|
||||
;; DEALINGS IN THE SOFTWARE.
|
||||
|
||||
;; Inspired by Danny Yoo's get-environment PLaneT package.
|
||||
|
||||
#lang scheme/base
|
||||
|
||||
(require scheme/foreign)
|
||||
(provide (rename-out (getenv get-environment-variable))
|
||||
get-environment-variables)
|
||||
|
||||
(unsafe!)
|
||||
|
||||
(define (get-environment-variables)
|
||||
(define (split-strings l)
|
||||
(for/list ([next (in-list l)])
|
||||
(let loop ((i 0) (len (string-length next)))
|
||||
(if (< i len)
|
||||
(if (char=? #\= (string-ref next i))
|
||||
(cons (substring next 0 i)
|
||||
(substring next (+ 1 i) len))
|
||||
(loop (+ 1 i) len))
|
||||
(cons next #f)))))
|
||||
(case (system-type)
|
||||
[(windows)
|
||||
(let ([get (get-ffi-obj "GetEnvironmentStringsW" #f (_fun #:abi 'stdcall -> _bytes))]
|
||||
[free (get-ffi-obj "FreeEnvironmentStringsW" #f (_fun #:abi 'stdcall _pointer -> _void))])
|
||||
(let* ([strs (get)]
|
||||
[len (let loop ([i 0])
|
||||
(if (and (= 0 (ptr-ref strs _byte i))
|
||||
(= 0 (ptr-ref strs _byte (+ i 1)))
|
||||
(= 0 (ptr-ref strs _byte (+ i 2)))
|
||||
(= 0 (ptr-ref strs _byte (+ i 3))))
|
||||
(+ i 4)
|
||||
(loop (+ i 2))))]
|
||||
[strs (cast strs _pointer (_bytes o len))])
|
||||
(begin0
|
||||
(split-strings
|
||||
(let loop ([pos 0])
|
||||
(let ([m (regexp-match-positions #rx"(?:..)*?\0\0" strs pos)])
|
||||
(if m
|
||||
(if (= (cdar m) (+ pos 2))
|
||||
null
|
||||
(cons (cast (ptr-add strs pos) _pointer _string/utf-16)
|
||||
(loop (cdar m))))
|
||||
null))))
|
||||
(free strs))))]
|
||||
[else
|
||||
(let ([environ (get-ffi-obj "environ" (ffi-lib #f) _pointer)])
|
||||
(split-strings
|
||||
(let loop ([i 0])
|
||||
(let ((next (ptr-ref environ _string/locale i)))
|
||||
(if next
|
||||
(cons next (loop (+ 1 i)))
|
||||
null)))))]))
|
||||
|
|
|
@ -964,4 +964,11 @@ This SRFI's syntax is part of PLT Scheme's default reader (no
|
|||
|
||||
@; ----------------------------------------
|
||||
|
||||
@srfi[98]{An interface to access environment variables}
|
||||
|
||||
@redirect[98 '((get-environment-variable #f "get-environment-variable")
|
||||
(get-environment-variables #f "get-environment-variables"))]
|
||||
|
||||
@; ----------------------------------------
|
||||
|
||||
@index-section[]
|
||||
|
|
191
doc/srfi-std/srfi-98.html
Normal file
191
doc/srfi-std/srfi-98.html
Normal file
|
@ -0,0 +1,191 @@
|
|||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
||||
<html><head>
|
||||
<meta http-equiv="content-type" content="text/html; charset=UTF-8"><!-- DO NOT EDIT THIS FILE-->
|
||||
<!-- Edit the .tex version instead-->
|
||||
|
||||
|
||||
<title>SRFI 98: An interface to access environment variables.</title>
|
||||
</head><body>
|
||||
|
||||
<h1>Title</h1>
|
||||
|
||||
An interface to access environment variables.
|
||||
|
||||
<h1>Author</h1>
|
||||
|
||||
Taro Minowa(Higepon)
|
||||
|
||||
<h1>Status</h1>
|
||||
|
||||
This SRFI is currently in ``final'' status. To see an explanation of
|
||||
each status that a SRFI can hold, see <a href="http://srfi.schemers.org/srfi-process.html">here</a>.
|
||||
|
||||
To provide input on this SRFI, please send email to
|
||||
<a href="mailto:srfi%20minus%2098%20at%20srfi%20dot%20schemers%20dot%20org">
|
||||
<code><srfi minus 98 at srfi dot schemers dot org></code></a>. See
|
||||
<a href="http://srfi.schemers.org/srfi-list-subscribe.html">instructions here</a> to subscribe to
|
||||
the list. You can access the discusssion via
|
||||
<a href="http://srfi.schemers.org/srfi-98/mail-archive/maillist.html">the archive of the mailing list</a>.
|
||||
You can access
|
||||
post-finalization messages via
|
||||
<a href="http://srfi.schemers.org/srfi-98/post-mail-archive/maillist.html">
|
||||
the archive of the mailing list</a>.
|
||||
<p></p><ul>
|
||||
|
||||
<li>Received: <a href="http://srfi.schemers.org/cgi-bin/viewcvs.cgi/*checkout*/srfi/srfi-98/srfi-98.html?rev=1.2">2008/07/06</a></li>
|
||||
<li>Draft: 2008/07/06 - 2008/09/06</li>
|
||||
<li>Revised: <a href="http://srfi.schemers.org/cgi-bin/viewcvs.cgi/*checkout*/srfi/srfi-98/srfi-98.html?rev=1.3">2008/07/18</a></li>
|
||||
<li>Revised: <a href="http://srfi.schemers.org/cgi-bin/viewcvs.cgi/*checkout*/srfi/srfi-98/srfi-98.html?rev=1.4">2008/07/18</a></li>
|
||||
<li>Revised: <a href="http://srfi.schemers.org/cgi-bin/viewcvs.cgi/*checkout*/srfi/srfi-98/srfi-98.html?rev=1.5">2008/08/14</a></li>
|
||||
<li>Final: <a href="http://srfi.schemers.org/cgi-bin/viewcvs.cgi/*checkout*/srfi/srfi-98/srfi-98.html?rev=1.7">2008/09/19</a></li>
|
||||
<li>R6RS library name: <a href="http://srfi.schemers.org/cgi-bin/viewcvs.cgi/*checkout*/srfi/srfi-98/srfi-98.html?rev=1.8">2009/02/16</a></li>
|
||||
</ul>
|
||||
|
||||
<h1>Abstract</h1>
|
||||
This SRFI specifies the procedure get-environment-variable, which gets
|
||||
the value of the specified environment variable, and the procedure
|
||||
get-environment-variables, which gets an association list of all
|
||||
environment variables.
|
||||
|
||||
<h1>Rationale</h1>
|
||||
<p>Most operating systems provide a mechanism for passing auxiliary
|
||||
parameters implicitly to child processes. Usually, this mechanism is
|
||||
called "the environment", and is conceptually a map from string names
|
||||
to string values. The string names are called enviornment
|
||||
variables.</p>
|
||||
|
||||
<p>Some applications rely on environment variables to modify their
|
||||
behavior according to local settings. Also, various established
|
||||
protocols rely on environment variables as a form of interprocess
|
||||
communication. For example, most implementations of the common
|
||||
gateway interface (CGI) use environment variables to pass
|
||||
Meta-Variables from the server to the script <a href="#0.1_cgi">[1]</a>.
|
||||
Environment variables are also required
|
||||
by <a href="http://srfi.schemers.org/srfi-96/srfi-96.html" title="SRFI
|
||||
96: SLIB Prerequisites">SRFI 96: SLIB Prerequisites</a>.
|
||||
Providing a means to access environment variables is therefore
|
||||
indispensable for writing practical programs in Scheme.
|
||||
</p>
|
||||
<p>Most widely-used Scheme implementations provide a function for
|
||||
getting the value of a specified environment variable. The name for
|
||||
this function is usually getenv, but varies (<a href="#0.1_appendix">see
|
||||
below</a>). Some implementations also provide a way to get all the
|
||||
environment variables, but others do not.</p>
|
||||
<p>This SRFI specifies a uniform interface for accessing environment
|
||||
variables. That should make it easier to write portable programs
|
||||
that need access to their environment.
|
||||
For example, a CGI program may portably obtain the values of the
|
||||
Meta-Variables "QUERY_STRING", "CONTENT_LENGTH" and
|
||||
"REQUEST_METHOD" as in the following examples:</p>
|
||||
<pre>(get-environment-variable "QUERY_STRING") => "foo=bar&huga=hige"
|
||||
(get-environment-variable "CONTENT_LENGTH") => "512"
|
||||
(get-environment-variable "REQUEST_METHOD") => "post"
|
||||
</pre>
|
||||
|
||||
<p><a name="0.1_cgi">[1]</a> The Common Gateway Interface (CGI) Version 1.1, RFC3875, <a href="http://www.ietf.org/rfc/rfc3875" target="_blank">http://www.ietf.org/rfc/rfc3875</a>.</p>
|
||||
<h1>Specification</h1>
|
||||
<pre>R6RS library name</pre>
|
||||
The following two procedures belong to the R6RS library named (srfi :98 os-environment-variables).
|
||||
<pre>Function: <a name="get-environment-variable">get-environment-variable</a> name</pre>Returns the value of
|
||||
the named environment variable as a string, or #f if the named
|
||||
environment variable is not found. The name argument is expected to be
|
||||
a string.
|
||||
get-environment-variable may use
|
||||
locale-setting information to encode the name and decode the value of
|
||||
the environment variable.
|
||||
If get-environment-variable can't decode the value, get-environment-variable may raise an exception.
|
||||
<pre>(get-environment-variable "PATH") => "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"
|
||||
</pre>
|
||||
<pre>Function: <a name="get-environment-variables">get-environment-variables</a></pre>
|
||||
Returns names and values of all the environment variables as an a-list.
|
||||
The same decoding considerations as for get-environment-variable apply.
|
||||
<pre>(get-environment-variables) => (("PATH" . "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin") ("USERNAME" . "taro"))
|
||||
</pre>
|
||||
|
||||
<h1>Implementation</h1>
|
||||
<h2>Gauche</h2>
|
||||
<pre>(define get-environment-variable sys-getenv)
|
||||
(define get-environment-variables sys-environ->alist)
|
||||
</pre>
|
||||
<h2>Scheme48</h2>
|
||||
<pre>(define (get-environment-variable name)
|
||||
(cond
|
||||
((lookup-environment-variable name) => os-string->string)
|
||||
(else #f)))
|
||||
(define (get-environment-variables)
|
||||
(map (lambda (p)
|
||||
(cons (os-string->string (car p)) (os-string->string (cdr p))))
|
||||
(environment-alist)))
|
||||
</pre>
|
||||
<h2>scsh</h2>
|
||||
<pre>(define get-environment-variable getenv)
|
||||
(define get-environment-variables env->alist)
|
||||
</pre>
|
||||
|
||||
<h2>SCM</h2>
|
||||
<pre>(define get-environment-variable getenv)
|
||||
(define get-environment-variables getenv)
|
||||
</pre>
|
||||
|
||||
<h1>Issues</h1>
|
||||
<p>get-environment-variable is expected to return a "Scheme string".
|
||||
Unfortunately, many current platforms, including POSIX-like ones, do
|
||||
not require environment variables to be interpretable as sequences of
|
||||
characters. In particular, environment variables can be used to name
|
||||
files, and filenames on the system can amount to NULL-terminated byte
|
||||
vectors, which, if the Scheme program were to collect uninterpreted
|
||||
and pass to, say, the open call, would work just fine, but which might
|
||||
not represent a string in the particular encoding the program expects.
|
||||
While in principle it may be desirable to provide a mechanism for
|
||||
accessing environment variables raw, this SRFI specifies a "string"
|
||||
return type because that best represents the consensus of existing
|
||||
implementations, and captures the semantically desirable behavior in
|
||||
the common case that the byte sequence is interpretable as a string.</p>
|
||||
|
||||
<a name="0.1_appendix"></a>
|
||||
<h1>Appendix: Existing implementations</h1>
|
||||
<table border="1">
|
||||
<tbody><tr><th>Scheme implementation</th><th>get environment variable</th><th>get all the environment variables as an a-list</th></tr>
|
||||
<tr><td>Bigloo</td><td>(getenv name) => (or string? false) name:string?</td><td> </td></tr>
|
||||
<tr><td>CHICKEN</td><td>(getenv name) => (or string? false) name:string?</td><td> </td></tr>
|
||||
<tr><td>Gambit</td><td>(getenv name . <default>) =>(or string? <default> <Unbound OS environment variable error>) name:string?</td><td> </td></tr>
|
||||
|
||||
<tr><td>Gauche</td><td>(sys-getenv name) => (or string? false) name:string?</td><td>(sys-environ)</td></tr>
|
||||
<tr><td>Guile</td><td>(getenv name) => (or string? false) name:string?</td><td> </td></tr>
|
||||
<tr><td>PLT</td><td>(getenv name) => (or string? false) name:string?</td><td> </td></tr>
|
||||
<tr><td>MIT/GNU Scheme</td><td>(get-environment-variable name) => (or string? false) name:string?</td><td> </td></tr>
|
||||
<tr><td>Scheme48</td><td>(lookup-environment-variable name) => (or string? false) name:string?</td><td>(environment-alist)</td></tr>
|
||||
|
||||
<tr><td>SLIB</td><td>(getenv name) => (or string? false) name:string?</td><td> </td></tr>
|
||||
<tr><td>STk</td><td>(getenv name) => (or string? false) name:string?</td><td> </td></tr>
|
||||
<tr><td>STklos</td><td>(getenv name) => (or string? false) name:string?</td><td>(getenv)</td></tr>
|
||||
<tr><td>SCM</td><td>(getenv name) => (or string? false) name:string?</td><td>(getenv)</td></tr>
|
||||
</tbody></table>
|
||||
<h1>Acknowledgements</h1>
|
||||
Thanks to Shiro Kawai, Alexey Radul, jmuk, Kokosabu, leque and all the members of the #Lisp_Scheme IRC channel on Freenode.
|
||||
<h1>Copyright</h1>
|
||||
Copyright (C) Taro Minowa(Higepon) (2008). All Rights Reserved.
|
||||
<p>
|
||||
Permission is hereby granted, free of charge, to any person obtaining a
|
||||
copy of this software and associated documentation files (the
|
||||
"Software"), to deal in the Software without restriction, including
|
||||
without limitation the rights to use, copy, modify, merge, publish,
|
||||
distribute, sublicense, and/or sell copies of the Software, and to
|
||||
permit persons to whom the Software is furnished to do so, subject to
|
||||
the following conditions:
|
||||
</p>
|
||||
<p>
|
||||
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
|
||||
</p>
|
||||
<p>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
||||
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
||||
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
||||
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
|
||||
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
|
||||
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
|
||||
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
</p>
|
||||
<hr>
|
||||
<address>Editor: <a href="mailto:srfi-editors%20at%20srfi%20dot%20schemers%20dot%20org">Mike Sperber</a></address>
|
||||
<!-- Last modified: Sun Jan 28 14:21:14 MET 2007 -->
|
||||
</body></html>
|
Loading…
Reference in New Issue
Block a user