PDG_AttributePattern.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.
 *
 * COMMENTS:
 */

#ifndef __PDG_ATTRIBUTE_PATTERN_H__
#define __PDG_ATTRIBUTE_PATTERN_H__

#include "PDG_API.h"

#include "PDG_AttributeTypes.h"
#include "PDG_BasePattern.h"

#include <SYS/SYS_Types.h>

#include <UT/UT_StringHolder.h>
#include <UT/UT_StringMap.h>

class UT_StringArray;
class UT_WorkBuffer;

/**
 * Pattern for matching a list of attributes. A pattern object is constructed
 * from a valid pattern string, such as: * ^foo.
 *
 * A pattern is a whitespace seperated sequence of match conditions. Each
 * condition can:
 *
 * - Optionally begin with a ^
 * - Be a single * character
 * - Or, be a valid attribute name with an optional leading *, trailing * or
 *   both a leading a trailing *
 * - Optionally end with a : followed by a valid type name, for example float,
 *   integer or string.
 *
 * The following are valid:
 *
 *      *
 *      * ^foo:float
 *      * ^*foo ^bar* ^*foobar* ^*:string
 *      *:integer
 *      foo ^bar *:python
 *
 *  The following are not:
 *      ^
 *      *foo*bar*
 *      **
 *      f*o
 *      ^:integer
 *      ^*:foobar
 *
 *  Pattern rules are applied left to right when checking if an attribute
 *  name matches.
 *
 *  If the pattern matcher is constructed with the strict option set to false,
 *  then all characters except for * an ^ are valid for attribute names. This
 *  also disables the type specifier : character, and type name parsing.
 */
class PDG_API PDG_AttributePattern : public PDG_BasePattern
{
public:
    /// For compound matching, e.g. *foobar* or bin*:float
    enum MatchType : uint8
    {
        /// The pattern is just a *
        eMatchAll,

        /// The pattern is a * followed by a string name
        eMatchPrefix,

        /// The pattern is a string name, followed by a *
        eMatchSuffix,

        /// The pattern is a string name with both a prefix and suffix
        eMatchBoth,

        /// The pattern has no *
        eMatchPlain,
    };

    /// Break down of the components that matched a pattern. For example,
    /// if the pattern is *foobar* and the input string is thefoobarstring,
    /// then:
    ///     myPrefix contains "the"
    ///     myMatch contains "foobar"
    ///     mySuffix contains "string"
    struct ComponentMatch
    {
        UT_StringHolder myPrefix;
        UT_StringHolder myMatch;
        UT_StringHolder mySuffix;
    };

    /// Map of attribute name to ComponentMatch
    using ComponentMap = UT_StringMap<ComponentMatch>;

public:

    /// Constructs a default-initialized, invalid pattern. 
    PDG_AttributePattern();

    /// Parses a pattern into a PDG_AttributePattern instance
    PDG_AttributePattern(const UT_StringHolder& pattern,
                         MatchType default_match_type=eMatchPlain,
                         bool strict=true);

    /// Clears the pattern and recompiles it from the specified pattern string
    bool                        reset(
                                    const UT_StringHolder& pattern,
                                    MatchType default_match_type=eMatchPlain,
                                    bool strict=true);

    /// Resets the pattern if doesn't match the specified pattern string and
    /// configuration arguments.
    bool                        tryReset(
                                    const UT_StringHolder& pattern,
                                    MatchType default_match_type=eMatchPlain,
                                    bool strict=true);

    /// Returns true if the attribute/type is include in the pattern
    bool                        contains(const UT_StringHolder& name,
                                         PDG_AttributeType type
                                          = PDG_AttributeType::eUndefined) const;

    /// Returns true if the attribute/type is included in the pattern, and
    /// writes the match components.
    bool                        components(
                                    ComponentMatch& components,
                                    const UT_StringHolder& name,
                                    PDG_AttributeType type
                                        = PDG_AttributeType::eUndefined) const;

    /// Applies the pattern to the specified list of input names, and returns
    /// the final list of names that matched the pattern. If keep_plain is
    /// true, then any non-glob pattern pattern entries are always included
    /// even if they don't appear in the input names list.
    void                        multiMatch(
                                    UT_StringArray& match_results,
                                    const UT_StringArray& input_names,
                                    bool keep_plain) const;

    /// Applies the pattern to the specified list of input names, and returns
    /// a map of matched components for each name. If keep_plain is true, then
    /// any non-glob pattern entries are always included even if they don't
    /// appear in the input names list.
    void                        multiMatch(
                                    ComponentMap& match_components,
                                    const UT_StringArray& input_names,
                                    bool keep_plain) const;

private:
    /// Compound match pattern
    struct AttributeMatch
    {
        /// The string name, possibly empty if match type is All
        UT_StringHolder         myMatchName;

        /// The attribute type
        PDG_AttributeType       myAttribType;

        /// The type of match prefix
        MatchType               myMatchType;

        /// Whether or not this is an exlucsion
        bool                    myExclude;
    };

private:
    bool                        parse(const UT_StringHolder& pattern);
    void                        addPattern(bool exclude,
                                           const UT_WorkBuffer& name,
                                           MatchType match_type,
                                           PDG_AttributeType attrib_type);
    bool                        matches(const AttributeMatch& match,
                                        const UT_StringHolder& name,
                                        PDG_AttributeType type) const;
    bool                        matches(ComponentMatch& components,
                                        const AttributeMatch& match,
                                        const UT_StringHolder& name,
                                        PDG_AttributeType type) const;

private:
    /// Extra compound patterns to exclude
    UT_Array<AttributeMatch>    myMatches;

    /// The default match type
    MatchType                   myDefaultMatchType;

    /// Whether or not the pattern has any exclusions
    bool                        myHasExclusions;
    
    /// Whether or not the pattern is strict
    bool                        myIsStrict;
};

#endif