00001 /******************************************************************************* 00002 00003 @file IReader.d 00004 00005 Copyright (C) 2004 Kris Bell 00006 00007 This software is provided 'as-is', without any express or implied 00008 warranty. In no event will the authors be held liable for damages 00009 of any kind arising from the use of this software. 00010 00011 Permission is hereby granted to anyone to use this software for any 00012 purpose, including commercial applications, and to alter it and/or 00013 redistribute it freely, subject to the following restrictions: 00014 00015 1. The origin of this software must not be misrepresented; you must 00016 not claim that you wrote the original software. If you use this 00017 software in a product, an acknowledgment within documentation of 00018 said product would be appreciated but is not required. 00019 00020 2. Altered source versions must be plainly marked as such, and must 00021 not be misrepresented as being the original software. 00022 00023 3. This notice may not be removed or altered from any distribution 00024 of the source. 00025 00026 00027 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 00028 00029 00030 @version Initial version, March 2004 00031 @author Kris 00032 00033 00034 *******************************************************************************/ 00035 00036 module mango.io.model.IReader; 00037 00038 public import mango.io.model.IBuffer; 00039 00040 /******************************************************************************* 00041 00042 Any class implementing IReadable becomes part of the Reader framework 00043 00044 *******************************************************************************/ 00045 00046 interface IReadable 00047 { 00048 void read (IReader r); 00049 } 00050 00051 /******************************************************************************* 00052 00053 *******************************************************************************/ 00054 00055 interface IArrayAllocator 00056 { 00057 void reset (); 00058 00059 void allocate (void[]* x, BufferConverter convert); 00060 } 00061 00062 /******************************************************************************* 00063 00064 Use instances of IStringDecoder to convert between character 'sizes' 00065 and to unwrap the various character encodings. These may throw an 00066 exception if they don't support the requested type. For example, an 00067 exception would/should be thrown where a Unicode-based IStringDecoder 00068 is requested to provide a char[] instead of a wchar[]. 00069 00070 An appropriate IStringDecoder should be attached to each IReader, and 00071 thus be available for subsequent use. An 8-bit ASCII implementation 00072 is attached by default. 00073 00074 Note that the 'count' argument is the number of bytes available in 00075 the 'dst' buffer. The decoders are expected to fill exactly that 00076 amount, or throw an exception. 00077 00078 *******************************************************************************/ 00079 00080 interface IStringDecoder 00081 { 00082 void char8 (void *dst, uint count); 00083 void char16 (void *dst, uint count); 00084 void char32 (void *dst, uint count); 00085 } 00086 00087 /******************************************************************************* 00088 00089 All reader instances should implement this interface. 00090 00091 *******************************************************************************/ 00092 00093 interface IReader 00094 { 00095 /*********************************************************************** 00096 00097 These are the basic reader methods 00098 00099 ***********************************************************************/ 00100 00101 IReader get (inout bool x); 00102 IReader get (inout byte x); 00103 IReader get (inout ubyte x); 00104 IReader get (inout short x); 00105 IReader get (inout ushort x); 00106 IReader get (inout int x); 00107 IReader get (inout uint x); 00108 IReader get (inout long x); 00109 IReader get (inout ulong x); 00110 IReader get (inout float x); 00111 IReader get (inout double x); 00112 IReader get (inout real x); 00113 00114 IReader get (inout char x); 00115 IReader get (inout wchar x); 00116 IReader get (inout dchar x); 00117 00118 IReader get (inout char[] x); 00119 IReader get (inout wchar[] x); 00120 IReader get (inout dchar[] x); 00121 00122 /*********************************************************************** 00123 00124 This is the mechanism used for binding arbitrary classes 00125 to the IO system. If a class implements IReadable, it can 00126 be used as a target for IReader get() operations. That is, 00127 implementing IReadable is intended to transform any class 00128 into an IReader adaptor for the content held therein. 00129 00130 ***********************************************************************/ 00131 00132 IReader get (IReadable x); 00133 00134 /*********************************************************************** 00135 00136 Push the size (in bytes) to use for the next array-read. 00137 By default, array sizes are read from the input stream, 00138 so this is the means by which one may specify the size 00139 where the stream is not formatted in such a manner. 00140 00141 @code 00142 char[] x; 00143 int size; 00144 IReader reader; 00145 00146 reader.push(size).get(x); 00147 @endcode 00148 00149 ***********************************************************************/ 00150 00151 IReader push (uint size); 00152 00153 /*********************************************************************** 00154 00155 Pause the current thread until some content arrives in 00156 the associated input buffer. This may stall forever. 00157 00158 ***********************************************************************/ 00159 00160 void wait (); 00161 00162 /*********************************************************************** 00163 00164 Return the size (byte count) of the subsequent data stream. 00165 This is typically read from the stream as a number, but may 00166 be provided by the client code via the push() method. 00167 00168 ***********************************************************************/ 00169 00170 uint length (); 00171 00172 /*********************************************************************** 00173 00174 Return the buffer associated with this reader 00175 00176 ***********************************************************************/ 00177 00178 IBuffer getBuffer (); 00179 00180 /*********************************************************************** 00181 00182 Set the allocator to use for array management. Arrays are 00183 always allocated by the IReader. That is, you cannot read 00184 data into an array slice (for example). Instead, a number 00185 of IArrayAllocator classes are available to manage memory 00186 allocation when reading array content. 00187 00188 By default, an IReader will allocate each array from the 00189 heap. You can change that behavior by calling this method 00190 with an IArrayAllocator of choice. For instance, there 00191 is a BufferAllocator which will slice an array directly 00192 from the buffer where possible. Also available is the 00193 record-oriented SliceAllocator, which slices memory from 00194 within a pre-allocated heap area, and should be reset by 00195 the client code after each record has been read (to avoid 00196 unnecessary growth). 00197 00198 See ArrayAllocator for more information. 00199 00200 ***********************************************************************/ 00201 00202 void setAllocator (IArrayAllocator memory); 00203 00204 /*********************************************************************** 00205 00206 Set the configured IStringDecoder. These are intended to 00207 be used as a conversion mechanism between various character 00208 representations. They are also expected to be used for the 00209 process of applying character encodings. 00210 00211 ***********************************************************************/ 00212 00213 void setStringDecoder (IStringDecoder s); 00214 00215 /*********************************************************************** 00216 00217 And these are used for the >> syntax 00218 00219 ***********************************************************************/ 00220 00221 version (UseShiftOperators) 00222 { 00223 IReader opShr (IReadable s); 00224 IReader opShr (inout bool x); 00225 IReader opShr (inout ubyte x); 00226 IReader opShr (inout byte x); 00227 IReader opShr (inout ushort x); 00228 IReader opShr (inout short x); 00229 IReader opShr (inout uint x); 00230 IReader opShr (inout int x); 00231 IReader opShr (inout ulong x); 00232 IReader opShr (inout long x); 00233 IReader opShr (inout float x); 00234 IReader opShr (inout double x); 00235 IReader opShr (inout real x); 00236 00237 IReader opShr (inout char x); 00238 IReader opShr (inout wchar x); 00239 IReader opShr (inout dchar x); 00240 00241 IReader opShr (inout char[] x); 00242 IReader opShr (inout wchar[] x); 00243 IReader opShr (inout dchar[] x); 00244 } 00245 }