ROOT logo
// @(#)root/reflex:$Id$
// Author: Stefan Roiser 2004

#ifndef Reflex_DictSelection
#define Reflex_DictSelection

#include "Reflex/Kernel.h"

/**
 * @file  DictSelection.h
 * @author scott snyder
 * @author Stefan Roiser (minor changes, mainly documentation)
 * @date Aug 2005
 * @brief Definitions for selection classes to provide metadata
 *        for SEAL dictionary generation.
 *
 * When generating dictionary information for a class,
 * one sometimes wants to specify additional information
 * beyond the class definition itself, for example, to specify
 * that certain members are to be treated as transient by the persistency
 * system.  This can be done by associating a dictionary selection class
 * with the class for which dictionary information is being generated.
 * The contents of this selection class encode the additional information.
 * Below, we first discuss how to associate a selection class
 * with your class; then we list the current Set of information
 * which may appear inside the selection class.
 *
 * The simplest case is for the case of a non-template class @c C.
 * By default, the Name of the selection class is then
 * @c Reflex::selection::C.  If you have such a class, it will be found
 * automatically.  If @c C is in a namespace, @c NS::C, then
 * the selection class should be in the same namespace: @c Reflex::selection::NS::C.
 * Examples:
 *
 * @code
 *   namespace N {
 *     class C { ... };
 *   }
 *  namespace Reflex {
 *    namespace selection {
 *      namespace N {
 *        class C { ... };
 *      }
 *    }
 *  }
 *
   @endcode
 *
 * If, however, we're dealing with a template class, @c C\<T>, then
 * things are trickier, since one needs to be sure that the
 * selection class gets properly instantiated.  As before, the dictionary
 * generator will look for a class @c Reflex::selection::C\<T> (with the same
 * template arguments as @c C).  This will only succeed, however,
 * if the selection class has otherwise been used.  Example:
 *
 * @code
 *
 * template <class T>
 * class C { ... };
 *
 *  namespace Reflex {
 *    namespace selection {
 *      template <class T>
 *      class C { ... };
 *    }
 *  }
 *
 * struct foo { C<int> x; };
 *
 * // Without this, the selection class won't be fully instantiated.
 * struct foo_selection { Reflex::selection::C<int> x; }
   @endcode
 *
 * What one would really like is a way to ensure that the selection class
 * gets instantiated whenever the class its describing does.  That does
 * not seem to be possible without modifying that class (at least not
 * without changes to gccxml).  The following idiom seems to work:
 *
 * @code
 *
 * template <class T> class Reflex::selection::C; // forward declaration
 *
 * template <class T>
 * class C
 * {
 *   ...
 *   typedef typename Reflex::selection::C<T>::self DictSelection;
 * };
 *
 *     namespace Reflex {
 *       namespace selection {
 *         template <class T>
 *         class C
 *         {
 *           typedef DictSelection<C> self;
 *           ...
 *         };
 *       }
 *     }
 *
   @endcode
 *
 * Note that if you instead use
 *
 * @code
 *
 *   typedef Reflex::selection::C<T> DictSelection;
 *
   @endcode
 *
 * then @c Reflex::selection::C\<T> will not be fully instantiated.
 *
 * We turn now to declarations the may be present in the selection class.
 * Below, we'll call the class being described by the selection class @c C.
 *
 * @Reflex::selection::AUTOSELECT
 *
 *   This can be useful for automatically including classes which @c C depends upon.
 *
 *   @code
 *   template <class T> class Reflex::selection::C; // forward declaration
 *
 *   // class C<T> depends on std::vector<T>.
 *   template <class T>
 *   class C
 *   {
 *   public:
 *     std::vector<T> fX;
 *     typedef typename Reflex::selection::C<T>::self DictSelection;
 *   };
 *
 *     namespace Reflex {
 *       namespace selection {
 *         template <class T>
 *         class C
 *         {
 *           typedef DictSelection<C> self;
 *           AUTOSELECT fX;
 *         };
 *       }
 *     }
 *
 * // The above declarations mark both C<T> and std::vector<T>
 * // as autoselect.  This means that dictionary information for them
 * // will be emitted wherever it's needed --- no need to list them
 * // in selection.xml.
 *
   @endcode
 *
 * @Reflex::selection::TRANSIENT
 *
 *   This declaration marks the corresponding MemberAt in @c C with
 *   the same Name as transient.  This allows the transient flag
 *   to be listed once in the class header, rather than having
 *   to list it in selection.xml (in possibly many places if @c C
 *   is a template class).  Example:
 *
 *   @code
 *
 *   class C
 *   {
 *   public:
 *     int fX;
 *     int fY;  // This shouldn't be saved.
 *   };
 *
 *     namespace Reflex {
 *       namespace selection {
 *         class C
 *         {
 *           TRANSIENT fY; // Don't save C::fY.
 *         };
 *       }
 *     }
 *
   @endcode
 *
 * @Reflex::selection::TEMPLATE_DEFAULTS<T1, T2, ...>
 *
 *   (The Name of the MemberAt used does not matter.)
 *   Declares default template arguments for @c C.  Up to 15 arguments
 *   may be listed.  If a given position cannot be defaulted, then
 *   use @c Reflex::selection::NODEFAULT.
 *
 *   If this declaration has been made, then any defaulted template
 *   arguments will be suppressed in the external representations
 *   of the class Name (such as seen by the persistency service).
 *   This can be used to add a new template argument to a class
 *   without breaking backwards compatibility.
 *   Example:
 *
 *   @code
 *   template <class T, class U> class Reflex::selection::C; // forward declaration
 *
 *   template <class T, class U=int>
 *   class C
 *   {
 *   public:
 *     ...
 *     typedef typename Reflex::selection::C<T>::self DictSelection;
 *   };
 *
 *     namespace Reflex {
 *       namespace selection {
 *         template <class T, class U>
 *         class C
 *         {
 *           typedef DictSelection<C> self;
 *
 *           TEMPLATE_DEFAULTS<NODEFAULT, int> dummy;
 *         };
 *       }
 *     }
 * // With the above, then C<T,int> will be represented externally
 * // as just `C<T>'.
 *
   @endcode
 */


