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 4. Derivative works are permitted, but they must carry this notice 00027 in full and credit the original source. 00028 00029 00030 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 00031 00032 00033 @version Initial version, March 2004 00034 @author Kris, Ivan Senji (the "alias opShr get" idea) 00035 00036 00037 *******************************************************************************/ 00038 00039 module mango.io.model.IReader; 00040 00041 public import mango.io.model.IBuffer; 00042 00043 /******************************************************************************* 00044 00045 *******************************************************************************/ 00046 00047 typedef uint delegate (void* dst, uint count) BufferDecoder; 00048 00049 /******************************************************************************* 00050 00051 Any class implementing IReadable becomes part of the Reader framework 00052 00053 *******************************************************************************/ 00054 00055 interface IReadable 00056 { 00057 void read (IReader r); 00058 } 00059 00060 /******************************************************************************* 00061 00062 Any class implementing IDecoder can be bound to a reader using 00063 the setDecoder() method. 00064 00065 *******************************************************************************/ 00066 00067 interface IDecoder 00068 { 00069 ConverterType type (); 00070 00071 BufferDecoder bind (IReader reader); 00072 } 00073 00074 /******************************************************************************* 00075 00076 *******************************************************************************/ 00077 00078 interface IArrayAllocator 00079 { 00080 void reset (); 00081 00082 void bind (IReader reader); 00083 00084 bool isMutable (void* x); 00085 00086 void allocate (void[]* x, uint size, uint width, BufferDecoder convert); 00087 } 00088 00089 /******************************************************************************* 00090 00091 All reader instances should implement this interface. 00092 00093 *******************************************************************************/ 00094 00095 interface IReader 00096 { 00097 alias opShr get; 00098 00099 /*********************************************************************** 00100 00101 These are the basic reader methods 00102 00103 ***********************************************************************/ 00104 00105 IReader opShr (inout bool x); 00106 IReader opShr (inout byte x); 00107 IReader opShr (inout ubyte x); 00108 IReader opShr (inout short x); 00109 IReader opShr (inout ushort x); 00110 IReader opShr (inout int x); 00111 IReader opShr (inout uint x); 00112 IReader opShr (inout long x); 00113 IReader opShr (inout ulong x); 00114 IReader opShr (inout float x); 00115 IReader opShr (inout double x); 00116 IReader opShr (inout real x); 00117 IReader opShr (inout char x); 00118 IReader opShr (inout wchar x); 00119 IReader opShr (inout dchar x); 00120 00121 IReader opShr (inout byte[] x); 00122 IReader opShr (inout short[] x); 00123 IReader opShr (inout int[] x); 00124 IReader opShr (inout long[] x); 00125 IReader opShr (inout ubyte[] x); 00126 IReader opShr (inout ushort[] x); 00127 IReader opShr (inout uint[] x); 00128 IReader opShr (inout ulong[] x); 00129 IReader opShr (inout float[] x); 00130 IReader opShr (inout double[] x); 00131 IReader opShr (inout real[] x); 00132 IReader opShr (inout char[] x); 00133 IReader opShr (inout wchar[] x); 00134 IReader opShr (inout dchar[] x); 00135 00136 /*********************************************************************** 00137 00138 This is the mechanism used for binding arbitrary classes 00139 to the IO system. If a class implements IReadable, it can 00140 be used as a target for IReader get() operations. That is, 00141 implementing IReadable is intended to transform any class 00142 into an IReader adaptor for the content held therein. 00143 00144 ***********************************************************************/ 00145 00146 IReader opShr (IReadable x); 00147 00148 /*********************************************************************** 00149 00150 Push the size (in bytes) to use for the next array-read. 00151 By default, array sizes are read from the input stream, 00152 so this is the means by which one may specify the size 00153 where the stream is not formatted in such a manner. 00154 00155 @code 00156 char[] x; 00157 int size; 00158 IReader reader; 00159 00160 reader.push(size).get(x); 00161 @endcode 00162 00163 ***********************************************************************/ 00164 00165 IReader push (uint size); 00166 00167 /*********************************************************************** 00168 00169 Pause the current thread until some content arrives in 00170 the associated input buffer. This may stall forever. 00171 00172 ***********************************************************************/ 00173 00174 void wait (); 00175 00176 /*********************************************************************** 00177 00178 Return the size (byte count) of the subsequent data stream. 00179 This is typically read from the stream as a number, but may 00180 be provided by the client code via the push() method. 00181 00182 ***********************************************************************/ 00183 00184 uint length (); 00185 00186 /*********************************************************************** 00187 00188 Return the buffer associated with this reader 00189 00190 ***********************************************************************/ 00191 00192 IBuffer getBuffer (); 00193 00194 /*********************************************************************** 00195 00196 Set the allocator to use for array management. Arrays are 00197 always allocated by the IReader. That is, you cannot read 00198 data into an array slice (for example). Instead, a number 00199 of IArrayAllocator classes are available to manage memory 00200 allocation when reading array content. 00201 00202 By default, an IReader will allocate each array from the 00203 heap. You can change that behavior by calling this method 00204 with an IArrayAllocator of choice. For instance, there 00205 is a BufferAllocator which will slice an array directly 00206 from the buffer where possible. Also available is the 00207 record-oriented SliceAllocator, which slices memory from 00208 within a pre-allocated heap area, and should be reset by 00209 the client code after each record has been read (to avoid 00210 unnecessary growth). 00211 00212 See ArrayAllocator for more information. 00213 00214 ***********************************************************************/ 00215 00216 void setAllocator (IArrayAllocator memory); 00217 00218 /*********************************************************************** 00219 00220 ***********************************************************************/ 00221 00222 IArrayAllocator getAllocator (); 00223 00224 /*********************************************************************** 00225 00226 Bind an IDecoder to the writer. Decoders are intended to 00227 be used as a conversion mechanism between various character 00228 representations (encodings), or the translation of any data 00229 type from one representation to another. Each data type may 00230 be configured with a distinct decoder, covering all native 00231 types (15 in total). 00232 00233 An appropriate decoder set should be attached to each 00234 IReader, and thus be available for subsequent use. A raw 00235 binary implementation is attached by default (no encoding). 00236 00237 See module mango.icu.UMango for an example of decoder 00238 implementation -- those classes bind the ICU converters 00239 to this IO package. 00240 00241 ***********************************************************************/ 00242 00243 void setDecoder (IDecoder d); 00244 }