home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 7 / Apprentice-Release7.iso / Source Code / C / Applications / Moscow ML 1.42 / lib / TextIO.sig < prev    next >
Encoding:
Text File  |  1997-08-18  |  6.9 KB  |  191 lines  |  [TEXT/Moml]
  1. (* TextIO -- SML Basis Library *)
  2.  
  3. type elem   = Char.char
  4. type vector = string
  5.  
  6. (* Text input: *)
  7.  
  8. type instream 
  9.  
  10. val openIn       : string -> instream
  11. val closeIn      : instream -> unit
  12. val input        : instream -> vector
  13. val inputAll     : instream -> vector
  14. val inputNoBlock : instream -> vector option
  15. val input1       : instream -> elem option
  16. val inputN       : instream * int -> vector
  17. val inputLine    : instream -> string
  18. val endOfStream  : instream -> bool
  19. val lookahead    : instream -> elem option
  20.  
  21. type cs (* character source state *)
  22.  
  23. val scanStream   : ((char, cs) StringCvt.reader -> ('a, cs) StringCvt.reader) 
  24.                    -> instream -> 'a option
  25.  
  26. val stdIn        : instream
  27.  
  28. (* Text output: *)
  29.  
  30. type outstream
  31.  
  32. val openOut      : string -> outstream
  33. val openAppend   : string -> outstream
  34. val closeOut     : outstream -> unit
  35. val output       : outstream * vector -> unit
  36. val output1      : outstream * elem -> unit
  37. val outputSubstr : outstream * substring -> unit
  38. val flushOut     : outstream -> unit
  39.  
  40. val stdOut       : outstream
  41. val stdErr       : outstream
  42.  
  43. val print        : string -> unit
  44.  
  45. (* This structure provides input/output functions on text streams.
  46.    The functions are state-based: reading from or writing to a stream
  47.    changes the state of the stream.  The streams are buffered: output
  48.    to a stream may not immediately affect the underlying file or
  49.    device.
  50.  
  51.    Note that under DOS, Windows, OS/2, and MacOS, text streams will be
  52.    `translated' by converting (e.g.) the double newline CRLF to a
  53.    single newline character \n.
  54.  
  55.    Type instream is the type of state-based characters input streams,
  56.    and type outstream is the type of state-based character output
  57.    streams.
  58.  
  59.    Type elem is the type char of characters, and type vector is the
  60.    type of character vectors (strings).
  61.  
  62.  
  63.    TEXT INPUT:
  64.  
  65.    [openIn s] creates a new instream associated with the file named s.
  66.    Raises Io.Io is file s does not exist or is not accessible.
  67.  
  68.    [closeIn istr] closes stream istr.  Has no effect if istr is closed
  69.    already.  Further operations on istr will behave as if istr is at
  70.    end of stream (that is, will return "" or NONE or true).
  71.  
  72.    [input istr] reads some elements from istr, returning a vector v of
  73.    those elements.  The vector will be empty (size v = 0) if and only
  74.    if istr is at end of stream or is closed.  May block (not return
  75.    until data are available in the external world).
  76.  
  77.    [inputAll istr] reads and returns the string v of all characters
  78.    remaining in istr up to end of stream.
  79.  
  80.    [inputNoBlock istr] returns SOME(v) if some elements v can be read
  81.    without blocking; returns SOME("") if it can be determined without
  82.    blocking that istr is at end of stream; returns NONE otherwise.  If
  83.    istr does not support non-blocking input, raises
  84.    Io.NonblockingNotSupported.
  85.  
  86.    [input1 istr] returns SOME(e) if at least one element e of istr is
  87.    available; returns NONE if istr is at end of stream or is closed;
  88.    blocks if necessary until one of these conditions holds.
  89.  
  90.    [inputN(istr, n)] returns the next n characters from istr as a
  91.    string, if that many are available; returns all remaining
  92.    characters if end of stream is reached before n characters are
  93.    available; blocks if necessary until one of these conditions holds.
  94.    (This is the behaviour of the `input' function prescribed in the
  95.    Definition of Standard ML).
  96.  
  97.    [inputLine istr] returns one line of text, including the
  98.    terminating newline character.  If end of stream is reached before
  99.    a newline character, then the remaining part of the stream is
  100.    returned, with a newline character added.  If istr is at end of
  101.    stream or is closed, then the empty string "" is returned.
  102.  
  103.    [endOfStream istr] returns false if any elements are available in
  104.    istr; returns true if istr is at end of stream or closed; blocks if
  105.    necessary until one of these conditions holds.
  106.  
  107.    [lookahead istr] returns SOME(e) where e is the next element in the
  108.    stream; returns NONE if istr is at end of stream or is closed;
  109.    blocks if necessary until one of these conditions holds.  Does not
  110.    advance the stream.
  111.  
  112.    [stdIn] is the buffered state-based standard input stream.
  113.  
  114.    [scanStream scan istr] turns the instream istr into a character
  115.    source and applies the scanner `scan' to that source.  See
  116.    StringCvt for more on character sources and scanners.  The Moscow
  117.    ML implementation currently can backtrack only 512 characters, and
  118.    raises Fail if the scanner backtracks further than that.
  119.  
  120.  
  121.    TEXT OUTPUT:
  122.  
  123.    [openOut s] creates a new outstream associated with the file named
  124.    s.  If file s does not exist, and the directory exists and is
  125.    writable, then a new file is created.  If file s exists, it is
  126.    truncated (any existing contents are lost).
  127.  
  128.    [openAppend s] creates a new outstream associated with the file
  129.    named s.  If file s does not exist, and the directory exists and is
  130.    writable, then a new file is created.  If file s exists, any
  131.    existing contents are retained, and output goes at the end of the
  132.    file.
  133.  
  134.    [closeOut ostr] closes stream ostr; further operations on ostr
  135.    (except for additional close operations) will raise exception Io.Io.
  136.  
  137.    [output(ostr, v)] writes the string v on outstream ostr.
  138.  
  139.    [output1(ostr, e)] writes the character e on outstream ostr.
  140.  
  141.    [flushOut ostr] flushes the outstream ostr, so that all data
  142.    written to ostr becomes available to the underlying file or device.
  143.  
  144.    [stdOut] is the buffered state-based standard output stream.
  145.  
  146.    [stdErr] is the unbuffered state-based standard error stream.  That
  147.    is, it is always kept flushed, so flushOut(stdErr) is redundant.
  148.  
  149.  
  150.    The functions below are not yet implemented:
  151.  
  152.    [setPosIn(istr, i)] sets istr to the (untranslated) position i.
  153.    Raises Io.Io if not supported on istr.
  154.  
  155.    [getPosIn istr] returns the (untranslated) current position of istr.
  156.    Raises Io.Io if not supported on istr.
  157.  
  158.    [endPosIn istr] returns the (untranslated) last position of istr.
  159.    Because of translation, one cannot expect to read 
  160.     endPosIn istr - getPosIn istr
  161.    from the current position.
  162.  
  163.    [getPosOut ostr] returns the current position in stream ostr.
  164.    Raises Io.Io if not supported on ostr.
  165.  
  166.    [endPosOut ostr] returns the ending position in stream ostr.
  167.    Raises Io.Io if not supported on ostr.
  168.  
  169.    [setPosOut(ostr, i)] sets the current position in stream to ostr to
  170.    i.  Raises Io.Io if not supported on ostr.
  171.  
  172.    [mkInstream sistr] creates a state-based instream from the
  173.    functional instream sistr.
  174.  
  175.    [getInstream istr] returns the functional instream underlying the
  176.    state-based instream istr.
  177.  
  178.    [setInstream(istr, sistr)] redirects istr, so that subsequent input
  179.    is taken from the functional instream sistr.
  180.  
  181.    [mkOutstream sostr] creates a state-based outstream from the
  182.    outstream sostr.
  183.  
  184.    [getOutstream ostr] returns the outstream underlying the
  185.    state-based outstream ostr.
  186.  
  187.    [setOutstream(ostr, sostr)] redirects the outstream ostr so that
  188.    subsequent output goes to sostr.
  189.  
  190. *)
  191.