Mercurial > projects > ldc
comparison tango/tango/io/protocol/model/IReader.d @ 132:1700239cab2e trunk
[svn r136] MAJOR UNSTABLE UPDATE!!!
Initial commit after moving to Tango instead of Phobos.
Lots of bugfixes...
This build is not suitable for most things.
author | lindquist |
---|---|
date | Fri, 11 Jan 2008 17:57:40 +0100 |
parents | |
children |
comparison
equal
deleted
inserted
replaced
131:5825d48b27d1 | 132:1700239cab2e |
---|---|
1 /******************************************************************************* | |
2 | |
3 copyright: Copyright (c) 2004 Kris Bell. All rights reserved | |
4 | |
5 license: BSD style: $(LICENSE) | |
6 | |
7 version: Oct 2004: Initial release | |
8 Dec 2006: Outback release | |
9 | |
10 author: Kris | |
11 Ivan Senji (the "alias get" idea) | |
12 | |
13 *******************************************************************************/ | |
14 | |
15 module tango.io.protocol.model.IReader; | |
16 | |
17 public import tango.io.model.IBuffer; | |
18 | |
19 private import tango.io.protocol.model.IProtocol; | |
20 | |
21 /******************************************************************************* | |
22 | |
23 IReader interface. Each reader operates upon an IBuffer, which is | |
24 provided at construction time. Readers are simple converters of data, | |
25 and have reasonably rigid rules regarding data format. For example, | |
26 each request for data expects the content to be available; an exception | |
27 is thrown where this is not the case. If the data is arranged in a more | |
28 relaxed fashion, consider using IBuffer directly instead. | |
29 | |
30 All readers support the full set of native data types, plus a full | |
31 selection of array types. The latter can be configured to produce | |
32 either a copy (.dup) of the buffer content, or a slice. See classes | |
33 HeapCopy, BufferSlice and HeapSlice for more on this topic. Applications | |
34 can disable memory management by configuring a Reader with one of the | |
35 binary oriented protocols, and ensuring the optional protocol 'prefix' | |
36 is disabled. | |
37 | |
38 Readers support Java-esque get() notation. However, the Tango | |
39 style is to place IO elements within their own parenthesis, like | |
40 so: | |
41 | |
42 --- | |
43 int count; | |
44 char[] verse; | |
45 | |
46 read (verse) (count); | |
47 --- | |
48 | |
49 Note that each element read is distict; this style is affectionately | |
50 known as "whisper". The code below illustrates basic operation upon a | |
51 memory buffer: | |
52 | |
53 --- | |
54 auto buf = new Buffer (256); | |
55 | |
56 // map same buffer into both reader and writer | |
57 auto read = new Reader (buf); | |
58 auto write = new Writer (buf); | |
59 | |
60 int i = 10; | |
61 long j = 20; | |
62 double d = 3.14159; | |
63 char[] c = "fred"; | |
64 | |
65 // write data using whisper syntax | |
66 write (c) (i) (j) (d); | |
67 | |
68 // read them back again | |
69 read (c) (i) (j) (d); | |
70 | |
71 | |
72 // same thing again, but using put() syntax instead | |
73 write.put(c).put(i).put(j).put(d); | |
74 read.get(c).get(i).get(j).get(d); | |
75 --- | |
76 | |
77 Note that certain protocols, such as the basic binary implementation, | |
78 expect to retrieve the number of array elements from the source. For | |
79 example: when reading an array from a file, the number of elements | |
80 is read from the file also, and the configurable memory-manager is | |
81 invoked to provide the array space. If content is not arranged in | |
82 such a manner you may read array content directly either by creating | |
83 a Reader with a protocol configured to sidestep array-prefixing, or | |
84 by accessing buffer content directly (via the methods exposed there) | |
85 e.g. | |
86 | |
87 --- | |
88 void[10] data; | |
89 | |
90 reader.buffer.fill (data); | |
91 --- | |
92 | |
93 Readers may also be used with any class implementing the IReadable | |
94 interface, along with any struct implementing an equivalent method | |
95 | |
96 *******************************************************************************/ | |
97 | |
98 abstract class IReader // could be an interface, but that causes poor codegen | |
99 { | |
100 alias get opCall; | |
101 | |
102 /*********************************************************************** | |
103 | |
104 These are the basic reader methods | |
105 | |
106 ***********************************************************************/ | |
107 | |
108 abstract IReader get (inout bool x); | |
109 abstract IReader get (inout byte x); /// ditto | |
110 abstract IReader get (inout ubyte x); /// ditto | |
111 abstract IReader get (inout short x); /// ditto | |
112 abstract IReader get (inout ushort x); /// ditto | |
113 abstract IReader get (inout int x); /// ditto | |
114 abstract IReader get (inout uint x); /// ditto | |
115 abstract IReader get (inout long x); /// ditto | |
116 abstract IReader get (inout ulong x); /// ditto | |
117 abstract IReader get (inout float x); /// ditto | |
118 abstract IReader get (inout double x); /// ditto | |
119 abstract IReader get (inout real x); /// ditto | |
120 abstract IReader get (inout char x); /// ditto | |
121 abstract IReader get (inout wchar x); /// ditto | |
122 abstract IReader get (inout dchar x); /// ditto | |
123 | |
124 abstract IReader get (inout bool[] x); /// ditto | |
125 abstract IReader get (inout byte[] x); /// ditto | |
126 abstract IReader get (inout short[] x); /// ditto | |
127 abstract IReader get (inout int[] x); /// ditto | |
128 abstract IReader get (inout long[] x); /// ditto | |
129 abstract IReader get (inout ubyte[] x); /// ditto | |
130 abstract IReader get (inout ushort[] x); /// ditto | |
131 abstract IReader get (inout uint[] x); /// ditto | |
132 abstract IReader get (inout ulong[] x); /// ditto | |
133 abstract IReader get (inout float[] x); /// ditto | |
134 abstract IReader get (inout double[] x); /// ditto | |
135 abstract IReader get (inout real[] x); /// ditto | |
136 abstract IReader get (inout char[] x); /// ditto | |
137 abstract IReader get (inout wchar[] x); /// ditto | |
138 abstract IReader get (inout dchar[] x); /// ditto | |
139 | |
140 /*********************************************************************** | |
141 | |
142 This is the mechanism used for binding arbitrary classes | |
143 to the IO system. If a class implements IReadable, it can | |
144 be used as a target for IReader get() operations. That is, | |
145 implementing IReadable is intended to transform any class | |
146 into an IReader adaptor for the content held therein. | |
147 | |
148 ***********************************************************************/ | |
149 | |
150 abstract IReader get (IReadable); | |
151 | |
152 alias void delegate (IReader) Closure; | |
153 | |
154 abstract IReader get (Closure); | |
155 | |
156 /*********************************************************************** | |
157 | |
158 Return the buffer associated with this reader | |
159 | |
160 ***********************************************************************/ | |
161 | |
162 abstract IBuffer buffer (); | |
163 | |
164 /*********************************************************************** | |
165 | |
166 Get the allocator to use for array management. Arrays are | |
167 generally allocated by the IReader, via configured managers. | |
168 A number of Allocator classes are available to manage memory | |
169 when reading array content. Alternatively, the application | |
170 may obtain responsibility for allocation by selecting one of | |
171 the NativeProtocol deriviatives and setting 'prefix' to be | |
172 false. The latter disables internal array management. | |
173 | |
174 Gaining access to the allocator can expose some additional | |
175 controls. For example, some allocators benefit from a reset | |
176 operation after each data 'record' has been processed. | |
177 | |
178 By default, an IReader will allocate each array from the | |
179 heap. You can change that by constructing the Reader | |
180 with an Allocator of choice. For instance, there is a | |
181 BufferSlice which will slice an array directly from | |
182 the buffer where possible. Also available is the record- | |
183 oriented HeaoSlice, which slices memory from within | |
184 a pre-allocated heap area, and should be reset by the client | |
185 code after each record has been read (to avoid unnecessary | |
186 growth). | |
187 | |
188 See module tango.io.protocol.Allocator for more information | |
189 | |
190 ***********************************************************************/ | |
191 | |
192 abstract IAllocator allocator (); | |
193 } | |
194 | |
195 /******************************************************************************* | |
196 | |
197 Any class implementing IReadable becomes part of the Reader framework | |
198 | |
199 *******************************************************************************/ | |
200 | |
201 interface IReadable | |
202 { | |
203 void read (IReader input); | |
204 } | |
205 |