logo

class

sys::OutStream

sys::Obj
  sys::OutStream
   1  //
   2  // Copyright (c) 2006, Brian Frank and Andy Frank
   3  // Licensed under the Academic Free License version 3.0
   4  //
   5  // History:
   6  //   16 Mar 06  Brian Frank  Creation
   7  //
   8  
   9  **
  10  ** OutStream is used to write binary and text data
  11  ** to an output stream.
  12  **
  13  class OutStream
  14  {
  15  
  16  //////////////////////////////////////////////////////////////////////////
  17  // Construction
  18  //////////////////////////////////////////////////////////////////////////
  19  
  20    **
  21    ** Make an output stream designed to write characters into the specified
  22    ** StrBuf.  The output stream is designed to write character data, attempts
  23    ** to do binary writes will throw UnsupportedErr.
  24    **
  25    static OutStream makeForStrBuf(StrBuf strBuf)
  26  
  27    **
  28    ** Constructor for an OutStream which wraps another stream.
  29    ** All writes to this stream will be routed to the specified
  30    ** inner stream.
  31    **
  32    ** If out is null, then it is the subclass responsibility to
  33    ** handle writes by overriding the following methods: `write`
  34    ** and `writeBuf`.
  35    **
  36    protected new make(OutStream out)
  37  
  38  //////////////////////////////////////////////////////////////////////////
  39  // Virtuals
  40  //////////////////////////////////////////////////////////////////////////
  41  
  42    **
  43    ** Write a byte to the output stream.  Throw IOErr on error.
  44    ** Return this.
  45    **
  46    virtual OutStream write(Int byte)
  47  
  48    **
  49    ** Write n bytes from the specified Buf at it's current position to
  50    ** this output stream.  If n is defaulted to buf.remaining(), then
  51    ** everything left in the buffer is drained to this output stream.
  52    ** The buf's position is advanced n bytes upon return.  Throw
  53    ** IOErr on error.  Return this.
  54    **
  55    virtual OutStream writeBuf(Buf buf, Int n := buf.remaining)
  56  
  57    **
  58    ** Flush the stream so any buffered bytes are written out.  Default
  59    ** implementation does nothing.  Throw IOErr on error.
  60    **
  61    virtual Void flush()
  62  
  63    **
  64    ** Close the input stream.  This method is guaranteed to never
  65    ** throw an IOErr.  Return true if the stream was closed successfully
  66    ** or false if the stream was closed abnormally.  Default implementation
  67    ** does nothing and returns true.
  68    **
  69    virtual Bool close()
  70  
  71  //////////////////////////////////////////////////////////////////////////
  72  // Binary Data
  73  //////////////////////////////////////////////////////////////////////////
  74  
  75    **
  76    ** Write two bytes as a 16-bit number in network byte order.  This method
  77    ** may be paired with `InStream.readU2` or `InStream.readS2`.  Throw IOErr
  78    ** on error.  Return this.
  79    **
  80    OutStream writeI2(Int n)
  81  
  82    **
  83    ** Write four bytes as a 32-bit number in network byte order.  This
  84    ** method may be paired with `InStream.readU4` or `InStream.readS4`.  Throw
  85    ** IOErr on error.  Return this.
  86    **
  87    OutStream writeI4(Int n)
  88  
  89    **
  90    ** Write eight bytes as a 64-bit number in network byte order.  This
  91    ** is paired with `InStream.readS8`.  Throw IOErr on error.  Return this.
  92    **
  93    OutStream writeI8(Int n)
  94  
  95    **
  96    ** Write four bytes as a 32-bit floating point number in network byte
  97    ** order according to `Float.bits32`.  This is paired with `InStream.readF4`.
  98    ** Throw IOErr on error.  Return this.
  99    **
 100    OutStream writeF4(Float r)
 101  
 102    **
 103    ** Write eight bytes as a 64-bit floating point number in network byte
 104    ** order according to `Float.bits`.  This is paired with `InStream.readF8`.
 105    ** Throw IOErr on error.  Return this.
 106    **
 107    OutStream writeF8(Float r)
 108  
 109    **
 110    ** Write one byte, one if true or zero if false.  This method is paired
 111    ** with `InStream.readBool`.  Throw IOErr on error.  Return this.
 112    **
 113    OutStream writeBool(Bool b)
 114  
 115    **
 116    ** Write a Str in modified UTF-8 format according the 'java.io.DataOutput'
 117    ** specification.  This method is paired with `InStream.readUtf`.  Throw
 118    ** IOErr on error.  Return this.
 119    **
 120    OutStream writeUtf(Str s)
 121  
 122  //////////////////////////////////////////////////////////////////////////
 123  // Text Data
 124  //////////////////////////////////////////////////////////////////////////
 125  
 126    **
 127    ** The current charset used to encode Unicode characters into
 128    ** bytes.  The default charset should always be UTF-8.
 129    **
 130    virtual Charset charset
 131  
 132    **
 133    ** Write one or more bytes to the stream for the specified Unicode
 134    ** character based on the current charset encoding.
 135    **
 136    OutStream writeChar(Int char)
 137  
 138    **
 139    ** Write the Unicode characters in the specified string to the
 140    ** stream using the current charset encoding.  Off specifies
 141    ** the index offset to start writing characters and len the
 142    ** number of characters in str to write.
 143    OutStream writeChars(Str str, Int off := 0, Int len := str.size-off)
 144  
 145    **
 146    ** Convenience for 'writeChars(obj.toStr)'.  If obj is null,
 147    ** then print the string "null".
 148    **
 149    virtual OutStream print(Obj s)
 150  
 151    **
 152    ** Convenience for 'writeChars(obj.toStr + "\n")'.  If obj
 153    ** is null then print the string "null\n".
 154    **
 155    virtual OutStream printLine(Obj obj := "")
 156  
 157    **
 158    ** Write a serialized object from the stream according to
 159    ** the Fan [serialization format]`docLang::Serialization`.
 160    ** Throw IOErr on error.  Return this.
 161    **
 162    ** The options may be used to specify the format of the output:
 163    **   - "indent": Int specifies how many spaces to indent
 164    **     each level.  Default is 0.
 165    **   - "skipDefaults": Bool specifies if we should skip fields
 166    **     at their default values.  Field values are compared according
 167    **     to the 'equals' method.  Default is false.
 168    **
 169    OutStream writeObj(Obj obj, Str:Obj options := null)
 170  
 171  //////////////////////////////////////////////////////////////////////////
 172  // Utils
 173  //////////////////////////////////////////////////////////////////////////
 174  
 175    **
 176    ** Write the given map of Str name/value pairs to the output stream
 177    ** according to the Fan props file format (see `InStream.readProps` for
 178    ** full specification).  The props are written using UTF-8 regardless
 179    ** of this stream's current charset.  If close argument is true, then
 180    ** automatically close the stream.  Return this.
 181    **
 182    OutStream writeProps(Str:Str props, Bool close := true)
 183  
 184  }
 185  
 186  **************************************************************************
 187  ** SysOutStream
 188  **************************************************************************
 189  
 190  internal class SysOutStream : OutStream
 191  {
 192    override OutStream write(Int byte)
 193    override OutStream writeBuf(Buf buf, Int n)
 194    override Void flush()
 195    override Bool close()
 196  }