HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
staticTokens.h
Go to the documentation of this file.
1 //
2 // Copyright 2016 Pixar
3 //
4 // Licensed under the terms set forth in the LICENSE.txt file available at
5 // https://openusd.org/license.
6 //
7 //todo: cleanup: TF_DEFINE_PRIVATE_TOKENS, should use the public versions
8 //todo: cleanup: document each macro extensively
9 //todo: cleanup: order macros, so that it is easier to see the structure
10 
11 #ifndef PXR_BASE_TF_STATIC_TOKENS_H
12 #define PXR_BASE_TF_STATIC_TOKENS_H
13 
14 /// \file tf/staticTokens.h
15 ///
16 /// This file defines some macros that are useful for declaring and using
17 /// static TfTokens. Typically, using static TfTokens is either cumbersome,
18 /// unsafe, or slow. These macros aim to solve many of the common problems.
19 ///
20 /// The following is an example of how they can be used.
21 ///
22 /// In header file:
23 ///
24 /// \code
25 /// #define MF_TOKENS \. <--- please ignore '.'
26 /// (transform) \.
27 /// (moves) \.
28 ///
29 /// // Syntax when string name differs from symbol.
30 /// ((foo, "bar"))
31 ///
32 /// TF_DECLARE_PUBLIC_TOKENS(MfTokens, MF_TOKENS);
33 /// \endcode
34 ///
35 /// In cpp file:
36 ///
37 /// \code
38 /// TF_DEFINE_PUBLIC_TOKENS(MfTokens, MF_TOKENS);
39 /// \endcode
40 ///
41 /// Access the token by using the key as though it were a pointer, like this:
42 ///
43 /// \code
44 /// MfTokens->transform;
45 /// \endcode
46 ///
47 /// An additional member, allTokens, is a std::vector<TfToken> populated
48 /// with all of the generated token members.
49 ///
50 /// There are PUBLIC and PRIVATE versions of the macros. The PRIVATE ones are
51 /// intended to be used when the tokens will only be used in a single .cpp
52 /// file, in which case they can be made file static. In the case of the
53 /// PRIVATE, you only need to use the DEFINE macro.
54 
55 #include "pxr/pxr.h"
57 #include "pxr/base/tf/staticData.h"
58 #include "pxr/base/tf/token.h"
59 
60 #include <vector>
61 
63 
64 // TF_DECLARE_PUBLIC_TOKENS use these macros to handle two or three arguments.
65 // The three argument version takes an export/import macro (e.g. TF_API)
66 // while the two argument version does not export the tokens.
67 
68 #define _TF_DECLARE_PUBLIC_TOKENS3(key, eiapi, seq) \
69  _TF_DECLARE_TOKENS3(key, seq, eiapi) \
70  extern eiapi TfStaticData<_TF_TOKENS_STRUCT_NAME(key)> key
71 #define _TF_DECLARE_PUBLIC_TOKENS2(key, seq) \
72  _TF_DECLARE_TOKENS2(key, seq) \
73  extern TfStaticData<_TF_TOKENS_STRUCT_NAME(key)> key
74 #define _TF_DECLARE_PUBLIC_TOKENS(N) _TF_DECLARE_PUBLIC_TOKENS##N
75 #define _TF_DECLARE_PUBLIC_TOKENS_EVAL(N) _TF_DECLARE_PUBLIC_TOKENS(N)
76 #define _TF_DECLARE_PUBLIC_TOKENS_EXPAND(x) x
77 
78 /// Macro to define public tokens. This declares a list of tokens that can be
79 /// used globally. Use in conjunction with TF_DEFINE_PUBLIC_TOKENS.
80 /// \hideinitializer
81 #define TF_DECLARE_PUBLIC_TOKENS(...) _TF_DECLARE_PUBLIC_TOKENS_EXPAND( _TF_DECLARE_PUBLIC_TOKENS_EVAL(_TF_DECLARE_PUBLIC_TOKENS_EXPAND( TF_PP_VARIADIC_SIZE(__VA_ARGS__) ))(__VA_ARGS__) )
82 
83 /// Macro to define public tokens. Use in conjunction with
84 /// TF_DECLARE_PUBLIC_TOKENS.
85 /// \hideinitializer
86 #define TF_DEFINE_PUBLIC_TOKENS(key, seq) \
87  _TF_DEFINE_TOKENS(key) \
88  TfStaticData<_TF_TOKENS_STRUCT_NAME(key)> key
89 
90 /// Macro to define private tokens.
91 /// \hideinitializer
92 #define TF_DEFINE_PRIVATE_TOKENS(key, seq) \
93  namespace { \
94  struct _TF_TOKENS_STRUCT_NAME_PRIVATE(key) { \
95  _TF_TOKENS_STRUCT_NAME_PRIVATE(key)() = default; \
96  _TF_TOKENS_DECLARE_MEMBERS(seq) \
97  }; \
98  } \
99  static TfStaticData<_TF_TOKENS_STRUCT_NAME_PRIVATE(key)> key
100 
101 ///////////////////////////////////////////////////////////////////////////////
102 // Private Macros
103 
104 // Private macro to generate struct name from key.
105 //
106 // Note that this needs to be a unique struct name for each translation unit.
107 //
108 #define _TF_TOKENS_STRUCT_NAME_PRIVATE(key) \
109  TF_PP_CAT(key, _PrivateStaticTokenType)
110 
111 // Private macro to generate struct name from key. This version is used
112 // by the public token declarations, and so key must be unique for the entire
113 // namespace.
114 //
115 #define _TF_TOKENS_STRUCT_NAME(key) \
116  TF_PP_CAT(key, _StaticTokenType)
117 
118 ///////////////////////////////////////////////////////////////////////////////
119 // Declaration Macros
120 
121 // Private macro used to generate TfToken member variables. elem can either
122 // be a tuple on the form (name, value) or just a name.
123 //
124 #define _TF_TOKENS_DECLARE_MEMBER(unused, elem) \
125  TfToken _TF_PP_IFF(TF_PP_IS_TUPLE(elem), \
126  TF_PP_TUPLE_ELEM(0, elem), elem){ \
127  _TF_PP_IFF(TF_PP_IS_TUPLE(elem), \
128  TF_PP_TUPLE_ELEM(1, elem), TF_PP_STRINGIZE(elem)), \
129  TfToken::Immortal};
130 #define _TF_TOKENS_DECLARE_TOKEN_MEMBERS(seq) \
131  TF_PP_SEQ_FOR_EACH(_TF_TOKENS_DECLARE_MEMBER, ~, seq)
132 
133 #define _TF_TOKENS_FORWARD_TOKEN(unused, elem) TF_PP_TUPLE_ELEM(0, elem),
134 #define _TF_TOKENS_DECLARE_ALL_TOKENS(seq) \
135  std::vector<TfToken> allTokens = \
136  {TF_PP_SEQ_FOR_EACH(_TF_TOKENS_FORWARD_TOKEN, ~, seq)};
137 
138 // Private macro used to declare the list of members as TfTokens
139 //
140 #define _TF_TOKENS_DECLARE_MEMBERS(seq) \
141  _TF_TOKENS_DECLARE_TOKEN_MEMBERS(seq) \
142  _TF_TOKENS_DECLARE_ALL_TOKENS(seq) \
143 
144 // Private macro used to generate a struct of TfTokens.
145 //
146 #define _TF_DECLARE_TOKENS3(key, seq, eiapi) \
147  struct _TF_TOKENS_STRUCT_NAME(key) { \
148  eiapi _TF_TOKENS_STRUCT_NAME(key)(); \
149  eiapi ~_TF_TOKENS_STRUCT_NAME(key)(); \
150  _TF_TOKENS_DECLARE_MEMBERS(seq) \
151  };
152 
153 #define _TF_DECLARE_TOKENS2(key, seq) \
154  struct _TF_TOKENS_STRUCT_NAME(key) { \
155  _TF_TOKENS_STRUCT_NAME(key)(); \
156  ~_TF_TOKENS_STRUCT_NAME(key)(); \
157  _TF_TOKENS_DECLARE_MEMBERS(seq) \
158  };
159 
160 ///////////////////////////////////////////////////////////////////////////////
161 // Definition Macros
162 
163 // Private macro to define the struct of tokens.
164 //
165 #define _TF_DEFINE_TOKENS(key) \
166  _TF_TOKENS_STRUCT_NAME(key)::~_TF_TOKENS_STRUCT_NAME(key)() = default; \
167  _TF_TOKENS_STRUCT_NAME(key)::_TF_TOKENS_STRUCT_NAME(key)() = default; \
168 
170 
171 #endif // PXR_BASE_TF_STATIC_TOKENS_H
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1425
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:74