UT/UT_TagManager.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * Produced by:
 *      Side Effects Software Inc
 *      123 Front Street West, Suite 1401
 *      Toronto, Ontario
 *      Canada   M5J 2M2
 *      416-504-9876
 *
 * NAME:        UT_TagManager.h ( UT Library, C++)
 *
 * COMMENTS:    Manage lists of tags.  Tags are simply name strings.  A list of
 *      tags is a list of names.  The names may contain alphanumeric characters
 *      along with the characters:
 *              '_' (underscore)
 *              '.' (period)
 *              '-' (minus) (we also support ^)
 *              ':' (colon)
 *      Names may NOT begin with '-' (minus).  Invalid characters will be
 *      forced to an '_' (underscore) character.
 *
 *      Pattern expression can also be created which can be matched against tag
 *      lists (see below for more documentation).
 *
 *      A global list of used tags are kept and may be retrieved.  The list is
 *      not cleared (TODO: it would be nice to have a garbage collection
 *      process)
 */

#ifndef __UT_TagManager__
#define __UT_TagManager__

#include "UT_API.h"
#include "UT_SymbolTable.h"
#include "UT_SmallObject.h"
#include "UT_String.h"
#include "UT_PtrArray.h"
#include <SYS/SYS_AtomicInt.h>

class UT_StringArray;
class UT_TagManager;
class UT_TagList;
class UT_TagExpression;
class ut_TagName;
class ut_TagList;
class ut_TagExpression;

class UT_API UT_TagList
        : public UT_SmallObject<UT_TagList,
                                UT_SMALLOBJECT_CLEANPAGES_ON,
                                512,
                                UT_SMALLOBJECT_THREADSAFE_ON>
{
public:
     UT_TagList(UT_TagManager &manager, ut_TagList *list)
         : myManager(manager), myList(list) { }
    ~UT_TagList();

    void         getListString(UT_WorkBuffer &buffer) const;
    bool         match(const UT_TagExpression &pattern) const;
    uint         hash() const;
    bool         compare(const UT_TagList &list) const;

private:
    UT_TagManager       &myManager;
    ut_TagList          *myList;
    friend class        UT_TagManager;
};

class UT_API UT_TagExpression
        : public UT_SmallObject<UT_TagExpression,
                                UT_SMALLOBJECT_CLEANPAGES_ON,
                                512,
                                UT_SMALLOBJECT_THREADSAFE_ON>
{
public:
     UT_TagExpression(UT_TagManager &manager, ut_TagExpression *pattern)
         : myManager(manager), myExpression(pattern) { }
    ~UT_TagExpression();

    void        getExpressionString(UT_WorkBuffer &buffer) const;
    bool        match(const UT_TagList &list) const;
    bool        isTautology() const;

private:
    UT_TagManager       &myManager;
    ut_TagExpression    *myExpression;
    friend class        UT_TagManager;
};

class UT_API UT_TagManager {
public:
     UT_TagManager(const char *name);
    ~UT_TagManager();

    /// getTagList() creates a tag-list object.  This is a list of names which
    /// are considered as tags for matching (see below).
    /// The names allow alphanumeric letters and characters from "_.:"
    UT_TagList          *createTagList(const char *list, UT_String &errs);
    UT_TagList          *copyTagList(const UT_TagList &src);

    /// createTagExpression() is used to create a pattern to match against tag
    /// lists.
    ///
    /// The tag expression can be a very simple expression consisting of
    ///   name  - Matches tag lists which have the name
    ///  -name  - Matches tag lists which do NOT contain the name
    ///   +     - Matches tag lists which have ANY entries
    ///   -     - Matches tag lists which have NO entries
    ///   *     - Matches all tag lists (Equivalent to "+|-")
    ///  -*     - Matches no tag lists (Equivalend to "+&-")
    ///
    /// Expressions may be joined with & or | (AND or OR).  For example
    ///   "-foo"        == Match all tags except those with "foo"
    ///   "* & -foo"    == Equivalent to "-foo"
    ///   "-foo & -bar" == Match all tags except those with "foo" or "bar"
    ///   "foo & -bar"  == Match all tags that have "foo" but don't have "bar"
    ///
    /// Expressions are processed left to right with AND at a higher
    /// precedence in the order of operations than OR.  Thus:
    ///    a & b & c | d & e | f | g & h
    /// is equivalent to:
    ///    (a & b & c) | (d & e) | f | (g & h)
    ///
    UT_TagExpression    *createTagExpression(const char *expression, UT_String &errs);

    /// Get a list of all the tags used by any list or pattern we've
    /// constructed
    void                 getAllNames(UT_StringArray &tags, bool listref=true);

    /// Test to see if the pattern matches the list
    bool         match(const UT_TagExpression &pattern, const UT_TagList &list);

    /// Check to see if the expression is a simple tautology (always true)
    bool         isTautology(const ut_TagExpression *expr) const;

    /// Get the amount of memory used by tags
    int          getMemUsage() const;

private:
    // Methods called by UT_TagList & UT_TagExpression
    void         freeList(ut_TagList *list);
    void         freeExpression(ut_TagExpression *pattern);

    void         makeListString(UT_WorkBuffer &buf,
                                const ut_TagList *list);
    void         makeExpressionString(UT_WorkBuffer &buf,
                                const ut_TagExpression *pattern);
    ut_TagName  *getTag(const char *tag);

    UT_String                           myName;
    UT_SymbolTable                      myNameTable;
    UT_PtrArray<ut_TagName *>           myNameList;
    int64                               myMemUsage;
    SYS_AtomicInt32                     myListCount;
    SYS_AtomicInt32                     myExpressionCount;

    friend class        UT_TagList;
    friend class        UT_TagExpression;
};

#endif

---