Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | File List | Namespace Members | Class Members | File Members | Related Pages

uniconfkey.h

Go to the documentation of this file.
00001 /* -*- Mode: C++ -*- 00002 * Worldvisions Weaver Software: 00003 * Copyright (C) 2002 Net Integration Technologies, Inc. 00004 * 00005 * UniConfKeys are paths in the UniConf hierarchy. 00006 */ 00007 #ifndef __UNICONFKEY_H 00008 #define __UNICONFKEY_H 00009 00010 #include "wvstring.h" 00011 #include "wvlinklist.h" 00012 00013 /** 00014 * Represents a UniConf key which is a path in a hierarchy structured much 00015 * like the traditional Unix filesystem. 00016 * 00017 * - Segments in the path are delimited by slashes. 00018 * - The empty string refers to the current level of the tree (eg. root). 00019 * - Keys are case insensitive yet preserve case information. 00020 * - Paired slashes are converted to single slashes. 00021 * - Trailing slashes are discarded. 00022 * 00023 * The following paths are equivalent when canonicalized: 00024 * 00025 * - foo/key (the canonical representation) 00026 * - Foo/Key (also canonical but preserves case) 00027 * - /foo/key (converted to foo/key) 00028 * - foo//key (converted to foo/key) 00029 * - foo/key/ (converted to foo/key) 00030 * 00031 * Keys that may contain slashes or nulls should be escaped in some fashion 00032 * prior to constructing a UniConfKey object. Simply prefixing slashes with 00033 * backslashes is inadequate because UniConfKey does not give any special 00034 * meaning to backslash. 00035 */ 00036 class UniConfKey 00037 { 00038 WvString path; 00039 00040 public: 00041 static UniConfKey EMPTY; /*!< represents "" (root) */ 00042 static UniConfKey ANY; /*!< represents "*" */ 00043 static UniConfKey RECURSIVE_ANY; /*!< represents "..." */ 00044 00045 /** Constructs an empty UniConfKey (the 'root'). */ 00046 UniConfKey(); 00047 00048 /** 00049 * Constructs a UniConfKey from a string. 00050 * 00051 * See the rules above for information about how the key string 00052 * is canonicalized. 00053 * 00054 * "key" is the key as a string 00055 */ 00056 UniConfKey(WvStringParm key) 00057 { init(key); } 00058 00059 /** 00060 * Constructs a UniConfKey from a string. 00061 * 00062 * See the rules above for information about how the key string 00063 * is canonicalized. This constructor only exists to help out the 00064 * C++ compiler with its automatic type conversions. 00065 * 00066 * "key" is the key as a string 00067 */ 00068 UniConfKey(const char *key) 00069 { init(key); } 00070 00071 /** Constructs a UniConfKey from an int. */ 00072 UniConfKey(int key) 00073 { init(key); } 00074 00075 /** 00076 * Copies a UniConfKey. 00077 * "other" is the key to copy 00078 */ 00079 UniConfKey(const UniConfKey &other); 00080 00081 /** 00082 * Constructs a UniConfKey by concatenating two keys. 00083 * "path" is the initial part of the new path 00084 * "key" is the tail of the new path 00085 */ 00086 UniConfKey(const UniConfKey &path, const UniConfKey &key); 00087 00088 /** 00089 * Appends a path to this path. 00090 * "other" is the path 00091 */ 00092 void append(const UniConfKey &other); 00093 00094 /** 00095 * Prepends a path to this path. 00096 * "other" is the path 00097 */ 00098 void prepend(const UniConfKey &other); 00099 00100 /** 00101 * Returns true if this path has zero segments (also known as root). 00102 * Returns: numsegments() == 0 00103 */ 00104 bool isempty() const; 00105 00106 /** Returns true if the key contains a wildcard. */ 00107 bool iswild() const; 00108 00109 /** 00110 * Returns the number of segments in this path. 00111 * 00112 * The number of segments is equal to the number of slashes 00113 * in the path unless the path is "/" (the root), which has 00114 * zero segments. 00115 * 00116 * Returns: the number of segments 00117 */ 00118 int numsegments() const; 00119 00120 /** 00121 * Returns the specified segment of the path. 00122 * "i" is the segment index 00123 * Returns: the segment 00124 */ 00125 UniConfKey segment(int i) const; 00126 00127 /** 00128 * Returns the path formed by the n first segments of this path. 00129 * "n" is the number of segments 00130 * Returns: the path 00131 */ 00132 UniConfKey first(int n = 1) const; 00133 00134 /** 00135 * Returns the path formed by the n last segments of this path. 00136 * "n" is the number of segments 00137 * Returns: the path 00138 */ 00139 UniConfKey last(int n = 1) const; 00140 00141 /** 00142 * Returns the path formed by removing the first n segments of 00143 * this path. 00144 * "n" is the number of segments 00145 * Returns: the path 00146 */ 00147 UniConfKey removefirst(int n = 1) const; 00148 00149 /** 00150 * Returns the path formed by removing the last n segments of 00151 * this path. 00152 * "n" is the number of segments 00153 * Returns: the path 00154 */ 00155 UniConfKey removelast(int n = 1) const; 00156 00157 /** 00158 * Returns a range of segments. 00159 * "i" is the first segment index, beginning if <= 0 00160 * "j" is the last segment index, end if >= numsegments() 00161 * Returns: the path, empty if j <= i 00162 */ 00163 UniConfKey range(int i, int j) const; 00164 00165 /** 00166 * Returns the canonical string representation of the path. 00167 * 00168 * If the UniConfKey was constructed in part or whole from 00169 * strings, then the string returned here will have the same 00170 * case information as those strings but the arrangement of 00171 * slashes may differ. That is, the identity 00172 * UniConfKey(string).printable() == string does not hold. 00173 * 00174 * Returns: the path as a string 00175 */ 00176 WvString printable() const; 00177 operator WvString() const 00178 { return printable(); } 00179 00180 /** 00181 * Assigns this path to equal another. 00182 * "other" is the other path 00183 */ 00184 UniConfKey &operator= (const UniConfKey &other); 00185 00186 /** 00187 * Compares two paths lexicographically. 00188 * Uses case-insensitive matching on the path string to produce 00189 * a total ordering of all paths. 00190 * "other" is the other path 00191 * Returns: 0 if *this == other, < 0 if *this < other, else > 0 00192 */ 00193 int compareto(const UniConfKey &other) const; 00194 00195 /** 00196 * Determines if the key matches a pattern. 00197 * Patterns are simply keys that may have path segments consiting 00198 * entirely of "*". Optional path segments are indicated by 00199 * the segment "..." which matches zero or more segments. 00200 * 00201 * Using wildcards to represent part of a segment is not supported yet. 00202 * "pattern" is the pattern 00203 * Returns: true if the key matches, false otherwise 00204 */ 00205 bool matches(const UniConfKey &pattern) const; 00206 00207 00208 /** 00209 * Returns true if this key is either the same key as the key specified 00210 * or a subkey of that key. 00211 */ 00212 bool suborsame(const UniConfKey &key) const; 00213 00214 /** 00215 * Determines if two paths are equal. 00216 * "other" is the other path 00217 * Returns: true in that case 00218 */ 00219 bool operator== (const UniConfKey &other) const 00220 { return compareto(other) == 0; } 00221 00222 /** 00223 * Determines if two paths are unequal. 00224 * "other" is the other path 00225 * Returns: true in that case 00226 */ 00227 bool operator!= (const UniConfKey &other) const 00228 { return ! (*this == other); } 00229 00230 /** 00231 * Determines if this path precedes the other lexicographically. 00232 * "other" is the other path 00233 * Returns: true in that case 00234 */ 00235 bool operator< (const UniConfKey &other) const 00236 { return compareto(other) < 0; } 00237 00238 class Iter; 00239 00240 protected: 00241 void init(WvStringParm key); 00242 }; 00243 00244 00245 DeclareWvList(UniConfKey); 00246 00247 /** An iterator over the segments of a key. */ 00248 class UniConfKey::Iter 00249 { 00250 const UniConfKey &key; 00251 int seg, max; 00252 UniConfKey curseg; 00253 00254 public: 00255 Iter(const UniConfKey &_key) : key(_key) 00256 { } 00257 00258 void rewind() 00259 { seg = -1; max = key.numsegments(); } 00260 00261 bool cur() 00262 { return seg >= 0 && seg < max; } 00263 00264 bool next() 00265 { seg++; curseg = key.segment(seg); return cur(); } 00266 00267 const UniConfKey *ptr() const 00268 { return &curseg; } 00269 00270 WvIterStuff(const UniConfKey); 00271 }; 00272 00273 #endif // __UNICONFKEY_H

Generated on Tue Oct 5 01:09:19 2004 for WvStreams by doxygen 1.3.7