added kdenlive
[feisty_meow.git] / nucleus / library / configuration / variable_tokenizer.h
1 #ifndef TOKENIZER_CLASS
2 #define TOKENIZER_CLASS
3
4 /*
5 *  Name   : variable_tokenizer
6 *  Author : Chris Koeritz
7 **
8 * Copyright (c) 1997-$now By Author.  This program is free software; you can  *
9 * redistribute it and/or modify it under the terms of the GNU General Public  *
10 * License as published by the Free Software Foundation; either version 2 of   *
11 * the License or (at your option) any later version.  This is online at:      *
12 *     http://www.fsf.org/copyleft/gpl.html                                    *
13 * Please send any updates to: fred@gruntose.com                               *
14 */
15
16 #include <basis/contracts.h>
17 #include <structures/string_table.h>
18
19 namespace configuration {
20
21 //! Manages a bank of textual definitions of variables.
22 /*!
23   Manipulates strings containing variable definitions where a variable
24   is syntactically defined as a name, an assignment operator, and a value.
25   The string can optionally define many variables by placing a separator
26   character between the definitions.  The assignment and separator are
27   referred to as sentinels in the following docs.
28   This class also supports quoted values if the appropriate constructor
29   is used.
30 */
31
32 class variable_tokenizer : public virtual basis::root_object
33 {
34 public:
35   enum constraints { DEFAULT_MAX_BITS = 7 };
36
37   variable_tokenizer(int max_bits = DEFAULT_MAX_BITS);
38     //!< creates a variable_tokenizer with the default characters.
39     /*!< this will not look for quote characters.  the "max_bits" establishes
40     the hashing width for the internal table of strings; there will be
41     2 ^ "max_bits" of space in the table.  the default assignment operator
42     is '=' and the default separator is ','. */
43
44   variable_tokenizer(const basis::astring &separator, const basis::astring &assignment,
45           int max_bits = DEFAULT_MAX_BITS);
46     //!< creates an empty list of tokens and uses the specified sentinel chars.
47     /*!< the character that is expected to be between name/value pairs is
48     "separator".  the "assignment" character is expected to be between each
49     name and its value.  note that if the "separator" or "assignment" are more
50     than one character long, these will be taken as a set of valid characters
51     that can be used for those purposes. */
52
53   variable_tokenizer(const basis::astring &separator, const basis::astring &assignment,
54           const basis::astring &quotes, bool nesting = true,
55           int max_bits = DEFAULT_MAX_BITS);
56     //!< similar to the constructor above, but supports quoting.
57     /*!< if the "quotes" list is not empty, then those characters will be
58     treated as quoting characters that must be matched in pairs.  inside a
59     quote, separators are ignored.  if "nesting" is not true, then only one
60     level of quotes will be considered; the occurrence of other types of
61     quotes will be ignored until the original type is completed. */
62
63   variable_tokenizer(const variable_tokenizer &to_copy);
64     //!< builds a variable_tokenizer that is identical to "to_copy".
65
66   virtual ~variable_tokenizer();
67
68   DEFINE_CLASS_NAME("variable_tokenizer");
69
70   void set_comment_chars(const basis::astring &comments);
71     //!< establishes a set of characters in "comments" as the comment items.
72     /*!< comments will be specially handled by being added to the string table
73     with the comment prefix.  this allows them to be regenerated uniquely
74     later. */
75
76   variable_tokenizer &operator =(const variable_tokenizer &to_copy);
77     //!< makes this variable_tokenizer identical to "to_copy".
78
79   int symbols() const;
80     //!< returns the number of entries in the variable_tokenizer.
81
82   void reset();
83     //!< clears all of the entries out.
84
85   const structures::string_table &table() const;
86     //!< provides a constant peek at the string_table holding the values.
87   structures::string_table &table();
88     //!< provides direct access to the string_table holding the values.
89
90 //fix these docs.
91   bool parse(const basis::astring &to_tokenize);
92     //!< parses the string using our established sentinel characters.
93     /*!< attempts to snag as many value/pairs from "to_tokenize" as are
94     possible by using the current separator and assignment characters.  
95     E.G.: if the separator is ';' and the assignment character
96     is '=', then one's string would look something like: @code
97       state_folder=/home/fred/state; GLOB=/usr/bin/glob.exe; ....  @endcode
98     whitespace is ignored if it's found (1) after a separator and before
99     the next variable name, (2) after the variable name and before the
100     assignment character, (3) after the assignment character and before the
101     value.  this unfortunately implies that white space cannot begin or end
102     a value.
103     NOTE: unpredictable results will occur: if one's variables are
104     improperly formed, if assignment operators are missing or misplaced,
105     or if the separator character is used within the value.
106     NOTE: carriage returns are considered white-space and can exist in the
107     string as described above.
108     NOTE: parse is additive; if multiple calls to parse() occur, then the
109     symbol_table will be built from the most recent values found in the
110     parameters to parse().  if this is not desired, the symbol table's
111     reset() function can be used to empty out all variables. */
112
113   basis::astring find(const basis::astring &name) const;
114     //!< locates the value for a variable named "name" if it exists.
115     /*!< if "name" doesn't exist, then it returns an empty string.  note that
116     an empty string might also indicate that the value is blank; locate is the
117     way to tell if a field is really missing.  also note that when a variable
118     name is followed by an assignment operator and an empty value (e.g.,
119     "avversione=" has no value), then a value of a single space character
120     will be stored.  this ensures that the same format is used on the
121     output side, but it also means that if you access the table directly,
122     then you will get a space as the value.  however, this function returns
123     an empty string for those entries to keep consistent with expectations. */
124
125   bool exists(const basis::astring &name) const;
126     //!< returns true if the "name" exists in the variable_tokenizer.
127
128   basis::astring text_form() const;
129     //!< creates a new token list as a string of text.
130     /*!< the first separator and assignment characters in each set are used
131     to generate it.  note that the whitespace that existed in the original
132     parsed string might not be exactly the same in the generated string. */
133   void text_form(basis::astring &to_fill) const;
134     //!< like text_form() above, but stores into "to_fill".
135
136   // dictates whether the output will have spaces between the assignment
137   // character and the key name and value.  default is to not add them.
138   bool add_spaces() const { return _add_spaces; }
139   void add_spaces(bool add_them) { _add_spaces = add_them; }
140
141   bool okay_for_variable_name(char to_check) const;
142     //!< true if "to_check" is a valid variable name character.
143     /*!< this includes any characters besides separators and assignments. */
144
145   const basis::astring &assignments() const;
146     //!< provides a peek at the assignments list.
147   const basis::astring &separators() const;
148     //!< provides a peek at the separators list.
149   const basis::astring &quotes() const;
150     //!< provides a peek at the quotes list.
151
152   bool assignment(char to_check) const;
153     //!< true if "to_check" is a valid assignment operator.
154
155   bool separator(char to_check) const;
156     //!< true if "to_check" is a valid separator.
157
158   bool comment_char(char to_check) const;
159     //!< true if "to_check" is a registered comment character.
160
161   bool is_eol_a_separator() const;
162     //!< reports whether any of the separators are an EOL character.
163
164   bool quote_mark(char to_check) const;
165     //!< true if "to_check" is a member of the quotes list.
166
167 private:
168   structures::string_table *_implementation;  //!< holds the parsed values.
169   basis::astring *_assignments;  //!< separates name from value.
170   basis::astring *_separators;  //!< separates name/value pairs from other pairs.
171   basis::astring *_quotes;  //!< the characters that are used for quoting.
172   bool _nesting;  //!< if true, we nest arbitrary levels of quotes.
173   basis::astring *_comments;  //!< if non-empty, characters that begin comments.
174   int _comment_number;  //!< automatically incremented for use in comment tags.
175   bool _add_spaces;  //!< records whether we add spaces around the assignment.
176 };
177
178 } //namespace.
179
180 #endif
181