namespace Reflex {
namespace Selection {
/*
 * @brief turn of autoselection of the class
 *
 * By default classes which appear in the Selection namespace will be selected
 * for dictionary generation. If a class has a member of type NO_SELF_AUTOSELECT
 * no dictionary information for this class will be generated.
 */
class RFLX_API NO_SELF_AUTOSELECT {};


/*
 * @brief Mark a MemberAt as being transient.
 *
 * This should be used in a selection class.  This marks the corresponding
 * MemberAt as being transient.  See the header comments for examples.
 */
class RFLX_API TRANSIENT {};


/*
 * @brief Mark the At of a (data)MemberAt as autoselected.
 *
 * This should be used in a selection class. The Name of the MemberAt shall be the same
 * as the MemberAt in the original class and will be automatically
 * selected to have dictionary information generated wherever it's
 * needed.  See the header comments for examples.
 */
class RFLX_API AUTOSELECT {};


/*
 * @brief Placeholder for @c TEMPLATE_DEFAULTS.
 *
 * This is used in the @c TEMPLATE_DEFAULTS template argument list
 * for positions where template arguments cannot be defaulted.
 */
struct RFLX_API NODEFAULT {};


/*
 * @brief Declare template argument defaults.
 *
 * This should be used in a selection class.  The template arguments
 * of this class give the template argument defaults for the class
 * being described.  If the class is used with defaulted template
 * arguments, then these arguments will be omitted from external
 * representations.  See the header comments for examples.
 */
template <class T1 = NODEFAULT,
          class T2 = NODEFAULT,
          class T3 = NODEFAULT,
          class T4 = NODEFAULT,
          class T5 = NODEFAULT,
          class T6 = NODEFAULT,
          class T7 = NODEFAULT,
          class T8 = NODEFAULT,
          class T9 = NODEFAULT,
          class T10 = NODEFAULT,
          class T11 = NODEFAULT,
          class T12 = NODEFAULT,
          class T13 = NODEFAULT,
          class T14 = NODEFAULT,
          class T15 = NODEFAULT>
struct TEMPLATE_DEFAULTS {
   typedef NODEFAULT nodefault;
   typedef T1 t1;
   typedef T2 t2;
   typedef T3 t3;
   typedef T4 t4;
   typedef T5 t5;
   typedef T6 t6;
   typedef T7 t7;
   typedef T8 t8;
   typedef T9 t9;
   typedef T10 t10;
   typedef T11 t11;
   typedef T12 t12;
   typedef T13 t13;
   typedef T14 t14;
   typedef T15 t15;
};

}    // namespace Selection

} // namespace Reflex


