Changes between Version 1 and Version 2 of PortsCowan


Ignore:
Timestamp:
09/02/10 09:16:13 (7 years ago)
Author:
cowan
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • PortsCowan

    v1 v2  
    55== Port model == 
    66 
    7 In this proposal, as in Gambit Scheme and SRFI 91, there are two classes of ports, binary ports and character ports.  Unusually, ''every binary port is automatically a character port.''  This implies that some character encoding must be associated with each binary port so that character I/O can be performed on it.  The only encoding that implementations MUST support is ASCII, so this is relatively cost-free, since for ASCII there need be no separate character buffer or encoding translation table. 
     7In this proposal, there are two kinds of ports, binary ports and character ports.  Unusually, ''every binary port is automatically a character port'', though not vice versa.  This implies that some character encoding must be associated with each binary port so that character I/O can be performed on it.  The only encoding that implementations MUST support is ASCII, so this is relatively cost-free, since for ASCII there need be no separate character buffer or encoding translation table. 
    88 
    99This proposal does not specify any way to create a bidirectional port, but allows for their possible existence in an implementation.  Sockets, terminals, and pipes are all examples. 
     
    1515`path:` 
    1616 
    17 Specifies the filename.  The interpretation of filenames is implementation-dependent.  There is no default value; this key MUST be present. 
     17Specifies the filename.  The interpretation of filenames is implementation-dependent.  There is no default value, but implementations MAY accept other keys in lieu of this one for opening non-file ports. 
    1818 
    1919`buffering:` 
    2020 
    21 Specifies what kind of buffering is present.  The value `#f` means there is no buffering; `binary` means that there is a binary buffer but no character buffer; `#t` means there both character and binary buffering.  Other values MAY be specified by an implementation.  Buffer sizes are implementation-dependent.  The default value is implementation-dependent. 
     21Specifies what kind of buffering is present.  The value `#f` means there is no buffering; `binary` means that there is a binary buffer but no character buffer; `#t` means there are both character and binary buffering.  Other values MAY be specified by an implementation.  Buffer sizes are implementation-dependent.  The default value is implementation-dependent. 
    2222 
    2323`encoding:` 
    2424 
    25 Specifies what character encoding to use on a binary port.  The value `US-ASCII` MUST be supported.  The values `ISO-8859-1`, and `UTF-8` SHOULD be supported if the implementation contains the appropriate repertoire of characters.  Other values MAY be supported.  The default value is implementation-dependent. 
     25Specifies what character encoding to use on a binary port.  The value `US-ASCII` MUST be supported.  The values `ISO-8859-1` and `UTF-8` SHOULD be supported if the implementation contains the appropriate repertoire of characters.  Other values MAY be supported.  The default value is implementation-dependent. 
    2626 
    2727If a BOM (Byte Order Mark, U+FEFF) is present at the beginning of input on a port encoded as UTF-8, it is skipped.  A BOM is not automatically written on output.  Implementations MAY provide a way around this. 
     
    4848Same as R5RS, but also return true on input/output ports. 
    4949 
    50 `port?` 
     50`(port? `''obj''`)` 
    5151 
    5252Mentioned in R5RS section 3 but not in section 6.6.  Part of R6RS. 
     
    5656`(current-output-port)` 
    5757 
    58 Same as R5RS.  These are binary ports whose character encoding is implementation-specified. 
     58Same as R5RS.  These are binary ports whose character encoding is implementation-dependent. 
    5959 
    6060`(current-error-port)` 
    6161 
    62 From R6RS.  This is a binary port whose character encoding is implementation-specified. 
     62From R6RS.  This is a binary port whose character encoding is implementation-dependent. 
    6363 
    6464`(force-output ` [ ''output-port'' ] ` ` [ ''character-only?'' ]`)` 
    6565 
    66 Drains the character buffer of ''output-port'', if any.  Then, if the port is an output port and the second argument is false, drains the binary buffer, if any.  The default output port is the current output port. 
     66Drains the character buffer of ''output-port'', if any.  Then, if the port is a binary port and the second argument is false, drains the binary buffer, if any.  The default port is the current output port. 
    6767 
    6868`(close-input-port `''port''`)` 
     
    8686Returns `#t` if ''port'' is a character port.  SRFI 91 calls this `char-port`. 
    8787 
    88 `(read-char `[ ''input-port'' ]`)` 
     88`(read-char `[ ''character-input-port'' ]`)` 
    8989 
    90 `(write-char `[ ''output-port'' ]`)` 
     90`(write-char `[ ''character-output-port'' ]`)` 
    9191 
    92 `(newline `[ ''output-port'' ]`)` 
     92`(newline `[ ''character-output-port'' ]`)` 
    9393 
    94 `(peek-char `[ ''input-port'' ]`)` 
     94`(peek-char `[ ''character-input-port'' ]`)` 
    9595 
    96 `(char-ready? `[ ''input-port'' ]`)` 
     96`(char-ready? `[ ''character-input-port'' ]`)` 
    9797 
    98 Same as R5RS. 
     98Same as R5RS.  It is an error to output characters not present in the encoding of a ''character-output-port''. 
    9999 
    100 `(read-line `[ ''port'' ]`)` 
     100`(read-line `[ ''character-input-port'' ]`)` 
    101101 
    102 Same as R6RS.  Reads a line from ''port'' (or the current input port) terminated by a `#\newline` character.  This is a convenience function. 
     102Same as R6RS.  Reads a line from ''port'' (or the current input port) terminated by a `#\newline` character (which may be the result of newline conversion in the port).  The default port is the current input port.  This is a convenience function. 
    103103 
    104104`(open-input-string `''string''`)` 
    105105 
    106 Same as SRFI 6. 
    107  
    108106`(open-output-string)` 
    109  
    110 Same as SRFI 6.  String ports are character ports, but not binary ports. 
    111107 
    112108`(get-output-string `''output-string-port''`)` 
     
    116112=== Binary I/O === 
    117113 
     114Note that string ports are character ports, but not binary ports. 
     115 
    118116`(binary-port? `''port''`)` 
    119117 
    120 Returns `#t` if ''port'' is a binary port.  String ports are character ports, but not binary ports; file ports are both.  SRFI 91 calls this `byte-port`. 
     118Returns `#t` if ''port'' is a binary port.  String ports are character ports but not binary ports; file ports are both.  SRFI 91 calls this `byte-port?`. 
    121119 
    122120`(read-u8 `[ ''binary-input-port'' ]`)` 
     
    153151`(file-exists? `''filename''`)` 
    154152 
    155 Same as R6RS.  Only string filenames are supported. 
     153Same as R6RS.  Only string ''filename''s are supported. 
    156154 
    157155 
    158 == Read Module == 
     156== Read and Write Modules == 
    159157 
    160 This is a separate module because many systems, especially embedded ones, don't require the ability to read general Scheme objects, and very small implementations may not want the overhead of a Scheme parser. 
     158These procedures are not in the core because many systems, especially embedded ones, don't require the ability to read or write general Scheme objects, and very small implementations may not want the overhead of a Scheme parser.  Writing may be useful even when reading is not, which is why there are two modules. 
     159 
     160Note that implementations may provide ports that are not character ports, and extend these procedure to work on them. 
     161 
     162=== Read Module === 
    161163 
    162164`(read ` [ ''input-port'' ]`)` 
     
    164166Same as R5RS. 
    165167 
    166  
    167 == Write Module == 
    168  
    169 This is a separate module for the same reasons as the read module. 
     168=== Write Module === 
    170169 
    171170`(write `''obj'' [ ''output-port'' ]`)` 
    172171 
    173 Same as R5RS, but specifies that only ASCII characters may be output (for re-readability).  Non-ASCII characters in symbols, strings, and character literals MUST be escaped. 
     172Same as R5RS, but specifies that only ASCII characters may be output (for re-readability).  Non-ASCII characters in symbols, strings, and character literals MUST be escaped.     
    174173 
    175174`(display `''obj'' [ ''port'' ]`)` 
    176175 
    177 Same as R5RS.  It is an error to output characters not present in the encoding of ''output-port''. 
    178  
     176Same as R5RS.  It is an error to output characters not present in the encoding of ''output-port''.  
    179177 
    180178== Thanks ==