ACE/ace/Tokenizer_T.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    Tokenizer_T.h
   6  *
   7  *  @author Douglas C. Schmidt (d.schmidt@vanderbilt.edu)
   8  *  @author Nanbor Wang <nanbor@cs.wustl.edu>
   9  */
  10 //=============================================================================
  11
  12 #ifndef ACE_TOKENIZER_T_H
  13 #define ACE_TOKENIZER_T_H
  14
  15 #include /**/ "ace/pre.h"
  16
  17 #include "ace/Global_Macros.h"
  18
  19 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  20 # pragma once
  21 #endif /* ACE_LACKS_PRAGMA_ONCE */
  22
  23 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  24
  25 /**
  26  * @class ACE_Tokenizer_T
  27  *
  28  * @brief Tokenizer
  29  *
  30  * Tokenizes a buffer.  Allows application to set delimiters and
  31  * preserve designators.  Does not allow special characters, yet
  32  * (e.g., printf ("\"like a quoted string\"")).
  33  */
  34 template <class ACE_CHAR_T>
  35 class ACE_Tokenizer_T
  36 {
  37 public:
  38   /**
  39    * \a buffer will be parsed.  Notice that ACE_Tokenizer_T will modify
  40    * \a buffer if you use <code> delimiter_replace </code> or <code>
  41    * preserve_designators </code> to do character substitution.
  42    * @note You should NOT pass a constant string or string literal
  43    * to this constructor, since ACE_Tokenizer_T will try to modify
  44    * the string.
  45    * \sa preserve_designators
  46    * \sa preserve_designators
  47    */
  48   ACE_Tokenizer_T (ACE_CHAR_T *buffer);
  49
  50   /**
  51    * \a d is a delimiter.
  52    * \return Returns 0 on success, -1 if there is no memory left.
  53    *
  54    * <B>Example:</B>
  55    * \verbatim
  56      char buf[30];
  57      ACE_OS::strcpy(buf, "William/Joseph/Hagins");
  58
  59      ACE_Tokenizer_T tok (buf);
  60      tok.delimiter ('/');
  61      for (char *p = tok.next (); p; p = tok.next ())
  62       cout << p << endl;
  63     \endverbatim
  64    *
  65    * This will print out:
  66    * \verbatim
  67      William/Joseph/Hagins
  68       Joseph/Hagins
  69       Hagins \endverbatim
  70    */
  71   int delimiter (ACE_CHAR_T d);
  72
  73   /**
  74    * \a d is a delimiter and, when found, will be replaced by
  75    * \a replacement.
  76    * \return 0 on success, -1 if there is no memory left.
  77    *
  78    * <B>Example:</B>
  79    * \verbatim
  80      char buf[30];
  81      ACE_OS::strcpy(buf, "William/Joseph/Hagins");
  82
  83      ACE_Tokenizer tok (buf);
  84      tok.delimiter_replace ('/', 0);
  85      for (char *p = tok.next (); p; p = tok.next ())
  86        cout << p << endl;
  87     \endverbatim
  88    *
  89    * This will print out:
  90    * \verbatim
  91        William
  92        Joseph
  93        Hagins \endverbatim
  94  */
  95   int delimiter_replace (ACE_CHAR_T d, ACE_CHAR_T replacement);
  96
  97   /**
  98    * Extract string between a pair of designator characters.
  99    * For instance, quotes, or '(' and ')'.
 100    * \a start specifies the begin designator.
 101    * \a stop specifies the end designator.
 102    * \a strip If \a strip == 1, then the preserve
 103    * designators will be stripped from the tokens returned by next.
 104    * \return 0 on success, -1 if there is no memory left.
 105    *
 106    * <B>Example with strip = 0:</B>
 107    * \verbatim
 108      char buf[30];
 109      ACE_OS::strcpy(buf, "William(Joseph)Hagins");
 110
 111      ACE_Tokenizer tok (buf);
 112      tok.preserve_designators ('(', ')', 0);
 113      for (char *p = tok.next (); p; p = tok.next ())
 114        cout << p << endl;
 115     \endverbatim
 116    *
 117    * This will print out:
 118    * \verbatim
 119       William(Joseph)Hagins
 120       (Joseph)Hagins
 121       )Hagins \endverbatim
 122    *
 123    * <B>Example with strip = 1:</B>
 124    * \verbatim
 125      char buf[30];
 126      ACE_OS::strcpy(buf, "William(Joseph)Hagins");
 127
 128      ACE_Tokenizer tok (buf);
 129      tok.preserve_designators ('(', ')', 1);
 130      for (char *p = tok.next (); p; p = tok.next ())
 131        cout << p << endl;
 132     \endverbatim
 133    *
 134    * This will print out:
 135    * \verbatim
 136       William
 137       Joseph
 138       Hagins \endverbatim
 139    */
 140   int preserve_designators (ACE_CHAR_T start, ACE_CHAR_T stop, int strip=1);
 141
 142   /// Returns the next token.
 143   ACE_CHAR_T *next (void);
 144
 145   enum {
 146     MAX_DELIMITERS=16,
 147     MAX_PRESERVES=16
 148   };
 149
 150 protected:
 151   /// Returns 1 if @a d is a delimiter, 0 otherwise.  If @a d should be
 152   /// replaced with @a r, @a replace is set to 1, otherwise 0.
 153   int is_delimiter (ACE_CHAR_T d, int &replace, ACE_CHAR_T &r);
 154
 155   /**
 156    * If @a start is a start preserve designator, returns 1 and sets
 157    * @a stop to the stop designator.  Returns 0 if @a start is not a
 158    * preserve designator.
 159    */
 160   int is_preserve_designator (ACE_CHAR_T start, ACE_CHAR_T &stop, int &strip);
 161
 162   ACE_CHAR_T *buffer_;
 163   int index_;
 164
 165   /**
 166    * @class Preserve_Entry
 167    *
 168    * @brief Preserve Entry
 169    *
 170    * Defines a set of characters that designate an area that
 171    * should not be parsed, but should be treated as a complete
 172    * token.  For instance, in: (this is a preserve region), start
 173    * would be a left paren -(- and stop would be a right paren
 174    * -)-.  The strip determines whether the designators should be
 175    * removed from the token.
 176    */
 177   class Preserve_Entry
 178   {
 179   public:
 180     /**
 181      * E.g., "(".
 182      * E.g., ")".
 183      * Whether the designators should be removed from the token.
 184      */
 185     ACE_CHAR_T start_;
 186     ACE_CHAR_T stop_;
 187     int strip_;
 188   };
 189
 190   /// The application can specify MAX_PRESERVES preserve designators.
 191   Preserve_Entry preserves_[MAX_PRESERVES];
 192
 193   /// Pointer to the next free spot in preserves_.
 194   int preserves_index_;
 195
 196   /**
 197    * @class Delimiter_Entry
 198    *
 199    * @brief Delimiter Entry
 200    *
 201    * Describes a delimiter for the tokenizer.
 202    */
 203   class Delimiter_Entry
 204   {
 205   public:
 206     /**
 207      * Most commonly a space ' '.
 208      * What occurrences of delimiter_ should be replaced with.
 209      * Whether replacement_ should be used.  This should be replaced
 210      * with a technique that sets replacement_ = delimiter by
 211      * default.  I'll do that next iteration.
 212      */
 213     ACE_CHAR_T delimiter_;
 214     ACE_CHAR_T replacement_;
 215     int replace_;
 216   };
 217
 218   /// The tokenizer allows MAX_DELIMITERS number of delimiters.
 219   Delimiter_Entry delimiters_[MAX_DELIMITERS];
 220
 221   /// Pointer to the next free space in delimiters_.
 222   int delimiter_index_;
 223 };
 224
 225 typedef ACE_Tokenizer_T <ACE_TCHAR> ACE_Tokenizer;
 226
 227 ACE_END_VERSIONED_NAMESPACE_DECL
 228
 229 #if defined (ACE_TEMPLATES_REQUIRE_SOURCE)
 230 #include "ace/Tokenizer_T.cpp"
 231 #endif /* ACE_TEMPLATES_REQUIRE_SOURCE */
 232
 233 #if defined (ACE_TEMPLATES_REQUIRE_PRAGMA)
 234 #pragma implementation ("Tokenizer_T.cpp")
 235 #endif /* ACE_TEMPLATES_REQUIRE_PRAGMA */
 236
 237 #include /**/ "ace/post.h"
 238
 239 #endif /* ACE_TOKENIZER_T_H */