Statistics
| Branch: | Revision:

root / src / nedxml / index.h @ 68da4f12

History | View | Annotate | Download (6.17 KB)

1
//==========================================================================
2
//  INDEX.H - part of
3
//                     OMNeT++/OMNEST
4
//            Discrete System Simulation in C++
5
//
6
//  Defines modules for documentation generation. Nothing useful for the
7
//  C++ compiler.
8
//
9
//==========================================================================
10

    
11
/*--------------------------------------------------------------*
12
  Copyright (C) 2002-2008 Andras Varga
13
  Copyright (C) 2006-2008 OpenSim Ltd.
14

15
  This file is distributed WITHOUT ANY WARRANTY. See the file
16
  `license' for details on this and other legal matters.
17
*--------------------------------------------------------------*/
18

    
19

    
20
/**
21
 * @mainpage \opp NEDXML API Reference
22
 *
23
 * This reference documents NEDXML -- a library for parsing NED and MSG files,
24
 * and much more. The result of parsing is a DOM-like object tree, which
25
 * you can export as an XML file (and import it back as well), generate C++
26
 * code from it (a la nedc), or -- possibly after modifying it -- convert
27
 * it back to the original NED/MSG format.
28
 *
29
 * For a start, read the @ref Overview, or you can go to one of the more
30
 * specific topics:
31
 *
32
 * - @ref DTD
33
 * - @ref Data
34
 * - @ref NEDParser
35
 * - @ref XMLParser
36
 * - @ref XMLGenerator
37
 * - @ref Validation
38
 * - @ref NEDResources
39
 * - @ref NEDGenerator
40
 * - @ref CppGenerator
41
 *
42
 */
43

    
44
/**
45
 * @defgroup Overview  Overview
46
 *
47
 * XML is ideal as an alternative representation of NED. By supporting XML,
48
 * NED becomes more interoperable with other systems, and it is be possible
49
 * to process it with standard tools. (Note that XML is unsuitable
50
 * though as the <i>only</i> representation of NED information because of its
51
 * relatively poor readability.)
52
 *
53
 * As an example, let's see a short NED code fragment and its XML representation:
54
 * <pre>
55
 * module FDDINode
56
 *     parameters:
57
 *         address : string;
58
 *     gates:
59
 *         in: net_in;
60
 *         out: net_out;
61
 *     submodules:
62
 *         MAC: FDDI_MAC
63
 *             parameters:
64
 *                 mac_address = address;
65
 *                 promiscuous = false;
66
 *         ...
67
 * endmodule
68
 * </pre>
69
 *
70
 * The XML version is a bit less readable but straightforward:
71
 *
72
 * <pre>
73
 * @verbatim
74
 * <?xml version="1.0" ?>
75
 * <nedfile filename="fddi.ned">
76
 *     <module name="FDDINode">
77
 *         <params>
78
 *             <param name="address" datatype="string"/>
79
 *         </params>
80
 *         <gates>
81
 *             <gate gatetype="in" isvector="false" name="net_in" />
82
 *             <gate gatetype="out" isvector="false" name="net_out" />
83
 *         </gates>
84
 *         <submodules>
85
 *             <submodule name="MAC" typename="FDDI_MAC">
86
 *                 <substparams>
87
 *                     <substparam name="mac_address" value="address"/>
88
 *                     <substparam name="promiscuous" value="false"/>
89
 *                 </substparams>
90
 *             </submodule>
91
 *             ...
92
 *
93
 * @endverbatim
94
 * </pre>
95
 *
96
 * The above XML fragment should be quite self-explanatory for those familiar
97
 * with NED.
98
 *
99
 * A DTD (document type descriptor) exists to describe the format of valid
100
 * NED XML documents.
101
 *
102
 * The NED-XML infrastructure is centered around data classes that are
103
 * the in-memory representation of NED. The data structure is an object tree,
104
 * where each XML element (e.g. &lt;param name="address" datatype="string"/&gt;)
105
 * is represented by an object. The central class is NEDElement, which provides
106
 * DOM-like generic methods to navigate the tree, enumerate and query attributes,
107
 * etc. Each XML element has a corresponding class, subclassed from NEDElement,
108
 * e.g. for the &lt;param&gt; element the class is called ParamElement. Specific
109
 * element classes provide a stricter, more typed interface to access the data
110
 * tree.
111
 *
112
 * Several components build around the data classes:
113
 *    - <i>input filters</i> build a NEDXML object tree using data from some external
114
 *      data source. Currently available input filters are <b>NED parser</b>
115
 *      and <b>XML parser</b>.
116
 *    - <i>output filters</i> take a NEDXML object tree and transform it into some
117
 *      other format. Currently available output filters are <b>NED generator</b>,
118
 *      <b>XML generator</b>, and <b>C++ code generator</b> (for nedc).
119
 *    - <i>validators</i> check that a NEDXML object tree contains valid information,
120
 *      that is, it conforms to the DTD and other, stricter rules. Currently implemented
121
 *      validators consist of several stages which can check the tree up to the level
122
 *      required by nedc.
123
 *
124
 * An exciting "output filter", <b>network builder</b> is implemented as an optional
125
 * part of the simulation library. Network builder can set up a simulation model
126
 * on the fly, provided that all simple modules are present in the executable.
127
 *
128
 * Based on the infrastructure, a NED compiler can be assembled from a NED
129
 * parser and a C++ code generator component. GNED can utilize the NED parser
130
 * and NED generator components. Both nedc and GNED will be able to import and
131
 * export XML by just adding the XML parser and XML generator components. The
132
 * infrastructure makes it easier to build models dynamically. For example, when
133
 * building networks from data coming from a database, one might
134
 * let the database query produce XML (several databases are already capable
135
 * of that), then apply an XSLT transformation to convert to NED-XML if
136
 * needed. Then one might apply the network builder to set up the network directly;
137
 * or use the NED generator to create NED source for debugging purposes.
138
 *
139
 * The central idea is to have a <i>common data structure</i> for representing NED,
140
 * and this data stucture can <i>act as a hub</i> for connecting different data formats,
141
 * data sources and applications.
142
 */
143

    
144

    
145
/**
146
 * @defgroup DTD  DTD
147
 *
148
 * The DTD that describes NED XML files:
149
 *
150
 * @include ned2.dtd
151
 */
152

    
153
/**
154
 * @defgroup Data  Data classes
155
 *
156
 */
157

    
158
/**
159
 * @defgroup NEDParser NED Parsing
160
 */
161

    
162
/**
163
 * @defgroup XMLParser  XML Parsing
164
 */
165

    
166
/**
167
 * @defgroup XMLGenerator Generating XML
168
 */
169

    
170
/**
171
 * @defgroup Validation  Validation
172
 *
173
 */
174

    
175
/**
176
 * @defgroup NEDResources  NED Resources
177
 *
178
 */
179

    
180
/**
181
 * @defgroup NEDGenerator  Generating NED
182
 *
183
 */
184

    
185
/**
186
 * @defgroup CppGenerator Generating C++ code
187
 *
188
 */
189

    
190

    
191