Changes between Version 2 and Version 3 of PortsCowan


Ignore:
Timestamp:
09/02/10 09:47:05 (7 years ago)
Author:
cowan
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • PortsCowan

    v2 v3  
    55== Port model == 
    66 
    7 In 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. 
     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 ASCII encoding does not require a separate character buffer or encoding translation table, only a few bits for newline translation and case sensitivity. 
    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. 
     
    3535Specifies if Scheme symbols are read from the port case-sensitively or not.  The value `#f` means that upper-case letters in symbols are translated to lower case unless escaped; `#t` means that no translation is done.  The default value is implementation-dependent. 
    3636 
     37Implementations MAY support other keys. 
     38 
    3739 
    3840== Core module == 
     
    6264From R6RS.  This is a binary port whose character encoding is implementation-dependent. 
    6365 
    64 `(force-output ` [ ''output-port'' ] ` ` [ ''character-only?'' ]`)` 
     66`(flush-output-port ` [ ''output-port'' ] ` ` [ ''character-only?'' ]`)` 
    6567 
    66 Drains 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. 
     68Same as R6RS, except that if the ''output-port'' is omitted, the default port is the current output port.  Drains the character buffer of ''output-port'', if any.  Then, if the port is a binary port, drains the binary buffer, if any. 
    6769 
    6870`(close-input-port `''port''`)` 
     
    7072`(close-output-port `''port''`)` 
    7173 
    72 From R5RS.  `Close-output-port` implicitly calls `force-output` first. 
     74From R5RS.  `Close-output-port` implicitly calls `flush-output-port` first. 
    7375 
    7476`(close-port)` 
     
    8486`(character-port? `''port''`)` 
    8587 
    86 Returns `#t` if ''port'' is a character port.  SRFI 91 calls this `char-port`. 
     88Returns `#t` if ''port'' is a character port.  SRFI 91 calls this `char-port`.  Implementations may define other kinds of character ports. 
    8789 
    8890`(read-char `[ ''character-input-port'' ]`)` 
     
    100102`(read-line `[ ''character-input-port'' ]`)` 
    101103 
    102 Same 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. 
     104Same 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). This is a convenience function. 
    103105 
    104106`(open-input-string `''string''`)` 
     
    112114=== Binary I/O === 
    113115 
    114 Note that string ports are character ports, but not binary ports. 
     116Note that string ports are character ports, but not binary ports, so these procedures do not apply to them.  Implementations MAY support other kinds of binary ports such as process ports or stream socket ports. 
    115117 
    116118`(binary-port? `''port''`)` 
    117119 
    118 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?`. 
     120Returns `#t` if ''port'' is a binary port.  SRFI 91 calls this `byte-port?`. 
    119121 
    120122`(read-u8 `[ ''binary-input-port'' ]`)` 
     
    127129 
    128130The direct binary analogues of `read-char`, `write-char`, `newline`, `peek-char`, and `char-ready?` respectively.  They return an exact integer between 0 and 255 rather than a character.  SRFI 91 talks of `byte` rather than `u8`. 
     131 
     132`(open-input-blob `''blob''`)` 
     133 
     134`(open-output-blob)` 
     135 
     136`(get-output-blob `''output-blob-port''`)` 
     137 
     138Blobs are (possibly specialized) vectors containing integers from 0 to 255 inclusive.  These procedures are the binary analogues of the SRFI 6 string port procedures.  The term ''blob'' is subject to change. 
     139 
    129140 
    130141 
     
    158169These 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. 
    159170 
    160 Note that implementations may provide ports that are not character ports, and extend these procedure to work on them. 
     171Note that implementations may provide ports that are not character ports, such as directory ports or vector ports, and extend these procedure to work on them. 
    161172 
    162173=== Read Module ===