PDG_PathMap.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_PATH_MAP_H
#define PDG_PATH_MAP_H

#include "PDG_API.h"

#include <UT/UT_Array.h>
#include <UT/UT_Lock.h>
#include <UT/UT_StringHolder.h>

class UT_WorkBuffer;

/*
 * Defines a list of mappings between path strings, which are grouped by a
 * mapping "zone". Path maps are applied to file paths to handle cross platform
 * path differences
 */
class PDG_API PDG_PathMap
{
public:
    /// Enumeration of path map matching types
    enum MatchType
    {
        /// The mapping can be matched anywhere in the input string. For
        /// example, "/path/" is a valid match in "H:/path/", "/mnt/path/"
        /// and "/path/subpath/".
        eMatchContains,

        /// The mapping is only valid as a prefix of the input string. For
        /// example, "/path/" is not a valid match for "H:/path/ nor
        /// "/mnt/path/", but is a valid match for "/path/subpath/".
        eMatchPrefix,

        /// The mapping is only valid as a suffix of the input string. For
        /// example, "/path/" is a valid match for "H:/path/ or "/mnt/path/",
        /// but is not a valid match for "/path/subpath/".
        eMatchSuffix,
    };

    /// Path mapping entry contain the from path string, to path string, and
    /// a boolean that indicates if `from` is a string of `to`.
    struct Entry
    {
        UT_StringHolder     myZone;

        UT_StringHolder     myFrom;
        UT_StringHolder     myTo;
        UT_StringHolder     myScheduler;

        MatchType           myMatchType;

        bool                myIsSubpath;
    };

    /// Array of path mapping entries
    using EntryArray = UT_Array<Entry>;

    /// Default zone for Windows systems -- WIN
    static const UT_StringHolder    theWinZone;

    /// Default zone for Mac systems -- MAC
    static const UT_StringHolder    theMacZone;

    /// Default zone for Linux systems -- LINUX
    static const UT_StringHolder    theLinuxZone;

    /// Special zone that matches with all platforms -- *
    static const UT_StringHolder    theAllZone;

    /// Current PDG Path Map data version
    static const int                theVersion;

    /// Sepecial scheduler name that matches all schedulers
    static const UT_StringHolder    theAllSchedulerName;

public:
                            PDG_PathMap(int version);

    /// Reloads the path map instance from the environment
    bool                    reload(bool merge, UT_WorkBuffer& errors);

    /// Returns a string representation of this path map
    const UT_StringHolder&  toString() const;

    /// Saves the path map to the specified work buffer, in JSON format
    bool                    save(UT_WorkBuffer& buffer) const;

    /// Loads a path map from the input JSON string
    bool                    load(const UT_StringHolder& path_map,
                                 bool update_vars,
                                 bool merge,
                                 UT_WorkBuffer& errors);

    /// Applies the path mapping to the input path, using the desired mapping
    /// zone.
    UT_StringHolder         mapPath(const UT_StringHolder& path,
                                    const UT_StringHolder& zone) const;

    /// Applies the path mapping using the mapping zone from the current
    /// platform.
    UT_StringHolder         mapPath(const UT_StringHolder& path) const
                                { return mapPath(path, myZone); }


    /// Returns the current zone for this path mapping instance
    const UT_StringHolder&  zone() const
                                { return myZone; }

    /// Sets the zone for this path mapping instance
    void                    setZone(const UT_StringHolder& zone)
                                {
                                    UT_Lock::Scope lock(myMapLock);
                                    myZone = zone;
                                }

    /// Returns the array of path mapping entries currently stored in
    /// this path map.
    const EntryArray&       mappings() const
                                { return myMapEntries; }

    /// Returns the mapping entries for a specific zone and/or scheduler
    void                    filteredMappings(
                                EntryArray& entries,
                                const UT_StringHolder& zone,
                                const UT_StringHolder& scheduler) const;

    /// Adds an entry to the path map
    void                    addPathMapping(
                                const UT_StringHolder& zone,
                                const UT_StringHolder& map_from,
                                const UT_StringHolder& map_to,
                                const UT_StringHolder& scheduler,
                                MatchType match_type);

    /// Clears path mapping entries for the specified scheduler path
    void                    clearSchedulerMappings(
                                const UT_StringHolder& scheduler);

    /// Clears all path mapping entries
    void                    clearAllMappings();

    /// Updates the internal string representation and env var for the path
    /// mapping.
    void                    commitPathMapping();


    /// Returns the shared global path mapping instance
    static PDG_PathMap&     globalMap();

private:
    /// Top level key for path map array
    static const UT_StringHolder        thePathMapArrayKey;

    /// Map key for a destination path
    static const UT_StringHolder        thePathMapDestKey;

    /// Map key for a destination zone
    static const UT_StringHolder        thePathMapZoneKey;

    /// Map key for a destination scheduler, e.g. the scheduler that
    /// supplied the entry
    static const UT_StringHolder        thePathMapSchedulerKey;

    /// Map key for the match type
    static const  UT_StringHolder       thePathMapMatchTypeKey;

    /// Version number key
    static const UT_StringHolder        theVersionKey;

private:
    EntryArray              myMapEntries;
    mutable UT_StringHolder myString;
    UT_StringHolder         myZone;
    UT_Lock                 myMapLock;
    int                     myVersion;
};

#endif