
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 }