libs.marshal.all source code

1 /**
2  * This library implements marshaling functionality for converting data into formats that are
3  * more easily saved or interpreted by humans and possibly back again.
4  *
5  * The library is broken into parts.  The main two files are:
6  * marshaller.d
7  * demarshaller.d
8  * These files define the root of the marshaller/demarshaller.  
9 
10  * First we cover the marshaller:
11  * marshaller.d is responsible only for defining the root functionality of a marshaller.  
12  * It does not contain any of the specifics about how structures are marshalled or in what
13  * format they are stored.
14  * Two different components are needed to form a fully functional marshaller:
15  *   1. A (Marshal)StorageStrategy
16  *   2. A MarshalStrategy
17  * A StorageStrategy defines how the marshaller will store the data.  For example it may be 
18  * stored in text format or binary format.  Storage strategies for text and binary are both 
19  * defined in the files text_marshaller.d and binary_marshaller.d.  
20  * A MarshalStrategy defines the specifics of what is to be marshalled.  It only makes sense to
21  * use a MarshalStrategy with a single kind of StorageStrategy, as each StorageStrategy defines 
22  * a different api.  For example, the TextMarshaller StorageStrategy implements marshal
23  * strategies for conversion to XML, JSON and to a human readable format.
24  * 
25  * To define a MarshalStrategy, copy the code from a similar strategy such as 
26  * xml_text_marshaller.d.  There are a few key things that are required in such a file:
27  *   1. Importing the main marshaller file: libs.marshal.marshaller
28  *   2. Importing the file containing your StorageStrategy, eg. libs.marshal.text_marshaller;
29  *   3. Creating an alias so the marshaller can be used externally, eg.
30  *      alias Marshaller!(XmlMarshallerStrategy, TextMarshallerStorageStrategy) XmlTextMarshaller;
31  *   4. Create a class that is templated and implements IMarshalStrategy.  The first line of the
32  *      body of this class should be a template mixin.  See example below:
33  *      	package class XmlMarshallerStrategy(StorageStrategy) : IMarshalStrategy
34  *      	{
35  *      		mixin MarshalMixinTemplate!(StorageStrategy);
36  *      		...
37  *      	}
38  *      It also needs to implement the member functions from IMarshalStrategy.  Some of these are
39  *      templated and will fail silently if not implemented so make sure you check.
40  *
41  * Next we define Demarshallers:
42  * demarshaller.d is responsible only for defining the root functionality of a demarshaller.  
43  * It does not contain any of the specifics about how structures are demarshalled or how the
44  * stored data should be interpreted.
45  * Two different components are needed to form a fully functional demarshaller:
46  *   1. A (Demarshal)StorageStrategy
47  *   2. A DemarshalStrategy
48  * A StorageStrategy defines how the demarshaller will interpret the stored data.  For example 
49  * data may be read in text or binary format.  Storage strategies for text and binary are both 
50  * defined in the files text_demarshaller.d and binary_demarshaller.d.  
51  * A DemarshalStrategy defines the specifics of what is to be demarshalled.  It only makes sense
52  * to use a DrmarshalStrategy with a single kind of StorageStrategy, as each StorageStrategy 
53  * defines a different api.  For example, the TextDemarshaller StorageStrategy implements 
54  * demarshal strategies for interpretation from XML and JSON.
55  */
56 module libs.marshal.all;
57 
58 public import libs.marshal.xml_text_marshaller;
59 public import libs.marshal.xml_text_demarshaller;
60 
61 public import libs.marshal.human_readable_text_marshaller;
62 
63 public import libs.marshal.compact_binary_demarshaller;
64 public import libs.marshal.compact_binary_marshaller;
65 
66 unittest {
67 	//Round trip test...
68 	XmlTextMarshaller xml_marshaller = new XmlTextMarshaller;
69 	XmlTextDemarshaller xml_demarshaller = new XmlTextDemarshaller;
70 	CompactBinaryMarshaller bin_marshaller = new CompactBinaryMarshaller;
71 	CompactBinaryDemarshaller bin_demarshaller = new CompactBinaryDemarshaller;
72 	
73 	struct X
74 	{
75 		int abc;
76 		int test;
77 		string str;
78 		float[] ary;
79 	}
80 	
81 	X[] x_ary_expect;
82 	for (auto i = 0; i < 10; ++i)
83 	{
84 		X x;
85 		x.abc = i;
86 		x.test = 2*i;
87 		x.str = "123";
88 		x.ary = [11.1, 22.2, 33.3, 44.4];
89 		x_ary_expect ~= x;
90 	}
91 	
92 	xml_marshaller.Marshal(x_ary_expect, "x_ary");
93 	
94 	xml_demarshaller.SetText(xml_marshaller.ToString());
95 	
96 	X[] x_ary;
97 	xml_demarshaller.Demarshal("x_ary", x_ary);
98 	
99 	assert ( x_ary == x_ary_expect);
100 	
101 	X[] x_ary_bin;
102 	
103 	bin_marshaller.Marshal(x_ary_expect, "");
104 	
105 	bin_demarshaller.SetBuffer(bin_marshaller.GetBuffer());
106 	bin_demarshaller.Demarshal("", x_ary_bin);
107 	
108 	assert ( x_ary_bin == x_ary_expect);
109 }