HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
templateString.h
Go to the documentation of this file.
1 //
2 // Copyright 2016 Pixar
3 //
4 // Licensed under the Apache License, Version 2.0 (the "Apache License")
5 // with the following modification; you may not use this file except in
6 // compliance with the Apache License and the following modification to it:
7 // Section 6. Trademarks. is deleted and replaced with:
8 //
9 // 6. Trademarks. This License does not grant permission to use the trade
10 // names, trademarks, service marks, or product names of the Licensor
11 // and its affiliates, except as required to comply with Section 4(c) of
12 // the License and to reproduce the content of the NOTICE file.
13 //
14 // You may obtain a copy of the Apache License at
15 //
16 // http://www.apache.org/licenses/LICENSE-2.0
17 //
18 // Unless required by applicable law or agreed to in writing, software
19 // distributed under the Apache License with the above modification is
20 // distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
21 // KIND, either express or implied. See the Apache License for the specific
22 // language governing permissions and limitations under the Apache License.
23 //
24 #ifndef PXR_BASE_TF_TEMPLATE_STRING_H
25 #define PXR_BASE_TF_TEMPLATE_STRING_H
26 
27 /// \file tf/templateString.h
28 
29 #include "pxr/pxr.h"
30 
31 #include "pxr/base/tf/api.h"
32 
33 #include <tbb/spin_mutex.h>
34 
35 #include <map>
36 #include <memory>
37 #include <string>
38 #include <vector>
39 
41 
42 /// \class TfTemplateString
43 /// \ingroup group_tf_String
44 ///
45 /// TfTemplateString provides simple string substitutions based on named
46 /// placeholders. Instead of the '%'-based substitutions used by printf,
47 /// template strings use '$'-based substitutions, using the following rules:
48 ///
49 /// \li "$$" is replaced with a single "$"
50 /// \li "$identifier" names a substitution placeholder matching a mapping key
51 /// of "identifier". The first non-identifier character after the "$"
52 /// character terminates the placeholder specification.
53 /// \li "${identifier}" is equivalent to "$identifier". It is required when
54 /// valid identifier characters follow the placeholder but are not part of the
55 /// placeholder, such as "${noun}ification".
56 /// \li An identifier is a sequence of characters "[A-Z][a-z][0-9]_".
57 ///
58 /// \a TfTemplateString is immutable: once one is created it may not be
59 /// modified. \a TfTemplateString is fast to copy, since it shares state
60 /// internally between copies. \a TfTemplateString is thread-safe. It may be
61 /// read freely by multiple threads concurrently.
62 ///
64 public:
65  typedef std::map<std::string, std::string> Mapping;
66 
67  /// Constructs a new template string.
68  TF_API
70 
71  /// Constructs a new template string.
72  TF_API
73  TfTemplateString(const std::string& template_);
74 
75  /// Returns the template source string supplied to the constructor.
76  const std::string& GetTemplate() const { return _data->template_; }
77 
78  /// Performs the template substitution, returning a new string. The mapping
79  /// contains keys which match the placeholders in the template. If a
80  /// placeholder is found for which no mapping is present, a coding error is
81  /// raised.
82  TF_API
83  std::string Substitute(const Mapping&) const;
84 
85  /// Like Substitute(), except that if placeholders are missing from the
86  /// mapping, instead of raising a coding error, the original placeholder
87  /// will appear in the resulting string intact.
88  TF_API
89  std::string SafeSubstitute(const Mapping&) const;
90 
91  /// Returns an empty mapping for the current template. This method first
92  /// calls IsValid to ensure that the template is valid.
93  TF_API
94  Mapping GetEmptyMapping() const;
95 
96  /// Returns true if the current template is well formed. Empty templates are
97  /// valid.
98  TF_API
99  bool IsValid() const;
100 
101  /// Returns any error messages generated during template parsing.
102  TF_API
103  std::vector<std::string> GetParseErrors() const;
104 
105 private:
106  struct _PlaceHolder {
107  _PlaceHolder(const std::string& n, size_t p, size_t l)
108  : name(n), pos(p), len(l) {}
110  size_t pos;
111  size_t len;
112  };
113 
114  // Returns a new string constructed by performing token replacement.
115  std::string _Evaluate(const Mapping&, std::vector<std::string>* = 0) const;
116 
117  // Finds the next token-like substring in the template and returns the
118  // token name, position and length. For token ${foo}, the name is 'foo',
119  // position is the position of '$' and length is the length of the entire
120  // token including optional enclosing braces.
121  bool _FindNextPlaceHolder(size_t*, std::vector<std::string>*) const;
122 
123  // Find all tokens in the template string and store away naming and
124  // position information.
125  void _ParseTemplate() const;
126 
127  // Emit any parse errors as TF_CODING_ERRORs.
128  void _EmitParseErrors() const;
129 
130  // Structure side-allocated and shared between copies.
131  struct _Data
132  {
133  _Data(_Data const &) = delete;
134  _Data &operator=(_Data const &) = delete;
135 
136  _Data() : parsed(false) {}
137 
138  std::string template_;
139  mutable std::vector<_PlaceHolder> placeholders;
140  mutable bool parsed;
141  mutable std::vector<std::string> parseErrors;
142  mutable tbb::spin_mutex mutex;
143  };
144 
145  std::shared_ptr<_Data> _data;
146 };
147 
149 
150 #endif // PXR_BASE_TF_TEMPLATE_STRING_H
GLuint const GLchar * name
Definition: glew.h:1814
#define TF_API
Definition: api.h:40
TF_API std::string SafeSubstitute(const Mapping &) const
GLdouble l
Definition: glew.h:9122
TF_API TfTemplateString()
Constructs a new template string.
const std::string & GetTemplate() const
Returns the template source string supplied to the constructor.
std::map< std::string, std::string > Mapping
GLsizei n
Definition: glew.h:4040
TF_API bool IsValid() const
TF_API std::vector< std::string > GetParseErrors() const
Returns any error messages generated during template parsing.
GLfloat GLfloat p
Definition: glew.h:16321
GLsizei const GLchar *const * string
Definition: glew.h:1844
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1346
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
TF_API Mapping GetEmptyMapping() const
TF_API std::string Substitute(const Mapping &) const
GLenum GLsizei len
Definition: glew.h:7752