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 Sat Feb 21 21:05:20 2004 for WvStreams by doxygen 1.3.5