#endif // Reflex_DictSelection
 DictSelection.h:1
 DictSelection.h:2
 DictSelection.h:3
 DictSelection.h:4
 DictSelection.h:5
 DictSelection.h:6
 DictSelection.h:7
 DictSelection.h:8
 DictSelection.h:9
 DictSelection.h:10
 DictSelection.h:11
 DictSelection.h:12
 DictSelection.h:13
 DictSelection.h:14
 DictSelection.h:15
 DictSelection.h:16
 DictSelection.h:17
 DictSelection.h:18
 DictSelection.h:19
 DictSelection.h:20
 DictSelection.h:21
 DictSelection.h:22
 DictSelection.h:23
 DictSelection.h:24
 DictSelection.h:25
 DictSelection.h:26
 DictSelection.h:27
 DictSelection.h:28
 DictSelection.h:29
 DictSelection.h:30
 DictSelection.h:31
 DictSelection.h:32
 DictSelection.h:33
 DictSelection.h:34
 DictSelection.h:35
 DictSelection.h:36
 DictSelection.h:37
 DictSelection.h:38
 DictSelection.h:39
 DictSelection.h:40
 DictSelection.h:41
 DictSelection.h:42
 DictSelection.h:43
 DictSelection.h:44
 DictSelection.h:45
 DictSelection.h:46
 DictSelection.h:47
 DictSelection.h:48
 DictSelection.h:49
 DictSelection.h:50
 DictSelection.h:51
 DictSelection.h:52
 DictSelection.h:53
 DictSelection.h:54
 DictSelection.h:55
 DictSelection.h:56
 DictSelection.h:57
 DictSelection.h:58
 DictSelection.h:59
 DictSelection.h:60
 DictSelection.h:61
 DictSelection.h:62
 DictSelection.h:63
 DictSelection.h:64
 DictSelection.h:65
 DictSelection.h:66
 DictSelection.h:67
 DictSelection.h:68
 DictSelection.h:69
 DictSelection.h:70
 DictSelection.h:71
 DictSelection.h:72
 DictSelection.h:73
 DictSelection.h:74
 DictSelection.h:75
 DictSelection.h:76
 DictSelection.h:77
 DictSelection.h:78
 DictSelection.h:79
 DictSelection.h:80
 DictSelection.h:81
 DictSelection.h:82
 DictSelection.h:83
 DictSelection.h:84
 DictSelection.h:85
 DictSelection.h:86
 DictSelection.h:87
 DictSelection.h:88
 DictSelection.h:89
 DictSelection.h:90
 DictSelection.h:91
 DictSelection.h:92
 DictSelection.h:93
 DictSelection.h:94
 DictSelection.h:95
 DictSelection.h:96
 DictSelection.h:97
 DictSelection.h:98
 DictSelection.h:99
 DictSelection.h:100
 DictSelection.h:101
 DictSelection.h:102
 DictSelection.h:103
 DictSelection.h:104
 DictSelection.h:105
 DictSelection.h:106
 DictSelection.h:107
 DictSelection.h:108
 DictSelection.h:109
 DictSelection.h:110
 DictSelection.h:111
 DictSelection.h:112
 DictSelection.h:113
 DictSelection.h:114
 DictSelection.h:115
 DictSelection.h:116
 DictSelection.h:117
 DictSelection.h:118
 DictSelection.h:119
 DictSelection.h:120
 DictSelection.h:121
 DictSelection.h:122
 DictSelection.h:123
 DictSelection.h:124
 DictSelection.h:125
 DictSelection.h:126
 DictSelection.h:127
 DictSelection.h:128
 DictSelection.h:129
 DictSelection.h:130
 DictSelection.h:131
 DictSelection.h:132
 DictSelection.h:133
 DictSelection.h:134
 DictSelection.h:135
 DictSelection.h:136
 DictSelection.h:137
 DictSelection.h:138
 DictSelection.h:139
 DictSelection.h:140
 DictSelection.h:141
 DictSelection.h:142
 DictSelection.h:143
 DictSelection.h:144
 DictSelection.h:145
 DictSelection.h:146
 DictSelection.h:147
 DictSelection.h:148
 DictSelection.h:149
 DictSelection.h:150
 DictSelection.h:151
 DictSelection.h:152
 DictSelection.h:153
 DictSelection.h:154
 DictSelection.h:155
 DictSelection.h:156
 DictSelection.h:157
 DictSelection.h:158
 DictSelection.h:159
 DictSelection.h:160
 DictSelection.h:161
 DictSelection.h:162
 DictSelection.h:163
 DictSelection.h:164
 DictSelection.h:165
 DictSelection.h:166
 DictSelection.h:167
 DictSelection.h:168
 DictSelection.h:169
 DictSelection.h:170
 DictSelection.h:171
 DictSelection.h:172
 DictSelection.h:173
 DictSelection.h:174
 DictSelection.h:175
 DictSelection.h:176
 DictSelection.h:177
 DictSelection.h:178
 DictSelection.h:179
 DictSelection.h:180
 DictSelection.h:181
 DictSelection.h:182
 DictSelection.h:183
 DictSelection.h:184
 DictSelection.h:185
 DictSelection.h:186
 DictSelection.h:187
 DictSelection.h:188
 DictSelection.h:189
 DictSelection.h:190
 DictSelection.h:191
 DictSelection.h:192
 DictSelection.h:193
 DictSelection.h:194
 DictSelection.h:195
 DictSelection.h:196
 DictSelection.h:197
 DictSelection.h:198
 DictSelection.h:199
 DictSelection.h:200
 DictSelection.h:201
 DictSelection.h:202
 DictSelection.h:203
 DictSelection.h:204
 DictSelection.h:205
 DictSelection.h:206
 DictSelection.h:207
 DictSelection.h:208
 DictSelection.h:209
 DictSelection.h:210
 DictSelection.h:211
 DictSelection.h:212
 DictSelection.h:213
 DictSelection.h:214
 DictSelection.h:215
 DictSelection.h:216
 DictSelection.h:217
 DictSelection.h:218
 DictSelection.h:219
 DictSelection.h:220
 DictSelection.h:221
 DictSelection.h:222
 DictSelection.h:223
 DictSelection.h:224
 DictSelection.h:225
 DictSelection.h:226
 DictSelection.h:227
 DictSelection.h:228
 DictSelection.h:229
 DictSelection.h:230
 DictSelection.h:231
 DictSelection.h:232
 DictSelection.h:233
 DictSelection.h:234
 DictSelection.h:235
 DictSelection.h:236
 DictSelection.h:237
 DictSelection.h:238
 DictSelection.h:239
 DictSelection.h:240
 DictSelection.h:241
 DictSelection.h:242
 DictSelection.h:243
 DictSelection.h:244
 DictSelection.h:245
 DictSelection.h:246
 DictSelection.h:247
 DictSelection.h:248
 DictSelection.h:249
 DictSelection.h:250
 DictSelection.h:251
 DictSelection.h:252
 DictSelection.h:253
 DictSelection.h:254
 DictSelection.h:255
 DictSelection.h:256
 DictSelection.h:257
 DictSelection.h:258
 DictSelection.h:259
 DictSelection.h:260
 DictSelection.h:261
 DictSelection.h:262
 DictSelection.h:263
 DictSelection.h:264
 DictSelection.h:265
 DictSelection.h:266
 DictSelection.h:267
 DictSelection.h:268
 DictSelection.h:269
 DictSelection.h:270
 DictSelection.h:271
 DictSelection.h:272
 DictSelection.h:273
 DictSelection.h:274
 DictSelection.h:275
 DictSelection.h:276
 DictSelection.h:277
 DictSelection.h:278
 DictSelection.h:279
 DictSelection.h:280
 DictSelection.h:281
 DictSelection.h:282
 DictSelection.h:283
 DictSelection.h:284
 DictSelection.h:285
 DictSelection.h:286
 DictSelection.h:287
 DictSelection.h:288
 DictSelection.h:289
 DictSelection.h:290
 DictSelection.h:291
 DictSelection.h:292
 DictSelection.h:293
 DictSelection.h:294
 DictSelection.h:295
 DictSelection.h:296
 DictSelection.h:297
 DictSelection.h:298
 DictSelection.h:299
 DictSelection.h:300
 DictSelection.h:301
 DictSelection.h:302
 DictSelection.h:303
 DictSelection.h:304
 DictSelection.h:305
 DictSelection.h:306
 DictSelection.h:307
 DictSelection.h:308
 DictSelection.h:309
 DictSelection.h:310